@socketsecurity/lib 5.27.0 → 6.0.0

package/dist/primordials/symbol.js

@@ -0,0 +1,94 @@
+"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 symbol_exports = {};
+__export(symbol_exports, {
+  SymbolAsyncDispose: () => SymbolAsyncDispose,
+  SymbolAsyncIterator: () => SymbolAsyncIterator,
+  SymbolCtor: () => SymbolCtor,
+  SymbolDispose: () => SymbolDispose,
+  SymbolFor: () => SymbolFor,
+  SymbolHasInstance: () => SymbolHasInstance,
+  SymbolIsConcatSpreadable: () => SymbolIsConcatSpreadable,
+  SymbolIterator: () => SymbolIterator,
+  SymbolKeyFor: () => SymbolKeyFor,
+  SymbolMatch: () => SymbolMatch,
+  SymbolMatchAll: () => SymbolMatchAll,
+  SymbolPrototypeDescription: () => SymbolPrototypeDescription,
+  SymbolPrototypeToString: () => SymbolPrototypeToString,
+  SymbolPrototypeValueOf: () => SymbolPrototypeValueOf,
+  SymbolReplace: () => SymbolReplace,
+  SymbolSearch: () => SymbolSearch,
+  SymbolSpecies: () => SymbolSpecies,
+  SymbolSplit: () => SymbolSplit,
+  SymbolToPrimitive: () => SymbolToPrimitive,
+  SymbolToStringTag: () => SymbolToStringTag,
+  SymbolUnscopables: () => SymbolUnscopables
+});
+module.exports = __toCommonJS(symbol_exports);
+var import_uncurry = require("./uncurry");
+const SymbolCtor = Symbol;
+const SymbolAsyncDispose = Symbol.asyncDispose;
+const SymbolAsyncIterator = Symbol.asyncIterator;
+const SymbolDispose = Symbol.dispose;
+const SymbolFor = Symbol.for;
+const SymbolHasInstance = Symbol.hasInstance;
+const SymbolIsConcatSpreadable = Symbol.isConcatSpreadable;
+const SymbolIterator = Symbol.iterator;
+const SymbolKeyFor = Symbol.keyFor;
+const SymbolMatch = Symbol.match;
+const SymbolMatchAll = Symbol.matchAll;
+const SymbolReplace = Symbol.replace;
+const SymbolSearch = Symbol.search;
+const SymbolSpecies = Symbol.species;
+const SymbolSplit = Symbol.split;
+const SymbolToPrimitive = Symbol.toPrimitive;
+const SymbolToStringTag = Symbol.toStringTag;
+const SymbolUnscopables = Symbol.unscopables;
+const _symbolDescriptionGetter = Symbol.prototype.__lookupGetter__("description");
+function SymbolPrototypeDescription(self) {
+  return _symbolDescriptionGetter ? _symbolDescriptionGetter.call(self) : self.description;
+}
+const SymbolPrototypeToString = (0, import_uncurry.uncurryThis)(Symbol.prototype.toString);
+const SymbolPrototypeValueOf = (0, import_uncurry.uncurryThis)(Symbol.prototype.valueOf);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SymbolAsyncDispose,
+  SymbolAsyncIterator,
+  SymbolCtor,
+  SymbolDispose,
+  SymbolFor,
+  SymbolHasInstance,
+  SymbolIsConcatSpreadable,
+  SymbolIterator,
+  SymbolKeyFor,
+  SymbolMatch,
+  SymbolMatchAll,
+  SymbolPrototypeDescription,
+  SymbolPrototypeToString,
+  SymbolPrototypeValueOf,
+  SymbolReplace,
+  SymbolSearch,
+  SymbolSpecies,
+  SymbolSplit,
+  SymbolToPrimitive,
+  SymbolToStringTag,
+  SymbolUnscopables
+});

package/dist/primordials/uncurry.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @file `uncurryThis` and the cluster of helpers built atop it. Mirrors
+ *   Node.js's internal/per_context/primordials.js. Every other primordials leaf
+ *   depends on `uncurryThis` to expose prototype-method primordials, so this
+ *   file must be import-safe before any of them. Smol fast paths
+ *   (`node:smol-util`) replace the JS forms when running on socket-btm's smol
+ *   Node binary; stock Node and other runtimes fall back to the standard
+ *   `bind.bind(call)` shape. **IMPORTANT**: do not destructure on `globalThis`
+ *   or `Reflect` here. tsgo has a bug that mis-transpiles destructured exports.
+ *   See: https://github.com/SocketDev/socket-packageurl-js/issues/3.
+ */
+export declare const uncurryThis: <T, A extends readonly unknown[], R>(fn: (this: T, ...args: A) => R) => (self: T, ...args: A) => R;
+export declare const applyBind: <T, A extends readonly unknown[], R>(fn: (this: T, ...args: A) => R) => (self: T, args: A) => R;
+export declare const applySafe: <T, A extends readonly unknown[], R>(fn: (this: T, ...args: A) => R) => (self: T, args: A) => R | undefined;
+type BindCall = <T, P extends readonly unknown[], A extends readonly unknown[], R>(fn: (this: T, ...args: [...P, ...A]) => R, thisArg: T, ...presetArgs: P) => (...newArgs: A) => R;
+export declare const bindCall: BindCall;
+export declare const weakRefSafe: <T extends object | symbol>(target: T) => WeakRef<T> | undefined;
+export {};

package/dist/primordials/uncurry.js

@@ -0,0 +1,65 @@
+"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 uncurry_exports = {};
+__export(uncurry_exports, {
+  applyBind: () => applyBind,
+  applySafe: () => applySafe,
+  bindCall: () => bindCall,
+  uncurryThis: () => uncurryThis,
+  weakRefSafe: () => weakRefSafe
+});
+module.exports = __toCommonJS(uncurry_exports);
+var import_detect = require("../smol/detect");
+const _smolUtil = (0, import_detect.getSmolUtil)();
+const { apply, bind, call } = Function.prototype;
+const uncurryThis = _smolUtil?.uncurryThis ?? bind.bind(call);
+const applyBind = _smolUtil?.applyBind ?? bind.bind(apply);
+const _applyBoundForSafe = applyBind;
+const applySafe = _smolUtil?.applySafe ?? ((fn) => {
+  const apply2 = _applyBoundForSafe(fn);
+  return (self, args) => {
+    try {
+      return apply2(self, args);
+    } catch {
+      return void 0;
+    }
+  };
+});
+const _bindCallFallback = ((fn, thisArg, ...presetArgs) => Function.prototype.bind.apply(fn, [
+  thisArg,
+  ...presetArgs
+]));
+const bindCall = _smolUtil?.bindCall ?? _bindCallFallback;
+const weakRefSafe = _smolUtil?.weakRefSafe ?? ((target) => {
+  try {
+    return new WeakRef(target);
+  } catch {
+    return void 0;
+  }
+});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  applyBind,
+  applySafe,
+  bindCall,
+  uncurryThis,
+  weakRefSafe
+});

package/dist/primordials/url.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @file Safe references to `URL`, `URLSearchParams`, and the
+ *   `URLSearchParams.prototype` methods.
+ */
+export declare const URLCtor: typeof URL;
+export declare const URLSearchParamsCtor: typeof URLSearchParams;
+export declare const URLSearchParamsPrototypeAppend: (self: unknown, name: string, value: string) => void;
+export declare const URLSearchParamsPrototypeDelete: (self: unknown, name: string, value?: string | undefined) => void;
+export declare const URLSearchParamsPrototypeForEach: <TThis = import("url").URLSearchParams>(self: unknown, fn: (this: TThis, value: string, name: string, searchParams: import("url").URLSearchParams) => void, thisArg?: TThis | undefined) => void;
+export declare const URLSearchParamsPrototypeGet: (self: unknown, name: string) => string | null;
+export declare const URLSearchParamsPrototypeGetAll: (self: unknown, name: string) => string[];
+export declare const URLSearchParamsPrototypeHas: (self: unknown, name: string, value?: string | undefined) => boolean;
+export declare const URLSearchParamsPrototypeSet: (self: unknown, name: string, value: string) => void;

package/dist/primordials/url.js

@@ -0,0 +1,69 @@
+"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 url_exports = {};
+__export(url_exports, {
+  URLCtor: () => URLCtor,
+  URLSearchParamsCtor: () => URLSearchParamsCtor,
+  URLSearchParamsPrototypeAppend: () => URLSearchParamsPrototypeAppend,
+  URLSearchParamsPrototypeDelete: () => URLSearchParamsPrototypeDelete,
+  URLSearchParamsPrototypeForEach: () => URLSearchParamsPrototypeForEach,
+  URLSearchParamsPrototypeGet: () => URLSearchParamsPrototypeGet,
+  URLSearchParamsPrototypeGetAll: () => URLSearchParamsPrototypeGetAll,
+  URLSearchParamsPrototypeHas: () => URLSearchParamsPrototypeHas,
+  URLSearchParamsPrototypeSet: () => URLSearchParamsPrototypeSet
+});
+module.exports = __toCommonJS(url_exports);
+var import_uncurry = require("./uncurry");
+const URLCtor = URL;
+const URLSearchParamsCtor = URLSearchParams;
+const URLSearchParamsPrototypeAppend = (0, import_uncurry.uncurryThis)(
+  URLSearchParams.prototype.append
+);
+const URLSearchParamsPrototypeDelete = (0, import_uncurry.uncurryThis)(
+  URLSearchParams.prototype.delete
+);
+const URLSearchParamsPrototypeForEach = (0, import_uncurry.uncurryThis)(
+  URLSearchParams.prototype.forEach
+);
+const URLSearchParamsPrototypeGet = (0, import_uncurry.uncurryThis)(
+  URLSearchParams.prototype.get
+);
+const URLSearchParamsPrototypeGetAll = (0, import_uncurry.uncurryThis)(
+  URLSearchParams.prototype.getAll
+);
+const URLSearchParamsPrototypeHas = (0, import_uncurry.uncurryThis)(
+  URLSearchParams.prototype.has
+);
+const URLSearchParamsPrototypeSet = (0, import_uncurry.uncurryThis)(
+  URLSearchParams.prototype.set
+);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  URLCtor,
+  URLSearchParamsCtor,
+  URLSearchParamsPrototypeAppend,
+  URLSearchParamsPrototypeDelete,
+  URLSearchParamsPrototypeForEach,
+  URLSearchParamsPrototypeGet,
+  URLSearchParamsPrototypeGetAll,
+  URLSearchParamsPrototypeHas,
+  URLSearchParamsPrototypeSet
+});

package/dist/process/_internal.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @file Private internals for `process/lock-*` modules — re-exports of the
+ *   canonical node:fs / node:path lazy loaders under the process/ legacy names.
+ *   New code should import getNodeFs / getNodePath from
+ *   `@socketsecurity/lib/node/{fs,path}` directly.
+ */
+export { getNodeFs as getFs } from '../node/fs';
+export { getNodePath as getPath } from '../node/path';

package/dist/process/_internal.js

@@ -0,0 +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 internal_exports = {};
+__export(internal_exports, {
+  getFs: () => import_fs.getNodeFs,
+  getPath: () => import_path.getNodePath
+});
+module.exports = __toCommonJS(internal_exports);
+var import_fs = require("../node/fs");
+var import_path = require("../node/path");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getFs,
+  getPath
+});

package/dist/process/abort.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @file Process control helpers. Lazily creates and exposes a shared
+ *   `AbortController` and its `AbortSignal` so cooperating modules can
+ *   coordinate cancellation from a single source.
+ */
+/**
+ * Get the process-scoped shared `AbortController` singleton. Cooperating
+ * modules use this to coordinate cancellation across the library.
+ *
+ * @returns The lazily-created shared `AbortController` instance.
+ */
+export declare function getAbortController(): AbortController;
+/**
+ * Get the process-scoped shared `AbortSignal` singleton. This is the `signal`
+ * property of {@link getAbortController}'s controller and is intended to be
+ * passed to APIs that accept an `AbortSignal`.
+ *
+ * @returns The shared `AbortSignal` instance.
+ */
+export declare function getAbortSignal(): AbortSignal;

package/dist/{constants/process.js → process/abort.js}

@@ -18,12 +18,12 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var process_exports = {};
-__export(process_exports, {
+var abort_exports = {};
+__export(abort_exports, {
   getAbortController: () => getAbortController,
   getAbortSignal: () => getAbortSignal
 });
-module.exports = __toCommonJS(process_exports);
+module.exports = __toCommonJS(abort_exports);
 let _abortController;
 function getAbortController() {
   if (_abortController === void 0) {

package/dist/process/lock-instance.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @file Singleton `processLock` instance — the canonical cross-cutting lock
+ *   manager. Most callers want this; only test harnesses that need an isolated
+ *   lock-tracking state should construct a `ProcessLockManager` directly.
+ */
+import { ProcessLockManager } from './lock-manager';
+/**
+ * Singleton process lock manager instance.
+ *
+ * @example
+ *   ;```typescript
+ *   import { processLock } from '@socketsecurity/lib/process/lock-instance'
+ *
+ *   await processLock.withLock('/tmp/my-lock', async () => {
+ *     // critical section
+ *   })
+ *   ```
+ */
+export declare const processLock: ProcessLockManager;

package/dist/process/lock-instance.js

@@ -0,0 +1,31 @@
+"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 lock_instance_exports = {};
+__export(lock_instance_exports, {
+  processLock: () => processLock
+});
+module.exports = __toCommonJS(lock_instance_exports);
+var import_lock_manager = require("./lock-manager");
+const processLock = new import_lock_manager.ProcessLockManager();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  processLock
+});

package/dist/process/lock-manager.d.ts

@@ -0,0 +1,152 @@
+/**
+ * @file `ProcessLockManager` — the class that owns active locks, touch timers,
+ *   and the exit-handler registration. Provides `acquire` / `release` /
+ *   `withLock`. Co-located with the touch and staleness helpers because they
+ *   share private state (`activeLocks` + `touchTimers`).
+ *
+ *   ## Why directories instead of files?
+ *
+ *   This implementation uses `mkdir()` to create lock directories (not files)
+ *   because:
+ *
+ *   1. **Atomic guarantee**: `mkdir()` is guaranteed atomic across ALL
+ *      filesystems, including NFS. Only ONE process can successfully create the
+ *      directory. If it exists, `mkdir()` fails with EEXIST instantly with no
+ *      race conditions.
+ *   2. **File-based locking issues**:
+ *
+ *   - `writeFile()` with `flag: 'wx'` - atomicity can fail on NFS
+ *   - `open()` with `O_EXCL` - not guaranteed atomic on older NFS
+ *   - Traditional lockfiles - can have race conditions on network filesystems
+ *
+ *   3. **Simplicity**: No need to write/read file content, track PIDs, or manage
+ *      file descriptors. Just create/delete directory and check mtime.
+ *   4. **Historical precedent**: Well-known Unix locking pattern used by package
+ *      managers for decades. Git uses similar approach for `.git/index.lock`.
+ *
+ *   ## The mtime trick
+ *
+ *   We periodically update the lock directory's mtime (modification time) by
+ *   "touching" it to signal "I'm still actively working". This prevents other
+ *   processes from treating the lock as stale and removing it. **The lock
+ *   directory remains empty** - it's just a sentinel that signals "locked". The
+ *   mtime is the only data needed to track lock freshness.
+ *
+ *   ## npm npx compatibility
+ *
+ *   This implementation matches npm npx's concurrency.lock approach:
+ *
+ *   - Lock created via `mkdir(path.join(installDir, 'concurrency.lock'))`
+ *   - 5-second stale timeout (if mtime is older than 5s, lock is stale)
+ *   - 2-second touching interval (updates mtime every 2s to keep lock fresh)
+ *   - Automatic cleanup on process exit
+ */
+import type { ProcessLockOptions } from './lock-types';
+/**
+ * Process lock manager with stale detection and exit cleanup. Provides
+ * cross-platform inter-process synchronization using file-system based locks.
+ */
+export declare class ProcessLockManager {
+    private activeLocks;
+    private touchTimers;
+    private exitHandlerRegistered;
+    /**
+     * Ensure process exit handler is registered for cleanup. Registers a handler
+     * that cleans up all active locks when the process exits.
+     */
+    private ensureExitHandler;
+    /**
+     * Touch a lock file to update its mtime. This prevents the lock from being
+     * detected as stale during long operations.
+     *
+     * @param lockPath - Path to the lock directory.
+     */
+    private touchLock;
+    /**
+     * Start periodic touching of a lock file. Aligned with npm npx strategy to
+     * prevent false stale detection.
+     *
+     * @param lockPath - Path to the lock directory.
+     * @param intervalMs - Touch interval in milliseconds.
+     */
+    private startTouchTimer;
+    /**
+     * Stop periodic touching of a lock file.
+     *
+     * @param lockPath - Path to the lock directory.
+     */
+    private stopTouchTimer;
+    /**
+     * Check if a lock is stale based on mtime. Uses second-level granularity to
+     * avoid APFS floating-point precision issues. Aligned with npm's npx locking
+     * strategy.
+     *
+     * @param lockPath - Path to the lock directory.
+     * @param staleMs - Stale timeout in milliseconds.
+     *
+     * @returns True if lock exists and is stale
+     */
+    private isStale;
+    /**
+     * Acquire a lock using mkdir for atomic operation. Handles stale locks and
+     * includes exit cleanup.
+     *
+     * This method attempts to create a lock directory atomically. If the lock
+     * already exists, it checks if it's stale and removes it before retrying.
+     * Uses exponential backoff with jitter for retry attempts.
+     *
+     * @example
+     *   ;```typescript
+     *   const release = await processLock.acquire('/tmp/my-lock')
+     *   try {
+     *     // Critical section
+     *   } finally {
+     *     release()
+     *   }
+     *   ```
+     *
+     * @param lockPath - Path to the lock directory.
+     * @param options - Lock acquisition options.
+     *
+     * @returns Release function to unlock
+     *
+     * @throws Error if lock cannot be acquired after all retries
+     */
+    acquire(lockPath: string, options?: ProcessLockOptions): Promise<() => void>;
+    /**
+     * Release a lock and remove from tracking. Stops periodic touching and
+     * removes the lock directory.
+     *
+     * @example
+     *   ;```typescript
+     *   processLock.release('/tmp/my-lock')
+     *   ```
+     *
+     * @param lockPath - Path to the lock directory.
+     */
+    release(lockPath: string): void;
+    /**
+     * Execute a function with exclusive lock protection. Automatically handles
+     * lock acquisition, execution, and cleanup.
+     *
+     * This is the recommended way to use process locks, as it guarantees cleanup
+     * even if the callback throws an error.
+     *
+     * @example
+     *   ;```typescript
+     *   const result = await processLock.withLock('/tmp/my-lock', async () => {
+     *     // Critical section
+     *     return someValue
+     *   })
+     *   ```
+     *
+     * @param lockPath - Path to the lock directory.
+     * @param fn - Function to execute while holding the lock.
+     * @param options - Lock acquisition options.
+     *
+     * @returns Result of the callback function
+     *
+     * @throws Error from callback or lock acquisition failure
+     */
+    withLock<T>(lockPath: string, fn: () => Promise<T>, options?: ProcessLockOptions): Promise<T>;
+}