actly 1.1.0 → 1.1.5

package/dist/types/index.d.ts

@@ -1,51 +1,131 @@
-/** The async function ACT wraps */
-export type ActFn<T> = () => Promise<T>;
-/** Where a successful result came from */
+/**
+ * The async function ACT wraps.
+ *
+ * Receives an {@link AbortSignal} that fires when:
+ *  - the caller aborts via `options.signal`,
+ *  - the per-attempt {@link TimeoutOptions} fires,
+ *  - the operation-wide {@link ActOptions.totalTimeout} fires.
+ *
+ * Cooperative cancellation: pass `signal` through to `fetch`, `AbortController`,
+ * database drivers, or any primitive that accepts one. If you ignore it, ACT
+ * will still return promptly (the outer promise rejects), but the underlying
+ * work will keep running in the background — leaking resources until it
+ * settles on its own.
+ *
+ * Backwards compatible: `() => Promise<T>` is assignable to this type, so
+ * existing call sites continue to compile and run. They simply forgo
+ * cancellation.
+ *
+ * @example
+ * // Cooperative
+ * act('user:42', async (signal) => {
+ *   return fetch(`/api/users/42`, { signal })
+ * }, { timeout: { ms: 5_000 } })
+ *
+ * @example
+ * // Legacy (still works, signal ignored)
+ * act('user:42', () => fetchUser(42))
+ */
+export type ActFn<T> = (signal: AbortSignal) => Promise<T> | T;
+/** Where a successful result came from. */
 export type ActSource = 'fresh' | 'cache';
 export interface ActSuccess<T> {
     ok: true;
     value: T;
     source: ActSource;
-    /** Number of attempts made before success */
+    /**
+     * Number of attempts made before success.
+     *
+     * - Fresh success on first try: `1`
+     * - Fresh success after N retries: `N`
+     * - Cache hit: `0` (no work was performed)
+     * - Dedupe joiner: mirrors the originator's attempt count
+     */
     attempts: number;
 }
 export interface ActFailure {
     ok: false;
     error: unknown;
-    /** Number of attempts made before final failure */
+    /**
+     * Number of attempts made before final failure.
+     * For dedupe joiners: mirrors the originator's attempt count.
+     */
     attempts: number;
 }
 export type ActResult<T> = ActSuccess<T> | ActFailure;
 export interface RetryOptions {
-    /** Total number of attempts including the first call. Must be >= 1. */
+    /**
+     * Total number of attempts including the first call.
+     * Must be an integer >= 1.
+     *
+     * `attempts: 1` is a no-op (equivalent to omitting `retry`); the policy
+     * is not added to the chain. This is intentional — adding a policy that
+     * never retries is pure overhead.
+     */
     attempts: number;
-    /** Base delay between attempts in ms. 0 = no delay. */
+    /**
+     * Base delay between attempts in milliseconds. Defaults to 0 (no delay).
+     * Must be a non-negative finite number.
+     */
     delayMs?: number;
     /**
      * How the base delay grows per attempt:
-     *  - 'none'        -> always delayMs
-     *  - 'linear'      -> delayMs * attempt
-     *  - 'exponential' -> delayMs * 2^(attempt-1)
+     *  - `'none'`        -> always `delayMs`
+     *  - `'linear'`      -> `delayMs * attempt`
+     *  - `'exponential'` -> `delayMs * 2^(attempt-1)`
+     *
+     * The computed delay is then capped by {@link maxDelay} and jittered by
+     * {@link jitter} before being slept.
+     *
+     * Defaults to `'none'`.
      */
     backoff?: 'none' | 'linear' | 'exponential';
+    /**
+     * Hard cap on the computed delay. Defaults to `Infinity`.
+     *
+     * Without a cap, `exponential` backoff with `delayMs: 1000` and
+     * `attempts: 10` would sleep 8.5 minutes between attempts 9 and 10
+     * (256 seconds). Set `maxDelay` to something sane (e.g. 30_000) to
+     * bound worst-case latency.
+     */
+    maxDelay?: number;
+    /**
+     * Jitter strategy applied to the (post-`maxDelay`) delay.
+     *
+     *  - `'none'`         -> no jitter, return delay as-is
+     *  - `'full'`         -> `random() * delay`  (default; best for thundering-herd prevention)
+     *  - `'equal'`        -> `delay/2 + random() * delay/2`
+     *  - `'decorrelated'` -> `base + random() * (delay - base)`
+     *
+     * Defaults to `'full'`. Jitter prevents synchronised retry storms when
+     * many callers fail at the same instant (e.g. after an upstream outage
+     * recovers) — without it, all callers retry on the same tick.
+     */
+    jitter?: 'none' | 'full' | 'equal' | 'decorrelated';
     /**
      * Predicate called after each failure, before the next attempt.
-     * Return false to stop retrying immediately and surface the error.
+     * Return `false` to stop retrying immediately and surface the error.
+     *
+     * Called for every failure including the last attempt (so observers stay
+     * informed); the return value is only consulted when there are remaining
+     * attempts.
      *
      * Use this to skip retries for errors that are definitively non-recoverable
      * (e.g. HTTP 4xx, AuthError, ValidationError).
      *
+     * Default behaviour: retry on every error except `AbortError` (which
+     * indicates the caller or a timeout cancelled the operation).
+     *
      * @param error   The error thrown by the most recent attempt.
      * @param attempt The 1-based number of the attempt that just failed.
-     *
-     * @example
-     * shouldRetry: (err, attempt) =>
-     *   !(err instanceof HttpError && err.status < 500)
      */
     shouldRetry?: (error: unknown, attempt: number) => boolean;
 }
 export interface TimeoutOptions {
-    /** Abort after this many ms */
+    /**
+     * Abort after this many milliseconds.
+     * Must be a positive finite number.
+     */
     ms: number;
 }
 export interface DedupeOptions {
@@ -54,45 +134,74 @@ export interface DedupeOptions {
      * Opt-in: be explicit when you want this behaviour.
      */
     enabled: boolean;
+    /**
+     * Safety-net TTL for the in-flight entry, in milliseconds.
+     *
+     * If the originator's promise does not settle within this window, the
+     * entry is removed from the store so subsequent callers can start fresh.
+     * Originator's promise continues in the background until it settles or
+     * an outer timeout fires.
+     *
+     * Default: `Infinity` (no safety net). Pair with `timeout` or
+     * `totalTimeout` for proper cancellation in production.
+     */
+    inflightTtl?: number;
 }
 export interface CacheOptions {
-    /** Keep a successful result for this many ms */
+    /** Keep a successful result for this many milliseconds. Must be > 0. */
     ttl: number;
 }
 export interface ActOptions {
     retry?: RetryOptions;
+    /** Per-attempt deadline. Each retry gets a fresh clock. */
     timeout?: TimeoutOptions;
     /**
      * Collapse concurrent calls with the same key into one in-flight Promise.
      *
      * Shorthand:  `dedupe: true`
-     * Full form:  `dedupe: { enabled: true }`
-     *
-     * Both are equivalent. The object form exists for forward compatibility.
+     * Full form:  `dedupe: { enabled: true, inflightTtl: 30_000 }`
      */
     dedupe?: boolean | DedupeOptions;
     cache?: CacheOptions;
     /**
      * Hard budget over the ENTIRE operation — including all retry attempts,
-     * delays, and the timeout per attempt.
+     * delays, and the per-attempt timeout.
      *
      * Distinct from `timeout`, which resets the clock on every attempt.
      * Use both together to express: "each attempt may take at most X ms,
      * but the whole thing must finish within Y ms."
      *
-     * Rejects with TotalTimeoutError if the deadline fires.
+     * Rejects with {@link TotalTimeoutError} if the budget fires.
      */
     totalTimeout?: TimeoutOptions;
+    /**
+     * Caller-provided cancellation signal.
+     *
+     * When this signal aborts:
+     *  - if the operation has not yet started, it rejects immediately with
+     *    the signal's `reason`,
+     *  - if it is in progress, the inner {@link ActFn} receives an aborted
+     *    signal (cooperative cancellation),
+     *  - if it has already settled, the result is returned as normal.
+     *
+     * Combined with `timeout` / `totalTimeout`, this gives you full control
+     * over cancellation from outside `act()`.
+     */
+    signal?: AbortSignal;
 }
 /**
  * Mutable bag mutated in-place during execution.
  * Policies annotate it; act() reads the final state to build ActResult.
+ *
+ * For dedupe joiners: the bag is copied from the originator's bag after the
+ * in-flight promise settles (success or failure), so `attempts` reflects
+ * the real effort, not the default `1`.
  */
 export interface RunMeta {
     attempts: number;
     source: ActSource;
 }
-/** Everything a policy receives about the current run */
+/** Everything a policy receives about the current run. */
 export interface PolicyContext {
     key: string;
     store: AnyStateStore;
@@ -101,28 +210,24 @@ export interface PolicyContext {
 /**
  * The ONLY shape the executor knows about policies.
  *
- * A policy wraps ActFn<T> and returns a new ActFn<T>.
- * It may intercept before, after, or instead of the inner call.
- * The executor never imports a concrete policy — only this type.
+ * A policy wraps `ActFn<T>` and returns a new `ActFn<T>`. It may intercept
+ * before, after, or instead of the inner call. The executor never imports
+ * a concrete policy — only this type.
  */
 export type PolicyApplier<T> = (fn: ActFn<T>, ctx: PolicyContext) => ActFn<T>;
 import type { SyncStateStore, AsyncStateStore } from '../stores/base.js';
 export type { SyncStateStore, AsyncStateStore };
 /**
- * Public store type. v1.1: alias for SyncStateStore to preserve the
- * existing contract — every v1.0 consumer typed against StateStore
- * continues to compile without changes.
+ * Public store type. v1.1+: alias for `SyncStateStore`.
  *
- * A future major version may widen this to SyncStateStore | AsyncStateStore
- * once call sites have been audited. For now: additive, non-breaking.
+ * Kept for backwards compatibility — every v1.0 consumer typed against
+ * `StateStore` continues to compile without changes. A future major version
+ * may widen this to `SyncStateStore | AsyncStateStore`.
  */
 export type StateStore = SyncStateStore;
 /**
- * Accepted by policies that support both sync and async stores (e.g. cache).
- * Not part of the public surface yet — internal use only until the
- * async-store path is fully documented and example adapters ship.
- *
- * @internal
+ * Union of sync and async stores. Used internally by `PolicyContext` and
+ * exported for consumers building custom policy chains or store adapters.
  */
 export type AnyStateStore = SyncStateStore | AsyncStateStore;
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAEA,mCAAmC;AACnC,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,CAAA;AAEvC,0CAA0C;AAC1C,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,CAAA;AAEzC,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,EAAE,EAAE,IAAI,CAAA;IACR,KAAK,EAAE,CAAC,CAAA;IACR,MAAM,EAAE,SAAS,CAAA;IACjB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,KAAK,CAAA;IACT,KAAK,EAAE,OAAO,CAAA;IACd,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAA;AAIrD,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAA;IAChB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,aAAa,CAAA;IAC3C;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAA;CAC3D;AAED,MAAM,WAAW,cAAc;IAC7B,+BAA+B;IAC/B,EAAE,EAAE,MAAM,CAAA;CACX;AAED,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAS,YAAY,CAAA;IAC3B,OAAO,CAAC,EAAO,cAAc,CAAA;IAC7B;;;;;;;OAOG;IACH,MAAM,CAAC,EAAQ,OAAO,GAAG,aAAa,CAAA;IACtC,KAAK,CAAC,EAAS,YAAY,CAAA;IAC3B;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,cAAc,CAAA;CAC9B;AAID;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAI,SAAS,CAAA;CACpB;AAED,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAI,MAAM,CAAA;IACb,KAAK,EAAE,aAAa,CAAA;IACpB,IAAI,EAAG,OAAO,CAAA;CACf;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,aAAa,KAAK,KAAK,CAAC,CAAC,CAAC,CAAA;AAO7E,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACxE,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,CAAA;AAE/C;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,cAAc,CAAA;AAEvC;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}

package/dist/utils/abort.cjs

@@ -0,0 +1,142 @@
+"use strict";
+// ─── AbortSignal helpers ──────────────────────────────────────────────────────
+//
+// Centralised utilities for composing AbortSignals. These exist because
+// Node 18 lacks `AbortSignal.any` (added in Node 20) and we want to keep
+// the `engines` floor at 18 for backwards compatibility with existing
+// consumers.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.anySignal = anySignal;
+exports.raceAbort = raceAbort;
+exports.sleep = sleep;
+exports.isAbortError = isAbortError;
+exports.linkSignal = linkSignal;
+/**
+ * Polyfill for `AbortSignal.any(signals)` (Node 20+).
+ *
+ * Returns a single signal that aborts when ANY of the input signals aborts,
+ * with the same reason. If any input is already aborted, the returned signal
+ * is aborted synchronously.
+ *
+ * Listener registration is `{ once: true }` — once any signal fires, we stop
+ * listening on the others. The composite signal cannot be "un-aborted".
+ */
+function anySignal(signals) {
+    // Fast path: native implementation (Node 20+, modern browsers, Bun).
+    // The cast is safe — the runtime check guards the call.
+    const native = AbortSignal.any;
+    if (typeof native === 'function')
+        return native.call(AbortSignal, signals);
+    // Polyfill for Node 18.
+    const controller = new AbortController();
+    for (const signal of signals) {
+        if (signal.aborted) {
+            controller.abort(signal.reason);
+            break;
+        }
+        signal.addEventListener('abort', () => controller.abort(signal.reason), { once: true });
+    }
+    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).
+ *
+ * The listener is registered with `{ once: true }` and never leaks: either
+ * the signal fires (listener auto-removed) or the promise settles (the
+ * signal will eventually be GC'd along with the listener).
+ *
+ * Used by `dedupePolicy` so joiners can cancel their own `await` even if the
+ * originator's `fn` is still running.
+ */
+function raceAbort(promise, signal) {
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const onAbort = () => {
+            if (settled)
+                return;
+            settled = true;
+            reject(signal.reason);
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then((value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        }, (error) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(error);
+        });
+    });
+}
+/**
+ * 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).
+ *
+ * Used by `retryPolicy` to make backoff delays interruptible: when an outer
+ * `totalTimeout` fires mid-delay, the delay rejects immediately instead of
+ * blocking the retry loop until the timer would have elapsed.
+ */
+function sleep(ms, signal) {
+    if (ms <= 0) {
+        if (signal?.aborted)
+            return Promise.reject(signal.reason);
+        return Promise.resolve();
+    }
+    if (signal?.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * 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;
+    const name = err.name;
+    return name === 'AbortError' || name === 'TimeoutError' &&
+        err instanceof Error &&
+        // DOMException with name 'TimeoutError' is what AbortSignal.timeout throws.
+        // Distinguish from our own TimeoutError class by checking for DOMException.
+        typeof DOMException !== 'undefined' &&
+        err instanceof DOMException;
+}
+/**
+ * Link a parent signal to a child controller: when the parent aborts, the
+ * child is aborted with the same reason. No-op if the parent is already
+ * aborted (the caller should check `parent.aborted` separately if it cares
+ * about synchronous abort).
+ *
+ * The listener is `{ once: true }` — no leak.
+ */
+function linkSignal(parent, child) {
+    if (parent.aborted) {
+        child.abort(parent.reason);
+        return;
+    }
+    parent.addEventListener('abort', () => child.abort(parent.reason), { once: true });
+}

package/dist/utils/abort.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Polyfill for `AbortSignal.any(signals)` (Node 20+).
+ *
+ * Returns a single signal that aborts when ANY of the input signals aborts,
+ * with the same reason. If any input is already aborted, the returned signal
+ * is aborted synchronously.
+ *
+ * Listener registration is `{ once: true }` — once any signal fires, we stop
+ * listening on the others. The composite signal cannot be "un-aborted".
+ */
+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).
+ *
+ * The listener is registered with `{ once: true }` and never leaks: either
+ * the signal fires (listener auto-removed) or the promise settles (the
+ * signal will eventually be GC'd along with the listener).
+ *
+ * Used by `dedupePolicy` so joiners can cancel their own `await` even if the
+ * originator's `fn` is still running.
+ */
+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).
+ *
+ * Used by `retryPolicy` to make backoff delays interruptible: when an outer
+ * `totalTimeout` fires mid-delay, the delay rejects immediately instead of
+ * blocking the retry loop until the timer would have elapsed.
+ */
+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 isAbortError(err: unknown): boolean;
+/**
+ * Link a parent signal to a child controller: when the parent aborts, the
+ * child is aborted with the same reason. No-op if the parent is already
+ * aborted (the caller should check `parent.aborted` separately if it cares
+ * about synchronous abort).
+ *
+ * The listener is `{ once: true }` — no leak.
+ */
+export declare function linkSignal(parent: AbortSignal, child: AbortController): void;
+//# sourceMappingURL=abort.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../../src/utils/abort.ts"],"names":[],"mappings":"AAOA;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,WAAW,CAwB1E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,CAAC,CAAC,CA2BZ;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBrE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CASlD;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,eAAe,GACrB,IAAI,CAUN"}

package/dist/utils/abort.js

@@ -0,0 +1,136 @@
+// ─── AbortSignal helpers ──────────────────────────────────────────────────────
+//
+// Centralised utilities for composing AbortSignals. These exist because
+// Node 18 lacks `AbortSignal.any` (added in Node 20) and we want to keep
+// the `engines` floor at 18 for backwards compatibility with existing
+// consumers.
+/**
+ * Polyfill for `AbortSignal.any(signals)` (Node 20+).
+ *
+ * Returns a single signal that aborts when ANY of the input signals aborts,
+ * with the same reason. If any input is already aborted, the returned signal
+ * is aborted synchronously.
+ *
+ * Listener registration is `{ once: true }` — once any signal fires, we stop
+ * listening on the others. The composite signal cannot be "un-aborted".
+ */
+export function anySignal(signals) {
+    // Fast path: native implementation (Node 20+, modern browsers, Bun).
+    // The cast is safe — the runtime check guards the call.
+    const native = AbortSignal.any;
+    if (typeof native === 'function')
+        return native.call(AbortSignal, signals);
+    // Polyfill for Node 18.
+    const controller = new AbortController();
+    for (const signal of signals) {
+        if (signal.aborted) {
+            controller.abort(signal.reason);
+            break;
+        }
+        signal.addEventListener('abort', () => controller.abort(signal.reason), { once: true });
+    }
+    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).
+ *
+ * The listener is registered with `{ once: true }` and never leaks: either
+ * the signal fires (listener auto-removed) or the promise settles (the
+ * signal will eventually be GC'd along with the listener).
+ *
+ * Used by `dedupePolicy` so joiners can cancel their own `await` even if the
+ * originator's `fn` is still running.
+ */
+export function raceAbort(promise, signal) {
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const onAbort = () => {
+            if (settled)
+                return;
+            settled = true;
+            reject(signal.reason);
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then((value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        }, (error) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(error);
+        });
+    });
+}
+/**
+ * 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).
+ *
+ * Used by `retryPolicy` to make backoff delays interruptible: when an outer
+ * `totalTimeout` fires mid-delay, the delay rejects immediately instead of
+ * blocking the retry loop until the timer would have elapsed.
+ */
+export function sleep(ms, signal) {
+    if (ms <= 0) {
+        if (signal?.aborted)
+            return Promise.reject(signal.reason);
+        return Promise.resolve();
+    }
+    if (signal?.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * 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;
+    const name = err.name;
+    return name === 'AbortError' || name === 'TimeoutError' &&
+        err instanceof Error &&
+        // DOMException with name 'TimeoutError' is what AbortSignal.timeout throws.
+        // Distinguish from our own TimeoutError class by checking for DOMException.
+        typeof DOMException !== 'undefined' &&
+        err instanceof DOMException;
+}
+/**
+ * Link a parent signal to a child controller: when the parent aborts, the
+ * child is aborted with the same reason. No-op if the parent is already
+ * aborted (the caller should check `parent.aborted` separately if it cares
+ * about synchronous abort).
+ *
+ * The listener is `{ once: true }` — no leak.
+ */
+export function linkSignal(parent, child) {
+    if (parent.aborted) {
+        child.abort(parent.reason);
+        return;
+    }
+    parent.addEventListener('abort', () => child.abort(parent.reason), { once: true });
+}
+//# sourceMappingURL=abort.js.map

package/dist/utils/abort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.js","sourceRoot":"","sources":["../../src/utils/abort.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,EAAE;AACF,wEAAwE;AACxE,yEAAyE;AACzE,sEAAsE;AACtE,aAAa;AAEb;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS,CAAC,OAAmC;IAC3D,qEAAqE;IACrE,wDAAwD;IACxD,MAAM,MAAM,GAAI,WAEd,CAAC,GAAG,CAAA;IACN,IAAI,OAAO,MAAM,KAAK,UAAU;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAA;IAE1E,wBAAwB;IACxB,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAA;IAExC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;YAC/B,MAAK;QACP,CAAC;QACD,MAAM,CAAC,gBAAgB,CACrB,OAAO,EACP,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EACrC,EAAE,IAAI,EAAE,IAAI,EAAE,CACf,CAAA;IACH,CAAC;IAED,OAAO,UAAU,CAAC,MAAM,CAAA;AAC1B,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,SAAS,CACvB,OAAmB,EACnB,MAAmB;IAEnB,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,OAAO,CAAC,MAAM,CAAI,MAAM,CAAC,MAAM,CAAC,CAAA;IAE3D,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACxC,IAAI,OAAO,GAAG,KAAK,CAAA;QAEnB,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,IAAI,OAAO;gBAAE,OAAM;YACnB,OAAO,GAAG,IAAI,CAAA;YACd,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QACvB,CAAC,CAAA;QAED,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;QAEzD,OAAO,CAAC,IAAI,CACV,CAAC,KAAK,EAAE,EAAE;YACR,IAAI,OAAO;gBAAE,OAAM;YACnB,OAAO,GAAG,IAAI,CAAA;YACd,OAAO,CAAC,KAAK,CAAC,CAAA;QAChB,CAAC,EACD,CAAC,KAAK,EAAE,EAAE;YACR,IAAI,OAAO;gBAAE,OAAM;YACnB,OAAO,GAAG,IAAI,CAAA;YACd,MAAM,CAAC,KAAK,CAAC,CAAA;QACf,CAAC,CACF,CAAA;IACH,CAAC,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,KAAK,CAAC,EAAU,EAAE,MAAoB;IACpD,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;QACZ,IAAI,MAAM,EAAE,OAAO;YAAE,OAAO,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QACzD,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;IAC1B,CAAC;IAED,IAAI,MAAM,EAAE,OAAO;QAAE,OAAO,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAEzD,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC3C,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;YAC7C,OAAO,EAAE,CAAA;QACX,CAAC,EAAE,EAAE,CAAC,CAAA;QAEN,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,YAAY,CAAC,KAAK,CAAC,CAAA;YACnB,MAAM,CAAC,MAAO,CAAC,MAAM,CAAC,CAAA;QACxB,CAAC,CAAA;QAED,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;IAC5D,CAAC,CAAC,CAAA;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,IAAI,GAAG,IAAI,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IACxD,MAAM,IAAI,GAAI,GAA0B,CAAC,IAAI,CAAA;IAC7C,OAAO,IAAI,KAAK,YAAY,IAAI,IAAI,KAAK,cAAc;QACrD,GAAG,YAAY,KAAK;QACpB,4EAA4E;QAC5E,4EAA4E;QAC5E,OAAO,YAAY,KAAK,WAAW;QACnC,GAAG,YAAY,YAAY,CAAA;AAC/B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CACxB,MAAmB,EACnB,KAAsB;IAEtB,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAC1B,OAAM;IACR,CAAC;IACD,MAAM,CAAC,gBAAgB,CACrB,OAAO,EACP,GAAG,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAChC,EAAE,IAAI,EAAE,IAAI,EAAE,CACf,CAAA;AACH,CAAC"}

package/dist/utils/backoff.cjs

@@ -0,0 +1,43 @@
+"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':
+            delay = base * attempt;
+            break;
+        case 'exponential':
+            delay = base * 2 ** (attempt - 1);
+            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
+    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': return base + Math.random() * (delay - base);
+        default: return delay;
+    }
+}