Add JSDoc documentation to core components

Author: jdalton

src/normalize.ts

@@ -7,16 +7,25 @@ import { isBlank } from './strings.js'
 
 import type { QualifiersObject } from './purl-component.js'
 
+/**
+ * Normalize package name by trimming whitespace.
+ */
 function normalizeName(rawName: unknown): string | undefined {
   return typeof rawName === 'string' ? rawName.trim() : undefined
 }
 
+/**
+ * Normalize package namespace by trimming and collapsing path separators.
+ */
 function normalizeNamespace(rawNamespace: unknown): string | undefined {
   return typeof rawNamespace === 'string'
     ? normalizePath(rawNamespace, undefined)
     : undefined
 }
 
+/**
+ * Normalize path by collapsing separators and filtering segments.
+ */
 function normalizePath(
   pathname: string,
   callback?: (_segment: string) => boolean,
@@ -55,6 +64,9 @@ function normalizePath(
   return collapsed
 }
 
+/**
+ * Normalize qualifiers by trimming values and lowercasing keys.
+ */
 function normalizeQualifiers(
   rawQualifiers: unknown,
 ): Record<string, string> | undefined {
@@ -77,18 +89,27 @@ function normalizeQualifiers(
   return qualifiers
 }
 
+/**
+ * Normalize subpath by filtering invalid segments.
+ */
 function normalizeSubpath(rawSubpath: unknown): string | undefined {
   return typeof rawSubpath === 'string'
     ? normalizePath(rawSubpath, subpathFilter)
     : undefined
 }
 
+/**
+ * Normalize package type to lowercase.
+ */
 function normalizeType(rawType: unknown): string | undefined {
   // The type must NOT be percent-encoded.
   // The type is case insensitive. The canonical form is lowercase.
   return typeof rawType === 'string' ? rawType.trim().toLowerCase() : undefined
 }
 
+/**
+ * Normalize package version by trimming whitespace.
+ */
 function normalizeVersion(rawVersion: unknown): string | undefined {
   return typeof rawVersion === 'string' ? rawVersion.trim() : undefined
 }
@@ -99,6 +120,9 @@ function normalizeVersion(rawVersion: unknown): string | undefined {
 // See: https://github.com/SocketDev/socket-packageurl-js/issues/3
 const ReflectApply = Reflect.apply
 
+/**
+ * Convert qualifiers to iterable entries.
+ */
 function qualifiersToEntries(
   rawQualifiers: unknown,
 ): Iterable<[string, string]> {
@@ -119,6 +143,9 @@ function qualifiersToEntries(
     : Object.entries({})
 }
 
+/**
+ * Filter invalid subpath segments.
+ */
 function subpathFilter(segment: string): boolean {
   // When percent-decoded, a segment
   //   - must not be any of '.' or '..'

src/objects.ts

@@ -4,10 +4,17 @@
  */
 import { LOOP_SENTINEL } from './constants.js'
 
+/**
+ * Check if value is an object type.
+ */
 function isObject(value: unknown): value is object {
   return value !== null && typeof value === 'object'
 }
 
+/**
+ * Recursively freeze an object and all nested objects.
+ * @throws {Error} When infinite loop detected.
+ */
 function recursiveFreeze<T>(value_: T): T {
   if (
     value_ === null ||

src/package-url-builder.ts

@@ -86,24 +86,23 @@ export class PackageURLBuilder {
   private _subpath?: string
 
   /**
-   * Set the package type for the PackageURL.
-   */
-  type(type: string): this {
-    this._type = type
-    return this
-  }
-
-  /**
-   * Set the package namespace for the PackageURL.
+   * Build and return the final PackageURL instance.
    *
-   * The namespace represents different concepts depending on the package type:
-   * - npm: organization or scope (e.g., '@angular' for '@angular/core')
-   * - maven: groupId (e.g., 'org.apache.commons')
-   * - pypi: typically unused
+   * This method creates a new PackageURL instance using all the properties
+   * set on this builder. The PackageURL constructor will handle validation
+   * and normalization of the provided values.
+   *
+   * @throws {Error} If the configuration results in an invalid PackageURL
    */
-  namespace(namespace: string): this {
-    this._namespace = namespace
-    return this
+  build(): PackageURL {
+    return new PackageURL(
+      this._type,
+      this._namespace,
+      this._name,
+      this._version,
+      this._qualifiers,
+      this._subpath,
+    )
   }
 
   /**
@@ -119,26 +118,15 @@ export class PackageURLBuilder {
   }
 
   /**
-   * Set the package version for the PackageURL.
-   *
-   * The version string should match the format used by the package repository.
-   * Some package types may normalize version formats (e.g., removing leading 'v').
-   */
-  version(version: string): this {
-    this._version = version
-    return this
-  }
-
-  /**
-   * Set all qualifiers at once, replacing any existing qualifiers.
+   * Set the package namespace for the PackageURL.
    *
-   * Qualifiers provide additional metadata about the package such as:
-   * - arch: target architecture
-   * - os: target operating system
-   * - classifier: additional classifier for the package
+   * The namespace represents different concepts depending on the package type:
+   * - npm: organization or scope (e.g., '@angular' for '@angular/core')
+   * - maven: groupId (e.g., 'org.apache.commons')
+   * - pypi: typically unused
    */
-  qualifiers(qualifiers: Record<string, string>): this {
-    this._qualifiers = { ...qualifiers }
+  namespace(namespace: string): this {
+    this._namespace = namespace
     return this
   }
 
@@ -156,6 +144,19 @@ export class PackageURLBuilder {
     return this
   }
 
+  /**
+   * Set all qualifiers at once, replacing any existing qualifiers.
+   *
+   * Qualifiers provide additional metadata about the package such as:
+   * - arch: target architecture
+   * - os: target operating system
+   * - classifier: additional classifier for the package
+   */
+  qualifiers(qualifiers: Record<string, string>): this {
+    this._qualifiers = { ...qualifiers }
+    return this
+  }
+
   /**
    * Set the subpath for the PackageURL.
    *
@@ -169,23 +170,42 @@ export class PackageURLBuilder {
   }
 
   /**
-   * Build and return the final PackageURL instance.
+   * Set the package type for the PackageURL.
+   */
+  type(type: string): this {
+    this._type = type
+    return this
+  }
+
+  /**
+   * Set the package version for the PackageURL.
    *
-   * This method creates a new PackageURL instance using all the properties
-   * set on this builder. The PackageURL constructor will handle validation
-   * and normalization of the provided values.
+   * The version string should match the format used by the package repository.
+   * Some package types may normalize version formats (e.g., removing leading 'v').
+   */
+  version(version: string): this {
+    this._version = version
+    return this
+  }
+
+  /**
+   * Create a builder with the cargo package type preset.
    *
-   * @throws {Error} If the configuration results in an invalid PackageURL
+   * This convenience method creates a new builder instance with the type
+   * already set to 'cargo', ready for building Rust crate URLs.
    */
-  build(): PackageURL {
-    return new PackageURL(
-      this._type,
-      this._namespace,
-      this._name,
-      this._version,
-      this._qualifiers,
-      this._subpath,
-    )
+  static cargo(): PackageURLBuilder {
+    return new PackageURLBuilder().type('cargo')
+  }
+
+  /**
+   * Create a builder with the composer package type preset.
+   *
+   * This convenience method creates a new builder instance with the type
+   * already set to 'composer', ready for building Composer package URLs.
+   */
+  static composer(): PackageURLBuilder {
+    return new PackageURLBuilder().type('composer')
   }
 
   /**
@@ -234,23 +254,23 @@ export class PackageURLBuilder {
   }
 
   /**
-   * Create a builder with the npm package type preset.
+   * Create a builder with the gem package type preset.
    *
    * This convenience method creates a new builder instance with the type
-   * already set to 'npm', ready for building npm package URLs.
+   * already set to 'gem', ready for building Ruby gem URLs.
    */
-  static npm(): PackageURLBuilder {
-    return new PackageURLBuilder().type('npm')
+  static gem(): PackageURLBuilder {
+    return new PackageURLBuilder().type('gem')
   }
 
   /**
-   * Create a builder with the pypi package type preset.
+   * Create a builder with the golang package type preset.
    *
    * This convenience method creates a new builder instance with the type
-   * already set to 'pypi', ready for building Python package URLs.
+   * already set to 'golang', ready for building Go package URLs.
    */
-  static pypi(): PackageURLBuilder {
-    return new PackageURLBuilder().type('pypi')
+  static golang(): PackageURLBuilder {
+    return new PackageURLBuilder().type('golang')
   }
 
   /**
@@ -264,33 +284,13 @@ export class PackageURLBuilder {
   }
 
   /**
-   * Create a builder with the gem package type preset.
-   *
-   * This convenience method creates a new builder instance with the type
-   * already set to 'gem', ready for building Ruby gem URLs.
-   */
-  static gem(): PackageURLBuilder {
-    return new PackageURLBuilder().type('gem')
-  }
-
-  /**
-   * Create a builder with the golang package type preset.
-   *
-   * This convenience method creates a new builder instance with the type
-   * already set to 'golang', ready for building Go package URLs.
-   */
-  static golang(): PackageURLBuilder {
-    return new PackageURLBuilder().type('golang')
-  }
-
-  /**
-   * Create a builder with the cargo package type preset.
+   * Create a builder with the npm package type preset.
    *
    * This convenience method creates a new builder instance with the type
-   * already set to 'cargo', ready for building Rust crate URLs.
+   * already set to 'npm', ready for building npm package URLs.
    */
-  static cargo(): PackageURLBuilder {
-    return new PackageURLBuilder().type('cargo')
+  static npm(): PackageURLBuilder {
+    return new PackageURLBuilder().type('npm')
   }
 
   /**
@@ -304,12 +304,12 @@ export class PackageURLBuilder {
   }
 
   /**
-   * Create a builder with the composer package type preset.
+   * Create a builder with the pypi package type preset.
    *
    * This convenience method creates a new builder instance with the type
-   * already set to 'composer', ready for building Composer package URLs.
+   * already set to 'pypi', ready for building Python package URLs.
    */
-  static composer(): PackageURLBuilder {
-    return new PackageURLBuilder().type('composer')
+  static pypi(): PackageURLBuilder {
+    return new PackageURLBuilder().type('pypi')
   }
 }