@socketsecurity/lib 5.28.0 → 6.0.0

package/dist/env/locale.d.ts

@@ -1,49 +1,46 @@
 /**
- * @fileoverview Locale and language environment variable getters.
- * Provides access to system locale settings.
+ * @file Locale and language environment variable getters. Provides access to
+ *   system locale settings.
  */
 /**
- * LANG environment variable.
- * System locale and language settings.
- *
- * @returns The system locale string, or `undefined` if not set
+ * LANG environment variable. System locale and language settings.
  *
  * @example
- * ```typescript
- * import { getLang } from '@socketsecurity/lib/env/locale'
+ *   ;```typescript
+ *   import { getLang } from '@socketsecurity/lib/env/locale'
+ *
+ *   const lang = getLang()
+ *   // e.g. 'en_US.UTF-8' or undefined
+ *   ```
  *
- * const lang = getLang()
- * // e.g. 'en_US.UTF-8' or undefined
- * ```
+ * @returns The system locale string, or `undefined` if not set
  */
 export declare function getLang(): string | undefined;
 /**
- * LC_ALL environment variable.
- * Override for all locale settings.
- *
- * @returns The locale override string, or `undefined` if not set
+ * LC_ALL environment variable. Override for all locale settings.
  *
  * @example
- * ```typescript
- * import { getLcAll } from '@socketsecurity/lib/env/locale'
+ *   ;```typescript
+ *   import { getLcAll } from '@socketsecurity/lib/env/locale'
  *
- * const lcAll = getLcAll()
- * // e.g. 'C' or 'en_US.UTF-8'
- * ```
+ *   const lcAll = getLcAll()
+ *   // e.g. 'C' or 'en_US.UTF-8'
+ *   ```
+ *
+ * @returns The locale override string, or `undefined` if not set
  */
 export declare function getLcAll(): string | undefined;
 /**
- * LC_MESSAGES environment variable.
- * Locale setting for message translations.
- *
- * @returns The messages locale string, or `undefined` if not set
+ * LC_MESSAGES environment variable. Locale setting for message translations.
  *
  * @example
- * ```typescript
- * import { getLcMessages } from '@socketsecurity/lib/env/locale'
+ *   ;```typescript
+ *   import { getLcMessages } from '@socketsecurity/lib/env/locale'
+ *
+ *   const lcMessages = getLcMessages()
+ *   // e.g. 'en_US.UTF-8' or undefined
+ *   ```
  *
- * const lcMessages = getLcMessages()
- * // e.g. 'en_US.UTF-8' or undefined
- * ```
+ * @returns The messages locale string, or `undefined` if not set
  */
 export declare function getLcMessages(): string | undefined;

package/dist/env/node-auth-token.d.ts

@@ -1,19 +1,19 @@
 /**
- * @fileoverview NODE_AUTH_TOKEN environment variable getter.
- * Exports `getNodeAuthToken()`, returning the value of `NODE_AUTH_TOKEN`
- * used to authenticate against Node.js package registries.
+ * @file NODE_AUTH_TOKEN environment variable getter. Exports
+ *   `getNodeAuthToken()`, returning the value of `NODE_AUTH_TOKEN` used to
+ *   authenticate against Node.js package registries.
  */
 /**
  * Returns the value of the NODE_AUTH_TOKEN environment variable.
  *
- * @returns The Node.js registry auth token, or `undefined` if not set
- *
  * @example
- * ```typescript
- * import { getNodeAuthToken } from '@socketsecurity/lib/env/node-auth-token'
+ *   ;```typescript
+ *   import { getNodeAuthToken } from '@socketsecurity/lib/env/node-auth-token'
  *
- * const token = getNodeAuthToken()
- * // e.g. 'npm_abc123...' or undefined
- * ```
+ *   const token = getNodeAuthToken()
+ *   // e.g. 'npm_abc123...' or undefined
+ *   ```
+ *
+ * @returns The Node.js registry auth token, or `undefined` if not set
  */
 export declare function getNodeAuthToken(): string | undefined;

package/dist/env/node-env.d.ts

@@ -1,19 +1,19 @@
 /**
- * @fileoverview NODE_ENV environment variable getter.
- * Exports `getNodeEnv()`, returning the raw `NODE_ENV` value (typically
- * 'production', 'development', or 'test') or `undefined` when unset.
+ * @file NODE_ENV environment variable getter. Exports `getNodeEnv()`, returning
+ *   the raw `NODE_ENV` value (typically 'production', 'development', or 'test')
+ *   or `undefined` when unset.
  */
 /**
  * Returns the value of the NODE_ENV environment variable.
  *
- * @returns The Node.js environment mode, or `undefined` if not set
- *
  * @example
- * ```typescript
- * import { getNodeEnv } from '@socketsecurity/lib/env/node-env'
+ *   ;```typescript
+ *   import { getNodeEnv } from '@socketsecurity/lib/env/node-env'
  *
- * const env = getNodeEnv()
- * // e.g. 'production', 'development', 'test', or undefined
- * ```
+ *   const env = getNodeEnv()
+ *   // e.g. 'production', 'development', 'test', or undefined
+ *   ```
+ *
+ * @returns The Node.js environment mode, or `undefined` if not set
  */
 export declare function getNodeEnv(): string | undefined;

package/dist/env/npm.d.ts

@@ -1,79 +1,77 @@
 /**
- * @fileoverview NPM environment variable getters.
- * Provides access to NPM and package manager environment variables.
+ * @file NPM environment variable getters. Provides access to NPM and package
+ *   manager environment variables.
  */
 /**
- * npm_config_registry environment variable.
- * NPM registry URL configured by package managers.
- *
- * @returns The configured NPM registry URL, or `undefined` if not set
+ * Npm_config_registry environment variable. NPM registry URL configured by
+ * package managers.
  *
  * @example
- * ```typescript
- * import { getNpmConfigRegistry } from '@socketsecurity/lib/env/npm'
+ *   ;```typescript
+ *   import { getNpmConfigRegistry } from '@socketsecurity/lib/env/npm'
+ *
+ *   const registry = getNpmConfigRegistry()
+ *   // e.g. 'https://registry.npmjs.org/' or undefined
+ *   ```
  *
- * const registry = getNpmConfigRegistry()
- * // e.g. 'https://registry.npmjs.org/' or undefined
- * ```
+ * @returns The configured NPM registry URL, or `undefined` if not set
  */
 export declare function getNpmConfigRegistry(): string | undefined;
 /**
- * npm_config_user_agent environment variable.
- * User agent string set by npm/pnpm/yarn package managers.
- *
- * @returns The package manager user agent string, or `undefined` if not set
+ * Npm_config_user_agent environment variable. User agent string set by
+ * npm/pnpm/yarn package managers.
  *
  * @example
- * ```typescript
- * import { getNpmConfigUserAgent } from '@socketsecurity/lib/env/npm'
+ *   ;```typescript
+ *   import { getNpmConfigUserAgent } from '@socketsecurity/lib/env/npm'
+ *
+ *   const ua = getNpmConfigUserAgent()
+ *   // e.g. 'pnpm/9.0.0 npm/? node/v20.0.0 darwin arm64'
+ *   ```
  *
- * const ua = getNpmConfigUserAgent()
- * // e.g. 'pnpm/9.0.0 npm/? node/v20.0.0 darwin arm64'
- * ```
+ * @returns The package manager user agent string, or `undefined` if not set
  */
 export declare function getNpmConfigUserAgent(): string | undefined;
 /**
- * npm_lifecycle_event environment variable.
- * The name of the npm lifecycle event that's currently running.
- *
- * @returns The current lifecycle event name, or `undefined` if not set
+ * Npm_lifecycle_event environment variable. The name of the npm lifecycle event
+ * that's currently running.
  *
  * @example
- * ```typescript
- * import { getNpmLifecycleEvent } from '@socketsecurity/lib/env/npm'
+ *   ;```typescript
+ *   import { getNpmLifecycleEvent } from '@socketsecurity/lib/env/npm'
  *
- * const event = getNpmLifecycleEvent()
- * // e.g. 'install', 'postinstall', or 'test'
- * ```
+ *   const event = getNpmLifecycleEvent()
+ *   // e.g. 'install', 'postinstall', or 'test'
+ *   ```
+ *
+ * @returns The current lifecycle event name, or `undefined` if not set
  */
 export declare function getNpmLifecycleEvent(): string | undefined;
 /**
- * NPM_REGISTRY environment variable.
- * NPM registry URL override.
- *
- * @returns The NPM registry URL override, or `undefined` if not set
+ * NPM_REGISTRY environment variable. NPM registry URL override.
  *
  * @example
- * ```typescript
- * import { getNpmRegistry } from '@socketsecurity/lib/env/npm'
+ *   ;```typescript
+ *   import { getNpmRegistry } from '@socketsecurity/lib/env/npm'
+ *
+ *   const registry = getNpmRegistry()
+ *   // e.g. 'https://registry.npmjs.org/' or undefined
+ *   ```
  *
- * const registry = getNpmRegistry()
- * // e.g. 'https://registry.npmjs.org/' or undefined
- * ```
+ * @returns The NPM registry URL override, or `undefined` if not set
  */
 export declare function getNpmRegistry(): string | undefined;
 /**
- * NPM_TOKEN environment variable.
- * Authentication token for NPM registry access.
- *
- * @returns The NPM auth token, or `undefined` if not set
+ * NPM_TOKEN environment variable. Authentication token for NPM registry access.
  *
  * @example
- * ```typescript
- * import { getNpmToken } from '@socketsecurity/lib/env/npm'
+ *   ;```typescript
+ *   import { getNpmToken } from '@socketsecurity/lib/env/npm'
  *
- * const token = getNpmToken()
- * // e.g. 'npm_abc123...' or undefined
- * ```
+ *   const token = getNpmToken()
+ *   // e.g. 'npm_abc123...' or undefined
+ *   ```
+ *
+ * @returns The NPM auth token, or `undefined` if not set
  */
 export declare function getNpmToken(): string | undefined;

package/dist/env/number.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @file `envAsNumber` — coerce an env-var-shaped value into a number. `mode:
+ *   'int'` uses `parseInt(_, 10)`; `mode: 'float'` uses `Number()`. Non-finite
+ *   results round-trip through `defaultValue` unless `allowInfinity: true` is
+ *   set.
+ */
+import type { EnvAsNumberOptions } from './types';
+/**
+ * Convert an environment variable value to a number.
+ *
+ * Back-compat overload: passing a bare number as the second argument is
+ * equivalent to `{ defaultValue: N }`.
+ *
+ * @example
+ *   ;```typescript
+ *   import { envAsNumber } from '@socketsecurity/lib/env/number'
+ *
+ *   envAsNumber('3000') // 3000 (int mode)
+ *   envAsNumber('3.14', { mode: 'float' }) // 3.14
+ *   envAsNumber('abc') // 0
+ *   envAsNumber(undefined, 42) // 42 (legacy positional default)
+ *   ```
+ *
+ * @param value - The value to convert.
+ * @param defaultValueOrOptions - Default (number) or options object.
+ *
+ * @returns The parsed number, or the default value if parsing fails
+ */
+export declare function envAsNumber(value: unknown, defaultValueOrOptions?: number | EnvAsNumberOptions | undefined): number;

package/dist/env/number.js

@@ -0,0 +1,54 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var number_exports = {};
+__export(number_exports, {
+  envAsNumber: () => envAsNumber
+});
+module.exports = __toCommonJS(number_exports);
+var import_number = require("../primordials/number");
+// @__NO_SIDE_EFFECTS__
+function envAsNumber(value, defaultValueOrOptions = 0) {
+  const opts = typeof defaultValueOrOptions === "number" ? { defaultValue: defaultValueOrOptions } : defaultValueOrOptions ?? {};
+  const { allowInfinity = false, defaultValue = 0, mode = "int" } = opts;
+  if (value === void 0 || value === null) {
+    return defaultValue;
+  }
+  if (typeof value === "string") {
+    if (!value) {
+      return defaultValue;
+    }
+    const num = mode === "float" ? (0, import_number.NumberCtor)(value) : (0, import_number.NumberParseInt)(value, 10);
+    if ((0, import_number.NumberIsNaN)(num)) {
+      return defaultValue;
+    }
+    if (!(0, import_number.NumberIsFinite)(num)) {
+      return allowInfinity ? num : defaultValue;
+    }
+    return num || 0;
+  }
+  const numOrNaN = mode === "float" ? (0, import_number.NumberCtor)(String(value)) : (0, import_number.NumberParseInt)(String(value), 10);
+  const numMayBeNegZero = (0, import_number.NumberIsFinite)(numOrNaN) ? numOrNaN : (0, import_number.NumberCtor)(defaultValue);
+  return numMayBeNegZero || 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  envAsNumber
+});

package/dist/env/package-manager.d.ts

@@ -1,62 +1,65 @@
 /**
- * @fileoverview Package manager environment detection.
- * Provides utilities to detect which package manager (npm/pnpm/yarn/bun) is running.
+ * @file Package manager environment detection. Provides utilities to detect
+ *   which package manager (npm/pnpm/yarn/bun) is running.
  */
 /**
  * Package manager type detected from environment.
  */
-export type PackageManagerType = 'npm' | 'pnpm' | 'yarn' | 'bun' | null;
+export type PackageManagerType = 'npm' | 'pnpm' | 'yarn' | 'bun' | undefined;
 /**
- * Detect which package manager is currently running based on environment variables.
- * Checks npm_config_user_agent which all package managers set.
+ * Detect which package manager is currently running based on environment
+ * variables. Checks npm_config_user_agent which all package managers set.
  *
  * Detection priority:
- * 1. npm_config_user_agent (most reliable, set by all package managers)
- * 2. Binary path analysis (fallback for non-standard environments)
  *
- * @returns The detected package manager or null if unable to determine
+ * 1. Npm_config_user_agent (most reliable, set by all package managers)
+ * 2. Binary path analysis (fallback for non-standard environments)
  *
  * @example
- * ```typescript
- * // During: npm install
- * detectPackageManager() // 'npm'
+ *   ;```typescript
+ *   // During: npm install
+ *   detectPackageManager() // 'npm'
  *
- * // During: pnpm install
- * detectPackageManager() // 'pnpm'
+ *   // During: pnpm install
+ *   detectPackageManager() // 'pnpm'
  *
- * // During: yarn install
- * detectPackageManager() // 'yarn'
+ *   // During: yarn install
+ *   detectPackageManager() // 'yarn'
  *
- * // Outside package manager context
- * detectPackageManager() // null
- * ```
+ *   // Outside package manager context
+ *   detectPackageManager() // undefined
+ *   ```
+ *
+ * @returns The detected package manager or null if unable to determine
  */
 export declare function detectPackageManager(): PackageManagerType;
 /**
  * Get the package manager name and version from user agent.
  *
- * @returns Object with name and version, or null if not available
  * @example
- * ```typescript
- * getPackageManagerInfo()
- * // { name: 'pnpm', version: '8.15.1' }
- * ```
+ *   ;```typescript
+ *   getPackageManagerInfo()
+ *   // { name: 'pnpm', version: '8.15.1' }
+ *   ```
+ *
+ * @returns Object with name and version, or null if not available
  */
 export declare function getPackageManagerInfo(): {
     name: string;
     version: string;
-} | null;
+} | undefined;
 /**
- * Get the package manager user agent from environment.
- * Package managers set npm_config_user_agent with format: "npm/8.19.2 node/v18.12.0 darwin arm64"
+ * Get the package manager user agent from environment. Package managers set
+ * npm_config_user_agent with format: "npm/8.19.2 node/v18.12.0 darwin arm64"
  *
- * @returns The user agent string or undefined
  * @example
- * ```typescript
- * getPackageManagerUserAgent()
- * // npm: "npm/10.2.4 node/v20.11.0 darwin arm64 workspaces/false"
- * // pnpm: "pnpm/8.15.1 npm/? node/v20.11.0 darwin arm64"
- * // yarn: "yarn/1.22.19 npm/? node/v20.11.0 darwin arm64"
- * ```
+ *   ;```typescript
+ *   getPackageManagerUserAgent()
+ *   // npm: "npm/10.2.4 node/v20.11.0 darwin arm64 workspaces/false"
+ *   // pnpm: "pnpm/8.15.1 npm/? node/v20.11.0 darwin arm64"
+ *   // yarn: "yarn/1.22.19 npm/? node/v20.11.0 darwin arm64"
+ *   ```
+ *
+ * @returns The user agent string or undefined
  */
 export declare function getPackageManagerUserAgent(): string | undefined;

package/dist/env/package-manager.js

@@ -61,13 +61,13 @@ function detectPackageManager() {
       return "npm";
     }
   }
-  return null;
+  return void 0;
 }
 // @__NO_SIDE_EFFECTS__
 function getPackageManagerInfo() {
   const userAgent = /* @__PURE__ */ getPackageManagerUserAgent();
   if (!userAgent) {
-    return null;
+    return void 0;
   }
   const match = userAgent.match(/^([^/]+)\/([^\s]+)/);
   if (match?.[1] && match[2]) {
@@ -76,7 +76,7 @@ function getPackageManagerInfo() {
       version: match[2]
     };
   }
-  return null;
+  return void 0;
 }
 // @__NO_SIDE_EFFECTS__
 function getPackageManagerUserAgent() {

package/dist/env/path.d.ts

@@ -1,19 +1,19 @@
 /**
- * @fileoverview PATH environment variable getter.
- * Exports `getPath()`, returning the raw value of the `PATH` environment
- * variable that lists executable search directories.
+ * @file PATH environment variable getter. Exports `getPath()`, returning the
+ *   raw value of the `PATH` environment variable that lists executable search
+ *   directories.
  */
 /**
  * Returns the value of the PATH environment variable.
  *
- * @returns The system executable search paths, or `undefined` if not set
- *
  * @example
- * ```typescript
- * import { getPath } from '@socketsecurity/lib/env/path'
+ *   ;```typescript
+ *   import { getPath } from '@socketsecurity/lib/env/path'
  *
- * const path = getPath()
- * // e.g. '/usr/local/bin:/usr/bin:/bin' or undefined
- * ```
+ *   const path = getPath()
+ *   // e.g. '/usr/local/bin:/usr/bin:/bin' or undefined
+ *   ```
+ *
+ * @returns The system executable search paths, or `undefined` if not set
  */
 export declare function getPath(): string | undefined;

package/dist/env/pre-commit.d.ts

@@ -1,20 +1,20 @@
 /**
- * @fileoverview PRE_COMMIT environment variable getter.
- * Exports `getPreCommit()`, a boolean coercion of `PRE_COMMIT` used to
- * detect when code is running inside a pre-commit hook.
+ * @file PRE_COMMIT environment variable getter. Exports `getPreCommit()`, a
+ *   boolean coercion of `PRE_COMMIT` used to detect when code is running inside
+ *   a pre-commit hook.
  */
 /**
  * Returns whether the PRE_COMMIT environment variable is set to a truthy value.
  *
- * @returns `true` if running in a pre-commit hook, `false` otherwise
- *
  * @example
- * ```typescript
- * import { getPreCommit } from '@socketsecurity/lib/env/pre-commit'
+ *   ;```typescript
+ *   import { getPreCommit } from '@socketsecurity/lib/env/pre-commit'
  *
- * if (getPreCommit()) {
- *   console.log('Running in pre-commit hook')
- * }
- * ```
+ *   if (getPreCommit()) {
+ *     console.log('Running in pre-commit hook')
+ *   }
+ *   ```
+ *
+ * @returns `true` if running in a pre-commit hook, `false` otherwise
  */
 export declare function getPreCommit(): boolean;

package/dist/env/pre-commit.js

@@ -23,11 +23,11 @@ __export(pre_commit_exports, {
   getPreCommit: () => getPreCommit
 });
 module.exports = __toCommonJS(pre_commit_exports);
-var import_helpers = require("./helpers");
+var import_boolean = require("./boolean");
 var import_rewire = require("./rewire");
 // @__NO_SIDE_EFFECTS__
 function getPreCommit() {
-  return (0, import_helpers.envAsBoolean)((0, import_rewire.getEnvValue)("PRE_COMMIT"));
+  return (0, import_boolean.envAsBoolean)((0, import_rewire.getEnvValue)("PRE_COMMIT"));
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/env/proxy.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @file `createEnvProxy` — wrap `process.env` (or any env-like record) in a
+ *   Proxy that adds case-insensitive lookups for known-Windows-sensitive keys
+ *   (PATH, APPDATA, etc.) and an `overrides` layer. Intended for cross-platform
+ *   test harnesses and child-process spawn env normalization.
+ */
+/**
+ * Create a case-insensitive environment variable Proxy for Windows
+ * compatibility. On Windows, environment variables are case-insensitive (PATH
+ * vs Path vs path). This Proxy provides consistent access regardless of case,
+ * with priority given to exact matches, then case-insensitive matches for known
+ * vars.
+ *
+ * **Use Cases:**
+ *
+ * - Cross-platform test environments needing consistent env var access
+ * - Windows compatibility when passing env to child processes
+ * - Merging environment overrides while preserving case-insensitive lookups
+ *
+ * **Performance Note:** Proxy operations have runtime overhead. Only use when
+ * Windows case-insensitive access is required. For most use cases, process.env
+ * directly is sufficient.
+ *
+ * @example
+ *   // Create a Proxy with overrides
+ *   const env = createEnvProxy(process.env, { NODE_ENV: 'test' })
+ *   console.log(env.PATH) // Works with any case: PATH, Path, path
+ *   console.log(env.NODE_ENV) // 'test'
+ *
+ * @example
+ *   // Pass to child process spawn
+ *   import { createEnvProxy } from '@socketsecurity/lib/env/proxy'
+ *   import { spawn } from '@socketsecurity/lib/spawn'
+ *
+ *   spawn('node', ['script.js'], {
+ *     env: createEnvProxy(process.env, { NODE_ENV: 'test' }),
+ *   })
+ *
+ * @param base - Base environment object (usually process.env)
+ * @param overrides - Optional overrides to merge.
+ *
+ * @returns Proxy that handles case-insensitive env var access
+ */
+export declare function createEnvProxy(base: NodeJS.ProcessEnv, overrides?: Record<string, string | undefined>): NodeJS.ProcessEnv;