@socketsecurity/lib 5.28.0 → 6.0.0

package/dist/debug.js

@@ -1,337 +0,0 @@
-"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 debug_exports = {};
-__export(debug_exports, {
-  debug: () => debug,
-  debugCache: () => debugCache,
-  debugCacheNs: () => debugCacheNs,
-  debugDir: () => debugDir,
-  debugDirNs: () => debugDirNs,
-  debugLog: () => debugLog,
-  debugLogNs: () => debugLogNs,
-  debugNs: () => debugNs,
-  debuglog: () => debuglog,
-  debugtime: () => debugtime,
-  isDebug: () => isDebug,
-  isDebugNs: () => isDebugNs
-});
-module.exports = __toCommonJS(debug_exports);
-var import_debug = require("./env/debug");
-var import_socket = require("./env/socket");
-var import_is_unicode_supported = __toESM(require("./external/@socketregistry/is-unicode-supported"));
-var import_debug2 = __toESM(require("./external/debug"));
-var import_logger = require("./logger");
-var import_objects = require("./objects");
-var import_primordials = require("./primordials");
-var import_spinner = require("./spinner");
-var import_strings = require("./strings");
-const logger = (0, import_logger.getDefaultLogger)();
-const debugByNamespace = new import_primordials.MapCtor();
-let _util;
-let pointingTriangle;
-// @__NO_SIDE_EFFECTS__
-function customLog(...args) {
-  const util = /* @__PURE__ */ getUtil();
-  const inspectOpts = import_debug2.default.inspectOpts ? {
-    ...import_debug2.default.inspectOpts,
-    showHidden: import_debug2.default.inspectOpts.showHidden === null ? void 0 : import_debug2.default.inspectOpts.showHidden,
-    depth: import_debug2.default.inspectOpts.depth === null || typeof import_debug2.default.inspectOpts.depth === "boolean" ? void 0 : import_debug2.default.inspectOpts.depth
-  } : {};
-  (0, import_primordials.ReflectApply)(logger.info, logger, [
-    util.formatWithOptions(inspectOpts, ...args)
-  ]);
-}
-// @__NO_SIDE_EFFECTS__
-function extractOptions(namespaces) {
-  return namespaces !== null && typeof namespaces === "object" ? { __proto__: null, ...namespaces } : { __proto__: null, namespaces };
-}
-// @__NO_SIDE_EFFECTS__
-function getCallerInfo(stackOffset = 3) {
-  let name = "";
-  const captureStackTrace = Error.captureStackTrace;
-  if (typeof captureStackTrace === "function") {
-    const obj = {};
-    captureStackTrace(obj, getCallerInfo);
-    const stack = obj.stack;
-    if (typeof stack === "string") {
-      let lineCount = 0;
-      let lineStart = 0;
-      for (let i = 0, { length } = stack; i < length; i += 1) {
-        if (stack[i] === "\n") {
-          lineCount += 1;
-          if (lineCount < stackOffset) {
-            lineStart = i + 1;
-          } else {
-            const line = stack.slice(lineStart, i).trimStart();
-            const match = /(?<=^at\s+).*?(?=\s+\(|$)/.exec(line)?.[0];
-            if (match) {
-              name = match.replace(/^(?:async|bound|get|new|set)\s+/, "");
-              if ((0, import_primordials.StringPrototypeStartsWith)(name, "Object.")) {
-                const afterDot = (0, import_primordials.StringPrototypeSlice)(name, 7);
-                if (!(0, import_objects.hasOwn)(Object, afterDot)) {
-                  name = afterDot;
-                }
-              }
-            }
-            break;
-          }
-        }
-      }
-    }
-  }
-  return name;
-}
-// @__NO_SIDE_EFFECTS__
-function getDebugJsInstance(namespace) {
-  let inst = debugByNamespace.get(namespace);
-  if (inst) {
-    return inst;
-  }
-  if (!(0, import_debug.getDebug)() && (0, import_socket.getSocketDebug)() && (namespace === "error" || namespace === "notice")) {
-    import_debug2.default.enable(namespace);
-  }
-  inst = (0, import_debug2.default)(namespace);
-  inst.log = customLog;
-  debugByNamespace.set(namespace, inst);
-  return inst;
-}
-// @__NO_SIDE_EFFECTS__
-function getUtil() {
-  if (_util === void 0) {
-    _util = require("node:util");
-  }
-  return _util;
-}
-// @__NO_SIDE_EFFECTS__
-function isEnabled(namespaces) {
-  if (!(0, import_socket.getSocketDebug)()) {
-    return false;
-  }
-  if (typeof namespaces !== "string" || !namespaces || namespaces === "*") {
-    return true;
-  }
-  const split = namespaces.trim().replace(/\s+/g, ",").split(",").filter(Boolean);
-  const names = [];
-  const skips = [];
-  for (const ns of split) {
-    if ((0, import_primordials.StringPrototypeStartsWith)(ns, "-")) {
-      skips.push(ns.slice(1));
-    } else {
-      names.push(ns);
-    }
-  }
-  if (names.length && !names.some((ns) => (/* @__PURE__ */ getDebugJsInstance(ns)).enabled)) {
-    return false;
-  }
-  return skips.every((ns) => !(/* @__PURE__ */ getDebugJsInstance(ns)).enabled);
-}
-function debug(...args) {
-  debugNs("*", ...args);
-}
-// @__NO_SIDE_EFFECTS__
-function debugCache(operation, key, meta) {
-  if (!(0, import_socket.getSocketDebug)()) {
-    return;
-  }
-  const callerName = /* @__PURE__ */ getCallerInfo(3) || "cache";
-  if (pointingTriangle === void 0) {
-    const supported = (0, import_is_unicode_supported.default)();
-    pointingTriangle = supported ? "\u25B8" : ">";
-  }
-  const prefix = `[CACHE] ${callerName} ${pointingTriangle} ${operation}: ${key}`;
-  const args = meta !== void 0 ? [prefix, meta] : [prefix];
-  console.log(...args);
-}
-function debugCacheNs(namespacesOrOpts, operation, key, meta) {
-  const options = /* @__PURE__ */ extractOptions(namespacesOrOpts);
-  const { namespaces } = options;
-  if (!/* @__PURE__ */ isEnabled(namespaces)) {
-    return;
-  }
-  const callerName = /* @__PURE__ */ getCallerInfo(4) || "cache";
-  if (pointingTriangle === void 0) {
-    const supported = (0, import_is_unicode_supported.default)();
-    pointingTriangle = supported ? "\u25B8" : ">";
-  }
-  const prefix = `[CACHE] ${callerName} ${pointingTriangle} ${operation}: ${key}`;
-  const logArgs = meta !== void 0 ? [prefix, meta] : [prefix];
-  const spinnerInstance = options.spinner || (0, import_spinner.getDefaultSpinner)();
-  const wasSpinning = spinnerInstance?.isSpinning;
-  spinnerInstance?.stop();
-  (0, import_primordials.ReflectApply)(logger.info, logger, logArgs);
-  if (wasSpinning) {
-    spinnerInstance?.start();
-  }
-}
-function debugDir(obj, inspectOpts) {
-  debugDirNs("*", obj, inspectOpts);
-}
-function debugDirNs(namespacesOrOpts, obj, inspectOpts) {
-  const options = /* @__PURE__ */ extractOptions(namespacesOrOpts);
-  const { namespaces } = options;
-  if (!/* @__PURE__ */ isEnabled(namespaces)) {
-    return;
-  }
-  const callerName = /* @__PURE__ */ getCallerInfo(4) || "anonymous";
-  if (pointingTriangle === void 0) {
-    const supported = (0, import_is_unicode_supported.default)();
-    pointingTriangle = supported ? "\u25B8" : ">";
-  }
-  let opts = inspectOpts;
-  if (opts === void 0) {
-    const debugOpts = import_debug2.default.inspectOpts;
-    if (debugOpts) {
-      opts = {
-        ...debugOpts,
-        showHidden: debugOpts.showHidden === null ? void 0 : debugOpts.showHidden,
-        depth: debugOpts.depth === null || typeof debugOpts.depth === "boolean" ? null : debugOpts.depth
-      };
-    }
-  }
-  const spinnerInstance = options.spinner || (0, import_spinner.getDefaultSpinner)();
-  const wasSpinning = spinnerInstance?.isSpinning;
-  spinnerInstance?.stop();
-  logger.info(`[DEBUG] ${callerName} ${pointingTriangle} object inspection:`);
-  logger.dir(obj, inspectOpts);
-  if (wasSpinning) {
-    spinnerInstance?.start();
-  }
-}
-function debugLog(...args) {
-  debugLogNs("*", ...args);
-}
-function debugLogNs(namespacesOrOpts, ...args) {
-  const options = /* @__PURE__ */ extractOptions(namespacesOrOpts);
-  const { namespaces } = options;
-  if (!/* @__PURE__ */ isEnabled(namespaces)) {
-    return;
-  }
-  const callerName = /* @__PURE__ */ getCallerInfo(4) || "anonymous";
-  if (pointingTriangle === void 0) {
-    const supported = (0, import_is_unicode_supported.default)();
-    pointingTriangle = supported ? "\u25B8" : ">";
-  }
-  const text = (0, import_primordials.ArrayPrototypeAt)(args, 0);
-  const logArgs = typeof text === "string" ? [
-    (0, import_strings.applyLinePrefix)(
-      `${callerName ? `${callerName} ${pointingTriangle} ` : ""}${text}`,
-      { prefix: "[DEBUG] " }
-    ),
-    ...(0, import_primordials.ArrayPrototypeSlice)(args, 1)
-  ] : [`[DEBUG] ${callerName} ${pointingTriangle}`, ...args];
-  const spinnerInstance = options.spinner || (0, import_spinner.getDefaultSpinner)();
-  const wasSpinning = spinnerInstance?.isSpinning;
-  spinnerInstance?.stop();
-  (0, import_primordials.ReflectApply)(logger.info, logger, logArgs);
-  if (wasSpinning) {
-    spinnerInstance?.start();
-  }
-}
-// @__NO_SIDE_EFFECTS__
-function debuglog(section) {
-  const util = /* @__PURE__ */ getUtil();
-  return util.debuglog(section);
-}
-function debugNs(namespacesOrOpts, ...args) {
-  const options = /* @__PURE__ */ extractOptions(namespacesOrOpts);
-  const { namespaces } = options;
-  if (!/* @__PURE__ */ isEnabled(namespaces)) {
-    return;
-  }
-  const name = /* @__PURE__ */ getCallerInfo(4) || "anonymous";
-  if (pointingTriangle === void 0) {
-    const supported = (0, import_is_unicode_supported.default)();
-    pointingTriangle = supported ? "\u25B8" : ">";
-  }
-  const text = (0, import_primordials.ArrayPrototypeAt)(args, 0);
-  const logArgs = typeof text === "string" ? [
-    (0, import_strings.applyLinePrefix)(
-      `${name ? `${name} ${pointingTriangle} ` : ""}${text}`,
-      { prefix: "[DEBUG] " }
-    ),
-    ...(0, import_primordials.ArrayPrototypeSlice)(args, 1)
-  ] : args;
-  const spinnerInstance = options.spinner || (0, import_spinner.getDefaultSpinner)();
-  const wasSpinning = spinnerInstance?.isSpinning;
-  spinnerInstance?.stop();
-  (0, import_primordials.ReflectApply)(logger.info, logger, logArgs);
-  if (wasSpinning) {
-    spinnerInstance?.start();
-  }
-}
-// @__NO_SIDE_EFFECTS__
-function debugtime(label) {
-  const util = /* @__PURE__ */ getUtil();
-  let startTime;
-  const impl = () => {
-    if (startTime === void 0) {
-      startTime = (0, import_primordials.DateNow)();
-    } else {
-      const duration = (0, import_primordials.DateNow)() - startTime;
-      util.debuglog("time")(`${label}: ${duration}ms`);
-      startTime = void 0;
-    }
-  };
-  impl.start = () => {
-    startTime = (0, import_primordials.DateNow)();
-  };
-  impl.end = () => {
-    if (startTime !== void 0) {
-      const duration = (0, import_primordials.DateNow)() - startTime;
-      util.debuglog("time")(`${label}: ${duration}ms`);
-      startTime = void 0;
-    }
-  };
-  return impl;
-}
-// @__NO_SIDE_EFFECTS__
-function isDebug() {
-  return !!(0, import_socket.getSocketDebug)();
-}
-// @__NO_SIDE_EFFECTS__
-function isDebugNs(namespaces) {
-  return !!(0, import_socket.getSocketDebug)() && /* @__PURE__ */ isEnabled(namespaces);
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  debug,
-  debugCache,
-  debugCacheNs,
-  debugDir,
-  debugDirNs,
-  debugLog,
-  debugLogNs,
-  debugNs,
-  debuglog,
-  debugtime,
-  isDebug,
-  isDebugNs
-});

package/dist/env/helpers.d.ts

@@ -1,66 +0,0 @@
-/**
- * @fileoverview Environment variable type conversion helpers.
- *
- * Thin wrappers over the unified implementations in `@socketsecurity/lib/env`
- * that preserve the narrower `string | undefined` input signature and the
- * original strict-no-trim / float / whitespace-preserving defaults. Prefer
- * the root `env` module for new code — it supports both modes via options.
- */
-/**
- * Convert an environment variable string to a boolean.
- * Strict matching — does NOT trim whitespace (' true ' is false).
- *
- * @param value - The environment variable value to convert
- * @returns `true` if value is exactly 'true', '1', or 'yes' (case-insensitive), `false` otherwise
- *
- * @example
- * ```typescript
- * import { envAsBoolean } from '@socketsecurity/lib/env/helpers'
- *
- * envAsBoolean('true')      // true
- * envAsBoolean('1')         // true
- * envAsBoolean('yes')       // true
- * envAsBoolean(' true ')    // false (no trim)
- * envAsBoolean(undefined)   // false
- * ```
- */
-export declare function envAsBoolean(value: string | undefined): boolean;
-/**
- * Convert an environment variable string to a number.
- * Uses `Number()` (decimals, hex, octal, binary, Infinity preserved); returns
- * 0 only for undefined/empty/NaN. For int-only parsing use `envAsNumber` in
- * `@socketsecurity/lib/env` with default `mode: 'int'`.
- *
- * @param value - The environment variable value to convert
- * @returns The parsed number, or `0` if the value is undefined or NaN
- *
- * @example
- * ```typescript
- * import { envAsNumber } from '@socketsecurity/lib/env/helpers'
- *
- * envAsNumber('3000')       // 3000
- * envAsNumber('3.14')       // 3.14
- * envAsNumber('Infinity')   // Infinity
- * envAsNumber(undefined)    // 0
- * envAsNumber('abc')        // 0
- * ```
- */
-export declare function envAsNumber(value: string | undefined): number;
-/**
- * Convert an environment variable value to a string, preserving whitespace.
- * For trimmed-string behavior use `envAsString` in `@socketsecurity/lib/env`
- * (default `trim: true`); this helper passes `trim: false`.
- *
- * @param value - The environment variable value to convert
- * @returns The string value, or an empty string if undefined
- *
- * @example
- * ```typescript
- * import { envAsString } from '@socketsecurity/lib/env/helpers'
- *
- * envAsString('hello')    // 'hello'
- * envAsString('  x  ')    // '  x  ' (whitespace preserved)
- * envAsString(undefined)  // ''
- * ```
- */
-export declare function envAsString(value: string | undefined): string;

package/dist/env.d.ts

@@ -1,182 +0,0 @@
-/**
- * @fileoverview Environment variable parsing and conversion utilities.
- * Provides type-safe conversion functions for boolean, number, and string values.
- */
-/**
- * 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.
- *
- * @param base - Base environment object (usually process.env)
- * @param overrides - Optional overrides to merge
- * @returns Proxy that handles case-insensitive env var access
- *
- * @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'
- * import { spawn } from '@socketsecurity/lib/spawn'
- *
- * spawn('node', ['script.js'], {
- *   env: createEnvProxy(process.env, { NODE_ENV: 'test' })
- * })
- */
-export declare function createEnvProxy(base: NodeJS.ProcessEnv, overrides?: Record<string, string | undefined>): NodeJS.ProcessEnv;
-/**
- * Options for `envAsBoolean`.
- */
-export interface EnvAsBooleanOptions {
-    /** Default when value is null/undefined. @default false */
-    defaultValue?: boolean | undefined;
-    /**
-     * Whether to trim whitespace from string values before matching. When
-     * `false`, `'  true  '` is NOT recognised as truthy — only exact matches.
-     * @default true
-     */
-    trim?: boolean | undefined;
-}
-/**
- * Convert an environment variable value to a boolean.
- *
- * Back-compat overload: passing a bare boolean as the second argument is
- * equivalent to `{ defaultValue: B }`.
- *
- * @param value - The value to convert
- * @param defaultValueOrOptions - Default (boolean) or options object
- * @returns `true` if value is '1', 'true', or 'yes' (case-insensitive), `false` otherwise
- *
- * @example
- * ```typescript
- * import { envAsBoolean } from '@socketsecurity/lib/env'
- *
- * envAsBoolean('true')                     // true
- * envAsBoolean('1')                        // true
- * envAsBoolean('yes')                      // true
- * envAsBoolean('  true  ')                 // true (trimmed)
- * envAsBoolean('  true  ', { trim: false }) // false (strict)
- * envAsBoolean(undefined)                  // false
- * envAsBoolean(undefined, true)            // true (legacy positional default)
- * ```
- */
-export declare function envAsBoolean(value: unknown, defaultValueOrOptions?: boolean | EnvAsBooleanOptions | undefined): boolean;
-/**
- * Options for `envAsNumber`.
- */
-export interface EnvAsNumberOptions {
-    /**
-     * Whether to return `±Infinity` when input parses to infinity. When
-     * `false` (default), infinities and NaN are coerced to `defaultValue`.
-     * @default false
-     */
-    allowInfinity?: boolean | undefined;
-    /** Default when value is not a finite number. @default 0 */
-    defaultValue?: number | undefined;
-    /**
-     * Parse mode. `'int'` (default) uses `parseInt(_, 10)` — integer only.
-     * `'float'` uses `Number()` — decimals preserved.
-     * @default 'int'
-     */
-    mode?: 'int' | 'float' | undefined;
-}
-/**
- * Convert an environment variable value to a number.
- *
- * Back-compat overload: passing a bare number as the second argument is
- * equivalent to `{ defaultValue: N }`.
- *
- * @param value - The value to convert
- * @param defaultValueOrOptions - Default (number) or options object
- * @returns The parsed number, or the default value if parsing fails
- *
- * @example
- * ```typescript
- * import { envAsNumber } from '@socketsecurity/lib/env'
- *
- * envAsNumber('3000')              // 3000 (int mode)
- * envAsNumber('3.14', { mode: 'float' }) // 3.14
- * envAsNumber('abc')               // 0
- * envAsNumber(undefined, 42)       // 42 (legacy positional default)
- * ```
- */
-export declare function envAsNumber(value: unknown, defaultValueOrOptions?: number | EnvAsNumberOptions | undefined): number;
-/**
- * Options for `envAsString`.
- */
-export interface EnvAsStringOptions {
-    /** Default when value is null/undefined. @default '' */
-    defaultValue?: string | undefined;
-    /**
-     * Whether to trim whitespace from string values. `true` (default) trims.
-     * Set `false` to preserve whitespace (helpers.envAsString semantics).
-     * @default true
-     */
-    trim?: boolean | undefined;
-}
-/**
- * Convert an environment variable value to a string.
- *
- * Back-compat overload: passing a bare string as the second argument is
- * equivalent to `{ defaultValue: S }`.
- *
- * @param value - The value to convert
- * @param defaultValueOrOptions - Default (string) or options object
- * @returns The string value, or the default value
- *
- * @example
- * ```typescript
- * import { envAsString } from '@socketsecurity/lib/env'
- *
- * envAsString('  hello  ')                    // 'hello' (trimmed)
- * envAsString('  hello  ', { trim: false })   // '  hello  '
- * envAsString(undefined)                      // ''
- * envAsString(null, 'n/a')                    // 'n/a' (legacy positional)
- * ```
- */
-export declare function envAsString(value: unknown, defaultValueOrOptions?: string | EnvAsStringOptions | undefined): string;
-/**
- * Find a case-insensitive environment variable key match.
- * Searches for an environment variable key that matches the given uppercase name,
- * using optimized fast-path checks to minimize expensive toUpperCase() calls.
- *
- * **Use Cases:**
- * - Finding PATH when env object has "Path" or "path"
- * - Cross-platform env var access where case may vary
- * - Custom case-insensitive env lookups
- *
- * **Performance:**
- * - Fast path: Checks length first (O(1)) before toUpperCase (expensive)
- * - Only converts to uppercase when length matches
- * - Early exit on first match
- *
- * @param env - Environment object or env-like record to search
- * @param upperEnvVarName - Uppercase environment variable name to find (e.g., 'PATH')
- * @returns The actual key from env that matches (e.g., 'Path'), or undefined
- *
- * @example
- * // Find PATH regardless of case
- * const envObj = { Path: 'C:\\Windows', NODE_ENV: 'test' }
- * const key = findCaseInsensitiveEnvKey(envObj, 'PATH')
- * console.log(key)  // 'Path'
- * console.log(envObj[key])  // 'C:\\Windows'
- *
- * @example
- * // Not found returns undefined
- * const key = findCaseInsensitiveEnvKey({}, 'MISSING')
- * console.log(key)  // undefined
- */
-export declare function findCaseInsensitiveEnvKey(env: Record<string, string | undefined>, upperEnvVarName: string): string | undefined;