actly 1.2.0 → 1.3.0

package/dist/utils/abort.cjs

@@ -1,51 +1,19 @@
 "use strict";
-// ─── AbortSignal helpers ──────────────────────────────────────────────────────
-//
-// Contract: zero listener accumulation on long-lived AbortSignals.
-//
-// Every `addEventListener('abort', ...)` MUST be paired with a
-// `removeEventListener` on the success path, OR use `AbortSignal.any()`
-// (Node 20+ native) which handles cleanup automatically.
-//
-// Long-lived signals (server shutdown, request pool) must not accumulate
-// one listener per `act()` call — that would cause
-// `MaxListenersExceededWarning` and unbounded closure retention.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.anySignal = anySignal;
 exports.raceAbort = raceAbort;
 exports.sleep = sleep;
 exports.isAbortError = isAbortError;
 exports.linkSignal = linkSignal;
-/**
- * Compose multiple AbortSignals into one. Aborts when ANY input aborts,
- * with the same reason.
- *
- * Uses native `AbortSignal.any()` on Node 20+ (zero allocations, no
- * listener leaks — the runtime owns the lifecycle). Falls back to a
- * polyfill that explicitly removes listeners on first abort.
- *
- * # Listener safety
- *
- * The polyfill registers `{ once: true }` listeners on each input and
- * manually removes the others when one fires. After settlement, the
- * composite signal holds zero references to the inputs — they may be GC'd.
- */
+const NATIVE_ANY = AbortSignal.any;
 function anySignal(signals) {
-    // Filter out undefined / null defensively.
     const filtered = signals.filter((s) => s != null);
-    if (filtered.length === 0) {
-        // No inputs → never-aborting signal. Use a fresh controller so callers
-        // get a real AbortSignal, not a hand-rolled mock.
+    if (filtered.length === 0)
         return new AbortController().signal;
-    }
     if (filtered.length === 1)
         return filtered[0];
-    // Native path (Node 20+, modern browsers, Bun).
-    const native = AbortSignal.any;
-    if (typeof native === 'function') {
-        return native.call(AbortSignal, filtered);
-    }
-    // Polyfill: only used when native is missing. Listener-safe.
+    if (NATIVE_ANY)
+        return NATIVE_ANY.call(AbortSignal, filtered);
     const controller = new AbortController();
     const listeners = [];
     for (const signal of filtered) {
@@ -55,41 +23,20 @@ function anySignal(signals) {
         }
         const onAbort = () => {
             controller.abort(signal.reason);
-            // Remove all other listeners — they hold closures over `signal`
-            // and would otherwise keep the inputs alive past settlement.
             for (const off of listeners)
                 off();
         };
         signal.addEventListener('abort', onAbort, { once: true });
         listeners.push(() => signal.removeEventListener('abort', onAbort));
     }
+    if (controller.signal.aborted) {
+        for (const off of listeners)
+            off();
+    }
     return controller.signal;
 }
-/**
- * Race a promise against an AbortSignal.
- *
- * - If the signal is already aborted, rejects immediately with `signal.reason`.
- * - If the signal aborts while the promise is pending, rejects with `signal.reason`.
- * - If the promise settles first, returns its value (or rejects with its error).
- *
- * # Listener safety
- *
- * On success path, the abort listener is explicitly removed. A
- * `{ once: true }` listener would stay attached on long-lived signals,
- * leaking one closure per call.
- *
- * # Mark-as-handled
- *
- * When the signal aborts first, the original `promise` may still settle
- * later (success or failure). We attach a no-op `.catch` to it so V8
- * doesn't emit an `unhandledRejection` warning. The error is NOT
- * swallowed from the caller — the caller already received `signal.reason`.
- */
 function raceAbort(promise, signal) {
     if (signal.aborted) {
-        // Mark the promise as handled — its eventual rejection won't surface
-        // as an unhandled rejection. Its eventual success is dropped silently,
-        // which is correct: the caller has already moved on.
         promise.catch(() => { });
         return Promise.reject(signal.reason);
     }
@@ -102,8 +49,6 @@ function raceAbort(promise, signal) {
             signal.removeEventListener('abort', onAbort);
             reject(signal.reason);
         };
-        // Not using `{ once: true }` — we want explicit removal on success
-        // path so the listener doesn't linger on a long-lived signal.
         signal.addEventListener('abort', onAbort);
         promise.then((value) => {
             if (settled)
@@ -120,20 +65,7 @@ function raceAbort(promise, signal) {
         });
     });
 }
-/**
- * Sleep for `ms` milliseconds, but abort early if `signal` fires.
- *
- * Resolves normally on timer expiry. Rejects with `signal.reason` if the
- * signal aborts before the timer fires. If the signal is already aborted
- * when called, rejects synchronously (in microtask).
- *
- * # Timer hygiene
- *
- * The internal `setTimeout` is `unref`'d on Node so it doesn't keep the
- * event loop alive solely for this sleep. On browsers there is no
- * equivalent — the timer is short-lived enough not to matter.
- */
-function sleep(ms, signal) {
+function sleep(ms, signal, opts) {
     if (ms <= 0) {
         if (signal?.aborted)
             return Promise.reject(signal.reason);
@@ -146,12 +78,9 @@ function sleep(ms, signal) {
             signal?.removeEventListener('abort', onAbort);
             resolve();
         }, ms);
-        // NOTE: do NOT `unref()` this timer. Unlike InMemoryStore's autoCleanup
-        // interval (which is a background housekeeping task), `sleep()` IS the
-        // operation the caller is awaiting. If we unref'd it, Node could exit
-        // the process while a retry delay was pending — silently dropping the
-        // operation. The timer is short-lived (cleared in onAbort or after ms),
-        // so the cost of keeping the loop alive is bounded.
+        if (opts?.unref && typeof timer.unref === 'function') {
+            timer.unref();
+        }
         const onAbort = () => {
             clearTimeout(timer);
             reject(signal.reason);
@@ -159,20 +88,14 @@ function sleep(ms, signal) {
         signal?.addEventListener('abort', onAbort);
     });
 }
-/**
- * True if `err` is an `AbortError` (DOMException name or Error name).
- *
- * The default `shouldRetry` predicate uses this to skip retrying on
- * cancellations — if the caller aborted, retrying would just abort again.
- */
 function isAbortError(err) {
     if (err == null || typeof err !== 'object')
         return false;
+    if (err.code === 'ACTLY_ABORT')
+        return true;
     const name = err.name;
     if (name === 'AbortError')
         return true;
-    // DOMException with name 'TimeoutError' is what AbortSignal.timeout throws.
-    // Distinguish from our own TimeoutError class by checking for DOMException.
     if (name === 'TimeoutError' &&
         err instanceof Error &&
         typeof DOMException !== 'undefined' &&
@@ -181,26 +104,6 @@ function isAbortError(err) {
     }
     return false;
 }
-/**
- * Link a parent signal to a child controller: when the parent aborts, the
- * child is aborted with the same reason.
- *
- * # Contract
- *
- * Returns an `unlink()` function that removes the listener. Callers MUST
- * call `unlink()` on success path — otherwise the listener stays attached
- * to the parent forever, leaking one closure per call.
- *
- * If the parent is already aborted, the child is aborted synchronously
- * and `unlink` is a no-op.
- *
- * # Prefer `anySignal()` instead
- *
- * For new code, prefer `anySignal([parent, timeoutSignal])` which uses
- * the native Node 20+ implementation and handles cleanup automatically.
- * This function exists for call sites that need an `AbortController`
- * (not just a signal) — e.g. to layer additional abort sources.
- */
 function linkSignal(parent, child) {
     if (parent.aborted) {
         child.abort(parent.reason);

package/dist/utils/abort.d.ts

@@ -1,79 +1,8 @@
-/**
- * Compose multiple AbortSignals into one. Aborts when ANY input aborts,
- * with the same reason.
- *
- * Uses native `AbortSignal.any()` on Node 20+ (zero allocations, no
- * listener leaks — the runtime owns the lifecycle). Falls back to a
- * polyfill that explicitly removes listeners on first abort.
- *
- * # Listener safety
- *
- * The polyfill registers `{ once: true }` listeners on each input and
- * manually removes the others when one fires. After settlement, the
- * composite signal holds zero references to the inputs — they may be GC'd.
- */
 export declare function anySignal(signals: ReadonlyArray<AbortSignal>): AbortSignal;
-/**
- * Race a promise against an AbortSignal.
- *
- * - If the signal is already aborted, rejects immediately with `signal.reason`.
- * - If the signal aborts while the promise is pending, rejects with `signal.reason`.
- * - If the promise settles first, returns its value (or rejects with its error).
- *
- * # Listener safety
- *
- * On success path, the abort listener is explicitly removed. A
- * `{ once: true }` listener would stay attached on long-lived signals,
- * leaking one closure per call.
- *
- * # Mark-as-handled
- *
- * When the signal aborts first, the original `promise` may still settle
- * later (success or failure). We attach a no-op `.catch` to it so V8
- * doesn't emit an `unhandledRejection` warning. The error is NOT
- * swallowed from the caller — the caller already received `signal.reason`.
- */
 export declare function raceAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T>;
-/**
- * Sleep for `ms` milliseconds, but abort early if `signal` fires.
- *
- * Resolves normally on timer expiry. Rejects with `signal.reason` if the
- * signal aborts before the timer fires. If the signal is already aborted
- * when called, rejects synchronously (in microtask).
- *
- * # Timer hygiene
- *
- * The internal `setTimeout` is `unref`'d on Node so it doesn't keep the
- * event loop alive solely for this sleep. On browsers there is no
- * equivalent — the timer is short-lived enough not to matter.
- */
-export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
-/**
- * True if `err` is an `AbortError` (DOMException name or Error name).
- *
- * The default `shouldRetry` predicate uses this to skip retrying on
- * cancellations — if the caller aborted, retrying would just abort again.
- */
+export declare function sleep(ms: number, signal?: AbortSignal, opts?: {
+    unref?: boolean;
+}): Promise<void>;
 export declare function isAbortError(err: unknown): boolean;
-/**
- * Link a parent signal to a child controller: when the parent aborts, the
- * child is aborted with the same reason.
- *
- * # Contract
- *
- * Returns an `unlink()` function that removes the listener. Callers MUST
- * call `unlink()` on success path — otherwise the listener stays attached
- * to the parent forever, leaking one closure per call.
- *
- * If the parent is already aborted, the child is aborted synchronously
- * and `unlink` is a no-op.
- *
- * # Prefer `anySignal()` instead
- *
- * For new code, prefer `anySignal([parent, timeoutSignal])` which uses
- * the native Node 20+ implementation and handles cleanup automatically.
- * This function exists for call sites that need an `AbortController`
- * (not just a signal) — e.g. to layer additional abort sources.
- */
 export declare function linkSignal(parent: AbortSignal, child: AbortController): () => void;
 //# sourceMappingURL=abort.d.ts.map

package/dist/utils/abort.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../../src/utils/abort.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,WAAW,CAsC1E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,CAAC,CAAC,CAsCZ;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BrE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAelD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,eAAe,GACrB,MAAM,IAAI,CAQZ"}
+{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../../src/utils/abort.ts"],"names":[],"mappings":"AAaA,wBAAgB,SAAS,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,WAAW,CAgC1E;AAOD,wBAAgB,SAAS,CAAC,CAAC,EACzB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,CAAC,CAAC,CAmCZ;AAWD,wBAAgB,KAAK,CACnB,EAAE,EAAE,MAAM,EACV,MAAM,CAAC,EAAE,WAAW,EACpB,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACzB,OAAO,CAAC,IAAI,CAAC,CAyBf;AAQD,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAelD;AASD,wBAAgB,UAAU,CACxB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,eAAe,GACrB,MAAM,IAAI,CAQZ"}

package/dist/utils/abort.js

@@ -1,44 +1,12 @@
-// ─── AbortSignal helpers ──────────────────────────────────────────────────────
-//
-// Contract: zero listener accumulation on long-lived AbortSignals.
-//
-// Every `addEventListener('abort', ...)` MUST be paired with a
-// `removeEventListener` on the success path, OR use `AbortSignal.any()`
-// (Node 20+ native) which handles cleanup automatically.
-//
-// Long-lived signals (server shutdown, request pool) must not accumulate
-// one listener per `act()` call — that would cause
-// `MaxListenersExceededWarning` and unbounded closure retention.
-/**
- * Compose multiple AbortSignals into one. Aborts when ANY input aborts,
- * with the same reason.
- *
- * Uses native `AbortSignal.any()` on Node 20+ (zero allocations, no
- * listener leaks — the runtime owns the lifecycle). Falls back to a
- * polyfill that explicitly removes listeners on first abort.
- *
- * # Listener safety
- *
- * The polyfill registers `{ once: true }` listeners on each input and
- * manually removes the others when one fires. After settlement, the
- * composite signal holds zero references to the inputs — they may be GC'd.
- */
+const NATIVE_ANY = AbortSignal.any;
 export function anySignal(signals) {
-    // Filter out undefined / null defensively.
     const filtered = signals.filter((s) => s != null);
-    if (filtered.length === 0) {
-        // No inputs → never-aborting signal. Use a fresh controller so callers
-        // get a real AbortSignal, not a hand-rolled mock.
+    if (filtered.length === 0)
         return new AbortController().signal;
-    }
     if (filtered.length === 1)
         return filtered[0];
-    // Native path (Node 20+, modern browsers, Bun).
-    const native = AbortSignal.any;
-    if (typeof native === 'function') {
-        return native.call(AbortSignal, filtered);
-    }
-    // Polyfill: only used when native is missing. Listener-safe.
+    if (NATIVE_ANY)
+        return NATIVE_ANY.call(AbortSignal, filtered);
     const controller = new AbortController();
     const listeners = [];
     for (const signal of filtered) {
@@ -48,41 +16,20 @@ export function anySignal(signals) {
         }
         const onAbort = () => {
             controller.abort(signal.reason);
-            // Remove all other listeners — they hold closures over `signal`
-            // and would otherwise keep the inputs alive past settlement.
             for (const off of listeners)
                 off();
         };
         signal.addEventListener('abort', onAbort, { once: true });
         listeners.push(() => signal.removeEventListener('abort', onAbort));
     }
+    if (controller.signal.aborted) {
+        for (const off of listeners)
+            off();
+    }
     return controller.signal;
 }
-/**
- * Race a promise against an AbortSignal.
- *
- * - If the signal is already aborted, rejects immediately with `signal.reason`.
- * - If the signal aborts while the promise is pending, rejects with `signal.reason`.
- * - If the promise settles first, returns its value (or rejects with its error).
- *
- * # Listener safety
- *
- * On success path, the abort listener is explicitly removed. A
- * `{ once: true }` listener would stay attached on long-lived signals,
- * leaking one closure per call.
- *
- * # Mark-as-handled
- *
- * When the signal aborts first, the original `promise` may still settle
- * later (success or failure). We attach a no-op `.catch` to it so V8
- * doesn't emit an `unhandledRejection` warning. The error is NOT
- * swallowed from the caller — the caller already received `signal.reason`.
- */
 export function raceAbort(promise, signal) {
     if (signal.aborted) {
-        // Mark the promise as handled — its eventual rejection won't surface
-        // as an unhandled rejection. Its eventual success is dropped silently,
-        // which is correct: the caller has already moved on.
         promise.catch(() => { });
         return Promise.reject(signal.reason);
     }
@@ -95,8 +42,6 @@ export function raceAbort(promise, signal) {
             signal.removeEventListener('abort', onAbort);
             reject(signal.reason);
         };
-        // Not using `{ once: true }` — we want explicit removal on success
-        // path so the listener doesn't linger on a long-lived signal.
         signal.addEventListener('abort', onAbort);
         promise.then((value) => {
             if (settled)
@@ -113,20 +58,7 @@ export function raceAbort(promise, signal) {
         });
     });
 }
-/**
- * Sleep for `ms` milliseconds, but abort early if `signal` fires.
- *
- * Resolves normally on timer expiry. Rejects with `signal.reason` if the
- * signal aborts before the timer fires. If the signal is already aborted
- * when called, rejects synchronously (in microtask).
- *
- * # Timer hygiene
- *
- * The internal `setTimeout` is `unref`'d on Node so it doesn't keep the
- * event loop alive solely for this sleep. On browsers there is no
- * equivalent — the timer is short-lived enough not to matter.
- */
-export function sleep(ms, signal) {
+export function sleep(ms, signal, opts) {
     if (ms <= 0) {
         if (signal?.aborted)
             return Promise.reject(signal.reason);
@@ -139,12 +71,9 @@ export function sleep(ms, signal) {
             signal?.removeEventListener('abort', onAbort);
             resolve();
         }, ms);
-        // NOTE: do NOT `unref()` this timer. Unlike InMemoryStore's autoCleanup
-        // interval (which is a background housekeeping task), `sleep()` IS the
-        // operation the caller is awaiting. If we unref'd it, Node could exit
-        // the process while a retry delay was pending — silently dropping the
-        // operation. The timer is short-lived (cleared in onAbort or after ms),
-        // so the cost of keeping the loop alive is bounded.
+        if (opts?.unref && typeof timer.unref === 'function') {
+            timer.unref();
+        }
         const onAbort = () => {
             clearTimeout(timer);
             reject(signal.reason);
@@ -152,20 +81,14 @@ export function sleep(ms, signal) {
         signal?.addEventListener('abort', onAbort);
     });
 }
-/**
- * True if `err` is an `AbortError` (DOMException name or Error name).
- *
- * The default `shouldRetry` predicate uses this to skip retrying on
- * cancellations — if the caller aborted, retrying would just abort again.
- */
 export function isAbortError(err) {
     if (err == null || typeof err !== 'object')
         return false;
+    if (err.code === 'ACTLY_ABORT')
+        return true;
     const name = err.name;
     if (name === 'AbortError')
         return true;
-    // DOMException with name 'TimeoutError' is what AbortSignal.timeout throws.
-    // Distinguish from our own TimeoutError class by checking for DOMException.
     if (name === 'TimeoutError' &&
         err instanceof Error &&
         typeof DOMException !== 'undefined' &&
@@ -174,26 +97,6 @@ export function isAbortError(err) {
     }
     return false;
 }
-/**
- * Link a parent signal to a child controller: when the parent aborts, the
- * child is aborted with the same reason.
- *
- * # Contract
- *
- * Returns an `unlink()` function that removes the listener. Callers MUST
- * call `unlink()` on success path — otherwise the listener stays attached
- * to the parent forever, leaking one closure per call.
- *
- * If the parent is already aborted, the child is aborted synchronously
- * and `unlink` is a no-op.
- *
- * # Prefer `anySignal()` instead
- *
- * For new code, prefer `anySignal([parent, timeoutSignal])` which uses
- * the native Node 20+ implementation and handles cleanup automatically.
- * This function exists for call sites that need an `AbortController`
- * (not just a signal) — e.g. to layer additional abort sources.
- */
 export function linkSignal(parent, child) {
     if (parent.aborted) {
         child.abort(parent.reason);
@@ -203,4 +106,3 @@ export function linkSignal(parent, child) {
     parent.addEventListener('abort', onAbort);
     return () => parent.removeEventListener('abort', onAbort);
 }
-//# sourceMappingURL=abort.js.map

package/dist/utils/abortPool.cjs

@@ -8,9 +8,8 @@ const MAX_POOL_SIZE = 64;
 function acquireController() {
     while (pool.length > 0) {
         const c = pool.pop();
-        if (!c.signal.aborted) {
+        if (!c.signal.aborted)
             return c;
-        }
     }
     return new AbortController();
 }

package/dist/utils/abortPool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"abortPool.d.ts","sourceRoot":"","sources":["../../src/utils/abortPool.ts"],"names":[],"mappings":"AAGA,wBAAgB,iBAAiB,IAAI,eAAe,CAQnD;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,eAAe,GAAG,IAAI,CAI1D;AAED,wBAAgB,QAAQ,IAAI,MAAM,CAEjC"}
+{"version":3,"file":"abortPool.d.ts","sourceRoot":"","sources":["../../src/utils/abortPool.ts"],"names":[],"mappings":"AAMA,wBAAgB,iBAAiB,IAAI,eAAe,CAOnD;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,eAAe,GAAG,IAAI,CAK1D;AAED,wBAAgB,QAAQ,IAAI,MAAM,CAEjC"}

package/dist/utils/abortPool.js

@@ -3,9 +3,8 @@ const MAX_POOL_SIZE = 64;
 export function acquireController() {
     while (pool.length > 0) {
         const c = pool.pop();
-        if (!c.signal.aborted) {
+        if (!c.signal.aborted)
             return c;
-        }
     }
     return new AbortController();
 }
@@ -19,4 +18,3 @@ export function releaseController(c) {
 export function poolSize() {
     return pool.length;
 }
-//# sourceMappingURL=abortPool.js.map

package/dist/utils/backoff.cjs

@@ -1,22 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.computeDelay = computeDelay;
-/**
- * Compute the delay before the next retry attempt, applying backoff, cap, and
- * jitter in that order.
- *
- * Order matters:
- *  1. `backoff` grows the base delay geometrically/linearly.
- *  2. `maxDelay` caps the result (prevents exponential blowup).
- *  3. `jitter` randomises within `[0, delay]` (prevents thundering herd).
- *
- * Returns 0 if `delayMs` is 0 or undefined — skipping the sleep entirely.
- */
 function computeDelay(attempt, opts) {
     const base = opts.delayMs ?? 0;
     if (base === 0)
         return 0;
-    // Step 1: backoff
     let delay;
     switch (opts.backoff ?? 'none') {
         case 'linear':
@@ -27,24 +15,18 @@ function computeDelay(attempt, opts) {
             break;
         default: delay = base;
     }
-    // Step 2: cap (guard against Infinity and NaN before Math.min)
     const max = opts.maxDelay ?? Number.POSITIVE_INFINITY;
     if (!Number.isFinite(delay))
         delay = max;
     delay = Math.min(delay, max);
-    // Step 3: jitter
-    // All jitter variants produce a delay in [0, delay].
-    // The `decorrelated` formula `base + random() * (delay - base)` assumes
-    // delay >= base, which can be violated when maxDelay caps below base.
-    // Fix: clamp the final result to [0, delay] to guarantee the cap holds.
     switch (opts.jitter ?? 'full') {
         case 'none': return delay;
         case 'full': return Math.random() * delay;
         case 'equal': return delay / 2 + Math.random() * delay / 2;
         case 'decorrelated': {
-            // If delay < base (maxDelay capped below base), decorrelated degrades
-            // to full jitter — the formula would otherwise produce values > delay.
-            const lo = Math.min(base, delay);
+            if (delay < base)
+                return Math.random() * delay;
+            const lo = base;
             const hi = delay;
             const result = lo + Math.random() * (hi - lo);
             return Math.max(0, Math.min(result, delay));

package/dist/utils/backoff.d.ts

@@ -1,14 +1,3 @@
 import type { RetryOptions } from '../types/index.js';
-/**
- * Compute the delay before the next retry attempt, applying backoff, cap, and
- * jitter in that order.
- *
- * Order matters:
- *  1. `backoff` grows the base delay geometrically/linearly.
- *  2. `maxDelay` caps the result (prevents exponential blowup).
- *  3. `jitter` randomises within `[0, delay]` (prevents thundering herd).
- *
- * Returns 0 if `delayMs` is 0 or undefined — skipping the sleep entirely.
- */
 export declare function computeDelay(attempt: number, opts: RetryOptions): number;
 //# sourceMappingURL=backoff.d.ts.map

package/dist/utils/backoff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../../src/utils/backoff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAErD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,MAAM,CAoCxE"}
+{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../../src/utils/backoff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AASrD,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,MAAM,CAgCxE"}

package/dist/utils/backoff.js

@@ -1,19 +1,7 @@
-/**
- * Compute the delay before the next retry attempt, applying backoff, cap, and
- * jitter in that order.
- *
- * Order matters:
- *  1. `backoff` grows the base delay geometrically/linearly.
- *  2. `maxDelay` caps the result (prevents exponential blowup).
- *  3. `jitter` randomises within `[0, delay]` (prevents thundering herd).
- *
- * Returns 0 if `delayMs` is 0 or undefined — skipping the sleep entirely.
- */
 export function computeDelay(attempt, opts) {
     const base = opts.delayMs ?? 0;
     if (base === 0)
         return 0;
-    // Step 1: backoff
     let delay;
     switch (opts.backoff ?? 'none') {
         case 'linear':
@@ -24,24 +12,18 @@ export function computeDelay(attempt, opts) {
             break;
         default: delay = base;
     }
-    // Step 2: cap (guard against Infinity and NaN before Math.min)
     const max = opts.maxDelay ?? Number.POSITIVE_INFINITY;
     if (!Number.isFinite(delay))
         delay = max;
     delay = Math.min(delay, max);
-    // Step 3: jitter
-    // All jitter variants produce a delay in [0, delay].
-    // The `decorrelated` formula `base + random() * (delay - base)` assumes
-    // delay >= base, which can be violated when maxDelay caps below base.
-    // Fix: clamp the final result to [0, delay] to guarantee the cap holds.
     switch (opts.jitter ?? 'full') {
         case 'none': return delay;
         case 'full': return Math.random() * delay;
         case 'equal': return delay / 2 + Math.random() * delay / 2;
         case 'decorrelated': {
-            // If delay < base (maxDelay capped below base), decorrelated degrades
-            // to full jitter — the formula would otherwise produce values > delay.
-            const lo = Math.min(base, delay);
+            if (delay < base)
+                return Math.random() * delay;
+            const lo = base;
             const hi = delay;
             const result = lo + Math.random() * (hi - lo);
             return Math.max(0, Math.min(result, delay));
@@ -49,4 +31,3 @@ export function computeDelay(attempt, opts) {
         default: return delay;
     }
 }
-//# sourceMappingURL=backoff.js.map