actly 1.1.0 → 1.2.0

package/dist/types/index.d.ts

@@ -1,51 +1,145 @@
-/** 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;
+    /**
+     * Trace ID for correlation across logs/metrics. Present when
+     * `options.observability` or `options.traceId` is set; `undefined` otherwise.
+     */
+    traceId?: string;
+    /** Wall-clock duration of this act() call in ms. */
+    durationMs?: 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;
+    /**
+     * Trace ID for correlation across logs/metrics. Present when
+     * `options.observability` or `options.traceId` is set; `undefined` otherwise.
+     */
+    traceId?: string;
+    /** Wall-clock duration of this act() call in ms. */
+    durationMs?: 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,75 +148,259 @@ 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 {
+export interface ActOptions<T = unknown> {
     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;
+    /**
+     * Observability hooks. All optional. When omitted entirely (the
+     * common case), zero overhead is incurred on the hot path — no event
+     * objects are allocated, no function calls are made.
+     *
+     * When hooks ARE registered, events are allocated lazily — only when
+     * the corresponding event actually fires.
+     *
+     * @example
+     * ```ts
+     * await act('user:42', fn, {
+     *   retry: { attempts: 3 },
+     *   observability: {
+     *     onAttempt: (e) => metrics.increment('act.attempt', { key: e.key, attempt: e.attempt }),
+     *     onFinalFailure: (e) => logger.error({ key: e.key, traceId: e.traceId, failedBy: e.failedBy }, 'act failed'),
+     *     onFinalSuccess: (e) => metrics.histogram('act.duration', e.durationMs),
+     *   },
+     * })
+     * ```
+     */
+    observability?: ObservabilityHooks;
+    /**
+     * Trace ID for logs/metrics correlation. Auto-generated via crypto.randomUUID()
+     * when omitted. Appears on every observability event and on ActResult.traceId.
+     */
+    traceId?: string;
+    /** Circuit breaker: trips open after N consecutive failures, blocks calls for a cooldown period. */
+    circuitBreaker?: CircuitBreakerOptions;
+    /** Bulkhead: limits concurrent in-flight calls per key. Excess callers queue or fail fast. */
+    bulkhead?: BulkheadOptions;
+    /** Rate limiter: limits calls per window per key. Excess callers fail with RateLimitError. */
+    rateLimit?: RateLimitOptions;
+    /** Hedge: sends a second fn call after delayMs if the first hasn't settled. Races them. */
+    hedge?: HedgeOptions;
+    /** Fallback: returns this value if all policies fail. Suppresses ActFailure. */
+    fallback?: FallbackOptions<T>;
+    /** Audit: logs every act() call with key, traceId, result, timestamp. */
+    audit?: AuditOptions;
+}
+export interface CircuitBreakerOptions {
+    /** Number of consecutive failures before the breaker opens. Must be >= 1. */
+    threshold: number;
+    /** How long to stay open before transitioning to half-open (ms). Must be > 0. */
+    cooldownMs: number;
+    /** Optional: reset failure count after this idle period (ms). Default: Infinity. */
+    resetTimeoutMs?: number;
+}
+export interface BulkheadOptions {
+    /** Max concurrent in-flight calls per key. Must be >= 1. */
+    maxConcurrent: number;
+    /** How long to queue before rejecting with BulkheadOverflowError (ms). Default: 0 (fail fast). */
+    queueTimeoutMs?: number;
+}
+export interface RateLimitOptions {
+    /** Max calls per window per key. Must be >= 1. */
+    maxCalls: number;
+    /** Window size in ms. Must be > 0. */
+    windowMs: number;
+}
+export interface HedgeOptions {
+    /** Delay before sending the second (hedge) call (ms). Must be > 0. */
+    delayMs: number;
+}
+export interface FallbackOptions<T> {
+    /** Value to return if all retries/policies fail. */
+    value: T | (() => T | Promise<T>);
+}
+export interface AuditOptions {
+    /** Called with audit entry after every act() call (success or failure). */
+    log: (entry: AuditEntry) => void;
+}
+export interface AuditEntry {
+    key: string;
+    traceId: string;
+    timestamp: number;
+    durationMs: number;
+    ok: boolean;
+    attempts: number;
+    failedBy?: string;
+    error?: unknown;
 }
 /**
  * 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 */
+export interface ObservabilityContext {
+    traceId: string;
+    hooks: ObservabilityHooks;
+    joinerCounter: number;
+}
+/** User-supplied observability hooks. See `observability.ts` for full shape. */
+export interface ObservabilityHooks {
+    onAttempt?: (event: {
+        readonly type: 'attempt';
+        readonly key: string;
+        readonly traceId: string;
+        readonly timestamp: number;
+        readonly attempt: number;
+        readonly durationMs?: number;
+        readonly error?: unknown;
+    }) => void;
+    onRetry?: (event: {
+        readonly type: 'retry';
+        readonly key: string;
+        readonly traceId: string;
+        readonly timestamp: number;
+        readonly attempt: number;
+        readonly delayMs: number;
+        readonly error: unknown;
+    }) => void;
+    onCacheHit?: (event: {
+        readonly type: 'cache-hit';
+        readonly key: string;
+        readonly traceId: string;
+        readonly timestamp: number;
+        readonly ageMs: number;
+    }) => void;
+    onCacheMiss?: (event: {
+        readonly type: 'cache-miss';
+        readonly key: string;
+        readonly traceId: string;
+        readonly timestamp: number;
+    }) => void;
+    onDedupeJoin?: (event: {
+        readonly type: 'dedupe-join';
+        readonly key: string;
+        readonly traceId: string;
+        readonly timestamp: number;
+        readonly joinerPosition: number;
+    }) => void;
+    onTimeout?: (event: {
+        readonly type: 'timeout';
+        readonly key: string;
+        readonly traceId: string;
+        readonly timestamp: number;
+        readonly kind: 'per-attempt' | 'total';
+        readonly ms: number;
+    }) => void;
+    onFinalSuccess?: (event: {
+        readonly type: 'final-success';
+        readonly key: string;
+        readonly traceId: string;
+        readonly timestamp: number;
+        readonly source: ActSource;
+        readonly attempts: number;
+        readonly durationMs: number;
+    }) => void;
+    onFinalFailure?: (event: {
+        readonly type: 'final-failure';
+        readonly key: string;
+        readonly traceId: string;
+        readonly timestamp: number;
+        readonly attempts: number;
+        readonly durationMs: number;
+        readonly failedBy: 'abort' | 'timeout' | 'total-timeout' | 'retry-exhausted' | 'fn-error' | 'validation';
+        readonly error: unknown;
+    }) => void;
+}
+/** Everything a policy receives about the current run. */
 export interface PolicyContext {
     key: string;
     store: AnyStateStore;
     meta: RunMeta;
+    /**
+     * Observability context. Present only when the caller supplied
+     * `options.observability` hooks. Policies check `ctx.observability != null`
+     * before allocating event objects — no overhead when absent.
+     */
+    observability?: ObservabilityContext;
 }
 /**
  * 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. Alias for `SyncStateStore` (backwards compat).
  *
- * 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 — consumers 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,212 @@
+"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.
+ */
+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.
+        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.
+    const controller = new AbortController();
+    const listeners = [];
+    for (const signal of filtered) {
+        if (signal.aborted) {
+            controller.abort(signal.reason);
+            break;
+        }
+        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));
+    }
+    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);
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const onAbort = () => {
+            if (settled)
+                return;
+            settled = true;
+            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)
+                return;
+            settled = true;
+            signal.removeEventListener('abort', onAbort);
+            resolve(value);
+        }, (error) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener('abort', onAbort);
+            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).
+ *
+ * # 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) {
+    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);
+        // 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.
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        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;
+    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' &&
+        err instanceof DOMException) {
+        return true;
+    }
+    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);
+        return () => { };
+    }
+    const onAbort = () => child.abort(parent.reason);
+    parent.addEventListener('abort', onAbort);
+    return () => parent.removeEventListener('abort', onAbort);
+}