Add explanatory comments for tsgo destructuring workaround

Document why we avoid destructuring from global objects due to a tsgo
transpilation bug that causes runtime errors. References issue #3.

Author: jdalton

src/decode.ts

@@ -4,7 +4,11 @@
  */
 import { PurlError } from './error.js'
 
-const { decodeURIComponent: decodeComponent } = globalThis
+// 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.
+// See: https://github.com/SocketDev/socket-packageurl-js/issues/3
+const decodeComponent = globalThis.decodeURIComponent
 
 function decodePurlComponent(comp: string, encodedComponent: string): string {
   try {

src/encode.ts

@@ -10,6 +10,10 @@ import {
 import { isObject } from './objects.js'
 import { isNonEmptyString } from './strings.js'
 
+// 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.
+// See: https://github.com/SocketDev/socket-packageurl-js/issues/3
 const encodeComponent = globalThis.encodeURIComponent
 
 function encodeName(name: unknown): string {

src/normalize.ts

@@ -93,7 +93,11 @@ function normalizeVersion(rawVersion: unknown): string | undefined {
   return typeof rawVersion === 'string' ? rawVersion.trim() : undefined
 }
 
-const { apply: ReflectApply } = Reflect
+// 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.
+// See: https://github.com/SocketDev/socket-packageurl-js/issues/3
+const ReflectApply = Reflect.apply
 
 function qualifiersToEntries(
   rawQualifiers: unknown,

src/validate.ts

@@ -8,7 +8,11 @@ import { isNonEmptyString } from './strings.js'
 
 import type { QualifiersObject } from './purl-component.js'
 
-const { apply: ReflectApply } = Reflect
+// 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.
+// See: https://github.com/SocketDev/socket-packageurl-js/issues/3
+const ReflectApply = Reflect.apply
 
 function validateEmptyByType(
   type: string,