@socketsecurity/lib 6.0.3 → 6.0.5

package/dist/env/pre-commit.js

@@ -1,35 +1,33 @@
 "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 pre_commit_exports = {};
-__export(pre_commit_exports, {
-  getPreCommit: () => getPreCommit
-});
-module.exports = __toCommonJS(pre_commit_exports);
-var import_boolean = require("./boolean");
-var import_rewire = require("./rewire");
-// @__NO_SIDE_EFFECTS__
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_env_boolean = require('./boolean.js');
+const require_env_rewire = require('./rewire.js');
+
+//#region src/env/pre-commit.ts
+/**
+* @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.
+*
+* @example
+*   ;```typescript
+*   import { getPreCommit } from '@socketsecurity/lib/env/pre-commit'
+*
+*   if (getPreCommit()) {
+*     console.log('Running in pre-commit hook')
+*   }
+*   ```
+*
+* @returns `true` if running in a pre-commit hook, `false` otherwise
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function getPreCommit() {
-  return (0, import_boolean.envAsBoolean)((0, import_rewire.getEnvValue)("PRE_COMMIT"));
+	return /* @__PURE__ */ require_env_boolean.envAsBoolean(require_env_rewire.getEnvValue("PRE_COMMIT"));
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  getPreCommit
-});
+
+//#endregion
+exports.getPreCommit = getPreCommit;

package/dist/env/proxy.js

@@ -1,126 +1,125 @@
 "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"
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_map_set = require('../primordials/map-set.js');
+const require_primordials_object = require('../primordials/object.js');
+const require_primordials_globals = require('../primordials/globals.js');
+const require_env_case_insensitive = require('./case-insensitive.js');
+
+//#region src/env/proxy.ts
+/**
+* @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.
+*/
+const caseInsensitiveKeys = new require_primordials_map_set.SetCtor([
+	"APPDATA",
+	"COMSPEC",
+	"HOME",
+	"LOCALAPPDATA",
+	"PATH",
+	"PATHEXT",
+	"PROGRAMFILES",
+	"SYSTEMROOT",
+	"TEMP",
+	"TMP",
+	"USERPROFILE",
+	"WINDIR"
 ]);
+/**
+* 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
+*/
 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;
-    }
-  });
+	function lookupEnvValue(prop) {
+		if (overrides && prop in overrides) return overrides[prop];
+		if (prop in base) return base[prop];
+		/* c8 ignore start */
+		const upperProp = prop.toUpperCase();
+		if (caseInsensitiveKeys.has(upperProp)) {
+			if (overrides) {
+				const key = require_env_case_insensitive.findCaseInsensitiveEnvKey(overrides, upperProp);
+				if (key !== void 0) return overrides[key];
+			}
+			const key = require_env_case_insensitive.findCaseInsensitiveEnvKey(base, upperProp);
+			if (key !== void 0) return base[key];
+		}
+	}
+	/* c8 ignore stop */
+	return new require_primordials_globals.ProxyCtor({}, {
+		get(_target, prop) {
+			if (typeof prop !== "string") return;
+			return lookupEnvValue(prop);
+		},
+		ownKeys(_target) {
+			return [...new Set([...require_primordials_object.ObjectKeys(base), ...overrides ? require_primordials_object.ObjectKeys(overrides) : []])];
+		},
+		getOwnPropertyDescriptor(_target, prop) {
+			if (typeof prop !== "string") return;
+			const value = lookupEnvValue(prop);
+			return value !== void 0 ? {
+				enumerable: true,
+				configurable: true,
+				writable: true,
+				value
+			} : void 0;
+		},
+		has(_target, prop) {
+			/* c8 ignore start */
+			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 && require_env_case_insensitive.findCaseInsensitiveEnvKey(overrides, upperProp) !== void 0) return true;
+				if (require_env_case_insensitive.findCaseInsensitiveEnvKey(base, upperProp) !== void 0) return true;
+			}
+			return false;
+			/* c8 ignore stop */
+		},
+		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
-});
+
+//#endregion
+exports.createEnvProxy = createEnvProxy;

package/dist/env/rewire.js

@@ -1,120 +1,228 @@
 "use strict";
-/* Socket Lib - Built with esbuild */
-"use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var rewire_exports = {};
-__export(rewire_exports, {
-  clearEnv: () => clearEnv,
-  getAsyncHooks: () => getAsyncHooks,
-  getEnvValue: () => getEnvValue,
-  hasOverride: () => hasOverride,
-  isInEnv: () => isInEnv,
-  resetEnv: () => resetEnv,
-  setEnv: () => setEnv,
-  withEnv: () => withEnv,
-  withEnvSync: () => withEnvSync
-});
-module.exports = __toCommonJS(rewire_exports);
-var import_node_process = __toESM(require("node:process"));
-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");
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_runtime = require('../_virtual/_rolldown/runtime.js');
+const require_primordials_map_set = require('../primordials/map-set.js');
+const require_primordials_object = require('../primordials/object.js');
+const require_objects_predicates = require('../objects/predicates.js');
+const require_env_boolean = require('./boolean.js');
+let node_process = require("node:process");
+node_process = require_runtime.__toESM(node_process);
+
+//#region src/env/rewire.ts
+/**
+* @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
+*/
 let _async_hooks;
-// @__NO_SIDE_EFFECTS__
+/**
+* Lazily load the async_hooks module to avoid Webpack errors.
+*
+* @private
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function getAsyncHooks() {
-  if (_async_hooks === void 0) {
-    _async_hooks = require("node:async_hooks");
-  }
-  return _async_hooks;
+	if (_async_hooks === void 0) _async_hooks = /* @__PURE__ */ require("node:async_hooks");
+	return _async_hooks;
 }
 const { AsyncLocalStorage } = /* @__PURE__ */ getAsyncHooks();
 const isolatedOverridesStorage = new AsyncLocalStorage();
-const sharedOverridesSymbol = Symbol.for(
-  "@socketsecurity/lib/env/rewire/test-overrides"
-);
+const sharedOverridesSymbol = Symbol.for("@socketsecurity/lib/env/rewire/test-overrides");
 const _globalThis = globalThis;
-const isVitestEnv = (0, import_boolean.envAsBoolean)(import_node_process.default.env["VITEST"]);
-if (isVitestEnv && !_globalThis[sharedOverridesSymbol]) {
-  _globalThis[sharedOverridesSymbol] = new import_map_set.MapCtor();
-}
+if (/* @__PURE__ */ require_env_boolean.envAsBoolean(node_process.default.env["VITEST"]) && !_globalThis[sharedOverridesSymbol]) _globalThis[sharedOverridesSymbol] = new require_primordials_map_set.MapCtor();
 const sharedOverrides = _globalThis[sharedOverridesSymbol];
+/**
+* Clear a specific environment variable override.
+*
+* @example
+*   ;```typescript
+*   import { setEnv, clearEnv } from '@socketsecurity/lib/env/rewire'
+*
+*   setEnv('CI', '1')
+*   clearEnv('CI')
+*   ```
+*
+* @param key - The environment variable name to clear.
+*/
 function clearEnv(key) {
-  sharedOverrides?.delete(key);
+	sharedOverrides?.delete(key);
 }
+/**
+* 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)
+*
+* @example
+*   ;```typescript
+*   import { getEnvValue } from '@socketsecurity/lib/env/rewire'
+*
+*   const value = getEnvValue('NODE_ENV')
+*   // e.g. 'production' or undefined
+*   ```
+*
+* @internal Used by env getters to support test rewiring
+*/
 function getEnvValue(key) {
-  const isolatedOverrides = isolatedOverridesStorage.getStore();
-  if (isolatedOverrides?.has(key)) {
-    return isolatedOverrides.get(key);
-  }
-  if (sharedOverrides?.has(key)) {
-    return sharedOverrides.get(key);
-  }
-  return import_node_process.default.env[key];
+	const isolatedOverrides = isolatedOverridesStorage.getStore();
+	if (isolatedOverrides?.has(key)) return isolatedOverrides.get(key);
+	if (sharedOverrides?.has(key)) return sharedOverrides.get(key);
+	return node_process.default.env[key];
 }
+/**
+* Check if an environment variable has been overridden.
+*
+* @example
+*   ;```typescript
+*   import { setEnv, hasOverride } from '@socketsecurity/lib/env/rewire'
+*
+*   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
+*/
 function hasOverride(key) {
-  const isolatedOverrides = isolatedOverridesStorage.getStore();
-  return !!(isolatedOverrides?.has(key) || sharedOverrides?.has(key));
+	return !!(isolatedOverridesStorage.getStore()?.has(key) || sharedOverrides?.has(key));
 }
+/**
+* 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)
+*
+* @example
+*   ;```typescript
+*   import { isInEnv } from '@socketsecurity/lib/env/rewire'
+*
+*   isInEnv('PATH') // true (usually set)
+*   isInEnv('MISSING') // false
+*   ```
+*
+* @internal Used by env getters to check for key presence (not value truthiness)
+*/
 function isInEnv(key) {
-  const isolatedOverrides = isolatedOverridesStorage.getStore();
-  if (isolatedOverrides?.has(key)) {
-    return true;
-  }
-  if (sharedOverrides?.has(key)) {
-    return true;
-  }
-  return (0, import_predicates.hasOwn)(import_node_process.default.env, key);
+	if (isolatedOverridesStorage.getStore()?.has(key)) return true;
+	if (sharedOverrides?.has(key)) return true;
+	return /* @__PURE__ */ require_objects_predicates.hasOwn(node_process.default.env, key);
 }
+/**
+* Clear all environment variable overrides. Useful in afterEach hooks to ensure
+* clean test state.
+*
+* @example
+*   ;```typescript
+*   import { resetEnv } from './rewire'
+*
+*   afterEach(() => {
+*     resetEnv()
+*   })
+*   ```
+*/
 function resetEnv() {
-  sharedOverrides?.clear();
+	sharedOverrides?.clear();
 }
+/**
+* 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)
+*   })
+*   ```
+*/
 function setEnv(key, value) {
-  sharedOverrides?.set(key, value);
+	sharedOverrides?.set(key, value);
 }
+/**
+* Run code with environment overrides in an isolated AsyncLocalStorage context.
+* Creates true context isolation - overrides don't leak to concurrent code.
+*
+* Useful for tests that need temporary overrides without affecting other tests
+* or for nested override scenarios.
+*
+* @example
+*   ;```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
+*   ```
+*
+* @example
+*   ;```typescript
+*   // Nested overrides work correctly
+*   setEnv('CI', '1') // Shared override (persistent)
+*
+*   await withEnv({ CI: '0' }, async () => {
+*     expect(getCI()).toBe(false) // Isolated override takes precedence
+*   })
+*
+*   expect(getCI()).toBe(true) // Back to shared override
+*   ```
+*/
 async function withEnv(overrides, fn) {
-  const map = new import_map_set.MapCtor((0, import_object.ObjectEntries)(overrides));
-  return await isolatedOverridesStorage.run(map, fn);
+	const map = new require_primordials_map_set.MapCtor(require_primordials_object.ObjectEntries(overrides));
+	return await isolatedOverridesStorage.run(map, fn);
 }
+/**
+* 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)
+*   ```
+*/
 function withEnvSync(overrides, fn) {
-  const map = new import_map_set.MapCtor((0, import_object.ObjectEntries)(overrides));
-  return isolatedOverridesStorage.run(map, fn);
+	const map = new require_primordials_map_set.MapCtor(require_primordials_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,
-  resetEnv,
-  setEnv,
-  withEnv,
-  withEnvSync
-});
+
+//#endregion
+exports.clearEnv = clearEnv;
+exports.getAsyncHooks = getAsyncHooks;
+exports.getEnvValue = getEnvValue;
+exports.hasOverride = hasOverride;
+exports.isInEnv = isInEnv;
+exports.resetEnv = resetEnv;
+exports.setEnv = setEnv;
+exports.withEnv = withEnv;
+exports.withEnvSync = withEnvSync;