refactor: improve source code quality and security

- Fix ReDoS vulnerabilities and add input validation
- Add length limits and circular dependency resolution
- Standardize error messages and error handling
- Replace process.exit with process.exitCode
- Use @socketsecurity/registry utilities
- Improve type safety and remove any types
- Add explicit undefined for optional properties
- Optimize performance and reduce allocations

Author: jdalton

src/decode.ts

@@ -4,9 +4,9 @@
  */
 import { PurlError } from './error.js'
 
-// IMPORTANT: Do not use destructuring here - use direct assignment instead.
+// IMPORTANT: Do not use destructuring here - use direct assignment instead
 // tsgo has a bug that incorrectly transpiles destructured exports, resulting in
-// `exports.decodeComponent = void 0;` which causes runtime errors.
+// `exports.decodeComponent = void 0;` which causes runtime errors
 // See: https://github.com/SocketDev/socket-packageurl-js/issues/3
 const decodeComponent = globalThis.decodeURIComponent
 

src/encode.ts

@@ -9,9 +9,9 @@ import {
 import { isObject } from './objects.js'
 import { isNonEmptyString } from './strings.js'
 
-// IMPORTANT: Do not use destructuring here (e.g., const { encodeURIComponent } = globalThis).
+// IMPORTANT: Do not use destructuring here (e.g., const { encodeURIComponent } = globalThis)
 // tsgo has a bug that incorrectly transpiles destructured exports, resulting in
-// `exports.encodeComponent = void 0;` which causes runtime errors.
+// `exports.encodeComponent = void 0;` which causes runtime errors
 // See: https://github.com/SocketDev/socket-packageurl-js/issues/3
 const encodeComponent = globalThis.encodeURIComponent
 
@@ -39,13 +39,13 @@ function encodeNamespace(namespace: unknown): string {
 function encodeQualifierParam(param: unknown): string {
   if (isNonEmptyString(param)) {
     const value = prepareValueForSearchParams(param)
-    // Use URLSearchParams#set to preserve plus signs.
+    // Use URLSearchParams#set to preserve plus signs
     // https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams#preserving_plus_signs
-    // Use a local instance to avoid mutation issues in concurrent scenarios.
+    // Use a local instance to avoid mutation issues in concurrent scenarios
     const searchParams = new URLSearchParams()
     searchParams.set(REUSED_SEARCH_PARAMS_KEY, value)
     // Param key and value are encoded with `percentEncodeSet` of
-    // 'application/x-www-form-urlencoded' and `spaceAsPlus` of `true`.
+    // 'application/x-www-form-urlencoded' and `spaceAsPlus` of `true`
     // https://url.spec.whatwg.org/#urlencoded-serializing
     const search = searchParams.toString()
     return normalizeSearchParamsEncoding(
@@ -60,15 +60,15 @@ function encodeQualifierParam(param: unknown): string {
  */
 function encodeQualifiers(qualifiers: unknown): string {
   if (isObject(qualifiers)) {
-    // Sort this list of qualifier strings lexicographically.
+    // Sort this list of qualifier strings lexicographically
     const qualifiersKeys = Object.keys(qualifiers).sort()
     const searchParams = new URLSearchParams()
     for (let i = 0, { length } = qualifiersKeys; i < length; i += 1) {
       const key = qualifiersKeys[i]!
       const value = prepareValueForSearchParams(
         (qualifiers as Record<string, unknown>)[key],
       )
-      // Use URLSearchParams#set to preserve plus signs.
+      // Use URLSearchParams#set to preserve plus signs
       // https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams#preserving_plus_signs
       searchParams.set(key!, value)
     }
@@ -106,7 +106,7 @@ function normalizeSearchParamsEncoding(encoded: string): string {
  * Prepare string value for URLSearchParams encoding.
  */
 function prepareValueForSearchParams(value: unknown): string {
-  // Replace spaces with %20's so they don't get converted to plus signs.
+  // Replace spaces with %20's so they don't get converted to plus signs
   return String(value).replaceAll(' ', '%20')
 }
 

src/error.ts

@@ -10,13 +10,13 @@ function formatPurlErrorMessage(message = ''): string {
   const { length } = message
   let formatted = ''
   if (length) {
-    // Lower case start of message.
+    // Lower case start of message
     const code0 = message.charCodeAt(0)
     formatted =
       code0 >= 65 /*'A'*/ && code0 <= 90 /*'Z'*/
         ? `${message[0]!.toLowerCase()}${message.slice(1)}`
         : message
-    // Remove period from end of message.
+    // Remove period from end of message
     if (
       length > 1 &&
       message.charCodeAt(length - 1) === 46 /*'.'*/ &&

src/helpers.ts

@@ -17,7 +17,7 @@ function createHelpersNamespaceObject(
     comparator?: ((_a: string, _b: string) => number) | undefined
   }
   const helperNames = Object.keys(helpers).sort()
-  // Collect all unique property names from all helper objects.
+  // Collect all unique property names from all helper objects
   const propNames = [
     ...new Set(
       Object.values(helpers).flatMap((helper: Record<string, unknown>) =>
@@ -26,7 +26,7 @@ function createHelpersNamespaceObject(
     ),
   ].sort(comparator)
   const nsObject: Record<string, Record<string, unknown>> = Object.create(null)
-  // Build inverted structure: property -> {helper1: value1, helper2: value2}.
+  // Build inverted structure: property -> {helper1: value1, helper2: value2}
   for (let i = 0, { length } = propNames; i < length; i += 1) {
     const propName = propNames[i]!
     const helpersForProp: Record<string, unknown> = Object.create(null)

src/index.ts

@@ -22,30 +22,66 @@ SOFTWARE.
 
 /**
  * @fileoverview Main entry point for the socket-packageurl-js library.
- * Provides exports for PackageURL, PurlComponent, PurlQualifierNames, and PurlType.
+ *
+ * This library provides a complete implementation of the Package URL (purl) specification.
+ * Package URLs are used to identify and locate software packages in a standardized way
+ * across different package management systems and ecosystems.
+ *
+ * Core exports:
+ * - PackageURL: Main class for parsing and constructing package URLs
+ * - PackageURLBuilder: Builder pattern for constructing package URLs
+ * - PurlType: Type-specific normalization and validation rules
+ * - PurlComponent: Component encoding/decoding utilities
+ * - PurlQualifierNames: Known qualifier names from the specification
+ *
+ * Utility exports:
+ * - UrlConverter: Convert between purls and repository/download URLs
+ * - Result utilities: Functional error handling with Ok/Err pattern
  */
 
-/* c8 ignore start - Re-export only file, no logic to test. */
+/* c8 ignore start - Re-export only file, no logic to test */
+
+// ============================================================================
+// Core Classes and Functions
+// ============================================================================
 export {
-  Err,
-  Ok,
   PackageURL,
-  PackageURLBuilder,
   PurlComponent,
   PurlQualifierNames,
   PurlType,
-  ResultUtils,
+} from './package-url.js'
+
+export { PackageURLBuilder } from './package-url-builder.js'
+
+// ============================================================================
+// Utility Classes and Functions
+// ============================================================================
+export {
   UrlConverter,
+} from './package-url.js'
+
+export {
+  Err,
+  Ok,
+  ResultUtils,
   err,
   ok,
 } from './package-url.js'
+
+// ============================================================================
+// TypeScript Type Definitions
+// ============================================================================
 export type {
   DownloadUrl,
   RepositoryUrl,
   Result,
 } from './package-url.js'
 
+// ============================================================================
+// Registry Integration
+// ============================================================================
 // Re-export PURL types from socket-registry for consistency
 export { PURL_Type } from '@socketsecurity/registry'
 export type { EcosystemString } from '@socketsecurity/registry'
+
 /* c8 ignore stop */

src/normalize.ts

@@ -34,31 +34,31 @@ function normalizePurlPath(
   let collapsed = ''
   let start = 0
   // Leading and trailing slashes, i.e. '/', are not significant and should be
-  // stripped in the canonical form.
+  // stripped in the canonical form
   while (pathname.charCodeAt(start) === 47 /*'/'*/) {
     start += 1
   }
   let nextIndex = pathname.indexOf('/', start)
   if (nextIndex === -1) {
-    // No slashes found - return trimmed pathname.
+    // No slashes found - return trimmed pathname
     return pathname.slice(start)
   }
   // Discard any empty string segments by collapsing repeated segment
-  // separator slashes, i.e. '/'.
+  // separator slashes, i.e. '/'
   while (nextIndex !== -1) {
     const segment = pathname.slice(start, nextIndex)
     if (callback === undefined || callback(segment)) {
-      // Add segment with separator if not first segment.
+      // Add segment with separator if not first segment
       collapsed = collapsed + (collapsed.length === 0 ? '' : '/') + segment
     }
-    // Skip to next segment, consuming multiple consecutive slashes.
+    // Skip to next segment, consuming multiple consecutive slashes
     start = nextIndex + 1
     while (pathname.charCodeAt(start) === 47) {
       start += 1
     }
     nextIndex = pathname.indexOf('/', start)
   }
-  // Handle last segment after final slash.
+  // Handle last segment after final slash
   const lastSegment = pathname.slice(start)
   if (
     lastSegment.length !== 0 &&
@@ -76,19 +76,19 @@ function normalizeQualifiers(
   rawQualifiers: unknown,
 ): Record<string, string> | undefined {
   let qualifiers: Record<string, string> | undefined
-  // Use for-of to work with entries iterators.
+  // Use for-of to work with entries iterators
   for (const { 0: key, 1: value } of qualifiersToEntries(rawQualifiers)) {
     const strValue = typeof value === 'string' ? value : String(value)
     const trimmed = strValue.trim()
     // A key=value pair with an empty value is the same as no key/value
-    // at all for this key.
+    // at all for this key
     if (trimmed.length === 0) {
       continue
     }
     if (qualifiers === undefined) {
       qualifiers = Object.create(null) as Record<string, string>
     }
-    // A key is case insensitive. The canonical form is lowercase.
+    // A key is case insensitive. The canonical form is lowercase
     qualifiers[key.toLowerCase()] = trimmed
   }
   return qualifiers
@@ -107,8 +107,8 @@ function normalizeSubpath(rawSubpath: unknown): string | 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.
+  // 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
 }
 
@@ -119,9 +119,9 @@ function normalizeVersion(rawVersion: unknown): string | undefined {
   return typeof rawVersion === 'string' ? rawVersion.trim() : undefined
 }
 
-// IMPORTANT: Do not use destructuring here - use direct assignment instead.
+// IMPORTANT: Do not use destructuring here - use direct assignment instead
 // tsgo has a bug that incorrectly transpiles destructured exports, resulting in
-// `exports.ReflectApply = void 0;` which causes runtime errors.
+// `exports.ReflectApply = void 0;` which causes runtime errors
 // See: https://github.com/SocketDev/socket-packageurl-js/issues/3
 const ReflectApply = Reflect.apply
 
@@ -132,7 +132,7 @@ function qualifiersToEntries(
   rawQualifiers: unknown,
 ): Iterable<[string, string]> {
   if (isObject(rawQualifiers)) {
-    // URLSearchParams instances have an "entries" method that returns an iterator.
+    // URLSearchParams instances have an "entries" method that returns an iterator
     const rawQualifiersObj = rawQualifiers as QualifiersObject | URLSearchParams
     const entriesProperty = (rawQualifiersObj as QualifiersObject)['entries']
     return typeof entriesProperty === 'function'

src/objects.ts

@@ -2,14 +2,10 @@
  * @fileoverview Object utility functions for type checking and immutable object creation.
  * Provides object validation and recursive freezing utilities.
  */
-import { LOOP_SENTINEL } from './constants.js'
+// eslint-disable-next-line import-x/extensions -- External package, no .js extension needed
+import { isObject } from '@socketsecurity/registry/lib/objects'
 
-/**
- * Check if value is an object type.
- */
-function isObject(value: unknown): value is object {
-  return value !== null && typeof value === 'object'
-}
+import { LOOP_SENTINEL } from './constants.js'
 
 /**
  * Recursively freeze an object and all nested objects.
@@ -24,21 +20,21 @@ function recursiveFreeze<T>(value_: T): T {
   ) {
     return value_
   }
-  // Use breadth-first traversal to avoid stack overflow on deep objects.
+  // Use breadth-first traversal to avoid stack overflow on deep objects
   const queue = [value_ as T & object]
   const visited = new WeakSet<object>()
   visited.add(value_ as T & object)
   let { length: queueLength } = queue
   let pos = 0
   while (pos < queueLength) {
-    // Safety check to prevent processing excessively large object graphs.
+    // Safety check to prevent processing excessively large object graphs
     if (pos === LOOP_SENTINEL) {
-      throw new Error('Object graph too large (exceeds 1,000,000 items)')
+      throw new Error('Object graph too large (exceeds 1,000,000 items).')
     }
     const obj = queue[pos++]!
     Object.freeze(obj)
     if (Array.isArray(obj)) {
-      // Queue unfrozen array items for processing.
+      // Queue unfrozen array items for processing
       for (let i = 0, { length } = obj; i < length; i += 1) {
         const item: unknown = obj[i]
         if (
@@ -52,10 +48,12 @@ function recursiveFreeze<T>(value_: T): T {
         }
       }
     } else {
-      // Queue unfrozen object properties for processing.
+      // Queue unfrozen object properties for processing
       const keys = Reflect.ownKeys(obj)
       for (let i = 0, { length } = keys; i < length; i += 1) {
-        const propValue: unknown = (obj as any)[keys[i]!]
+        const propValue: unknown = (obj as Record<PropertyKey, unknown>)[
+          keys[i]!
+        ]
         if (
           propValue !== null &&
           (typeof propValue === 'object' || typeof propValue === 'function') &&