@socketsecurity/lib 5.28.0 → 6.0.1

package/dist/env/proxy.js

@@ -0,0 +1,126 @@
+"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 proxy_exports = {};
+__export(proxy_exports, {
+  createEnvProxy: () => createEnvProxy
+});
+module.exports = __toCommonJS(proxy_exports);
+var import_globals = require("../primordials/globals");
+var import_map_set = require("../primordials/map-set");
+var import_object = require("../primordials/object");
+var import_case_insensitive = require("./case-insensitive");
+const caseInsensitiveKeys = new import_map_set.SetCtor([
+  "APPDATA",
+  "COMSPEC",
+  "HOME",
+  "LOCALAPPDATA",
+  "PATH",
+  "PATHEXT",
+  "PROGRAMFILES",
+  "SYSTEMROOT",
+  "TEMP",
+  "TMP",
+  "USERPROFILE",
+  "WINDIR"
+]);
+function createEnvProxy(base, overrides) {
+  function lookupEnvValue(prop) {
+    if (overrides && prop in overrides) {
+      return overrides[prop];
+    }
+    if (prop in base) {
+      return base[prop];
+    }
+    const upperProp = prop.toUpperCase();
+    if (caseInsensitiveKeys.has(upperProp)) {
+      if (overrides) {
+        const key2 = (0, import_case_insensitive.findCaseInsensitiveEnvKey)(overrides, upperProp);
+        if (key2 !== void 0) {
+          return overrides[key2];
+        }
+      }
+      const key = (0, import_case_insensitive.findCaseInsensitiveEnvKey)(base, upperProp);
+      if (key !== void 0) {
+        return base[key];
+      }
+    }
+    return void 0;
+  }
+  return new import_globals.ProxyCtor({}, {
+    get(_target, prop) {
+      if (typeof prop !== "string") {
+        return void 0;
+      }
+      return lookupEnvValue(prop);
+    },
+    ownKeys(_target) {
+      const keys = /* @__PURE__ */ new Set([
+        ...(0, import_object.ObjectKeys)(base),
+        ...overrides ? (0, import_object.ObjectKeys)(overrides) : []
+      ]);
+      return [...keys];
+    },
+    getOwnPropertyDescriptor(_target, prop) {
+      if (typeof prop !== "string") {
+        return void 0;
+      }
+      const value = lookupEnvValue(prop);
+      return value !== void 0 ? {
+        enumerable: true,
+        configurable: true,
+        writable: true,
+        value
+      } : void 0;
+    },
+    has(_target, prop) {
+      if (typeof prop !== "string") {
+        return false;
+      }
+      if (overrides && prop in overrides) {
+        return true;
+      }
+      if (prop in base) {
+        return true;
+      }
+      const upperProp = prop.toUpperCase();
+      if (caseInsensitiveKeys.has(upperProp)) {
+        if (overrides && (0, import_case_insensitive.findCaseInsensitiveEnvKey)(overrides, upperProp) !== void 0) {
+          return true;
+        }
+        if ((0, import_case_insensitive.findCaseInsensitiveEnvKey)(base, upperProp) !== void 0) {
+          return true;
+        }
+      }
+      return false;
+    },
+    set(_target, prop, value) {
+      if (typeof prop === "string" && overrides) {
+        overrides[prop] = value;
+        return true;
+      }
+      return false;
+    }
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createEnvProxy
+});

package/dist/env/rewire.d.ts

@@ -1,119 +1,125 @@
 /**
- * @fileoverview Environment variable rewiring utilities for testing.
- * Uses AsyncLocalStorage for context-isolated overrides that work with concurrent tests.
- *
- * Features:
- * - Context-isolated overrides via withEnv() for advanced use cases
- * - Test-friendly setEnv/clearEnv/resetEnv that work in beforeEach/afterEach
- * - Compatible with vi.stubEnv() - reads from process.env as final fallback
- * - Thread-safe for concurrent test execution
+ * @file Environment variable rewiring utilities for testing. Uses
+ *   AsyncLocalStorage for context-isolated overrides that work with concurrent
+ *   tests. Features:
+ *
+ *   - Context-isolated overrides via withEnv() for advanced use cases
+ *   - Test-friendly setEnv/clearEnv/resetEnv that work in beforeEach/afterEach
+ *   - Compatible with vi.stubEnv() - reads from process.env as final fallback
+ *   - Thread-safe for concurrent test execution
  */
 /**
- * Clear a specific environment variable override.
+ * Lazily load the async_hooks module to avoid Webpack errors.
  *
- * @param key - The environment variable name to clear
+ * @private
+ */
+export declare function getAsyncHooks(): typeof import('node:async_hooks');
+/**
+ * Clear a specific environment variable override.
  *
  * @example
- * ```typescript
- * import { setEnv, clearEnv } from '@socketsecurity/lib/env/rewire'
+ *   ;```typescript
+ *   import { setEnv, clearEnv } from '@socketsecurity/lib/env/rewire'
+ *
+ *   setEnv('CI', '1')
+ *   clearEnv('CI')
+ *   ```
  *
- * setEnv('CI', '1')
- * clearEnv('CI')
- * ```
+ * @param key - The environment variable name to clear.
  */
 export declare function clearEnv(key: string): void;
 /**
  * Get an environment variable value, checking overrides first.
  *
- * Resolution order:
- * 1. Isolated overrides (temporary - set via withEnv/withEnvSync)
- * 2. Shared overrides (persistent - set via setEnv in beforeEach)
- * 3. process.env (including vi.stubEnv modifications)
- *
- * @internal Used by env getters to support test rewiring
+ * Resolution order: 1. Isolated overrides (temporary - set via
+ * withEnv/withEnvSync) 2. Shared overrides (persistent - set via setEnv in
+ * beforeEach) 3. process.env (including vi.stubEnv modifications)
  *
  * @example
- * ```typescript
- * import { getEnvValue } from '@socketsecurity/lib/env/rewire'
+ *   ;```typescript
+ *   import { getEnvValue } from '@socketsecurity/lib/env/rewire'
+ *
+ *   const value = getEnvValue('NODE_ENV')
+ *   // e.g. 'production' or undefined
+ *   ```
  *
- * const value = getEnvValue('NODE_ENV')
- * // e.g. 'production' or undefined
- * ```
+ * @internal Used by env getters to support test rewiring
  */
 export declare function getEnvValue(key: string): string | undefined;
 /**
  * Check if an environment variable has been overridden.
  *
- * @param key - The environment variable name to check
- * @returns `true` if the variable has been overridden, `false` otherwise
- *
  * @example
- * ```typescript
- * import { setEnv, hasOverride } from '@socketsecurity/lib/env/rewire'
+ *   ;```typescript
+ *   import { setEnv, hasOverride } from '@socketsecurity/lib/env/rewire'
  *
- * hasOverride('CI')  // false
- * setEnv('CI', '1')
- * hasOverride('CI')  // true
- * ```
+ *   hasOverride('CI') // false
+ *   setEnv('CI', '1')
+ *   hasOverride('CI') // true
+ *   ```
+ *
+ * @param key - The environment variable name to check.
+ *
+ * @returns `true` if the variable has been overridden, `false` otherwise
  */
 export declare function hasOverride(key: string): boolean;
 /**
- * Check if an environment variable exists (has a key), checking overrides first.
- *
- * Resolution order:
- * 1. Isolated overrides (temporary - set via withEnv/withEnvSync)
- * 2. Shared overrides (persistent - set via setEnv in beforeEach)
- * 3. process.env (including vi.stubEnv modifications)
+ * Check if an environment variable exists (has a key), checking overrides
+ * first.
  *
- * @internal Used by env getters to check for key presence (not value truthiness)
+ * Resolution order: 1. Isolated overrides (temporary - set via
+ * withEnv/withEnvSync) 2. Shared overrides (persistent - set via setEnv in
+ * beforeEach) 3. process.env (including vi.stubEnv modifications)
  *
  * @example
- * ```typescript
- * import { isInEnv } from '@socketsecurity/lib/env/rewire'
+ *   ;```typescript
+ *   import { isInEnv } from '@socketsecurity/lib/env/rewire'
  *
- * isInEnv('PATH')     // true (usually set)
- * isInEnv('MISSING')  // false
- * ```
+ *   isInEnv('PATH') // true (usually set)
+ *   isInEnv('MISSING') // false
+ *   ```
+ *
+ * @internal Used by env getters to check for key presence (not value truthiness)
  */
 export declare function isInEnv(key: string): boolean;
 /**
- * Clear all environment variable overrides.
- * Useful in afterEach hooks to ensure clean test state.
+ * Clear all environment variable overrides. Useful in afterEach hooks to ensure
+ * clean test state.
  *
  * @example
- * ```typescript
- * import { resetEnv } from './rewire'
+ *   ;```typescript
+ *   import { resetEnv } from './rewire'
  *
- * afterEach(() => {
- *   resetEnv()
- * })
- * ```
+ *   afterEach(() => {
+ *     resetEnv()
+ *   })
+ *   ```
  */
 export declare function resetEnv(): void;
 /**
- * Set an environment variable override for testing.
- * This does not modify process.env, only affects env getters.
+ * Set an environment variable override for testing. This does not modify
+ * process.env, only affects env getters.
  *
  * Works in test hooks (beforeEach) without needing AsyncLocalStorage context.
  * Vitest's module isolation ensures each test file has independent overrides.
  *
  * @example
- * ```typescript
- * import { setEnv, resetEnv } from './rewire'
- * import { getCI } from './ci'
- *
- * beforeEach(() => {
- *   setEnv('CI', '1')
- * })
- *
- * afterEach(() => {
- *   resetEnv()
- * })
- *
- * it('should detect CI environment', () => {
- *   expect(getCI()).toBe(true)
- * })
- * ```
+ *   ;```typescript
+ *   import { setEnv, resetEnv } from './rewire'
+ *   import { getCI } from './ci'
+ *
+ *   beforeEach(() => {
+ *     setEnv('CI', '1')
+ *   })
+ *
+ *   afterEach(() => {
+ *     resetEnv()
+ *   })
+ *
+ *   it('should detect CI environment', () => {
+ *     expect(getCI()).toBe(true)
+ *   })
+ *   ```
  */
 export declare function setEnv(key: string, value: string | undefined): void;
 /**
@@ -124,42 +130,42 @@ export declare function setEnv(key: string, value: string | undefined): void;
  * or for nested override scenarios.
  *
  * @example
- * ```typescript
- * import { withEnv } from './rewire'
- * import { getCI } from './ci'
+ *   ;```typescript
+ *   import { withEnv } from './rewire'
+ *   import { getCI } from './ci'
  *
- * // Temporary override in isolated context
- * await withEnv({ CI: '1' }, async () => {
- *   expect(getCI()).toBe(true)
- * })
- * expect(getCI()).toBe(false) // Override is gone
- * ```
+ *   // Temporary override in isolated context
+ *   await withEnv({ CI: '1' }, async () => {
+ *     expect(getCI()).toBe(true)
+ *   })
+ *   expect(getCI()).toBe(false) // Override is gone
+ *   ```
  *
  * @example
- * ```typescript
- * // Nested overrides work correctly
- * setEnv('CI', '1') // Shared override (persistent)
+ *   ;```typescript
+ *   // Nested overrides work correctly
+ *   setEnv('CI', '1') // Shared override (persistent)
  *
- * await withEnv({ CI: '0' }, async () => {
- *   expect(getCI()).toBe(false) // Isolated override takes precedence
- * })
+ *   await withEnv({ CI: '0' }, async () => {
+ *     expect(getCI()).toBe(false) // Isolated override takes precedence
+ *   })
  *
- * expect(getCI()).toBe(true) // Back to shared override
- * ```
+ *   expect(getCI()).toBe(true) // Back to shared override
+ *   ```
  */
 export declare function withEnv<T>(overrides: Record<string, string | undefined>, fn: () => T | Promise<T>): Promise<T>;
 /**
  * Synchronous version of withEnv for non-async code.
  *
  * @example
- * ```typescript
- * import { withEnvSync } from './rewire'
- * import { getCI } from './ci'
- *
- * const result = withEnvSync({ CI: '1' }, () => {
- *   return getCI()
- * })
- * expect(result).toBe(true)
- * ```
+ *   ;```typescript
+ *   import { withEnvSync } from './rewire'
+ *   import { getCI } from './ci'
+ *
+ *   const result = withEnvSync({ CI: '1' }, () => {
+ *     return getCI()
+ *   })
+ *   expect(result).toBe(true)
+ *   ```
  */
 export declare function withEnvSync<T>(overrides: Record<string, string | undefined>, fn: () => T): T;

package/dist/env/rewire.js

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var rewire_exports = {};
 __export(rewire_exports, {
   clearEnv: () => clearEnv,
+  getAsyncHooks: () => getAsyncHooks,
   getEnvValue: () => getEnvValue,
   hasOverride: () => hasOverride,
   isInEnv: () => isInEnv,
@@ -41,9 +42,10 @@ __export(rewire_exports, {
 });
 module.exports = __toCommonJS(rewire_exports);
 var import_node_process = __toESM(require("node:process"));
-var import_objects = require("../objects");
-var import_helpers = require("./helpers");
-var import_primordials = require("../primordials");
+var import_predicates = require("../objects/predicates");
+var import_boolean = require("./boolean");
+var import_map_set = require("../primordials/map-set");
+var import_object = require("../primordials/object");
 let _async_hooks;
 // @__NO_SIDE_EFFECTS__
 function getAsyncHooks() {
@@ -58,9 +60,9 @@ const sharedOverridesSymbol = Symbol.for(
   "@socketsecurity/lib/env/rewire/test-overrides"
 );
 const _globalThis = globalThis;
-const isVitestEnv = (0, import_helpers.envAsBoolean)(import_node_process.default.env["VITEST"]);
+const isVitestEnv = (0, import_boolean.envAsBoolean)(import_node_process.default.env["VITEST"]);
 if (isVitestEnv && !_globalThis[sharedOverridesSymbol]) {
-  _globalThis[sharedOverridesSymbol] = new import_primordials.MapCtor();
+  _globalThis[sharedOverridesSymbol] = new import_map_set.MapCtor();
 }
 const sharedOverrides = _globalThis[sharedOverridesSymbol];
 function clearEnv(key) {
@@ -88,7 +90,7 @@ function isInEnv(key) {
   if (sharedOverrides?.has(key)) {
     return true;
   }
-  return (0, import_objects.hasOwn)(import_node_process.default.env, key);
+  return (0, import_predicates.hasOwn)(import_node_process.default.env, key);
 }
 function resetEnv() {
   sharedOverrides?.clear();
@@ -97,16 +99,17 @@ function setEnv(key, value) {
   sharedOverrides?.set(key, value);
 }
 async function withEnv(overrides, fn) {
-  const map = new import_primordials.MapCtor((0, import_primordials.ObjectEntries)(overrides));
+  const map = new import_map_set.MapCtor((0, import_object.ObjectEntries)(overrides));
   return await isolatedOverridesStorage.run(map, fn);
 }
 function withEnvSync(overrides, fn) {
-  const map = new import_primordials.MapCtor((0, import_primordials.ObjectEntries)(overrides));
+  const map = new import_map_set.MapCtor((0, import_object.ObjectEntries)(overrides));
   return isolatedOverridesStorage.run(map, fn);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   clearEnv,
+  getAsyncHooks,
   getEnvValue,
   hasOverride,
   isInEnv,

package/dist/env/shell.d.ts

@@ -1,19 +1,19 @@
 /**
- * @fileoverview SHELL environment variable getter.
- * Exports `getShell()`, returning the Unix/macOS `SHELL` path (for example
- * `/bin/zsh`) or `undefined` when the variable is unset.
+ * @file SHELL environment variable getter. Exports `getShell()`, returning the
+ *   Unix/macOS `SHELL` path (for example `/bin/zsh`) or `undefined` when the
+ *   variable is unset.
  */
 /**
  * Returns the value of the SHELL environment variable.
  *
- * @returns The user's default shell path, or `undefined` if not set
- *
  * @example
- * ```typescript
- * import { getShell } from '@socketsecurity/lib/env/shell'
+ *   ;```typescript
+ *   import { getShell } from '@socketsecurity/lib/env/shell'
  *
- * const shell = getShell()
- * // e.g. '/bin/zsh' or '/bin/bash'
- * ```
+ *   const shell = getShell()
+ *   // e.g. '/bin/zsh' or '/bin/bash'
+ *   ```
+ *
+ * @returns The user's default shell path, or `undefined` if not set
  */
 export declare function getShell(): string | undefined;