@socketsecurity/lib 1.0.5 → 1.1.0

package/dist/promises.d.ts

@@ -1,67 +1,472 @@
+/**
+ * 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 {
-    args?: unknown[];
-    backoffFactor?: number;
-    baseDelayMs?: number;
-    factor?: number;
-    jitter?: boolean;
-    maxDelayMs?: number;
-    maxTimeout?: number;
-    minTimeout?: number;
-    onRetry?: (attempt: number, error: unknown, delay: number) => boolean | number | undefined;
-    onRetryCancelOnFalse?: boolean;
-    onRetryRethrow?: boolean;
-    retries?: number;
-    signal?: AbortSignal;
+    /**
+     * 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)`.
+     *
+     * @default 2
+     * @example
+     * // With backoffFactor: 2, baseDelayMs: 100
+     * // Retry 1: 100ms
+     * // Retry 2: 200ms
+     * // Retry 3: 400ms
+     */
+    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;
+    /**
+     * Legacy alias for `backoffFactor`. Use `backoffFactor` instead.
+     *
+     * @deprecated Use `backoffFactor` instead
+     * @default 2
+     */
+    factor?: 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.
+     *
+     * @default true
+     * @example
+     * // With jitter: true, delay: 100ms
+     * // Actual wait: 100ms + random(0-100ms) = 100-200ms
+     */
+    jitter?: boolean | undefined;
+    /**
+     * Upper limit for any backoff delay (in milliseconds).
+     * Prevents exponential backoff from growing unbounded.
+     *
+     * @default 10000
+     */
+    maxDelayMs?: number | undefined;
+    /**
+     * Legacy alias for `maxDelayMs`. Use `maxDelayMs` instead.
+     *
+     * @deprecated Use `maxDelayMs` instead
+     * @default 10000
+     */
+    maxTimeout?: number | undefined;
+    /**
+     * Legacy alias for `baseDelayMs`. Use `baseDelayMs` instead.
+     *
+     * @deprecated Use `baseDelayMs` instead
+     * @default 200
+     */
+    minTimeout?: number | undefined;
+    /**
+     * Callback invoked on each retry attempt.
+     * Can observe errors, customize delays, or cancel retries.
+     *
+     * @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
+     *
+     * @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, ...
+     */
+    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).
+     *
+     * @default 0
+     * @example
+     * // retries: 0 -> 1 total attempt (no retries)
+     * // retries: 3 -> 4 total attempts (1 initial + 3 retries)
+     */
+    retries?: number | undefined;
+    /**
+     * AbortSignal to support cancellation of retry operations.
+     * When aborted, immediately stops retrying and returns `undefined`.
+     *
+     * @default process abort signal
+     * @example
+     * const controller = new AbortController()
+     * pRetry(fn, { signal: controller.signal })
+     * // Later: controller.abort() to cancel
+     */
+    signal?: AbortSignal | undefined;
 }
+/**
+ * Configuration options for iteration functions with concurrency control.
+ *
+ * Controls how array operations are parallelized and retried.
+ */
 export interface IterationOptions {
-    concurrency?: number;
-    retries?: number | RetryOptions;
-    signal?: AbortSignal;
+    /**
+     * The number of concurrent executions performed at one time.
+     * Higher values increase parallelism but may overwhelm resources.
+     *
+     * @default 1
+     * @example
+     * // Process 5 items at a time
+     * await pEach(items, processItem, { concurrency: 5 })
+     */
+    concurrency?: number | undefined;
+    /**
+     * Retry configuration as a number (retry count) or full options object.
+     * Applied to each individual item's callback execution.
+     *
+     * @default 0 (no retries)
+     * @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
+     *   }
+     * })
+     */
+    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;
 }
 /**
  * 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.
+ *
+ * @param options - Concurrency as number, or full options object, or undefined
+ * @returns Normalized options with concurrency, retries, and signal
+ *
+ * @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 }
  */
 /*@__NO_SIDE_EFFECTS__*/
-export declare function normalizeIterationOptions(options?: number | IterationOptions): {
+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.
+ *
+ * @param options - Retry count as number, or full options object, or undefined
+ * @returns Normalized retry options with all properties set
+ *
+ * @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, ... }
  */
 /*@__NO_SIDE_EFFECTS__*/
-export declare function normalizeRetryOptions(options?: number | RetryOptions): RetryOptions;
+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.
+ *
+ * @param options - Retry count as number, or partial options object, or undefined
+ * @returns Resolved retry options with defaults for basic properties
+ *
+ * @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 }
  */
 /*@__NO_SIDE_EFFECTS__*/
-export declare function resolveRetryOptions(options?: number | RetryOptions): RetryOptions;
+export declare function resolveRetryOptions(options?: number | RetryOptions | undefined): RetryOptions;
 /**
  * Execute an async function for each array element with concurrency control.
+ *
+ * Processes array items in parallel batches (chunks) with configurable concurrency.
+ * Each item's callback can be retried independently on failure. Similar to
+ * `Promise.all(array.map(fn))` but with controlled parallelism.
+ *
+ * @template T - The type of array elements
+ * @param array - The array to iterate over
+ * @param callbackFn - Async function to execute for each item
+ * @param options - Concurrency as number, or full iteration options, or undefined
+ * @returns Promise that resolves when all items are processed
+ *
+ * @example
+ * // Process items serially (concurrency: 1)
+ * await pEach(urls, async (url) => {
+ *   await fetch(url)
+ * })
+ *
+ * @example
+ * // Process 5 items at a time
+ * await pEach(files, async (file) => {
+ *   await processFile(file)
+ * }, 5)
+ *
+ * @example
+ * // With retries and cancellation
+ * const controller = new AbortController()
+ * await pEach(tasks, async (task) => {
+ *   await executeTask(task)
+ * }, {
+ *   concurrency: 3,
+ *   retries: 2,
+ *   signal: controller.signal
+ * })
  */
 /*@__NO_SIDE_EFFECTS__*/
-export declare function pEach<T>(array: T[], callbackFn: (item: T) => Promise<unknown>, options?: number | IterationOptions): Promise<void>;
+export declare function pEach<T>(array: T[], callbackFn: (item: T) => Promise<unknown>, options?: number | IterationOptions | undefined): Promise<void>;
 /**
  * Filter an array asynchronously with concurrency control.
+ *
+ * Tests each element with an async predicate function, processing items in parallel
+ * batches. Returns a new array with only items that pass the test. Similar to
+ * `array.filter()` but for async predicates with controlled concurrency.
+ *
+ * @template T - The type of array elements
+ * @param array - The array to filter
+ * @param callbackFn - Async predicate function returning true to keep item
+ * @param options - Concurrency as number, or full iteration options, or undefined
+ * @returns Promise resolving to filtered array
+ *
+ * @example
+ * // Filter serially
+ * const activeUsers = await pFilter(users, async (user) => {
+ *   return await isUserActive(user.id)
+ * })
+ *
+ * @example
+ * // Filter with concurrency
+ * const validFiles = await pFilter(filePaths, async (path) => {
+ *   try {
+ *     await fs.access(path)
+ *     return true
+ *   } catch {
+ *     return false
+ *   }
+ * }, 10)
+ *
+ * @example
+ * // With retries for flaky checks
+ * const reachable = await pFilter(endpoints, async (url) => {
+ *   const response = await fetch(url)
+ *   return response.ok
+ * }, {
+ *   concurrency: 5,
+ *   retries: 2
+ * })
  */
 /*@__NO_SIDE_EFFECTS__*/
-export declare function pFilter<T>(array: T[], callbackFn: (item: T) => Promise<boolean>, options?: number | IterationOptions): Promise<T[]>;
+export declare function pFilter<T>(array: T[], callbackFn: (item: T) => Promise<boolean>, options?: number | IterationOptions | undefined): Promise<T[]>;
 /**
  * Process array in chunks with an async callback.
+ *
+ * Divides the array into fixed-size chunks and processes each chunk sequentially
+ * with the callback. Useful for batch operations like bulk database inserts or
+ * API calls with payload size limits.
+ *
+ * @template T - The type of array elements
+ * @param array - The array to process in chunks
+ * @param callbackFn - Async function to execute for each chunk
+ * @param options - Chunk size and retry options
+ * @returns Promise that resolves when all chunks are processed
+ *
+ * @example
+ * // Insert records in batches of 100
+ * await pEachChunk(records, async (chunk) => {
+ *   await db.batchInsert(chunk)
+ * }, { chunkSize: 100 })
+ *
+ * @example
+ * // Upload files in batches with retries
+ * await pEachChunk(files, async (batch) => {
+ *   await uploadBatch(batch)
+ * }, {
+ *   chunkSize: 50,
+ *   retries: 3,
+ *   baseDelayMs: 1000
+ * })
+ *
+ * @example
+ * // Process with cancellation support
+ * const controller = new AbortController()
+ * await pEachChunk(items, async (chunk) => {
+ *   await processChunk(chunk)
+ * }, {
+ *   chunkSize: 25,
+ *   signal: controller.signal
+ * })
  */
 /*@__NO_SIDE_EFFECTS__*/
-export declare function pEachChunk<T>(array: T[], callbackFn: (chunk: T[]) => Promise<unknown>, options?: RetryOptions & {
-    chunkSize?: number;
-}): Promise<void>;
+export declare function pEachChunk<T>(array: T[], callbackFn: (chunk: T[]) => Promise<unknown>, options?: (RetryOptions & {
+    chunkSize?: number | undefined;
+}) | undefined): Promise<void>;
 /**
  * Filter chunked arrays with an async predicate.
+ *
+ * Internal helper for `pFilter`. Processes pre-chunked arrays, applying the
+ * predicate to each element within each chunk with retry support.
+ *
+ * @template T - The type of array elements
+ * @param chunks - Pre-chunked array (array of arrays)
+ * @param callbackFn - Async predicate function
+ * @param options - Retry count as number, or full retry options, or undefined
+ * @returns Promise resolving to array of filtered chunks
+ *
+ * @example
+ * const chunks = [[1, 2], [3, 4], [5, 6]]
+ * const filtered = await pFilterChunk(chunks, async (n) => n % 2 === 0)
+ * // => [[2], [4], [6]]
  */
 /*@__NO_SIDE_EFFECTS__*/
-export declare function pFilterChunk<T>(chunks: T[][], callbackFn: (value: T) => Promise<boolean>, options?: number | RetryOptions): Promise<T[][]>;
+export declare function pFilterChunk<T>(chunks: T[][], callbackFn: (value: T) => Promise<boolean>, options?: number | RetryOptions | undefined): Promise<T[][]>;
 /**
  * Retry an async function with exponential backoff.
- * @throws {Error} The last error if all retries fail.
+ *
+ * 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.
+ *
+ * @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
+ *
+ * @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' }]
+ *   }
+ * )
  */
 /*@__NO_SIDE_EFFECTS__*/
-export declare function pRetry<T>(callbackFn: (...args: unknown[]) => Promise<T>, options?: number | RetryOptions): Promise<T | undefined>;
+export declare function pRetry<T>(callbackFn: (...args: unknown[]) => Promise<T>, options?: number | RetryOptions | undefined): Promise<T | undefined>;

package/dist/promises.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/promises.ts"],
-  "sourcesContent": ["/**\n * @fileoverview Promise utilities including chunked iteration and timers.\n * Provides async control flow helpers and promise-based timing functions.\n */\n\nimport { UNDEFINED_TOKEN } from '#constants/core'\nimport { getAbortSignal } from '#constants/process'\n\nimport { arrayChunk } from './arrays'\n\nconst abortSignal = getAbortSignal()\n\nexport interface RetryOptions {\n  args?: unknown[]\n  backoffFactor?: number\n  baseDelayMs?: number\n  factor?: number\n  jitter?: boolean\n  maxDelayMs?: number\n  maxTimeout?: number\n  minTimeout?: number\n  onRetry?: (\n    attempt: number,\n    error: unknown,\n    delay: number,\n  ) => boolean | number | undefined\n  onRetryCancelOnFalse?: boolean\n  onRetryRethrow?: boolean\n  retries?: number\n  signal?: AbortSignal\n}\n\nexport interface IterationOptions {\n  concurrency?: number\n  retries?: number | RetryOptions\n  signal?: AbortSignal\n}\n\nlet _timers: typeof import('node:timers/promises') | undefined\n/**\n * Get the timers/promises module.\n * @private\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction getTimers() {\n  if (_timers === undefined) {\n    // Use non-'node:' prefixed require to avoid Webpack errors.\n\n    _timers = /*@__PURE__*/ require('node:timers/promises')\n  }\n  return _timers as typeof import('node:timers/promises')\n}\n\n/**\n * Normalize options for iteration functions.\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function normalizeIterationOptions(\n  options?: number | IterationOptions,\n): { concurrency: number; retries: RetryOptions; signal: AbortSignal } {\n  // Handle number as concurrency shorthand\n  const opts = typeof options === 'number' ? { concurrency: options } : options\n\n  const {\n    // The number of concurrent executions performed at one time.\n    concurrency = 1,\n    // Retries as a number or options object.\n    retries,\n    // AbortSignal used to support cancellation.\n    signal = abortSignal,\n  } = { __proto__: null, ...opts } as IterationOptions\n\n  // Ensure concurrency is at least 1\n  const normalizedConcurrency = Math.max(1, concurrency)\n  const retryOpts = resolveRetryOptions(retries)\n  return {\n    __proto__: null,\n    concurrency: normalizedConcurrency,\n    retries: normalizeRetryOptions({ signal, ...retryOpts }),\n    signal,\n  } as { concurrency: number; retries: RetryOptions; signal: AbortSignal }\n}\n\n/**\n * Normalize options for retry functionality.\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function normalizeRetryOptions(\n  options?: number | RetryOptions,\n): RetryOptions {\n  const resolved = resolveRetryOptions(options)\n  const {\n    // Arguments to pass to the callback function.\n    args = [],\n    // Multiplier for exponential backoff (e.g., 2 doubles delay each retry).\n    backoffFactor = resolved.factor || 2,\n    // Initial delay before the first retry (in milliseconds).\n    baseDelayMs = resolved.minTimeout || 200,\n    // Whether to apply randomness to spread out retries.\n    jitter = true,\n    // Upper limit for any backoff delay (in milliseconds).\n    maxDelayMs = resolved.maxTimeout || 10_000,\n    // Optional callback invoked on each retry attempt:\n    // (attempt: number, error: unknown, delay: number) => void\n    onRetry,\n    // Whether onRetry can cancel retries by returning `false`.\n    onRetryCancelOnFalse = false,\n    // Whether onRetry will rethrow errors.\n    onRetryRethrow = false,\n    // Number of retry attempts (0 = no retries, only initial attempt).\n    retries = resolved.retries || 0,\n    // AbortSignal used to support cancellation.\n    signal = abortSignal,\n  } = resolved\n  return {\n    args,\n    backoffFactor,\n    baseDelayMs,\n    jitter,\n    maxDelayMs,\n    minTimeout: baseDelayMs,\n    maxTimeout: maxDelayMs,\n    onRetry,\n    onRetryCancelOnFalse,\n    onRetryRethrow,\n    retries,\n    signal,\n  } as RetryOptions\n}\n\n/**\n * Resolve retry options from various input formats.\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function resolveRetryOptions(\n  options?: number | RetryOptions,\n): RetryOptions {\n  const defaults = {\n    __proto__: null,\n    retries: 0,\n    minTimeout: 200,\n    maxTimeout: 10_000,\n    factor: 2,\n  }\n\n  if (typeof options === 'number') {\n    return { ...defaults, retries: options }\n  }\n\n  return options ? { ...defaults, ...options } : defaults\n}\n\n/**\n * Execute an async function for each array element with concurrency control.\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport async function pEach<T>(\n  array: T[],\n  callbackFn: (item: T) => Promise<unknown>,\n  options?: number | IterationOptions,\n): Promise<void> {\n  const iterOpts = normalizeIterationOptions(options)\n  const { concurrency, retries, signal } = iterOpts\n\n  // Process items with concurrency control.\n  const chunks = arrayChunk(array, concurrency)\n  for (const chunk of chunks) {\n    if (signal?.aborted) {\n      return\n    }\n    // Process each item in the chunk concurrently.\n    // eslint-disable-next-line no-await-in-loop\n    await Promise.all(\n      chunk.map((item: T) =>\n        pRetry((...args: unknown[]) => callbackFn(args[0] as T), {\n          ...retries,\n          args: [item],\n          signal,\n        }),\n      ),\n    )\n  }\n}\n\n/**\n * Filter an array asynchronously with concurrency control.\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport async function pFilter<T>(\n  array: T[],\n  callbackFn: (item: T) => Promise<boolean>,\n  options?: number | IterationOptions,\n): Promise<T[]> {\n  const iterOpts = normalizeIterationOptions(options)\n  return (\n    await pFilterChunk(\n      arrayChunk(array, iterOpts.concurrency),\n      callbackFn,\n      iterOpts.retries,\n    )\n  ).flat()\n}\n\n/**\n * Process array in chunks with an async callback.\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport async function pEachChunk<T>(\n  array: T[],\n  callbackFn: (chunk: T[]) => Promise<unknown>,\n  options?: RetryOptions & { chunkSize?: number },\n): Promise<void> {\n  const { chunkSize = 100, ...retryOpts } = options || {}\n  const chunks = arrayChunk(array, chunkSize)\n  const normalizedRetryOpts = normalizeRetryOptions(retryOpts)\n  const { signal } = normalizedRetryOpts\n  for (const chunk of chunks) {\n    if (signal?.aborted) {\n      return\n    }\n    // eslint-disable-next-line no-await-in-loop\n    await pRetry((...args: unknown[]) => callbackFn(args[0] as T[]), {\n      ...normalizedRetryOpts,\n      args: [chunk],\n    })\n  }\n}\n\n/**\n * Filter chunked arrays with an async predicate.\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport async function pFilterChunk<T>(\n  chunks: T[][],\n  callbackFn: (value: T) => Promise<boolean>,\n  options?: number | RetryOptions,\n): Promise<T[][]> {\n  const retryOpts = normalizeRetryOptions(options)\n  const { signal } = retryOpts\n  const { length } = chunks\n  const filteredChunks = Array(length)\n  for (let i = 0; i < length; i += 1) {\n    // Process each chunk, filtering based on the callback function.\n    if (signal?.aborted) {\n      filteredChunks[i] = []\n    } else {\n      const chunk = chunks[i] as T[]\n      // eslint-disable-next-line no-await-in-loop\n      const predicateResults = await Promise.all(\n        chunk.map(value =>\n          pRetry((...args: unknown[]) => callbackFn(args[0] as T), {\n            ...retryOpts,\n            args: [value],\n          }),\n        ),\n      )\n      filteredChunks[i] = chunk.filter((_v, i) => predicateResults[i])\n    }\n  }\n  return filteredChunks\n}\n\n/**\n * Retry an async function with exponential backoff.\n * @throws {Error} The last error if all retries fail.\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport async function pRetry<T>(\n  callbackFn: (...args: unknown[]) => Promise<T>,\n  options?: number | RetryOptions,\n): Promise<T | undefined> {\n  const {\n    args,\n    backoffFactor,\n    baseDelayMs,\n    jitter,\n    maxDelayMs,\n    onRetry,\n    onRetryCancelOnFalse,\n    onRetryRethrow,\n    retries,\n    signal,\n  } = normalizeRetryOptions(options)\n  if (signal?.aborted) {\n    return undefined\n  }\n  if (retries === 0) {\n    return await callbackFn(...(args || []), { signal })\n  }\n\n  const timers = getTimers()\n\n  let attempts = retries as number\n  let delay = baseDelayMs as number\n  let error: unknown = UNDEFINED_TOKEN\n\n  while (attempts-- >= 0) {\n    // Check abort before attempt.\n    if (signal?.aborted) {\n      return undefined\n    }\n\n    try {\n      // eslint-disable-next-line no-await-in-loop\n      return await callbackFn(...(args || []), { signal })\n    } catch (e) {\n      if (error === UNDEFINED_TOKEN) {\n        error = e\n      }\n      if (attempts < 0) {\n        break\n      }\n      let waitTime = delay\n      if (jitter) {\n        // Add randomness: Pick a value between 0 and `delay`.\n        waitTime += Math.floor(Math.random() * delay)\n      }\n      // Clamp wait time to max delay.\n      waitTime = Math.min(waitTime, maxDelayMs as number)\n      if (typeof onRetry === 'function') {\n        try {\n          const result = onRetry((retries as number) - attempts, e, waitTime)\n          if (result === false && onRetryCancelOnFalse) {\n            break\n          }\n          // If onRetry returns a number, use it as the custom delay.\n          if (typeof result === 'number' && result >= 0) {\n            waitTime = Math.min(result, maxDelayMs as number)\n          }\n        } catch (e) {\n          if (onRetryRethrow) {\n            throw e\n          }\n        }\n      }\n\n      try {\n        // eslint-disable-next-line no-await-in-loop\n        await timers.setTimeout(waitTime, undefined, { signal })\n      } catch {\n        // setTimeout was aborted.\n        return undefined\n      }\n\n      // Check abort again after delay.\n      if (signal?.aborted) {\n        return undefined\n      }\n\n      // Exponentially increase the delay for the next attempt, capping at maxDelayMs.\n      delay = Math.min(delay * (backoffFactor as number), maxDelayMs as number)\n    }\n  }\n  if (error !== UNDEFINED_TOKEN) {\n    throw error\n  }\n  return undefined\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["/**\n * @fileoverview Promise utilities including chunked iteration and timers.\n * Provides async control flow helpers and promise-based timing functions.\n */\n\nimport { UNDEFINED_TOKEN } from '#constants/core'\nimport { getAbortSignal } from '#constants/process'\n\nimport { arrayChunk } from './arrays'\n\nconst abortSignal = getAbortSignal()\n\n/**\n * Configuration options for retry behavior with exponential backoff.\n *\n * Controls how failed operations are retried, including timing, backoff strategy,\n * and callback hooks for observing or modifying retry behavior.\n */\nexport interface RetryOptions {\n  /**\n   * Arguments to pass to the callback function on each attempt.\n   *\n   * @default []\n   */\n  args?: unknown[] | undefined\n\n  /**\n   * Multiplier for exponential backoff (e.g., 2 doubles delay each retry).\n   * Each retry waits `baseDelayMs * (backoffFactor ** attemptNumber)`.\n   *\n   * @default 2\n   * @example\n   * // With backoffFactor: 2, baseDelayMs: 100\n   * // Retry 1: 100ms\n   * // Retry 2: 200ms\n   * // Retry 3: 400ms\n   */\n  backoffFactor?: number | undefined\n\n  /**\n   * Initial delay before the first retry (in milliseconds).\n   * This is the base value for exponential backoff calculations.\n   *\n   * @default 200\n   */\n  baseDelayMs?: number | undefined\n\n  /**\n   * Legacy alias for `backoffFactor`. Use `backoffFactor` instead.\n   *\n   * @deprecated Use `backoffFactor` instead\n   * @default 2\n   */\n  factor?: number | undefined\n\n  /**\n   * Whether to apply randomness to spread out retries and avoid thundering herd.\n   * When `true`, adds random delay between 0 and current delay value.\n   *\n   * @default true\n   * @example\n   * // With jitter: true, delay: 100ms\n   * // Actual wait: 100ms + random(0-100ms) = 100-200ms\n   */\n  jitter?: boolean | undefined\n\n  /**\n   * Upper limit for any backoff delay (in milliseconds).\n   * Prevents exponential backoff from growing unbounded.\n   *\n   * @default 10000\n   */\n  maxDelayMs?: number | undefined\n\n  /**\n   * Legacy alias for `maxDelayMs`. Use `maxDelayMs` instead.\n   *\n   * @deprecated Use `maxDelayMs` instead\n   * @default 10000\n   */\n  maxTimeout?: number | undefined\n\n  /**\n   * Legacy alias for `baseDelayMs`. Use `baseDelayMs` instead.\n   *\n   * @deprecated Use `baseDelayMs` instead\n   * @default 200\n   */\n  minTimeout?: number | undefined\n\n  /**\n   * Callback invoked on each retry attempt.\n   * Can observe errors, customize delays, or cancel retries.\n   *\n   * @param attempt - The current attempt number (1-based: 1, 2, 3, ...)\n   * @param error - The error that triggered this retry\n   * @param delay - The calculated delay in milliseconds before next retry\n   * @returns `false` to cancel retries (if `onRetryCancelOnFalse` is `true`),\n   *          a number to override the delay, or `undefined` to use calculated delay\n   *\n   * @example\n   * // Log each retry\n   * onRetry: (attempt, error, delay) => {\n   *   console.log(`Retry ${attempt} after ${delay}ms: ${error}`)\n   * }\n   *\n   * @example\n   * // Cancel retries for specific errors\n   * onRetry: (attempt, error) => {\n   *   if (error instanceof ValidationError) return false\n   * }\n   *\n   * @example\n   * // Use custom delay\n   * onRetry: (attempt) => attempt * 1000 // 1s, 2s, 3s, ...\n   */\n  onRetry?:\n    | ((\n        attempt: number,\n        error: unknown,\n        delay: number,\n      ) => boolean | number | undefined)\n    | undefined\n\n  /**\n   * Whether `onRetry` can cancel retries by returning `false`.\n   * When `true`, returning `false` from `onRetry` stops retry attempts.\n   *\n   * @default false\n   */\n  onRetryCancelOnFalse?: boolean | undefined\n\n  /**\n   * Whether errors thrown by `onRetry` should propagate.\n   * When `true`, exceptions in `onRetry` terminate the retry loop.\n   * When `false`, exceptions in `onRetry` are silently caught.\n   *\n   * @default false\n   */\n  onRetryRethrow?: boolean | undefined\n\n  /**\n   * Number of retry attempts (0 = no retries, only initial attempt).\n   * The callback is executed `retries + 1` times total (initial + retries).\n   *\n   * @default 0\n   * @example\n   * // retries: 0 -> 1 total attempt (no retries)\n   * // retries: 3 -> 4 total attempts (1 initial + 3 retries)\n   */\n  retries?: number | undefined\n\n  /**\n   * AbortSignal to support cancellation of retry operations.\n   * When aborted, immediately stops retrying and returns `undefined`.\n   *\n   * @default process abort signal\n   * @example\n   * const controller = new AbortController()\n   * pRetry(fn, { signal: controller.signal })\n   * // Later: controller.abort() to cancel\n   */\n  signal?: AbortSignal | undefined\n}\n\n/**\n * Configuration options for iteration functions with concurrency control.\n *\n * Controls how array operations are parallelized and retried.\n */\nexport interface IterationOptions {\n  /**\n   * The number of concurrent executions performed at one time.\n   * Higher values increase parallelism but may overwhelm resources.\n   *\n   * @default 1\n   * @example\n   * // Process 5 items at a time\n   * await pEach(items, processItem, { concurrency: 5 })\n   */\n  concurrency?: number | undefined\n\n  /**\n   * Retry configuration as a number (retry count) or full options object.\n   * Applied to each individual item's callback execution.\n   *\n   * @default 0 (no retries)\n   * @example\n   * // Simple: retry each item up to 3 times\n   * await pEach(items, fetchItem, { retries: 3 })\n   *\n   * @example\n   * // Advanced: custom backoff for each item\n   * await pEach(items, fetchItem, {\n   *   retries: {\n   *     retries: 3,\n   *     baseDelayMs: 1000,\n   *     backoffFactor: 2\n   *   }\n   * })\n   */\n  retries?: number | RetryOptions | undefined\n\n  /**\n   * AbortSignal to support cancellation of the entire iteration.\n   * When aborted, stops processing remaining items.\n   *\n   * @default process abort signal\n   */\n  signal?: AbortSignal | undefined\n}\n\nlet _timers: typeof import('node:timers/promises') | undefined\n/**\n * Get the timers/promises module.\n * Uses lazy loading to avoid Webpack bundling issues.\n *\n * @private\n * @returns The Node.js timers/promises module\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction getTimers() {\n  if (_timers === undefined) {\n    // Use non-'node:' prefixed require to avoid Webpack errors.\n\n    _timers = /*@__PURE__*/ require('node:timers/promises')\n  }\n  return _timers as typeof import('node:timers/promises')\n}\n\n/**\n * Normalize options for iteration functions.\n *\n * Converts various option formats into a consistent structure with defaults applied.\n * Handles number shorthand for concurrency and ensures minimum values.\n *\n * @param options - Concurrency as number, or full options object, or undefined\n * @returns Normalized options with concurrency, retries, and signal\n *\n * @example\n * // Number shorthand for concurrency\n * normalizeIterationOptions(5)\n * // => { concurrency: 5, retries: {...}, signal: AbortSignal }\n *\n * @example\n * // Full options\n * normalizeIterationOptions({ concurrency: 3, retries: 2 })\n * // => { concurrency: 3, retries: {...}, signal: AbortSignal }\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function normalizeIterationOptions(\n  options?: number | IterationOptions | undefined,\n): { concurrency: number; retries: RetryOptions; signal: AbortSignal } {\n  // Handle number as concurrency shorthand\n  const opts = typeof options === 'number' ? { concurrency: options } : options\n\n  const {\n    // The number of concurrent executions performed at one time.\n    concurrency = 1,\n    // Retries as a number or options object.\n    retries,\n    // AbortSignal used to support cancellation.\n    signal = abortSignal,\n  } = { __proto__: null, ...opts } as IterationOptions\n\n  // Ensure concurrency is at least 1\n  const normalizedConcurrency = Math.max(1, concurrency)\n  const retryOpts = resolveRetryOptions(retries)\n  return {\n    __proto__: null,\n    concurrency: normalizedConcurrency,\n    retries: normalizeRetryOptions({ signal, ...retryOpts }),\n    signal,\n  } as { concurrency: number; retries: RetryOptions; signal: AbortSignal }\n}\n\n/**\n * Normalize options for retry functionality.\n *\n * Converts various retry option formats into a complete configuration with all defaults.\n * Handles legacy property names (`factor`, `minTimeout`, `maxTimeout`) and merges them\n * with modern equivalents.\n *\n * @param options - Retry count as number, or full options object, or undefined\n * @returns Normalized retry options with all properties set\n *\n * @example\n * // Number shorthand\n * normalizeRetryOptions(3)\n * // => { retries: 3, baseDelayMs: 200, backoffFactor: 2, ... }\n *\n * @example\n * // Full options with defaults filled in\n * normalizeRetryOptions({ retries: 5, baseDelayMs: 500 })\n * // => { retries: 5, baseDelayMs: 500, backoffFactor: 2, jitter: true, ... }\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function normalizeRetryOptions(\n  options?: number | RetryOptions | undefined,\n): RetryOptions {\n  const resolved = resolveRetryOptions(options)\n  const {\n    // Arguments to pass to the callback function.\n    args = [],\n    // Multiplier for exponential backoff (e.g., 2 doubles delay each retry).\n    backoffFactor = resolved.factor || 2,\n    // Initial delay before the first retry (in milliseconds).\n    baseDelayMs = resolved.minTimeout || 200,\n    // Whether to apply randomness to spread out retries.\n    jitter = true,\n    // Upper limit for any backoff delay (in milliseconds).\n    maxDelayMs = resolved.maxTimeout || 10_000,\n    // Optional callback invoked on each retry attempt:\n    // (attempt: number, error: unknown, delay: number) => void\n    onRetry,\n    // Whether onRetry can cancel retries by returning `false`.\n    onRetryCancelOnFalse = false,\n    // Whether onRetry will rethrow errors.\n    onRetryRethrow = false,\n    // Number of retry attempts (0 = no retries, only initial attempt).\n    retries = resolved.retries || 0,\n    // AbortSignal used to support cancellation.\n    signal = abortSignal,\n  } = resolved\n  return {\n    args,\n    backoffFactor,\n    baseDelayMs,\n    jitter,\n    maxDelayMs,\n    minTimeout: baseDelayMs,\n    maxTimeout: maxDelayMs,\n    onRetry,\n    onRetryCancelOnFalse,\n    onRetryRethrow,\n    retries,\n    signal,\n  } as RetryOptions\n}\n\n/**\n * Resolve retry options from various input formats.\n *\n * Converts shorthand and partial options into a base configuration that can be\n * further normalized. This is an internal helper for option processing.\n *\n * @param options - Retry count as number, or partial options object, or undefined\n * @returns Resolved retry options with defaults for basic properties\n *\n * @example\n * resolveRetryOptions(3)\n * // => { retries: 3, minTimeout: 200, maxTimeout: 10000, factor: 2 }\n *\n * @example\n * resolveRetryOptions({ retries: 5, maxTimeout: 5000 })\n * // => { retries: 5, minTimeout: 200, maxTimeout: 5000, factor: 2 }\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function resolveRetryOptions(\n  options?: number | RetryOptions | undefined,\n): RetryOptions {\n  const defaults = {\n    __proto__: null,\n    retries: 0,\n    minTimeout: 200,\n    maxTimeout: 10_000,\n    factor: 2,\n  }\n\n  if (typeof options === 'number') {\n    return { ...defaults, retries: options }\n  }\n\n  return options ? { ...defaults, ...options } : defaults\n}\n\n/**\n * Execute an async function for each array element with concurrency control.\n *\n * Processes array items in parallel batches (chunks) with configurable concurrency.\n * Each item's callback can be retried independently on failure. Similar to\n * `Promise.all(array.map(fn))` but with controlled parallelism.\n *\n * @template T - The type of array elements\n * @param array - The array to iterate over\n * @param callbackFn - Async function to execute for each item\n * @param options - Concurrency as number, or full iteration options, or undefined\n * @returns Promise that resolves when all items are processed\n *\n * @example\n * // Process items serially (concurrency: 1)\n * await pEach(urls, async (url) => {\n *   await fetch(url)\n * })\n *\n * @example\n * // Process 5 items at a time\n * await pEach(files, async (file) => {\n *   await processFile(file)\n * }, 5)\n *\n * @example\n * // With retries and cancellation\n * const controller = new AbortController()\n * await pEach(tasks, async (task) => {\n *   await executeTask(task)\n * }, {\n *   concurrency: 3,\n *   retries: 2,\n *   signal: controller.signal\n * })\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport async function pEach<T>(\n  array: T[],\n  callbackFn: (item: T) => Promise<unknown>,\n  options?: number | IterationOptions | undefined,\n): Promise<void> {\n  const iterOpts = normalizeIterationOptions(options)\n  const { concurrency, retries, signal } = iterOpts\n\n  // Process items with concurrency control.\n  const chunks = arrayChunk(array, concurrency)\n  for (const chunk of chunks) {\n    if (signal?.aborted) {\n      return\n    }\n    // Process each item in the chunk concurrently.\n    // eslint-disable-next-line no-await-in-loop\n    await Promise.all(\n      chunk.map((item: T) =>\n        pRetry((...args: unknown[]) => callbackFn(args[0] as T), {\n          ...retries,\n          args: [item],\n          signal,\n        }),\n      ),\n    )\n  }\n}\n\n/**\n * Filter an array asynchronously with concurrency control.\n *\n * Tests each element with an async predicate function, processing items in parallel\n * batches. Returns a new array with only items that pass the test. Similar to\n * `array.filter()` but for async predicates with controlled concurrency.\n *\n * @template T - The type of array elements\n * @param array - The array to filter\n * @param callbackFn - Async predicate function returning true to keep item\n * @param options - Concurrency as number, or full iteration options, or undefined\n * @returns Promise resolving to filtered array\n *\n * @example\n * // Filter serially\n * const activeUsers = await pFilter(users, async (user) => {\n *   return await isUserActive(user.id)\n * })\n *\n * @example\n * // Filter with concurrency\n * const validFiles = await pFilter(filePaths, async (path) => {\n *   try {\n *     await fs.access(path)\n *     return true\n *   } catch {\n *     return false\n *   }\n * }, 10)\n *\n * @example\n * // With retries for flaky checks\n * const reachable = await pFilter(endpoints, async (url) => {\n *   const response = await fetch(url)\n *   return response.ok\n * }, {\n *   concurrency: 5,\n *   retries: 2\n * })\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport async function pFilter<T>(\n  array: T[],\n  callbackFn: (item: T) => Promise<boolean>,\n  options?: number | IterationOptions | undefined,\n): Promise<T[]> {\n  const iterOpts = normalizeIterationOptions(options)\n  return (\n    await pFilterChunk(\n      arrayChunk(array, iterOpts.concurrency),\n      callbackFn,\n      iterOpts.retries,\n    )\n  ).flat()\n}\n\n/**\n * Process array in chunks with an async callback.\n *\n * Divides the array into fixed-size chunks and processes each chunk sequentially\n * with the callback. Useful for batch operations like bulk database inserts or\n * API calls with payload size limits.\n *\n * @template T - The type of array elements\n * @param array - The array to process in chunks\n * @param callbackFn - Async function to execute for each chunk\n * @param options - Chunk size and retry options\n * @returns Promise that resolves when all chunks are processed\n *\n * @example\n * // Insert records in batches of 100\n * await pEachChunk(records, async (chunk) => {\n *   await db.batchInsert(chunk)\n * }, { chunkSize: 100 })\n *\n * @example\n * // Upload files in batches with retries\n * await pEachChunk(files, async (batch) => {\n *   await uploadBatch(batch)\n * }, {\n *   chunkSize: 50,\n *   retries: 3,\n *   baseDelayMs: 1000\n * })\n *\n * @example\n * // Process with cancellation support\n * const controller = new AbortController()\n * await pEachChunk(items, async (chunk) => {\n *   await processChunk(chunk)\n * }, {\n *   chunkSize: 25,\n *   signal: controller.signal\n * })\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport async function pEachChunk<T>(\n  array: T[],\n  callbackFn: (chunk: T[]) => Promise<unknown>,\n  options?: (RetryOptions & { chunkSize?: number | undefined }) | undefined,\n): Promise<void> {\n  const { chunkSize = 100, ...retryOpts } = options || {}\n  const chunks = arrayChunk(array, chunkSize)\n  const normalizedRetryOpts = normalizeRetryOptions(retryOpts)\n  const { signal } = normalizedRetryOpts\n  for (const chunk of chunks) {\n    if (signal?.aborted) {\n      return\n    }\n    // eslint-disable-next-line no-await-in-loop\n    await pRetry((...args: unknown[]) => callbackFn(args[0] as T[]), {\n      ...normalizedRetryOpts,\n      args: [chunk],\n    })\n  }\n}\n\n/**\n * Filter chunked arrays with an async predicate.\n *\n * Internal helper for `pFilter`. Processes pre-chunked arrays, applying the\n * predicate to each element within each chunk with retry support.\n *\n * @template T - The type of array elements\n * @param chunks - Pre-chunked array (array of arrays)\n * @param callbackFn - Async predicate function\n * @param options - Retry count as number, or full retry options, or undefined\n * @returns Promise resolving to array of filtered chunks\n *\n * @example\n * const chunks = [[1, 2], [3, 4], [5, 6]]\n * const filtered = await pFilterChunk(chunks, async (n) => n % 2 === 0)\n * // => [[2], [4], [6]]\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport async function pFilterChunk<T>(\n  chunks: T[][],\n  callbackFn: (value: T) => Promise<boolean>,\n  options?: number | RetryOptions | undefined,\n): Promise<T[][]> {\n  const retryOpts = normalizeRetryOptions(options)\n  const { signal } = retryOpts\n  const { length } = chunks\n  const filteredChunks = Array(length)\n  for (let i = 0; i < length; i += 1) {\n    // Process each chunk, filtering based on the callback function.\n    if (signal?.aborted) {\n      filteredChunks[i] = []\n    } else {\n      const chunk = chunks[i] as T[]\n      // eslint-disable-next-line no-await-in-loop\n      const predicateResults = await Promise.all(\n        chunk.map(value =>\n          pRetry((...args: unknown[]) => callbackFn(args[0] as T), {\n            ...retryOpts,\n            args: [value],\n          }),\n        ),\n      )\n      filteredChunks[i] = chunk.filter((_v, i) => predicateResults[i])\n    }\n  }\n  return filteredChunks\n}\n\n/**\n * Retry an async function with exponential backoff.\n *\n * Attempts to execute a function multiple times with increasing delays between attempts.\n * Implements exponential backoff with optional jitter to prevent thundering herd problems.\n * Supports custom retry logic via `onRetry` callback.\n *\n * The delay calculation follows: `min(baseDelayMs * (backoffFactor ** attempt), maxDelayMs)`\n * With jitter: adds random value between 0 and calculated delay.\n *\n * @template T - The return type of the callback function\n * @param callbackFn - Async function to retry\n * @param options - Retry count as number, or full retry options, or undefined\n * @returns Promise resolving to callback result, or `undefined` if aborted\n *\n * @throws {Error} The last error if all retry attempts fail\n *\n * @example\n * // Simple retry: 3 attempts with default backoff\n * const data = await pRetry(async () => {\n *   return await fetchData()\n * }, 3)\n *\n * @example\n * // Custom backoff strategy\n * const result = await pRetry(async () => {\n *   return await unreliableOperation()\n * }, {\n *   retries: 5,\n *   baseDelayMs: 1000,    // Start at 1 second\n *   backoffFactor: 2,      // Double each time\n *   maxDelayMs: 30000,     // Cap at 30 seconds\n *   jitter: true           // Add randomness\n * })\n * // Delays: ~1s, ~2s, ~4s, ~8s, ~16s (each \u00B1 random jitter)\n *\n * @example\n * // With custom retry logic\n * const data = await pRetry(async () => {\n *   return await apiCall()\n * }, {\n *   retries: 3,\n *   onRetry: (attempt, error, delay) => {\n *     console.log(`Attempt ${attempt} failed: ${error}`)\n *     console.log(`Waiting ${delay}ms before retry...`)\n *\n *     // Cancel retries for client errors (4xx)\n *     if (error.statusCode >= 400 && error.statusCode < 500) {\n *       return false\n *     }\n *\n *     // Use longer delay for rate limit errors\n *     if (error.statusCode === 429) {\n *       return 60000 // Wait 1 minute\n *     }\n *   },\n *   onRetryCancelOnFalse: true\n * })\n *\n * @example\n * // With cancellation support\n * const controller = new AbortController()\n * setTimeout(() => controller.abort(), 5000) // Cancel after 5s\n *\n * const result = await pRetry(async ({ signal }) => {\n *   return await longRunningTask(signal)\n * }, {\n *   retries: 10,\n *   signal: controller.signal\n * })\n * // Returns undefined if aborted\n *\n * @example\n * // Pass arguments to callback\n * const result = await pRetry(\n *   async (url, options) => {\n *     return await fetch(url, options)\n *   },\n *   {\n *     retries: 3,\n *     args: ['https://api.example.com', { method: 'POST' }]\n *   }\n * )\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport async function pRetry<T>(\n  callbackFn: (...args: unknown[]) => Promise<T>,\n  options?: number | RetryOptions | undefined,\n): Promise<T | undefined> {\n  const {\n    args,\n    backoffFactor,\n    baseDelayMs,\n    jitter,\n    maxDelayMs,\n    onRetry,\n    onRetryCancelOnFalse,\n    onRetryRethrow,\n    retries,\n    signal,\n  } = normalizeRetryOptions(options)\n  if (signal?.aborted) {\n    return undefined\n  }\n  if (retries === 0) {\n    return await callbackFn(...(args || []), { signal })\n  }\n\n  const timers = getTimers()\n\n  let attempts = retries as number\n  let delay = baseDelayMs as number\n  let error: unknown = UNDEFINED_TOKEN\n\n  while (attempts-- >= 0) {\n    // Check abort before attempt.\n    if (signal?.aborted) {\n      return undefined\n    }\n\n    try {\n      // eslint-disable-next-line no-await-in-loop\n      return await callbackFn(...(args || []), { signal })\n    } catch (e) {\n      if (error === UNDEFINED_TOKEN) {\n        error = e\n      }\n      if (attempts < 0) {\n        break\n      }\n      let waitTime = delay\n      if (jitter) {\n        // Add randomness: Pick a value between 0 and `delay`.\n        waitTime += Math.floor(Math.random() * delay)\n      }\n      // Clamp wait time to max delay.\n      waitTime = Math.min(waitTime, maxDelayMs as number)\n      if (typeof onRetry === 'function') {\n        try {\n          const result = onRetry((retries as number) - attempts, e, waitTime)\n          if (result === false && onRetryCancelOnFalse) {\n            break\n          }\n          // If onRetry returns a number, use it as the custom delay.\n          if (typeof result === 'number' && result >= 0) {\n            waitTime = Math.min(result, maxDelayMs as number)\n          }\n        } catch (e) {\n          if (onRetryRethrow) {\n            throw e\n          }\n        }\n      }\n\n      try {\n        // eslint-disable-next-line no-await-in-loop\n        await timers.setTimeout(waitTime, undefined, { signal })\n      } catch {\n        // setTimeout was aborted.\n        return undefined\n      }\n\n      // Check abort again after delay.\n      if (signal?.aborted) {\n        return undefined\n      }\n\n      // Exponentially increase the delay for the next attempt, capping at maxDelayMs.\n      delay = Math.min(delay * (backoffFactor as number), maxDelayMs as number)\n    }\n  }\n  if (error !== UNDEFINED_TOKEN) {\n    throw error\n  }\n  return undefined\n}\n"],
+  "mappings": "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",
   "names": ["i", "e"]
 }