@socketsecurity/lib 5.28.0 → 6.0.0

package/dist/promises/retry.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @file `pRetry` — exponential-backoff retry with optional jitter, abort-signal
+ *   support, and an `onRetry` hook for customizing delays or canceling retries
+ *   entirely. Cycles with `iterate.ts`: pRetry is called by pEach / pEachChunk
+ *   / pFilter / pFilterChunk to apply per-item retry. ESM tolerates the cycle
+ *   since both sides reference each other through functions only.
+ */
+import type { RetryOptions } from './types';
+/**
+ * Retry an async function with exponential backoff.
+ *
+ * Attempts to execute a function multiple times with increasing delays between
+ * attempts. Implements exponential backoff with optional jitter to prevent
+ * thundering herd problems. Supports custom retry logic via `onRetry`
+ * callback.
+ *
+ * The delay calculation follows: `min(baseDelayMs * (backoffFactor ** attempt),
+ * maxDelayMs)` With jitter: adds random value between 0 and calculated delay.
+ *
+ * @example
+ *   // Simple retry: 3 attempts with default backoff
+ *   const data = await pRetry(async () => {
+ *     return await fetchData()
+ *   }, 3)
+ *
+ * @example
+ *   // Custom backoff strategy
+ *   const result = await pRetry(
+ *     async () => {
+ *       return await unreliableOperation()
+ *     },
+ *     {
+ *       retries: 5,
+ *       baseDelayMs: 1000, // Start at 1 second
+ *       backoffFactor: 2, // Double each time
+ *       maxDelayMs: 30000, // Cap at 30 seconds
+ *       jitter: true, // Add randomness
+ *     },
+ *   )
+ *   // Delays: ~1s, ~2s, ~4s, ~8s, ~16s (each ± random jitter)
+ *
+ * @example
+ *   // With custom retry logic
+ *   const data = await pRetry(
+ *     async () => {
+ *       return await apiCall()
+ *     },
+ *     {
+ *       retries: 3,
+ *       onRetry: (attempt, error, delay) => {
+ *         console.log(`Attempt ${attempt} failed: ${error}`)
+ *         console.log(`Waiting ${delay}ms before retry...`)
+ *
+ *         // Cancel retries for client errors (4xx)
+ *         if (error.statusCode >= 400 && error.statusCode < 500) {
+ *           return false
+ *         }
+ *
+ *         // Use longer delay for rate limit errors
+ *         if (error.statusCode === 429) {
+ *           return 60000 // Wait 1 minute
+ *         }
+ *       },
+ *       onRetryCancelOnFalse: true,
+ *     },
+ *   )
+ *
+ * @example
+ *   // With cancellation support
+ *   const controller = new AbortController()
+ *   setTimeout(() => controller.abort(), 5000) // Cancel after 5s
+ *
+ *   const result = await pRetry(
+ *     async ({ signal }) => {
+ *       return await longRunningTask(signal)
+ *     },
+ *     {
+ *       retries: 10,
+ *       signal: controller.signal,
+ *     },
+ *   )
+ *   // Returns undefined if aborted
+ *
+ * @example
+ *   // Pass arguments to callback
+ *   const result = await pRetry(
+ *     async (url, options) => {
+ *       return await fetch(url, options)
+ *     },
+ *     {
+ *       retries: 3,
+ *       args: ['https://api.example.com', { method: 'POST' }],
+ *     },
+ *   )
+ *
+ * @template T - The return type of the callback function.
+ *
+ * @param callbackFn - Async function to retry.
+ * @param options - Retry count as number, or full retry options, or undefined.
+ *
+ * @returns Promise resolving to callback result, or `undefined` if aborted
+ *
+ * @throws {Error} The last error if all retry attempts fail
+ */
+export declare function pRetry<T>(callbackFn: (...args: unknown[]) => Promise<T>, options?: number | RetryOptions | undefined): Promise<T | undefined>;

package/dist/promises/retry.js

@@ -0,0 +1,104 @@
+"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 retry_exports = {};
+__export(retry_exports, {
+  pRetry: () => pRetry
+});
+module.exports = __toCommonJS(retry_exports);
+var import_sentinels = require("../constants/sentinels");
+var import_math = require("../primordials/math");
+var import_internal = require("./_internal");
+var import_options = require("./options");
+// @__NO_SIDE_EFFECTS__
+async function pRetry(callbackFn, options) {
+  const {
+    args,
+    backoffFactor,
+    baseDelayMs,
+    jitter,
+    maxDelayMs,
+    onRetry,
+    onRetryCancelOnFalse,
+    onRetryRethrow,
+    retries,
+    signal
+  } = (0, import_options.normalizeRetryOptions)(options);
+  if (signal?.aborted) {
+    return void 0;
+  }
+  if (retries === 0) {
+    return await callbackFn(...args || [], { signal });
+  }
+  const timers = (0, import_internal.getTimers)();
+  let attempts = retries;
+  let delay = baseDelayMs;
+  let error = import_sentinels.UNDEFINED_TOKEN;
+  while (attempts-- >= 0) {
+    if (signal?.aborted) {
+      return void 0;
+    }
+    try {
+      return await callbackFn(...args || [], { signal });
+    } catch (e) {
+      error = e;
+      if (attempts < 0) {
+        break;
+      }
+      let waitTime = delay;
+      if (jitter) {
+        waitTime += (0, import_math.MathFloor)((0, import_math.MathRandom)() * delay);
+      }
+      waitTime = (0, import_math.MathMin)(waitTime, maxDelayMs);
+      if (typeof onRetry === "function") {
+        try {
+          const result = onRetry(retries - attempts, e, waitTime);
+          if (result === false && onRetryCancelOnFalse) {
+            break;
+          }
+          if (typeof result === "number" && result >= 0) {
+            waitTime = (0, import_math.MathMin)(result, maxDelayMs);
+          }
+        } catch (e2) {
+          if (onRetryRethrow) {
+            throw e2;
+          }
+        }
+      }
+      try {
+        await timers.setTimeout(waitTime, void 0, { signal });
+      } catch {
+        return void 0;
+      }
+      if (signal?.aborted) {
+        return void 0;
+      }
+      delay = (0, import_math.MathMin)(delay * backoffFactor, maxDelayMs);
+    }
+  }
+  if (error !== import_sentinels.UNDEFINED_TOKEN) {
+    throw error;
+  }
+  return void 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  pRetry
+});

package/dist/promises/types.d.ts

@@ -0,0 +1,190 @@
+/**
+ * @file Public type surface for `promises/*` modules: `RetryOptions`,
+ *   `IterationOptions`, and `PromiseWithResolvers`. Pure types, no runtime side
+ *   effects.
+ */
+/**
+ * Configuration options for retry behavior with exponential backoff.
+ *
+ * Controls how failed operations are retried, including timing, backoff
+ * strategy, and callback hooks for observing or modifying retry behavior.
+ */
+export interface RetryOptions {
+    /**
+     * Arguments to pass to the callback function on each attempt.
+     *
+     * @default [ ]
+     */
+    args?: unknown[] | undefined;
+    /**
+     * Multiplier for exponential backoff (e.g., 2 doubles delay each retry). Each
+     * retry waits `baseDelayMs * (backoffFactor ** attemptNumber)`.
+     *
+     * @example
+     *   // With backoffFactor: 2, baseDelayMs: 100
+     *   // Retry 1: 100ms
+     *   // Retry 2: 200ms
+     *   // Retry 3: 400ms
+     *
+     * @default 2
+     */
+    backoffFactor?: number | undefined;
+    /**
+     * Initial delay before the first retry (in milliseconds). This is the base
+     * value for exponential backoff calculations.
+     *
+     * @default 200
+     */
+    baseDelayMs?: number | undefined;
+    /**
+     * Whether to apply randomness to spread out retries and avoid thundering
+     * herd. When `true`, adds random delay between 0 and current delay value.
+     *
+     * @example
+     *   // With jitter: true, delay: 100ms
+     *   // Actual wait: 100ms + random(0-100ms) = 100-200ms
+     *
+     * @default true
+     */
+    jitter?: boolean | undefined;
+    /**
+     * Upper limit for any backoff delay (in milliseconds). Prevents exponential
+     * backoff from growing unbounded.
+     *
+     * @default 10000
+     */
+    maxDelayMs?: number | undefined;
+    /**
+     * Callback invoked on each retry attempt. Can observe errors, customize
+     * delays, or cancel retries.
+     *
+     * @example
+     *   // Log each retry
+     *   onRetry: (attempt, error, delay) => {
+     *     console.log(`Retry ${attempt} after ${delay}ms: ${error}`)
+     *   }
+     *
+     * @example
+     *   // Cancel retries for specific errors
+     *   onRetry: (attempt, error) => {
+     *     if (error instanceof ValidationError) return false
+     *   }
+     *
+     * @example
+     *   // Use custom delay
+     *   onRetry: attempt => attempt * 1000 // 1s, 2s, 3s, ...
+     *
+     * @param attempt - The current attempt number (1-based: 1, 2, 3, ...)
+     * @param error - The error that triggered this retry.
+     * @param delay - The calculated delay in milliseconds before next retry.
+     *
+     * @returns `false` to cancel retries (if `onRetryCancelOnFalse` is `true`), a
+     *   number to override the delay, or `undefined` to use calculated delay.
+     */
+    onRetry?: ((attempt: number, error: unknown, delay: number) => boolean | number | undefined) | undefined;
+    /**
+     * Whether `onRetry` can cancel retries by returning `false`. When `true`,
+     * returning `false` from `onRetry` stops retry attempts.
+     *
+     * @default false
+     */
+    onRetryCancelOnFalse?: boolean | undefined;
+    /**
+     * Whether errors thrown by `onRetry` should propagate. When `true`,
+     * exceptions in `onRetry` terminate the retry loop. When `false`, exceptions
+     * in `onRetry` are silently caught.
+     *
+     * @default false
+     */
+    onRetryRethrow?: boolean | undefined;
+    /**
+     * Number of retry attempts (0 = no retries, only initial attempt). The
+     * callback is executed `retries + 1` times total (initial + retries).
+     *
+     * @example
+     *   // retries: 0 -> 1 total attempt (no retries)
+     *   // retries: 3 -> 4 total attempts (1 initial + 3 retries)
+     *
+     * @default 0
+     */
+    retries?: number | undefined;
+    /**
+     * AbortSignal to support cancellation of retry operations. When aborted,
+     * immediately stops retrying and returns `undefined`.
+     *
+     * @example
+     *   const controller = new AbortController()
+     *   pRetry(fn, { signal: controller.signal })
+     *   // Later: controller.abort() to cancel
+     *
+     * @default process abort signal
+     */
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Configuration options for iteration functions with concurrency control.
+ *
+ * Controls how array operations are parallelized and retried.
+ */
+export interface IterationOptions {
+    /**
+     * The number of concurrent executions performed at one time. Higher values
+     * increase parallelism but may overwhelm resources.
+     *
+     * @example
+     *   // Process 5 items at a time
+     *   await pEach(items, processItem, { concurrency: 5 })
+     *
+     * @default 1
+     */
+    concurrency?: number | undefined;
+    /**
+     * Retry configuration as a number (retry count) or full options object.
+     * Applied to each individual item's callback execution.
+     *
+     * @example
+     *   // Simple: retry each item up to 3 times
+     *   await pEach(items, fetchItem, { retries: 3 })
+     *
+     * @example
+     *   // Advanced: custom backoff for each item
+     *   await pEach(items, fetchItem, {
+     *     retries: {
+     *       retries: 3,
+     *       baseDelayMs: 1000,
+     *       backoffFactor: 2,
+     *     },
+     *   })
+     *
+     * @default 0 (no retries)
+     */
+    retries?: number | RetryOptions | undefined;
+    /**
+     * AbortSignal to support cancellation of the entire iteration. When aborted,
+     * stops processing remaining items.
+     *
+     * @default process abort signal
+     */
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Shape returned by {@link withResolvers}: a fresh pending promise plus the
+ * `resolve` / `reject` handles that settle it.
+ *
+ * Matches the spec return-shape exactly ([ECMA-262
+ * §27.2.4.9](https://tc39.es/ecma262/#sec-promise.withResolvers)).
+ */
+export interface PromiseWithResolvers<T> {
+    /**
+     * The pending promise.
+     */
+    promise: Promise<T>;
+    /**
+     * Resolves {@link promise} with the given value (or thenable).
+     */
+    resolve: (value: T | PromiseLike<T>) => void;
+    /**
+     * Rejects {@link promise} with the given reason.
+     */
+    reject: (reason?: unknown) => void;
+}

package/dist/promises/types.js

@@ -0,0 +1,18 @@
+"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 __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 types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/regexps/escape.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @file Public `escapeRegExp` entry — binds to native `RegExp.escape` (TC39
+ *   Stage 4, Node 24+ / V8 13.7) when available, otherwise falls back to the
+ *   spec-compliant implementation in `./spec`.
+ */
+export declare const escapeRegExp: (str: string) => string;

package/dist/regexps/escape.js

@@ -0,0 +1,32 @@
+"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 escape_exports = {};
+__export(escape_exports, {
+  escapeRegExp: () => escapeRegExp
+});
+module.exports = __toCommonJS(escape_exports);
+var import_spec = require("./spec");
+const maybeNativeEscape = RegExp.escape;
+const escapeRegExp = typeof maybeNativeEscape === "function" ? maybeNativeEscape : import_spec.escapeRegExpFallback;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  escapeRegExp
+});

package/dist/regexps/hex.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @file Hex-encoding helpers — fixed-width `\xHH` (`hex2`) and `\uHHHH`
+ *   (`hex4`) producers used by the spec-compliant `RegExp.escape` fallback to
+ *   emit canonical escape sequences.
+ */
+export declare function hex2(n: number): string;
+export declare function hex4(n: number): string;

package/dist/regexps/hex.js

@@ -0,0 +1,38 @@
+"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 hex_exports = {};
+__export(hex_exports, {
+  hex2: () => hex2,
+  hex4: () => hex4
+});
+module.exports = __toCommonJS(hex_exports);
+var import_number = require("../primordials/number");
+function hex2(n) {
+  return (0, import_number.NumberPrototypeToString)(n, 16).padStart(2, "0");
+}
+function hex4(n) {
+  return (0, import_number.NumberPrototypeToString)(n, 16).padStart(4, "0");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  hex2,
+  hex4
+});

package/dist/regexps/spec.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @file Spec-compliant fallback for the TC39 `RegExp.escape`
+ *   (https://tc39.es/ecma262/#sec-regexp.escape). Implements
+ *   `escapeRegExpFallback` plus the `isSpecHexEscapeCp` classifier used by both
+ *   the fallback and downstream callers. The fallback handles every branch of
+ *   the spec `EncodeForRegExpEscape` algorithm: leading [0-9A-Za-z] are always
+ *   `\xHH`-escaped (guards against `\0..\9` / `\c` merging in a larger
+ *   pattern), syntax characters (and `/`) get a plain backslash prefix, the
+ *   `ControlEscape` set maps to its `\t \n \v \f \r` names, the other
+ *   punctuators and the whitespace / line-terminator / lone-surrogate code
+ *   points route through `\xHH` or `\uHHHH`. Every other code point is emitted
+ *   verbatim.
+ */
+export declare function escapeRegExpFallback(str: string): string;
+export declare function isSpecHexEscapeCp(cp: number): boolean;

package/dist/{regexps.js → regexps/spec.js}

@@ -18,49 +18,31 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var regexps_exports = {};
-__export(regexps_exports, {
-  escapeRegExp: () => escapeRegExp
+var spec_exports = {};
+__export(spec_exports, {
+  escapeRegExpFallback: () => escapeRegExpFallback,
+  isSpecHexEscapeCp: () => isSpecHexEscapeCp
 });
-module.exports = __toCommonJS(regexps_exports);
-var import_primordials = require("./primordials");
-const SYNTAX_CHARACTERS = new import_primordials.SetCtor("^$\\.*+?()[]{}|/");
-const CONTROL_ESCAPES = new import_primordials.MapCtor([
+module.exports = __toCommonJS(spec_exports);
+var import_map_set = require("../primordials/map-set");
+var import_string = require("../primordials/string");
+var import_hex = require("./hex");
+const SYNTAX_CHARACTERS = new import_map_set.SetCtor("^$\\.*+?()[]{}|/");
+const CONTROL_ESCAPES = new import_map_set.MapCtor([
   [9, "\\t"],
   [10, "\\n"],
   [11, "\\v"],
   [12, "\\f"],
   [13, "\\r"]
 ]);
-const OTHER_PUNCTUATORS = new import_primordials.SetCtor(",-=<>#&!%:;@~'`\"");
-function isSpecHexEscapeCp(cp) {
-  if (OTHER_PUNCTUATORS.has((0, import_primordials.StringFromCodePoint)(cp))) {
-    return true;
-  }
-  if (cp === 10 || cp === 13 || cp === 8232 || cp === 8233) {
-    return true;
-  }
-  if (cp === 9 || cp === 11 || cp === 12 || cp === 32 || cp === 160 || cp === 65279) {
-    return true;
-  }
-  if (cp >= 55296 && cp <= 57343) {
-    return true;
-  }
-  return false;
-}
-function hex2(n) {
-  return (0, import_primordials.NumberPrototypeToString)(n, 16).padStart(2, "0");
-}
-function hex4(n) {
-  return (0, import_primordials.NumberPrototypeToString)(n, 16).padStart(4, "0");
-}
+const OTHER_PUNCTUATORS = new import_map_set.SetCtor(",-=<>#&!%:;@~'`\"");
 function escapeRegExpFallback(str) {
   let out = "";
   let isFirst = true;
   for (const char of str) {
-    const cp = (0, import_primordials.StringPrototypeCodePointAt)(char, 0);
+    const cp = (0, import_string.StringPrototypeCodePointAt)(char, 0);
     if (isFirst && (cp >= 48 && cp <= 57 || cp >= 65 && cp <= 90 || cp >= 97 && cp <= 122)) {
-      out += "\\x" + hex2(cp);
+      out += "\\x" + (0, import_hex.hex2)(cp);
     } else if (SYNTAX_CHARACTERS.has(char)) {
       out += "\\" + char;
     } else {
@@ -69,10 +51,10 @@ function escapeRegExpFallback(str) {
         out += ctrl;
       } else if (isSpecHexEscapeCp(cp)) {
         if (cp <= 255) {
-          out += "\\x" + hex2(cp);
+          out += "\\x" + (0, import_hex.hex2)(cp);
         } else {
           for (let i = 0; i < char.length; i++) {
-            out += "\\u" + hex4((0, import_primordials.StringPrototypeCharCodeAt)(char, i));
+            out += "\\u" + (0, import_hex.hex4)((0, import_string.StringPrototypeCharCodeAt)(char, i));
           }
         }
       } else {
@@ -83,9 +65,23 @@ function escapeRegExpFallback(str) {
   }
   return out;
 }
-const maybeNativeEscape = RegExp.escape;
-const escapeRegExp = typeof maybeNativeEscape === "function" ? maybeNativeEscape : escapeRegExpFallback;
+function isSpecHexEscapeCp(cp) {
+  if (OTHER_PUNCTUATORS.has((0, import_string.StringFromCodePoint)(cp))) {
+    return true;
+  }
+  if (cp === 10 || cp === 13 || cp === 8232 || cp === 8233) {
+    return true;
+  }
+  if (cp === 9 || cp === 11 || cp === 12 || cp === 32 || cp === 160 || cp === 65279) {
+    return true;
+  }
+  if (cp >= 55296 && cp <= 57343) {
+    return true;
+  }
+  return false;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  escapeRegExp
+  escapeRegExpFallback,
+  isSpecHexEscapeCp
 });