actly 1.1.0 → 1.2.0

package/dist/policies/retry.cjs

@@ -1,47 +1,124 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.retryPolicy = retryPolicy;
-// ─── Helpers ─────────────────────────────────────────────────────────────────
-function computeDelay(attempt, opts) {
-    const base = opts.delayMs ?? 0;
-    if (base === 0)
-        return 0;
-    switch (opts.backoff ?? 'none') {
-        case 'linear': return base * attempt;
-        case 'exponential': return base * 2 ** (attempt - 1);
-        default: return base;
-    }
+const backoff_js_1 = require("../utils/backoff.js");
+const abort_js_1 = require("../utils/abort.js");
+const errors_js_1 = require("../errors.js");
+// ─── Default predicate ────────────────────────────────────────────────────────
+/**
+ * Default `shouldRetry`: retry on any error EXCEPT abort errors.
+ *
+ * Abort errors indicate the caller or a timeout cancelled the operation —
+ * retrying would just abort again on the next attempt, wasting delay budget.
+ *
+ * User-supplied `shouldRetry` overrides this entirely.
+ */
+function defaultShouldRetry(error, _attempt) {
+    return !(0, abort_js_1.isAbortError)(error);
 }
-const sleep = (ms) => new Promise(r => setTimeout(r, ms));
-// ─── Policy ──────────────────────────────────────────────────────────────────
+// ─── Policy ───────────────────────────────────────────────────────────────────
 /**
- * Retries fn up to opts.attempts times on any thrown error.
- * Writes the live attempt count into ctx.meta.attempts.
+ * Retry `fn` up to `opts.attempts` times on retryable errors.
+ *
+ * Writes the live attempt count into `ctx.meta.attempts` so `act()` can
+ * report it in the final `ActResult`.
+ *
+ * # Signal awareness
+ *
+ * - Before each attempt, checks `parentSignal.aborted`. If the parent (e.g.
+ *   `totalTimeout` or caller) has aborted, throws the parent's reason
+ *   immediately — no more attempts.
+ * - Sleeps between attempts use `sleep(delay, parentSignal)`. If the parent
+ *   aborts mid-delay, the sleep rejects immediately instead of blocking
+ *   the loop until the timer would have elapsed.
+ *
+ * # `shouldRetry` invocation
+ *
+ * Called after EVERY failure, including the last attempt. This preserves the
+ * predicate's contract for observers / metrics that rely on it being called
+ * per-attempt. The return value is only consulted when `attempt < max`.
+ *
+ * # Default predicate
+ *
+ * If `shouldRetry` is omitted, uses `defaultShouldRetry` which retries on
+ * every error EXCEPT abort errors (so timeouts and caller cancellations
+ * don't waste retry budget).
  */
 function retryPolicy(opts) {
-    const max = Math.max(1, opts.attempts);
-    return (fn, ctx) => async () => {
+    const max = Math.max(1, Math.floor(opts.attempts));
+    const shouldRetry = opts.shouldRetry ?? defaultShouldRetry;
+    return (fn, ctx) => async (parentSignal) => {
+        const errors = [];
         let lastErr;
+        let retriedAtLeastOnce = false;
+        const obs = ctx.observability;
         for (let attempt = 1; attempt <= max; attempt++) {
+            // Parent (totalTimeout or caller signal) already aborted — bail.
+            if (parentSignal.aborted)
+                throw parentSignal.reason;
             ctx.meta.attempts = attempt;
+            const attemptStart = Date.now();
             try {
-                return await fn();
+                // Emit onAttempt before each attempt. (We could emit
+                // after with duration/error, but before lets observers track
+                // in-flight attempts in real time.)
+                if (obs) {
+                    obs.hooks.onAttempt?.({
+                        type: 'attempt', key: ctx.key, traceId: obs.traceId,
+                        timestamp: attemptStart, attempt,
+                    });
+                }
+                return await fn(parentSignal);
             }
             catch (err) {
                 lastErr = err;
-                if (attempt < max) {
-                    // Non-retryable error — bail immediately without consuming
-                    // remaining attempts. The error surfaces exactly as-is.
-                    if (opts.shouldRetry && !opts.shouldRetry(err, attempt)) {
-                        throw err;
+                errors.push(err);
+                // Invoke shouldRetry. If the predicate throws, treat as "don't retry"
+                // and surface the original fn error (not the predicate error).
+                let retryable;
+                try {
+                    retryable = shouldRetry(err, attempt);
+                }
+                catch {
+                    // Predicate threw — don't retry, surface original error
+                    throw err;
+                }
+                if (attempt >= max) {
+                    // Last attempt. If we retried at least once (predicate
+                    // allowed retries), wrap in RetryExhaustedError for context.
+                    if (retriedAtLeastOnce) {
+                        throw new errors_js_1.RetryExhaustedError({
+                            key: ctx.key,
+                            attempts: attempt,
+                            lastError: err,
+                            errors,
+                        });
                     }
-                    const delay = computeDelay(attempt, opts);
-                    if (delay > 0)
-                        await sleep(delay);
+                    throw err;
+                }
+                if (!retryable) {
+                    // Non-retryable error — bail immediately.
+                    throw err;
+                }
+                // Mark that we retried at least once — affects final wrap.
+                retriedAtLeastOnce = true;
+                // Parent aborted mid-attempt — don't sleep, bail.
+                if (parentSignal.aborted)
+                    throw parentSignal.reason;
+                const delay = (0, backoff_js_1.computeDelay)(attempt, opts);
+                // Emit onRetry before the delay sleep.
+                if (obs) {
+                    obs.hooks.onRetry?.({
+                        type: 'retry', key: ctx.key, traceId: obs.traceId,
+                        timestamp: Date.now(), attempt, delayMs: delay, error: err,
+                    });
+                }
+                if (delay > 0) {
+                    await (0, abort_js_1.sleep)(delay, parentSignal);
                 }
             }
         }
-        // Every attempt failed — surface the last error upstream
+        // Unreachable: the loop either returns or throws on every iteration.
         throw lastErr;
     };
 }

package/dist/policies/retry.d.ts

@@ -1,7 +1,30 @@
 import type { PolicyApplier, RetryOptions } from '../types/index.js';
 /**
- * Retries fn up to opts.attempts times on any thrown error.
- * Writes the live attempt count into ctx.meta.attempts.
+ * Retry `fn` up to `opts.attempts` times on retryable errors.
+ *
+ * Writes the live attempt count into `ctx.meta.attempts` so `act()` can
+ * report it in the final `ActResult`.
+ *
+ * # Signal awareness
+ *
+ * - Before each attempt, checks `parentSignal.aborted`. If the parent (e.g.
+ *   `totalTimeout` or caller) has aborted, throws the parent's reason
+ *   immediately — no more attempts.
+ * - Sleeps between attempts use `sleep(delay, parentSignal)`. If the parent
+ *   aborts mid-delay, the sleep rejects immediately instead of blocking
+ *   the loop until the timer would have elapsed.
+ *
+ * # `shouldRetry` invocation
+ *
+ * Called after EVERY failure, including the last attempt. This preserves the
+ * predicate's contract for observers / metrics that rely on it being called
+ * per-attempt. The return value is only consulted when `attempt < max`.
+ *
+ * # Default predicate
+ *
+ * If `shouldRetry` is omitted, uses `defaultShouldRetry` which retries on
+ * every error EXCEPT abort errors (so timeouts and caller cancellations
+ * don't waste retry budget).
  */
 export declare function retryPolicy<T>(opts: RetryOptions): PolicyApplier<T>;
 //# sourceMappingURL=retry.d.ts.map

package/dist/policies/retry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/policies/retry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,aAAa,EAAiB,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAmB1F;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,GAAG,aAAa,CAAC,CAAC,CAAC,CA8BnE"}
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/policies/retry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,aAAa,EAAiB,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAqB1F;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,GAAG,aAAa,CAAC,CAAC,CAAC,CAuFnE"}

package/dist/policies/retry.js

@@ -1,44 +1,121 @@
-// ─── Helpers ─────────────────────────────────────────────────────────────────
-function computeDelay(attempt, opts) {
-    const base = opts.delayMs ?? 0;
-    if (base === 0)
-        return 0;
-    switch (opts.backoff ?? 'none') {
-        case 'linear': return base * attempt;
-        case 'exponential': return base * 2 ** (attempt - 1);
-        default: return base;
-    }
+import { computeDelay } from '../utils/backoff.js';
+import { isAbortError, sleep } from '../utils/abort.js';
+import { RetryExhaustedError } from '../errors.js';
+// ─── Default predicate ────────────────────────────────────────────────────────
+/**
+ * Default `shouldRetry`: retry on any error EXCEPT abort errors.
+ *
+ * Abort errors indicate the caller or a timeout cancelled the operation —
+ * retrying would just abort again on the next attempt, wasting delay budget.
+ *
+ * User-supplied `shouldRetry` overrides this entirely.
+ */
+function defaultShouldRetry(error, _attempt) {
+    return !isAbortError(error);
 }
-const sleep = (ms) => new Promise(r => setTimeout(r, ms));
-// ─── Policy ──────────────────────────────────────────────────────────────────
+// ─── Policy ───────────────────────────────────────────────────────────────────
 /**
- * Retries fn up to opts.attempts times on any thrown error.
- * Writes the live attempt count into ctx.meta.attempts.
+ * Retry `fn` up to `opts.attempts` times on retryable errors.
+ *
+ * Writes the live attempt count into `ctx.meta.attempts` so `act()` can
+ * report it in the final `ActResult`.
+ *
+ * # Signal awareness
+ *
+ * - Before each attempt, checks `parentSignal.aborted`. If the parent (e.g.
+ *   `totalTimeout` or caller) has aborted, throws the parent's reason
+ *   immediately — no more attempts.
+ * - Sleeps between attempts use `sleep(delay, parentSignal)`. If the parent
+ *   aborts mid-delay, the sleep rejects immediately instead of blocking
+ *   the loop until the timer would have elapsed.
+ *
+ * # `shouldRetry` invocation
+ *
+ * Called after EVERY failure, including the last attempt. This preserves the
+ * predicate's contract for observers / metrics that rely on it being called
+ * per-attempt. The return value is only consulted when `attempt < max`.
+ *
+ * # Default predicate
+ *
+ * If `shouldRetry` is omitted, uses `defaultShouldRetry` which retries on
+ * every error EXCEPT abort errors (so timeouts and caller cancellations
+ * don't waste retry budget).
  */
 export function retryPolicy(opts) {
-    const max = Math.max(1, opts.attempts);
-    return (fn, ctx) => async () => {
+    const max = Math.max(1, Math.floor(opts.attempts));
+    const shouldRetry = opts.shouldRetry ?? defaultShouldRetry;
+    return (fn, ctx) => async (parentSignal) => {
+        const errors = [];
         let lastErr;
+        let retriedAtLeastOnce = false;
+        const obs = ctx.observability;
         for (let attempt = 1; attempt <= max; attempt++) {
+            // Parent (totalTimeout or caller signal) already aborted — bail.
+            if (parentSignal.aborted)
+                throw parentSignal.reason;
             ctx.meta.attempts = attempt;
+            const attemptStart = Date.now();
             try {
-                return await fn();
+                // Emit onAttempt before each attempt. (We could emit
+                // after with duration/error, but before lets observers track
+                // in-flight attempts in real time.)
+                if (obs) {
+                    obs.hooks.onAttempt?.({
+                        type: 'attempt', key: ctx.key, traceId: obs.traceId,
+                        timestamp: attemptStart, attempt,
+                    });
+                }
+                return await fn(parentSignal);
             }
             catch (err) {
                 lastErr = err;
-                if (attempt < max) {
-                    // Non-retryable error — bail immediately without consuming
-                    // remaining attempts. The error surfaces exactly as-is.
-                    if (opts.shouldRetry && !opts.shouldRetry(err, attempt)) {
-                        throw err;
+                errors.push(err);
+                // Invoke shouldRetry. If the predicate throws, treat as "don't retry"
+                // and surface the original fn error (not the predicate error).
+                let retryable;
+                try {
+                    retryable = shouldRetry(err, attempt);
+                }
+                catch {
+                    // Predicate threw — don't retry, surface original error
+                    throw err;
+                }
+                if (attempt >= max) {
+                    // Last attempt. If we retried at least once (predicate
+                    // allowed retries), wrap in RetryExhaustedError for context.
+                    if (retriedAtLeastOnce) {
+                        throw new RetryExhaustedError({
+                            key: ctx.key,
+                            attempts: attempt,
+                            lastError: err,
+                            errors,
+                        });
                     }
-                    const delay = computeDelay(attempt, opts);
-                    if (delay > 0)
-                        await sleep(delay);
+                    throw err;
+                }
+                if (!retryable) {
+                    // Non-retryable error — bail immediately.
+                    throw err;
+                }
+                // Mark that we retried at least once — affects final wrap.
+                retriedAtLeastOnce = true;
+                // Parent aborted mid-attempt — don't sleep, bail.
+                if (parentSignal.aborted)
+                    throw parentSignal.reason;
+                const delay = computeDelay(attempt, opts);
+                // Emit onRetry before the delay sleep.
+                if (obs) {
+                    obs.hooks.onRetry?.({
+                        type: 'retry', key: ctx.key, traceId: obs.traceId,
+                        timestamp: Date.now(), attempt, delayMs: delay, error: err,
+                    });
+                }
+                if (delay > 0) {
+                    await sleep(delay, parentSignal);
                 }
             }
         }
-        // Every attempt failed — surface the last error upstream
+        // Unreachable: the loop either returns or throws on every iteration.
         throw lastErr;
     };
 }

package/dist/policies/retry.js.map

@@ -1 +1 @@
-{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/policies/retry.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAEhF,SAAS,YAAY,CAAC,OAAe,EAAE,IAAkB;IACvD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,CAAA;IAC9B,IAAI,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,CAAA;IAExB,QAAQ,IAAI,CAAC,OAAO,IAAI,MAAM,EAAE,CAAC;QAC/B,KAAK,QAAQ,CAAC,CAAM,OAAO,IAAI,GAAG,OAAO,CAAA;QACzC,KAAK,aAAa,CAAC,CAAC,OAAO,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAA;QACpD,OAAO,CAAC,CAAY,OAAO,IAAI,CAAA;IACjC,CAAC;AACH,CAAC;AAED,MAAM,KAAK,GAAG,CAAC,EAAU,EAAE,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAA;AAEvE,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAI,IAAkB;IAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAA;IAEtC,OAAO,CAAC,EAAY,EAAE,GAAkB,EAAY,EAAE,CACpD,KAAK,IAAI,EAAE;QACT,IAAI,OAAgB,CAAA;QAEpB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,GAAG,EAAE,OAAO,EAAE,EAAE,CAAC;YAChD,GAAG,CAAC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAA;YAC3B,IAAI,CAAC;gBACH,OAAO,MAAM,EAAE,EAAE,CAAA;YACnB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,GAAG,GAAG,CAAA;gBAEb,IAAI,OAAO,GAAG,GAAG,EAAE,CAAC;oBAClB,2DAA2D;oBAC3D,wDAAwD;oBACxD,IAAI,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,CAAC;wBACxD,MAAM,GAAG,CAAA;oBACX,CAAC;oBAED,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;oBACzC,IAAI,KAAK,GAAG,CAAC;wBAAE,MAAM,KAAK,CAAC,KAAK,CAAC,CAAA;gBACnC,CAAC;YACH,CAAC;QACH,CAAC;QAED,yDAAyD;QACzD,MAAM,OAAO,CAAA;IACf,CAAC,CAAA;AACL,CAAC"}
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/policies/retry.ts"],"names":[],"mappings":"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"}

package/dist/policies/timeout.cjs

@@ -3,55 +3,97 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TotalTimeoutError = exports.TimeoutError = void 0;
 exports.timeoutPolicy = timeoutPolicy;
 exports.totalTimeoutPolicy = totalTimeoutPolicy;
-// ─── Errors ───────────────────────────────────────────────────────────────────
-class TimeoutError extends Error {
-    constructor(ms) {
-        super(`ACT timed out after ${ms}ms`);
-        this.name = 'TimeoutError';
-        this.ms = ms;
-    }
-}
-exports.TimeoutError = TimeoutError;
+const abort_js_1 = require("../utils/abort.js");
+const errors_js_1 = require("../errors.js");
+Object.defineProperty(exports, "TimeoutError", { enumerable: true, get: function () { return errors_js_1.TimeoutError; } });
+Object.defineProperty(exports, "TotalTimeoutError", { enumerable: true, get: function () { return errors_js_1.TotalTimeoutError; } });
+// ─── Policy ───────────────────────────────────────────────────────────────────
 /**
- * Thrown when the total budget across all attempts is exceeded.
- * Distinct from TimeoutError (per-attempt) so callers can instanceof-check
- * which deadline fired.
+ * Build a timeout policy that throws `ErrorCtor` on deadline.
+ *
+ * # Cancellation contract
+ *
+ * Each invocation:
+ *   1. Creates a fresh `AbortController` for this attempt.
+ *   2. Arms a `setTimeout` that aborts the controller with a fresh `ErrorCtor(ms)`.
+ *   3. Links the parent signal: if the parent aborts (e.g. `totalTimeout` or
+ *      caller cancellation), the child aborts with the parent's reason.
+ *   4. Races `fn(childSignal)` against the abort event.
+ *
+ * The race is critical: it ensures `act()` returns promptly even if `fn`
+ * ignores the signal. The underlying `fn` may keep running in the background
+ * (resource leak), but the caller is unblocked. This is the best JavaScript
+ * can do without cooperation from `fn`.
+ *
+ * If `fn` cooperates (passes `signal` to `fetch`, `AbortController`, etc.),
+ * the underlying work is cancelled properly — no leak.
+ *
+ * # Error attribution
+ *
+ * If the per-attempt timer fires, we throw `ErrorCtor(ms)` regardless of
+ * what `fn` does. If the parent signal fires first, we throw the parent's
+ * reason (could be `TotalTimeoutError`, an `AbortError`, or anything else).
  */
-class TotalTimeoutError extends Error {
-    constructor(ms) {
-        super(`ACT total timeout exceeded after ${ms}ms`);
-        this.name = 'TotalTimeoutError';
-        this.ms = ms;
-    }
-}
-exports.TotalTimeoutError = TotalTimeoutError;
-// ─── Helpers ──────────────────────────────────────────────────────────────────
-/** Shared race-against-a-timer logic. ErrorCtor lets callers pick the error type. */
 function makeTimeoutPolicy(opts, ErrorCtor) {
-    return (fn, _ctx) => () => new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(new ErrorCtor(opts.ms)), opts.ms);
-        fn()
-            .then((v) => { clearTimeout(timer); resolve(v); })
-            .catch((e) => { clearTimeout(timer); reject(e); });
-    });
+    return (fn, ctx) => async (parentSignal) => {
+        const controller = new AbortController();
+        // Pass key to the error ctor for better debugging context.
+        const timerError = new ErrorCtor(opts.ms, { key: ctx.key });
+        // Arm the per-attempt timer. The error object is allocated once so the
+        // stack trace points here (the policy frame), not at setTimeout's
+        // internal callback.
+        const timer = setTimeout(() => controller.abort(timerError), opts.ms);
+        // NOTE: do NOT `unref()` this timer. The timeout IS the operation
+        // the caller is awaiting. unref'ing would let Node exit the process
+        // while a timeout was pending — silently dropping the operation.
+        // The timer is cleared in the finally block below.
+        // Link parent → child. Capture the unlink function so we can clean
+        // up the listener on success path (contract).
+        const unlink = (0, abort_js_1.linkSignal)(parentSignal, controller);
+        try {
+            // Race fn against the abort event. If fn settles first, we get its
+            // result/error. If the signal aborts first, we reject with reason.
+            //
+            // We do NOT use AbortSignal.timeout() here because we need to throw
+            // our own ErrorCtor, not a DOMException named "TimeoutError".
+            return await new Promise((resolve, reject) => {
+                if (controller.signal.aborted) {
+                    reject(controller.signal.reason);
+                    return;
+                }
+                const onAbort = () => reject(controller.signal.reason);
+                controller.signal.addEventListener('abort', onAbort, { once: true });
+                Promise.resolve(fn(controller.signal)).then((value) => {
+                    controller.signal.removeEventListener('abort', onAbort);
+                    resolve(value);
+                }, (error) => {
+                    controller.signal.removeEventListener('abort', onAbort);
+                    reject(error);
+                });
+            });
+        }
+        finally {
+            clearTimeout(timer);
+            unlink();
+        }
+    };
 }
-// ─── Policies ─────────────────────────────────────────────────────────────────
 /**
- * Races fn against a hard deadline.
- * Rejects with TimeoutError if the deadline fires first.
+ * Per-attempt timeout. Races `fn` against a deadline that resets on retry.
  *
- * Place this INSIDE retryPolicy (closer to fn) so each attempt has its own clock.
+ * Place this INSIDE `retryPolicy` (closer to `fn`) so each attempt has its
+ * own clock.
  */
 function timeoutPolicy(opts) {
-    return makeTimeoutPolicy(opts, TimeoutError);
+    return makeTimeoutPolicy(opts, errors_js_1.TimeoutError);
 }
 /**
- * Races the ENTIRE operation (all retry attempts + delays) against a budget.
- * Rejects with TotalTimeoutError if the budget is exhausted.
+ * Operation-wide timeout. Races the ENTIRE chain (all retry attempts +
+ * delays) against a hard budget that does NOT reset.
  *
  * Place this as the OUTERMOST policy so the clock starts before any other
  * policy runs and stops regardless of what the inner chain is doing.
  */
 function totalTimeoutPolicy(opts) {
-    return makeTimeoutPolicy(opts, TotalTimeoutError);
+    return makeTimeoutPolicy(opts, errors_js_1.TotalTimeoutError);
 }

package/dist/policies/timeout.d.ts

@@ -1,27 +1,16 @@
 import type { PolicyApplier, TimeoutOptions } from '../types/index.js';
-export declare class TimeoutError extends Error {
-    readonly ms: number;
-    constructor(ms: number);
-}
+import { TimeoutError, TotalTimeoutError } from '../errors.js';
+export { TimeoutError, TotalTimeoutError };
 /**
- * Thrown when the total budget across all attempts is exceeded.
- * Distinct from TimeoutError (per-attempt) so callers can instanceof-check
- * which deadline fired.
- */
-export declare class TotalTimeoutError extends Error {
-    readonly ms: number;
-    constructor(ms: number);
-}
-/**
- * Races fn against a hard deadline.
- * Rejects with TimeoutError if the deadline fires first.
+ * Per-attempt timeout. Races `fn` against a deadline that resets on retry.
  *
- * Place this INSIDE retryPolicy (closer to fn) so each attempt has its own clock.
+ * Place this INSIDE `retryPolicy` (closer to `fn`) so each attempt has its
+ * own clock.
  */
 export declare function timeoutPolicy<T>(opts: TimeoutOptions): PolicyApplier<T>;
 /**
- * Races the ENTIRE operation (all retry attempts + delays) against a budget.
- * Rejects with TotalTimeoutError if the budget is exhausted.
+ * Operation-wide timeout. Races the ENTIRE chain (all retry attempts +
+ * delays) against a hard budget that does NOT reset.
  *
  * Place this as the OUTERMOST policy so the clock starts before any other
  * policy runs and stops regardless of what the inner chain is doing.

package/dist/policies/timeout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timeout.d.ts","sourceRoot":"","sources":["../../src/policies/timeout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,aAAa,EAAiB,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAI5F,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;gBAEP,EAAE,EAAE,MAAM;CAKvB;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;gBAEP,EAAE,EAAE,MAAM;CAKvB;AAyBD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,GAAG,aAAa,CAAC,CAAC,CAAC,CAEvE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,GAAG,aAAa,CAAC,CAAC,CAAC,CAE5E"}
+{"version":3,"file":"timeout.d.ts","sourceRoot":"","sources":["../../src/policies/timeout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,aAAa,EAAiB,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAE5F,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAa9D,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,CAAA;AAyF1C;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,GAAG,aAAa,CAAC,CAAC,CAAC,CAEvE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,GAAG,aAAa,CAAC,CAAC,CAAC,CAE5E"}