@socketsecurity/lib 3.0.2 → 3.0.4

package/dist/env.js.map

@@ -2,6 +2,6 @@
   "version": 3,
   "sources": ["../src/env.ts"],
   "sourcesContent": ["/**\n * @fileoverview Environment variable parsing and conversion utilities.\n * Provides type-safe conversion functions for boolean, number, and string values.\n */\n\nconst NumberCtor = Number\n// IMPORTANT: Do not use destructuring here - use direct assignment instead.\n// tsgo has a bug that incorrectly transpiles destructured exports, resulting in\n// `exports.SomeName = void 0;` which causes runtime errors.\n// See: https://github.com/SocketDev/socket-packageurl-js/issues/3\nconst NumberIsFinite = Number.isFinite\nconst NumberParseInt = Number.parseInt\nconst StringCtor = String\n\n// Common environment variables that have case sensitivity issues on Windows.\n// These are checked with case-insensitive matching when exact matches fail.\nconst caseInsensitiveKeys = new Set([\n  'APPDATA',\n  'COMSPEC',\n  'HOME',\n  'LOCALAPPDATA',\n  'PATH',\n  'PATHEXT',\n  'PROGRAMFILES',\n  'SYSTEMROOT',\n  'TEMP',\n  'TMP',\n  'USERPROFILE',\n  'WINDIR',\n])\n\n/**\n * Create a case-insensitive environment variable Proxy for Windows compatibility.\n * On Windows, environment variables are case-insensitive (PATH vs Path vs path).\n * This Proxy provides consistent access regardless of case, with priority given\n * to exact matches, then case-insensitive matches for known vars.\n *\n * **Use Cases:**\n * - Cross-platform test environments needing consistent env var access\n * - Windows compatibility when passing env to child processes\n * - Merging environment overrides while preserving case-insensitive lookups\n *\n * **Performance Note:**\n * Proxy operations have runtime overhead. Only use when Windows case-insensitive\n * access is required. For most use cases, process.env directly is sufficient.\n *\n * @param base - Base environment object (usually process.env)\n * @param overrides - Optional overrides to merge\n * @returns Proxy that handles case-insensitive env var access\n *\n * @example\n * // Create a Proxy with overrides\n * const env = createEnvProxy(process.env, { NODE_ENV: 'test' })\n * console.log(env.PATH)  // Works with any case: PATH, Path, path\n * console.log(env.NODE_ENV)  // 'test'\n *\n * @example\n * // Pass to child process spawn\n * import { createEnvProxy } from '@socketsecurity/lib/env'\n * import { spawn } from '@socketsecurity/lib/spawn'\n *\n * spawn('node', ['script.js'], {\n *   env: createEnvProxy(process.env, { NODE_ENV: 'test' })\n * })\n */\nexport function createEnvProxy(\n  base: NodeJS.ProcessEnv,\n  overrides?: Record<string, string | undefined>,\n): NodeJS.ProcessEnv {\n  return new Proxy(\n    {},\n    {\n      get(_target, prop) {\n        if (typeof prop !== 'string') {\n          return undefined\n        }\n\n        // Priority 1: Check overrides for exact match.\n        if (overrides && prop in overrides) {\n          return overrides[prop]\n        }\n\n        // Priority 2: Check base for exact match.\n        if (prop in base) {\n          return base[prop]\n        }\n\n        // Priority 3: Case-insensitive lookup for known keys.\n        const upperProp = prop.toUpperCase()\n        if (caseInsensitiveKeys.has(upperProp)) {\n          // Check overrides with case variations.\n          if (overrides) {\n            const key = findCaseInsensitiveEnvKey(overrides, upperProp)\n            if (key !== undefined) {\n              return overrides[key]\n            }\n          }\n          // Check base with case variations.\n          const key = findCaseInsensitiveEnvKey(base, upperProp)\n          if (key !== undefined) {\n            return base[key]\n          }\n        }\n\n        return undefined\n      },\n\n      ownKeys(_target) {\n        const keys = new Set<string>([\n          ...Object.keys(base),\n          ...(overrides ? Object.keys(overrides) : []),\n        ])\n        return [...keys]\n      },\n\n      getOwnPropertyDescriptor(_target, prop) {\n        if (typeof prop !== 'string') {\n          return undefined\n        }\n\n        // Use the same lookup logic as get().\n        const value = this.get?.(_target, prop, _target)\n        return value !== undefined\n          ? {\n              enumerable: true,\n              configurable: true,\n              writable: true,\n              value,\n            }\n          : undefined\n      },\n\n      has(_target, prop) {\n        if (typeof prop !== 'string') {\n          return false\n        }\n\n        // Check overrides.\n        if (overrides && prop in overrides) {\n          return true\n        }\n\n        // Check base.\n        if (prop in base) {\n          return true\n        }\n\n        // Case-insensitive check.\n        const upperProp = prop.toUpperCase()\n        if (caseInsensitiveKeys.has(upperProp)) {\n          if (\n            overrides &&\n            findCaseInsensitiveEnvKey(overrides, upperProp) !== undefined\n          ) {\n            return true\n          }\n          if (findCaseInsensitiveEnvKey(base, upperProp) !== undefined) {\n            return true\n          }\n        }\n\n        return false\n      },\n\n      set(_target, prop, value) {\n        if (typeof prop === 'string' && overrides) {\n          overrides[prop] = value\n          return true\n        }\n        return false\n      },\n    },\n  ) as NodeJS.ProcessEnv\n}\n\n/**\n * Convert an environment variable value to a boolean.\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function envAsBoolean(value: unknown, defaultValue = false): boolean {\n  if (typeof value === 'string') {\n    const trimmed = value.trim()\n    return trimmed === '1' || trimmed.toLowerCase() === 'true'\n  }\n  if (value === null || value === undefined) {\n    return !!defaultValue\n  }\n  return !!value\n}\n\n/**\n * Convert an environment variable value to a number.\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function envAsNumber(value: unknown, defaultValue = 0): number {\n  const numOrNaN = NumberParseInt(String(value), 10)\n  const numMayBeNegZero = NumberIsFinite(numOrNaN)\n    ? numOrNaN\n    : NumberCtor(defaultValue)\n  // Ensure -0 is treated as 0.\n  return numMayBeNegZero || 0\n}\n\n/**\n * Convert an environment variable value to a trimmed string.\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function envAsString(value: unknown, defaultValue = ''): string {\n  if (typeof value === 'string') {\n    return value.trim()\n  }\n  if (value === null || value === undefined) {\n    return defaultValue === '' ? defaultValue : StringCtor(defaultValue).trim()\n  }\n  return StringCtor(value).trim()\n}\n\n/**\n * Find a case-insensitive environment variable key match.\n * Searches for an environment variable key that matches the given uppercase name,\n * using optimized fast-path checks to minimize expensive toUpperCase() calls.\n *\n * **Use Cases:**\n * - Finding PATH when env object has \"Path\" or \"path\"\n * - Cross-platform env var access where case may vary\n * - Custom case-insensitive env lookups\n *\n * **Performance:**\n * - Fast path: Checks length first (O(1)) before toUpperCase (expensive)\n * - Only converts to uppercase when length matches\n * - Early exit on first match\n *\n * @param env - Environment object or env-like record to search\n * @param upperEnvVarName - Uppercase environment variable name to find (e.g., 'PATH')\n * @returns The actual key from env that matches (e.g., 'Path'), or undefined\n *\n * @example\n * // Find PATH regardless of case\n * const envObj = { Path: 'C:\\\\Windows', NODE_ENV: 'test' }\n * const key = findCaseInsensitiveEnvKey(envObj, 'PATH')\n * console.log(key)  // 'Path'\n * console.log(envObj[key])  // 'C:\\\\Windows'\n *\n * @example\n * // Not found returns undefined\n * const key = findCaseInsensitiveEnvKey({}, 'MISSING')\n * console.log(key)  // undefined\n */\nexport function findCaseInsensitiveEnvKey(\n  env: Record<string, string | undefined>,\n  upperEnvVarName: string,\n): string | undefined {\n  const targetLength = upperEnvVarName.length\n  for (const key of Object.keys(env)) {\n    // Fast path: bail early if lengths don't match.\n    if (key.length !== targetLength) {\n      continue\n    }\n    // Only call toUpperCase if length matches.\n    if (key.toUpperCase() === upperEnvVarName) {\n      return key\n    }\n  }\n  return undefined\n}\n"],
-  "mappings": ";4ZAAA,IAAAA,EAAA,GAAAC,EAAAD,EAAA,oBAAAE,EAAA,iBAAAC,EAAA,gBAAAC,EAAA,gBAAAC,EAAA,8BAAAC,IAAA,eAAAC,EAAAP,GAKA,MAAMQ,EAAa,OAKbC,EAAiB,OAAO,SACxBC,EAAiB,OAAO,SACxBC,EAAa,OAIbC,EAAsB,IAAI,IAAI,CAClC,UACA,UACA,OACA,eACA,OACA,UACA,eACA,aACA,OACA,MACA,cACA,QACF,CAAC,EAoCM,SAASV,EACdW,EACAC,EACmB,CACnB,OAAO,IAAI,MACT,CAAC,EACD,CACE,IAAIC,EAASC,EAAM,CACjB,GAAI,OAAOA,GAAS,SAClB,OAIF,GAAIF,GAAaE,KAAQF,EACvB,OAAOA,EAAUE,CAAI,EAIvB,GAAIA,KAAQH,EACV,OAAOA,EAAKG,CAAI,EAIlB,MAAMC,EAAYD,EAAK,YAAY,EACnC,GAAIJ,EAAoB,IAAIK,CAAS,EAAG,CAEtC,GAAIH,EAAW,CACb,MAAMI,EAAMZ,EAA0BQ,EAAWG,CAAS,EAC1D,GAAIC,IAAQ,OACV,OAAOJ,EAAUI,CAAG,CAExB,CAEA,MAAMA,EAAMZ,EAA0BO,EAAMI,CAAS,EACrD,GAAIC,IAAQ,OACV,OAAOL,EAAKK,CAAG,CAEnB,CAGF,EAEA,QAAQH,EAAS,CAKf,MAAO,CAAC,GAJK,IAAI,IAAY,CAC3B,GAAG,OAAO,KAAKF,CAAI,EACnB,GAAIC,EAAY,OAAO,KAAKA,CAAS,EAAI,CAAC,CAC5C,CAAC,CACc,CACjB,EAEA,yBAAyBC,EAASC,EAAM,CACtC,GAAI,OAAOA,GAAS,SAClB,OAIF,MAAMG,EAAQ,KAAK,MAAMJ,EAASC,EAAMD,CAAO,EAC/C,OAAOI,IAAU,OACb,CACE,WAAY,GACZ,aAAc,GACd,SAAU,GACV,MAAAA,CACF,EACA,MACN,EAEA,IAAIJ,EAASC,EAAM,CACjB,GAAI,OAAOA,GAAS,SAClB,MAAO,GAST,GALIF,GAAaE,KAAQF,GAKrBE,KAAQH,EACV,MAAO,GAIT,MAAMI,EAAYD,EAAK,YAAY,EACnC,MAAI,GAAAJ,EAAoB,IAAIK,CAAS,IAEjCH,GACAR,EAA0BQ,EAAWG,CAAS,IAAM,QAIlDX,EAA0BO,EAAMI,CAAS,IAAM,QAMvD,EAEA,IAAIF,EAASC,EAAMG,EAAO,CACxB,OAAI,OAAOH,GAAS,UAAYF,GAC9BA,EAAUE,CAAI,EAAIG,EACX,IAEF,EACT,CACF,CACF,CACF,CAMO,SAAShB,EAAagB,EAAgBC,EAAe,GAAgB,CAC1E,GAAI,OAAOD,GAAU,SAAU,CAC7B,MAAME,EAAUF,EAAM,KAAK,EAC3B,OAAOE,IAAY,KAAOA,EAAQ,YAAY,IAAM,MACtD,CACA,OAAIF,GAAU,KACL,CAAC,CAACC,EAEJ,CAAC,CAACD,CACX,CAMO,SAASf,EAAYe,EAAgBC,EAAe,EAAW,CACpE,MAAME,EAAWZ,EAAe,OAAOS,CAAK,EAAG,EAAE,EAKjD,OAJwBV,EAAea,CAAQ,EAC3CA,EACAd,EAAWY,CAAY,IAED,CAC5B,CAMO,SAASf,EAAYc,EAAgBC,EAAe,GAAY,CACrE,OAAI,OAAOD,GAAU,SACZA,EAAM,KAAK,EAEhBA,GAAU,KACLC,IAAiB,GAAKA,EAAeT,EAAWS,CAAY,EAAE,KAAK,EAErET,EAAWQ,CAAK,EAAE,KAAK,CAChC,CAiCO,SAASb,EACdiB,EACAC,EACoB,CACpB,MAAMC,EAAeD,EAAgB,OACrC,UAAWN,KAAO,OAAO,KAAKK,CAAG,EAE/B,GAAIL,EAAI,SAAWO,GAIfP,EAAI,YAAY,IAAMM,EACxB,OAAON,CAIb",
-  "names": ["env_exports", "__export", "createEnvProxy", "envAsBoolean", "envAsNumber", "envAsString", "findCaseInsensitiveEnvKey", "__toCommonJS", "NumberCtor", "NumberIsFinite", "NumberParseInt", "StringCtor", "caseInsensitiveKeys", "base", "overrides", "_target", "prop", "upperProp", "key", "value", "defaultValue", "trimmed", "numOrNaN", "env", "upperEnvVarName", "targetLength"]
+  "mappings": "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",
+  "names": ["key"]
 }