@socketsecurity/lib 5.28.0 → 6.0.1

package/dist/promises/iterate.js

@@ -0,0 +1,111 @@
+"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 iterate_exports = {};
+__export(iterate_exports, {
+  pEach: () => pEach,
+  pEachChunk: () => pEachChunk,
+  pFilter: () => pFilter,
+  pFilterChunk: () => pFilterChunk
+});
+module.exports = __toCommonJS(iterate_exports);
+var import_chunk = require("../arrays/chunk");
+var import_promise = require("../primordials/promise");
+var import_options = require("./options");
+var import_retry = require("./retry");
+// @__NO_SIDE_EFFECTS__
+async function pEach(array, callbackFn, options) {
+  const iterOpts = (0, import_options.normalizeIterationOptions)(options);
+  const { concurrency, retries, signal } = iterOpts;
+  const chunks = (0, import_chunk.arrayChunk)(array, concurrency);
+  for (const chunk of chunks) {
+    if (signal?.aborted) {
+      return;
+    }
+    await (0, import_promise.PromiseAllSettled)(
+      chunk.map(
+        (item) => (0, import_retry.pRetry)((...args) => callbackFn(args[0]), {
+          ...retries,
+          args: [item],
+          signal
+        })
+      )
+    );
+  }
+}
+// @__NO_SIDE_EFFECTS__
+async function pEachChunk(array, callbackFn, options) {
+  const { chunkSize = 100, ...retryOpts } = options || {};
+  const chunks = (0, import_chunk.arrayChunk)(array, chunkSize);
+  const normalizedRetryOpts = (0, import_options.normalizeRetryOptions)(retryOpts);
+  const { signal } = normalizedRetryOpts;
+  for (const chunk of chunks) {
+    if (signal?.aborted) {
+      return;
+    }
+    await (0, import_retry.pRetry)((...args) => callbackFn(args[0]), {
+      ...normalizedRetryOpts,
+      args: [chunk]
+    });
+  }
+}
+// @__NO_SIDE_EFFECTS__
+async function pFilter(array, callbackFn, options) {
+  const iterOpts = (0, import_options.normalizeIterationOptions)(options);
+  return (await /* @__PURE__ */ pFilterChunk(
+    (0, import_chunk.arrayChunk)(array, iterOpts.concurrency),
+    callbackFn,
+    iterOpts.retries
+  )).flat();
+}
+// @__NO_SIDE_EFFECTS__
+async function pFilterChunk(chunks, callbackFn, options) {
+  const retryOpts = (0, import_options.normalizeRetryOptions)(options);
+  const { signal } = retryOpts;
+  const { length } = chunks;
+  const filteredChunks = Array(length);
+  for (let i = 0; i < length; i += 1) {
+    if (signal?.aborted) {
+      filteredChunks[i] = [];
+    } else {
+      const chunk = chunks[i];
+      const settled = await (0, import_promise.PromiseAllSettled)(
+        chunk.map(
+          (value) => (0, import_retry.pRetry)((...args) => callbackFn(args[0]), {
+            ...retryOpts,
+            args: [value]
+          })
+        )
+      );
+      const predicateResults = settled.map(
+        (r) => r.status === "fulfilled" ? r.value : false
+      );
+      filteredChunks[i] = chunk.filter((_v, i2) => predicateResults[i2]);
+    }
+  }
+  return filteredChunks;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  pEach,
+  pEachChunk,
+  pFilter,
+  pFilterChunk
+});

package/dist/promises/options.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @file Option-shape normalizers for the iteration / retry helpers. Three free
+ *   functions — kept together because they're a tiny cluster of pure transforms
+ *   that callers cycle through: `resolveRetryOptions` (number-shorthand →
+ *   minimal object) → `normalizeRetryOptions` (defaults + signal binding) →
+ *   `normalizeIterationOptions` (concurrency + retries combined).
+ */
+import type { IterationOptions, RetryOptions } from './types';
+/**
+ * Normalize options for iteration functions.
+ *
+ * Converts various option formats into a consistent structure with defaults
+ * applied. Handles number shorthand for concurrency and ensures minimum
+ * values.
+ *
+ * @example
+ *   // Number shorthand for concurrency
+ *   normalizeIterationOptions(5)
+ *   // => { concurrency: 5, retries: {...}, signal: AbortSignal }
+ *
+ * @example
+ *   // Full options
+ *   normalizeIterationOptions({ concurrency: 3, retries: 2 })
+ *   // => { concurrency: 3, retries: {...}, signal: AbortSignal }
+ *
+ * @param options - Concurrency as number, or full options object, or undefined.
+ *
+ * @returns Normalized options with concurrency, retries, and signal
+ */
+export declare function normalizeIterationOptions(options?: number | IterationOptions | undefined): {
+    concurrency: number;
+    retries: RetryOptions;
+    signal: AbortSignal;
+};
+/**
+ * Normalize options for retry functionality.
+ *
+ * Converts various retry option formats into a complete configuration with all
+ * defaults. Handles legacy property names (`factor`, `minTimeout`,
+ * `maxTimeout`) and merges them with modern equivalents.
+ *
+ * @example
+ *   // Number shorthand
+ *   normalizeRetryOptions(3)
+ *   // => { retries: 3, baseDelayMs: 200, backoffFactor: 2, ... }
+ *
+ * @example
+ *   // Full options with defaults filled in
+ *   normalizeRetryOptions({ retries: 5, baseDelayMs: 500 })
+ *   // => { retries: 5, baseDelayMs: 500, backoffFactor: 2, jitter: true, ... }
+ *
+ * @param options - Retry count as number, or full options object, or undefined.
+ *
+ * @returns Normalized retry options with all properties set
+ */
+export declare function normalizeRetryOptions(options?: number | RetryOptions | undefined): RetryOptions;
+/**
+ * Resolve retry options from various input formats.
+ *
+ * Converts shorthand and partial options into a base configuration that can be
+ * further normalized. This is an internal helper for option processing.
+ *
+ * @example
+ *   resolveRetryOptions(3)
+ *   // => { retries: 3, minTimeout: 200, maxTimeout: 10000, factor: 2 }
+ *
+ * @example
+ *   resolveRetryOptions({ retries: 5, maxTimeout: 5000 })
+ *   // => { retries: 5, minTimeout: 200, maxTimeout: 5000, factor: 2 }
+ *
+ * @param options - Retry count as number, or partial options object, or
+ *   undefined.
+ *
+ * @returns Resolved retry options with defaults for basic properties
+ */
+export declare function resolveRetryOptions(options?: number | RetryOptions | undefined): RetryOptions;

package/dist/promises/options.js

@@ -0,0 +1,108 @@
+"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 options_exports = {};
+__export(options_exports, {
+  normalizeIterationOptions: () => normalizeIterationOptions,
+  normalizeRetryOptions: () => normalizeRetryOptions,
+  resolveRetryOptions: () => resolveRetryOptions
+});
+module.exports = __toCommonJS(options_exports);
+var import_math = require("../primordials/math");
+var import_internal = require("./_internal");
+// @__NO_SIDE_EFFECTS__
+function normalizeIterationOptions(options) {
+  const opts = typeof options === "number" ? { concurrency: options } : options;
+  const {
+    // The number of concurrent executions performed at one time.
+    concurrency = 1,
+    // Retries as a number or options object.
+    retries,
+    // AbortSignal used to support cancellation.
+    signal = import_internal.abortSignal
+  } = { __proto__: null, ...opts };
+  const normalizedConcurrency = (0, import_math.MathMax)(1, concurrency);
+  const retryOpts = /* @__PURE__ */ resolveRetryOptions(retries);
+  return {
+    __proto__: null,
+    concurrency: normalizedConcurrency,
+    retries: /* @__PURE__ */ normalizeRetryOptions({ signal, ...retryOpts }),
+    signal
+  };
+}
+// @__NO_SIDE_EFFECTS__
+function normalizeRetryOptions(options) {
+  const resolved = /* @__PURE__ */ resolveRetryOptions(options);
+  const {
+    // Arguments to pass to the callback function.
+    args = [],
+    // Multiplier for exponential backoff (e.g., 2 doubles delay each retry).
+    backoffFactor = 2,
+    // Initial delay before the first retry (in milliseconds).
+    baseDelayMs = 200,
+    // Whether to apply randomness to spread out retries.
+    jitter = true,
+    // Upper limit for any backoff delay (in milliseconds).
+    maxDelayMs = 1e4,
+    // Optional callback invoked on each retry attempt:
+    // (attempt: number, error: unknown, delay: number) => void
+    onRetry,
+    // Whether onRetry can cancel retries by returning `false`.
+    onRetryCancelOnFalse = false,
+    // Whether onRetry will rethrow errors.
+    onRetryRethrow = false,
+    // Number of retry attempts (0 = no retries, only initial attempt).
+    retries = 0,
+    // AbortSignal used to support cancellation.
+    signal = import_internal.abortSignal
+  } = resolved;
+  return {
+    args,
+    backoffFactor,
+    baseDelayMs,
+    jitter,
+    maxDelayMs,
+    onRetry,
+    onRetryCancelOnFalse,
+    onRetryRethrow,
+    retries,
+    signal
+  };
+}
+// @__NO_SIDE_EFFECTS__
+function resolveRetryOptions(options) {
+  const defaults = {
+    __proto__: null,
+    retries: 0,
+    baseDelayMs: 200,
+    maxDelayMs: 1e4,
+    backoffFactor: 2
+  };
+  if (typeof options === "number") {
+    return { ...defaults, retries: options };
+  }
+  return options ? { ...defaults, ...options } : defaults;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  normalizeIterationOptions,
+  normalizeRetryOptions,
+  resolveRetryOptions
+});

package/dist/promises/queue.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @file Bounded concurrency promise queue. Exports the `PromiseQueue` class,
+ *   which limits how many async tasks run simultaneously, supports an optional
+ *   max queue length (new tasks beyond the cap are rejected with "Task dropped:
+ *   queue length exceeded"), and exposes an idle-wait helper.
+ */
+export declare class PromiseQueue {
+    private queue;
+    private running;
+    private idleResolvers;
+    private readonly maxConcurrency;
+    private readonly maxQueueLength;
+    /**
+     * Creates a new PromiseQueue.
+     *
+     * @param maxConcurrency - Maximum number of promises that can run
+     *   concurrently.
+     * @param maxQueueLength - Maximum queue size; submissions past the cap reject
+     *   with "Task dropped: queue length exceeded" instead of evicting a caller
+     *   that has been waiting patiently. Callers must handle this rejection or
+     *   they'll see an unhandled rejection.
+     */
+    constructor(maxConcurrency: number, maxQueueLength?: number | undefined);
+    /**
+     * Add a task to the queue.
+     *
+     * @param fn - Async function to execute.
+     *
+     * @returns Promise that resolves with the function's result, or rejects with
+     *   "Task dropped: queue length exceeded" if the queue is full.
+     */
+    add<T>(fn: () => Promise<T>): Promise<T>;
+    private runNext;
+    private notifyIdleIfNeeded;
+    /**
+     * Wait for all queued and running tasks to complete.
+     */
+    onIdle(): Promise<void>;
+    /**
+     * Get the number of tasks currently running.
+     */
+    get activeCount(): number;
+    /**
+     * Get the number of tasks waiting in the queue.
+     */
+    get pendingCount(): number;
+    /**
+     * Clear all pending tasks from the queue (does not affect running tasks)
+     */
+    clear(): void;
+}

package/dist/{promise-queue.js → promises/queue.js}

@@ -18,12 +18,13 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var promise_queue_exports = {};
-__export(promise_queue_exports, {
+var queue_exports = {};
+__export(queue_exports, {
   PromiseQueue: () => PromiseQueue
 });
-module.exports = __toCommonJS(promise_queue_exports);
-var import_primordials = require("./primordials");
+module.exports = __toCommonJS(queue_exports);
+var import_error = require("../primordials/error");
+var import_promise = require("../primordials/promise");
 class PromiseQueue {
   queue = [];
   running = 0;
@@ -31,30 +32,34 @@ class PromiseQueue {
   maxConcurrency;
   maxQueueLength;
   /**
-   * Creates a new PromiseQueue
-   * @param maxConcurrency - Maximum number of promises that can run concurrently
-   * @param maxQueueLength - Maximum queue size; submissions past the cap
-   * reject with "Task dropped: queue length exceeded" instead of evicting
-   * a caller that has been waiting patiently. Callers must handle this
-   * rejection or they'll see an unhandled rejection.
+   * Creates a new PromiseQueue.
+   *
+   * @param maxConcurrency - Maximum number of promises that can run
+   *   concurrently.
+   * @param maxQueueLength - Maximum queue size; submissions past the cap reject
+   *   with "Task dropped: queue length exceeded" instead of evicting a caller
+   *   that has been waiting patiently. Callers must handle this rejection or
+   *   they'll see an unhandled rejection.
    */
   constructor(maxConcurrency, maxQueueLength) {
     this.maxConcurrency = maxConcurrency;
     this.maxQueueLength = maxQueueLength;
     if (maxConcurrency < 1) {
-      throw new import_primordials.ErrorCtor("maxConcurrency must be at least 1");
+      throw new import_error.ErrorCtor("maxConcurrency must be at least 1");
     }
   }
   /**
-   * Add a task to the queue
-   * @param fn - Async function to execute
-   * @returns Promise that resolves with the function's result, or rejects
-   * with "Task dropped: queue length exceeded" if the queue is full.
+   * Add a task to the queue.
+   *
+   * @param fn - Async function to execute.
+   *
+   * @returns Promise that resolves with the function's result, or rejects with
+   *   "Task dropped: queue length exceeded" if the queue is full.
    */
   async add(fn) {
-    return await new import_primordials.PromiseCtor((resolve, reject) => {
+    return await new import_promise.PromiseCtor((resolve, reject) => {
       if (this.maxQueueLength !== void 0 && this.queue.length >= this.maxQueueLength) {
-        reject(new import_primordials.ErrorCtor("Task dropped: queue length exceeded"));
+        reject(new import_error.ErrorCtor("Task dropped: queue length exceeded"));
         return;
       }
       const task = { fn, resolve, reject };
@@ -93,24 +98,24 @@ class PromiseQueue {
     }
   }
   /**
-   * Wait for all queued and running tasks to complete
+   * Wait for all queued and running tasks to complete.
    */
   async onIdle() {
     if (this.running === 0 && this.queue.length === 0) {
       return;
     }
-    return await new import_primordials.PromiseCtor((resolve) => {
+    return await new import_promise.PromiseCtor((resolve) => {
       this.idleResolvers.push(resolve);
     });
   }
   /**
-   * Get the number of tasks currently running
+   * Get the number of tasks currently running.
    */
   get activeCount() {
     return this.running;
   }
   /**
-   * Get the number of tasks waiting in the queue
+   * Get the number of tasks waiting in the queue.
    */
   get pendingCount() {
     return this.queue.length;
@@ -122,7 +127,7 @@ class PromiseQueue {
     const pending = this.queue;
     this.queue = [];
     for (const task of pending) {
-      task.reject(new import_primordials.ErrorCtor("Task cancelled: queue cleared"));
+      task.reject(new import_error.ErrorCtor("Task cancelled: queue cleared"));
     }
     this.notifyIdleIfNeeded();
   }

package/dist/promises/resolvers.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @file ECMA-262 standalone async helpers — `withResolvers`
+ *   (Promise.withResolvers) and `fromAsync` (Array.fromAsync). Both prefer the
+ *   captured primordial when present, with a spec-equivalent fallback for older
+ *   runtimes. Why this lives separate from `retry.ts` / `iterate.ts`: these are
+ *   direct mirrors of standardized JS APIs, not Socket-specific helpers. They
+ *   have no retry / concurrency surface to share with the rest of the module.
+ */
+import type { PromiseWithResolvers } from './types';
+/**
+ * Drain an async iterable into an array, per [TC39
+ * Array.fromAsync](https://tc39.es/proposal-array-from-async/).
+ *
+ * Uses the `ArrayFromAsync` primordial (already bound) when available (Node
+ * 22+; V8 ≥ 12.0); otherwise falls back to a `for await…of` + push loop.
+ *
+ * Use this instead of the manual `const out = []; for await (const x of iter)
+ * out.push(x); return out` dance when collecting an async iterator's values.
+ *
+ * Like the native, this only handles the unary form (no `mapFn` / `thisArg`
+ * overload).
+ *
+ * @example
+ *   ;```typescript
+ *   import { glob } from 'node:fs/promises'
+ *   const files = await fromAsync(glob('**\/*.ts', { cwd: '/tmp/proj' }))
+ *   ```
+ */
+export declare const fromAsync: <T>(source: AsyncIterable<T> | Iterable<T | PromiseLike<T>>) => Promise<T[]>;
+/**
+ * Create a pending promise together with its `resolve` and `reject` handles as
+ * first-class values, per [ECMA-262
+ * §27.2.4.9](https://tc39.es/ecma262/#sec-promise.withResolvers).
+ *
+ * Uses the `PromiseWithResolvers` primordial (already bound) when available
+ * (Node 20.12+ / 21+ / 22+; V8 ≥ 12.0); otherwise falls back to a
+ * spec-equivalent `new Promise(executor)` that captures the handles via
+ * closure. The returned object always has own data properties `promise`,
+ * `resolve`, `reject` on `Object.prototype` — writable, enumerable, and
+ * configurable — matching the spec's `CreateDataPropertyOrThrow` steps.
+ *
+ * Use this instead of the manual `let resolve; const p = new Promise(r => {
+ * resolve = r })` dance for deferred-resolution patterns (event-driven bridges,
+ * adapter layers, handshake signaling) where the settle path lives outside the
+ * executor.
+ *
+ * @example
+ *   ;```typescript
+ *   const { promise, resolve, reject } = withResolvers<string>()
+ *   emitter.once('ready', () => resolve('ok'))
+ *   emitter.once('error', err => reject(err))
+ *   const result = await promise
+ *   ```
+ */
+export declare const withResolvers: <T>() => PromiseWithResolvers<T>;

package/dist/promises/resolvers.js

@@ -0,0 +1,49 @@
+"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 resolvers_exports = {};
+__export(resolvers_exports, {
+  fromAsync: () => fromAsync,
+  withResolvers: () => withResolvers
+});
+module.exports = __toCommonJS(resolvers_exports);
+var import_array = require("../primordials/array");
+var import_promise = require("../primordials/promise");
+const fromAsync = import_array.ArrayFromAsync !== void 0 ? import_array.ArrayFromAsync : async (source) => {
+  const out = [];
+  for await (const item of source) {
+    out.push(item);
+  }
+  return out;
+};
+const withResolvers = import_promise.PromiseWithResolvers !== void 0 ? import_promise.PromiseWithResolvers : () => {
+  let resolve;
+  let reject;
+  const promise = new import_promise.PromiseCtor((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  fromAsync,
+  withResolvers
+});

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>;