docs: add JSDocs

README.md

@@ -5,11 +5,13 @@ Simple CLI script to sync Spotify tracks from a raw text to a playlist.
 ## Usage
 
 Install Deno, and run:
+
 ```bash
 deno run --allow-net jsr:@dirkluijk/text-to-playlist <inputFileOrText> --playlist <playlistUrl>
 ```
 
 ## Options
+
 ```
 -h, --help                            - Show this help.                                                                  
 -V, --version                         - Show the version number for this program.                                        
@@ -21,5 +23,5 @@ deno run --allow-net jsr:@dirkluijk/text-to-playlist <inputFileOrText> --playlis
 
 ## Contributors
 
-* [@dirkluijk](https://github.com/dirkluijk) - Deno fork
-* [@janluijk](https://github.com/janluijk) - original Python implementation
+- [@dirkluijk](https://github.com/dirkluijk) - Deno fork
+- [@janluijk](https://github.com/janluijk) - original Python implementation

main.ts

@@ -19,7 +19,7 @@ const { args, options } = await new Command()
     "The Spotify Playlist URL to add to tracks to",
     { required: true },
   )
-  .option('-D, --debug', 'Outputs debugging logs')
+  .option("-D, --debug", "Outputs debugging logs")
   .option(
     "--remove-duplicates [flag:boolean]",
     "Whether to filter out duplicates from input",
@@ -50,8 +50,8 @@ const trackUrls = removeDuplicates
 const tracks = trackUrls.map(Track.fromUrl);
 
 if (options.debug) {
-  console.debug('Found tracks:');
-  console.table(tracks.map((it) => it.toUrl()))
+  console.debug("Found tracks:");
+  console.table(tracks.map((it) => it.toUrl()));
 }
 
 const currentTracks = await new PageIterator(

src/utils/spotify-authorization.ts

@@ -8,9 +8,10 @@ const REDIRECT_URI = "http://localhost:8888/callback";
 
 const [codeVerifier, codeChallenge] = await createPkceChallenge();
 
+/**
+ * Starts a local web server to accept the callback from the Spotify Authorization flow.
+ */
 function waitForAuthorization(options: { port: number }): Promise<string> {
-  // wait for user to have accepted
-  // opens web server to accept the callback
   return new Promise<string>((resolve, reject) => {
     const abortController = new AbortController();
     const server = Deno.serve({
@@ -52,8 +53,11 @@ export async function retrieveAccessToken(): Promise<string> {
       }).toString(),
   );
 
+  // wait for user to have accepted
+  // opens web server to accept the callback
   const code = await waitForAuthorization({ port: 8888 });
 
+  // now request the access token based on the authorization code
   const { access_token } = await wretch("https://accounts.spotify.com/api/token")
     .addon(FormUrlAddon)
     .formUrl({

src/utils/spotify.ts

@@ -1,6 +1,13 @@
+/**
+ * Represents a Spotify track.
+ */
 export class Track {
   constructor(public id: string) {}
 
+  /**
+   * Parses a track from its Spotify URL.
+   * @see https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids
+   */
   static fromUrl(trackUrl: string) {
     const pattern = new URLPattern("https://open.spotify.com/track/:id");
     const result = pattern.exec(trackUrl);
@@ -12,18 +19,33 @@ export class Track {
     return new Track(result.pathname.groups.id);
   }
 
+  /**
+   * Returns the Spotify track URI.
+   * @see https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids
+   */
   public toUri(): string {
     return `spotify:track:${this.id}`;
   }
 
+  /**
+   * Returns the Spotify track URL.
+   * @see https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids
+   */
   public toUrl(): string {
     return `https://open.spotify.com/track/${this.id}`;
   }
 }
 
+/**
+ * Represents a Spotify playlist.
+ */
 export class Playlist {
   constructor(public id: string) {}
 
+  /**
+   * Parses a playlist from its Spotify URL.
+   * @see https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids
+   */
   static fromUrl(playlistUrl: string) {
     const pattern = new URLPattern("https://open.spotify.com/playlist/:id");
     const result = pattern.exec(playlistUrl);
@@ -35,10 +57,18 @@ export class Playlist {
     return new Playlist(result.pathname.groups.id);
   }
 
+  /**
+   * Returns the Spotify playlist URI.
+   * @see https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids
+   */
   public toUri(): string {
     return `spotify:playlist:${this.id}`;
   }
 
+  /**
+   * Returns the Spotify playlist URL.
+   * @see https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids
+   */
   public toUrl(): string {
     return `https://open.spotify.com/playlist/${this.id}`;
   }