@zap-studio/retry 0.1.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @zap-studio/retry
 
+## 0.3.0
+
+### Breaking
+
+- **Subpath for error types:** use `@zap-studio/retry/errors` (plural) for `RetryError`, `AbortError`, and related types. A prior JSR `error` subpath that pointed at a non-existent `error.ts` entry is removed; update deep imports from `@zap-studio/retry/error` to `@zap-studio/retry/errors`.
+
+### Changed
+
+- Add dedicated `AbortError` and normalize cancellation paths so retry internals throw/return `RetryError` or `AbortError` instead of plain `Error`.
+- Expose `defaultSleep` from the `@zap-studio/retry/sleep` subpath only (the main entry does not re-export it; `run` still uses it internally when `sleep` is omitted).
+- Align non-throw exhaustion metadata so `result.attempts` and `result.error.attempts` stay consistent for `RetryError` outcomes.
+- In non-throw mode, return a normalized `AbortError` on `result.error` for cancellation; `result.attempts` still reports completed attempts.
+- Refactor result-mode internals into smaller helpers for lower complexity and cleaner maintainability.
+- Expand docs across README and package docs pages to explain `AbortError` behavior in throw and non-throw modes.
+- Split the retry runner into dedicated modules: `throw-mode` (throwing execution path), `result-mode` (non-throw `RetryRunResult` path), and `sleep` (the default `defaultSleep` implementation). `BaseRetryPolicy` in `index` now delegates to these modules without changing public behavior.
+- Add exhaustive TSDoc for `result-mode` and other `src` modules, including private helpers, policy option and state fields, and `RetryRunResult` union members.
+- Rework test layout into `sleep`, `throw-mode`, `result-mode`, and `index` test files with a shared `sequence-policy` fixture, replacing the prior combined `index` and `abort` test files.
+
+## 0.2.0
+
+### Changed
+
+- Optimize retry runner hot paths by splitting throw/non-throw execution flows and skipping sleep calls when delay is non-positive.
+- Add `AbortSignal` support to `run(...)` so retry orchestration can be canceled before or between attempts.
+- Add retry benchmarking coverage with core and ecosystem scenarios, including real-world and fair-mode comparisons.
+- Add abort-focused ecosystem benchmarks comparing signal overhead and immediate cancellation behavior.
+- Expand TSDoc coverage for new runner internals added in this release.
+
 ## 0.1.2
 
 ### Changed

package/README.md

@@ -33,10 +33,11 @@ const data = await exponential.run(async () => {
 
 `run(...)` throws when retries are exhausted.
 
-By default, policies extending `BaseRetryPolicy` throw `RetryError`.
+By default, policies extending `BaseRetryPolicy` throw `RetryError` on exhaustion
+and `AbortError` on cancellation.
 
 ```ts
-import { RetryError } from "@zap-studio/retry/error";
+import { AbortError, RetryError } from "@zap-studio/retry/errors";
 
 try {
   const data = await exponential.run(async () => {
@@ -50,6 +51,8 @@ try {
   if (error instanceof RetryError) {
     console.error("Retries exhausted:", error.attempts);
     console.error("Last error:", error.lastError);
+  } else if (error instanceof AbortError) {
+    console.error("Retry aborted:", error.message);
   } else {
     throw error;
   }
@@ -77,6 +80,60 @@ if (!result.ok) {
 }
 ```
 
+## Default sleep
+
+`BaseRetryPolicy.run` automatically applies a delay between retry attempts when no custom `sleep` function is provided in the options.
+
+That default is the `defaultSleep` helper, exported from `@zap-studio/retry/sleep`.
+
+By default, this delay mechanism relies on the native JavaScript `setTimeout`, meaning retries are scheduled using the standard event loop timing rather than any custom or blocking implementation.
+
+## Cancellation With AbortSignal
+
+Use `signal` in `run(...)` options to stop retrying early.
+
+```ts
+const controller = new AbortController();
+
+const promise = exponential.run(
+  async () => {
+    const response = await $fetch("https://api.example.com/users", {
+      throwOnFetchError: true,
+    });
+    return await response.json();
+  },
+  { signal: controller.signal },
+);
+
+controller.abort(new Error("Request canceled"));
+
+await promise;
+```
+
+In non-throw mode, abort is returned as `{ ok: false }` with `AbortError` on
+`result.error`:
+
+```ts
+const controller = new AbortController();
+
+const result = await exponential.run(
+  async () => {
+    const response = await $fetch("https://api.example.com/users", {
+      throwOnFetchError: true,
+    });
+    return await response.json();
+  },
+  {
+    signal: controller.signal,
+    throwOnExhausted: false,
+  },
+);
+
+if (!result.ok) {
+  console.error("Retry stopped:", result.error);
+}
+```
+
 ## Choosing The Right Policy
 
 Use `ExponentialBackoff` for transient network instability and shared upstream services.
@@ -144,7 +201,7 @@ const value = await policy.run(doWork);
 Use `RetryError` when an orchestrator exhausts retries and needs to surface final context.
 
 ```ts
-import { RetryError } from "@zap-studio/retry/error";
+import { RetryError } from "@zap-studio/retry/errors";
 
 throw new RetryError("Retry policy exhausted all attempts.", {
   attempts: attempt,

package/dist/abort.d.mts

@@ -0,0 +1,30 @@
+import { t as AbortError } from "./errors-fWo_KyVO.mjs";
+
+//#region src/abort.d.ts
+/**
+* Throws when the provided abort signal is already aborted.
+*
+* @param signal - Optional abort signal to inspect.
+* @throws {AbortError} When the signal is aborted.
+*/
+declare function throwIfAborted(signal?: AbortSignal): void;
+/**
+* Converts an abort reason into a normalized `AbortError`.
+*
+* @param reason - Arbitrary abort reason value.
+* @returns Normalized abort error instance.
+*/
+declare function toAbortError(reason: unknown): AbortError;
+/**
+* Waits for delay sleep while observing cancellation through an abort signal.
+*
+* @param sleep - Sleep function used to await `delayMs`.
+* @param delayMs - Delay duration in milliseconds.
+* @param signal - Abort signal to observe while waiting.
+* @returns Promise that resolves when delay finishes.
+* @throws {AbortError} When the signal aborts before or during wait.
+*/
+declare function sleepWithAbortSignal(sleep: (delayMs: number) => Promise<void>, delayMs: number, signal: AbortSignal): Promise<void>;
+//#endregion
+export { sleepWithAbortSignal, throwIfAborted, toAbortError };
+//# sourceMappingURL=abort.d.mts.map

package/dist/abort.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.d.mts","names":[],"sources":["../src/abort.ts"],"mappings":";;;;;AA4BA;;;;iBAdgB,cAAA,CAAe,MAAA,GAAS,WAAA;AA+CxC;;;;;;AAAA,iBAjCgB,YAAA,CAAa,MAAA,YAAkB,UAAA;;;;;;;;;;iBAiCzB,oBAAA,CACpB,KAAA,GAAQ,OAAA,aAAoB,OAAA,QAC5B,OAAA,UACA,MAAA,EAAQ,WAAA,GACP,OAAA"}

package/dist/abort.mjs

@@ -0,0 +1,61 @@
+import { AbortError } from "./errors.mjs";
+//#region src/abort.ts
+/**
+* Abort-signal helpers for retry orchestration internals.
+*
+* @module @zap-studio/retry/abort
+*/
+/**
+* Throws when the provided abort signal is already aborted.
+*
+* @param signal - Optional abort signal to inspect.
+* @throws {AbortError} When the signal is aborted.
+*/
+function throwIfAborted(signal) {
+	if (!signal?.aborted) return;
+	throw toAbortError(signal.reason);
+}
+/**
+* Converts an abort reason into a normalized `AbortError`.
+*
+* @param reason - Arbitrary abort reason value.
+* @returns Normalized abort error instance.
+*/
+function toAbortError(reason) {
+	if (reason instanceof AbortError) return reason;
+	if (reason instanceof Error) return new AbortError(reason.message, { cause: reason });
+	if (typeof reason === "string" && reason.length > 0) return new AbortError(reason);
+	if (reason === void 0) return new AbortError("Retry aborted.");
+	try {
+		return new AbortError(`Retry aborted: ${JSON.stringify(reason)}`);
+	} catch {
+		return new AbortError("Retry aborted.");
+	}
+}
+/**
+* Waits for delay sleep while observing cancellation through an abort signal.
+*
+* @param sleep - Sleep function used to await `delayMs`.
+* @param delayMs - Delay duration in milliseconds.
+* @param signal - Abort signal to observe while waiting.
+* @returns Promise that resolves when delay finishes.
+* @throws {AbortError} When the signal aborts before or during wait.
+*/
+async function sleepWithAbortSignal(sleep, delayMs, signal) {
+	if (signal.aborted) throw toAbortError(signal.reason);
+	let onAbort;
+	try {
+		await Promise.race([sleep(delayMs), new Promise((_, reject) => {
+			onAbort = () => {
+				reject(toAbortError(signal.reason));
+			};
+			signal.addEventListener("abort", onAbort, { once: true });
+		})]);
+	} finally {
+		if (onAbort) signal.removeEventListener("abort", onAbort);
+	}
+}
+//#endregion
+export { sleepWithAbortSignal, throwIfAborted, toAbortError };
+
+//# sourceMappingURL=abort.mjs.map

package/dist/abort.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.mjs","names":[],"sources":["../src/abort.ts"],"sourcesContent":["/**\n * Abort-signal helpers for retry orchestration internals.\n *\n * @module @zap-studio/retry/abort\n */\n\nimport { AbortError } from \"./errors.js\";\n\n/**\n * Throws when the provided abort signal is already aborted.\n *\n * @param signal - Optional abort signal to inspect.\n * @throws {AbortError} When the signal is aborted.\n */\nexport function throwIfAborted(signal?: AbortSignal): void {\n  if (!signal?.aborted) {\n    return;\n  }\n\n  throw toAbortError(signal.reason);\n}\n\n/**\n * Converts an abort reason into a normalized `AbortError`.\n *\n * @param reason - Arbitrary abort reason value.\n * @returns Normalized abort error instance.\n */\nexport function toAbortError(reason: unknown): AbortError {\n  if (reason instanceof AbortError) {\n    return reason;\n  }\n\n  if (reason instanceof Error) {\n    return new AbortError(reason.message, { cause: reason });\n  }\n\n  if (typeof reason === \"string\" && reason.length > 0) {\n    return new AbortError(reason);\n  }\n\n  if (reason === undefined) {\n    return new AbortError(\"Retry aborted.\");\n  }\n\n  try {\n    return new AbortError(`Retry aborted: ${JSON.stringify(reason)}`);\n  } catch {\n    return new AbortError(\"Retry aborted.\");\n  }\n}\n\n/**\n * Waits for delay sleep while observing cancellation through an abort signal.\n *\n * @param sleep - Sleep function used to await `delayMs`.\n * @param delayMs - Delay duration in milliseconds.\n * @param signal - Abort signal to observe while waiting.\n * @returns Promise that resolves when delay finishes.\n * @throws {AbortError} When the signal aborts before or during wait.\n */\nexport async function sleepWithAbortSignal(\n  sleep: (delayMs: number) => Promise<void>,\n  delayMs: number,\n  signal: AbortSignal,\n): Promise<void> {\n  if (signal.aborted) {\n    throw toAbortError(signal.reason);\n  }\n\n  let onAbort: (() => void) | undefined;\n\n  try {\n    await Promise.race([\n      sleep(delayMs),\n      new Promise<never>((_, reject) => {\n        onAbort = (): void => {\n          reject(toAbortError(signal.reason));\n        };\n\n        signal.addEventListener(\"abort\", onAbort, { once: true });\n      }),\n    ]);\n  } finally {\n    if (onAbort) {\n      signal.removeEventListener(\"abort\", onAbort);\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AAcA,SAAgB,eAAe,QAA4B;AACzD,KAAI,CAAC,QAAQ,QACX;AAGF,OAAM,aAAa,OAAO,OAAO;;;;;;;;AASnC,SAAgB,aAAa,QAA6B;AACxD,KAAI,kBAAkB,WACpB,QAAO;AAGT,KAAI,kBAAkB,MACpB,QAAO,IAAI,WAAW,OAAO,SAAS,EAAE,OAAO,QAAQ,CAAC;AAG1D,KAAI,OAAO,WAAW,YAAY,OAAO,SAAS,EAChD,QAAO,IAAI,WAAW,OAAO;AAG/B,KAAI,WAAW,KAAA,EACb,QAAO,IAAI,WAAW,iBAAiB;AAGzC,KAAI;AACF,SAAO,IAAI,WAAW,kBAAkB,KAAK,UAAU,OAAO,GAAG;SAC3D;AACN,SAAO,IAAI,WAAW,iBAAiB;;;;;;;;;;;;AAa3C,eAAsB,qBACpB,OACA,SACA,QACe;AACf,KAAI,OAAO,QACT,OAAM,aAAa,OAAO,OAAO;CAGnC,IAAI;AAEJ,KAAI;AACF,QAAM,QAAQ,KAAK,CACjB,MAAM,QAAQ,EACd,IAAI,SAAgB,GAAG,WAAW;AAChC,mBAAsB;AACpB,WAAO,aAAa,OAAO,OAAO,CAAC;;AAGrC,UAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,MAAM,CAAC;IACzD,CACH,CAAC;WACM;AACR,MAAI,QACF,QAAO,oBAAoB,SAAS,QAAQ"}

package/dist/errors-fWo_KyVO.d.mts

@@ -0,0 +1,76 @@
+//#region src/errors.d.ts
+/**
+* Terminal error types used by retry policies and runners.
+*
+* @module @zap-studio/retry/errors
+*/
+/**
+* Context payload attached to `RetryError`.
+*/
+interface RetryErrorContext {
+  /**
+  * Count of completed attempts at exhaustion.
+  */
+  readonly attempts: number;
+  /**
+  * The last error object raised by a failed `execute` attempt.
+  */
+  readonly lastError?: unknown;
+  /**
+  * Optional data captured from the last attempt when provided by a policy.
+  */
+  readonly lastData?: unknown;
+}
+/**
+* Context payload attached to `AbortError`.
+*/
+interface AbortErrorContext {
+  /**
+  * When the abort `reason` was an `Error`, the optional wrapped cause.
+  */
+  readonly cause?: unknown;
+}
+/**
+* Error thrown when retries are exhausted.
+*
+* @example
+* throw new RetryError("Retry exhausted", {
+*   attempts: 3,
+*   lastError: new Error("network"),
+* });
+*/
+declare class RetryError extends Error {
+  /**
+  * Total attempts performed before exhaustion.
+  */
+  readonly attempts: number;
+  /**
+  * Last captured error from execution.
+  */
+  readonly lastError?: unknown;
+  /**
+  * Last captured data value, when available.
+  */
+  readonly lastData?: unknown;
+  /**
+  * Creates a RetryError with structured terminal context.
+  */
+  constructor(message: string, context: RetryErrorContext);
+}
+/**
+* Error thrown when retry orchestration is canceled through `AbortSignal`.
+*/
+declare class AbortError extends Error {
+  /**
+  * Optional wrapped cause when the native abort `reason` was an `Error`.
+  */
+  override readonly cause?: unknown;
+  /**
+  * @param message - Human-readable abort description.
+  * @param context - Optional `cause` link for diagnostic chaining.
+  */
+  constructor(message: string, context?: AbortErrorContext);
+}
+//#endregion
+export { RetryErrorContext as i, AbortErrorContext as n, RetryError as r, AbortError as t };
+//# sourceMappingURL=errors-fWo_KyVO.d.mts.map

package/dist/errors-fWo_KyVO.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors-fWo_KyVO.d.mts","names":[],"sources":["../src/errors.ts"],"mappings":";;AASA;;;;;;;UAAiB,iBAAA;EAYN;AAMX;;EANW,SARA,QAAA;EAcM;;AAgBjB;EAhBiB,SAVN,SAAA;;;;WAIA,QAAA;AAAA;;;;UAMM,iBAAA;;;;WAIN,KAAA;AAAA;;;;;;;;;;cAYE,UAAA,SAAmB,KAAA;;;;WAId,QAAA;;;;WAIA,SAAA;;;;WAIA,QAAA;;;;EAKhB,WAAA,CAAY,OAAA,UAAiB,OAAA,EAAS,iBAAA;AAAA;;;;cAY3B,UAAA,SAAmB,KAAA;;;;oBAIL,KAAA;;;;;EAMzB,WAAA,CAAY,OAAA,UAAiB,OAAA,GAAS,iBAAA;AAAA"}

package/dist/errors.d.mts

@@ -0,0 +1,2 @@
+import { i as RetryErrorContext, n as AbortErrorContext, r as RetryError, t as AbortError } from "./errors-fWo_KyVO.mjs";
+export { AbortError, AbortErrorContext, RetryError, RetryErrorContext };

package/dist/{error.mjs → errors.mjs}

@@ -1,4 +1,4 @@
-//#region src/error.ts
+//#region src/errors.ts
 /**
 * Error thrown when retries are exhausted.
 *
@@ -32,7 +32,25 @@ var RetryError = class extends Error {
 		this.lastData = context.lastData;
 	}
 };
+/**
+* Error thrown when retry orchestration is canceled through `AbortSignal`.
+*/
+var AbortError = class extends Error {
+	/**
+	* Optional wrapped cause when the native abort `reason` was an `Error`.
+	*/
+	cause;
+	/**
+	* @param message - Human-readable abort description.
+	* @param context - Optional `cause` link for diagnostic chaining.
+	*/
+	constructor(message, context = {}) {
+		super(message);
+		this.name = "AbortError";
+		this.cause = context.cause;
+	}
+};
 //#endregion
-export { RetryError };
+export { AbortError, RetryError };
 
-//# sourceMappingURL=error.mjs.map
+//# sourceMappingURL=errors.mjs.map

package/dist/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Terminal error types used by retry policies and runners.\n *\n * @module @zap-studio/retry/errors\n */\n\n/**\n * Context payload attached to `RetryError`.\n */\nexport interface RetryErrorContext {\n  /**\n   * Count of completed attempts at exhaustion.\n   */\n  readonly attempts: number;\n  /**\n   * The last error object raised by a failed `execute` attempt.\n   */\n  readonly lastError?: unknown;\n  /**\n   * Optional data captured from the last attempt when provided by a policy.\n   */\n  readonly lastData?: unknown;\n}\n\n/**\n * Context payload attached to `AbortError`.\n */\nexport interface AbortErrorContext {\n  /**\n   * When the abort `reason` was an `Error`, the optional wrapped cause.\n   */\n  readonly cause?: unknown;\n}\n\n/**\n * Error thrown when retries are exhausted.\n *\n * @example\n * throw new RetryError(\"Retry exhausted\", {\n *   attempts: 3,\n *   lastError: new Error(\"network\"),\n * });\n */\nexport class RetryError extends Error {\n  /**\n   * Total attempts performed before exhaustion.\n   */\n  public readonly attempts: number;\n  /**\n   * Last captured error from execution.\n   */\n  public readonly lastError?: unknown;\n  /**\n   * Last captured data value, when available.\n   */\n  public readonly lastData?: unknown;\n\n  /**\n   * Creates a RetryError with structured terminal context.\n   */\n  constructor(message: string, context: RetryErrorContext) {\n    super(message);\n    this.name = \"RetryError\";\n    this.attempts = context.attempts;\n    this.lastError = context.lastError;\n    this.lastData = context.lastData;\n  }\n}\n\n/**\n * Error thrown when retry orchestration is canceled through `AbortSignal`.\n */\nexport class AbortError extends Error {\n  /**\n   * Optional wrapped cause when the native abort `reason` was an `Error`.\n   */\n  public override readonly cause?: unknown;\n\n  /**\n   * @param message - Human-readable abort description.\n   * @param context - Optional `cause` link for diagnostic chaining.\n   */\n  constructor(message: string, context: AbortErrorContext = {}) {\n    super(message);\n    this.name = \"AbortError\";\n    this.cause = context.cause;\n  }\n}\n"],"mappings":";;;;;;;;;;AA2CA,IAAa,aAAb,cAAgC,MAAM;;;;CAIpC;;;;CAIA;;;;CAIA;;;;CAKA,YAAY,SAAiB,SAA4B;AACvD,QAAM,QAAQ;AACd,OAAK,OAAO;AACZ,OAAK,WAAW,QAAQ;AACxB,OAAK,YAAY,QAAQ;AACzB,OAAK,WAAW,QAAQ;;;;;;AAO5B,IAAa,aAAb,cAAgC,MAAM;;;;CAIpC;;;;;CAMA,YAAY,SAAiB,UAA6B,EAAE,EAAE;AAC5D,QAAM,QAAQ;AACd,OAAK,OAAO;AACZ,OAAK,QAAQ,QAAQ"}

package/dist/exponential-backoff.d.mts

@@ -6,8 +6,17 @@ import { BaseRetryPolicy } from "./index.mjs";
 * Configuration for `ExponentialBackoff`.
 */
 interface ExponentialBackoffOptions {
+  /**
+  * Maximum number of attempts (including the first) before giving up.
+  */
   maxAttempts: number;
+  /**
+  * Initial delay in milliseconds, doubled each retry until capped.
+  */
   baseDelayMs: number;
+  /**
+  * Hard upper bound in milliseconds for computed exponential delay.
+  */
   maxDelayMs: number;
 }
 /**
@@ -21,8 +30,17 @@ interface ExponentialBackoffOptions {
 * });
 */
 declare class ExponentialBackoff extends BaseRetryPolicy {
+  /**
+  * Maximum number of attempts before the policy returns `max-attempts-reached`.
+  */
   private readonly maxAttempts;
+  /**
+  * Base delay in milliseconds used in `baseDelayMs * 2 ** (attempt - 1)`.
+  */
   private readonly baseDelayMs;
+  /**
+  * Upper cap for computed delay, applied with `Math.min`.
+  */
   private readonly maxDelayMs;
   /**
   * Creates an exponential backoff retry policy.

package/dist/exponential-backoff.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"exponential-backoff.d.mts","names":[],"sources":["../src/exponential-backoff.ts"],"mappings":";;;;;;;UAYiB,yBAAA;EACf,WAAA;EACA,WAAA;EACA,UAAA;AAAA;;;;;;;;;;;cAaW,kBAAA,SAA2B,eAAA;EAAA,iBACrB,WAAA;EAAA,iBACA,WAAA;EAAA,iBACA,UAAA;;;;EAKjB,WAAA,CAAY,OAAA,EAAS,yBAAA;;;;EAUrB,IAAA,CAAY,KAAA,EAAO,kBAAA,GAAqB,aAAA;AAAA"}
+{"version":3,"file":"exponential-backoff.d.mts","names":[],"sources":["../src/exponential-backoff.ts"],"mappings":";;;;;;;UAYiB,yBAAA;;;AAyBjB;EArBE,WAAA;;;;EAIA,WAAA;;;;EAIA,UAAA;AAAA;;;;;;;;;;;cAaW,kBAAA,SAA2B,eAAA;;;;mBAIrB,WAAA;;;;mBAIA,WAAA;;;;mBAIA,UAAA;;;;EAKjB,WAAA,CAAY,OAAA,EAAS,yBAAA;;;;EAUrB,IAAA,CAAY,KAAA,EAAO,kBAAA,GAAqB,aAAA;AAAA"}

package/dist/exponential-backoff.mjs

@@ -3,7 +3,7 @@ import { BaseRetryPolicy } from "./index.mjs";
 /**
 * Exponential backoff retry strategy.
 *
-* @module
+* @module @zap-studio/retry/exponential-backoff
 */
 /**
 * Retries with exponential delay growth up to a max cap.
@@ -16,8 +16,17 @@ import { BaseRetryPolicy } from "./index.mjs";
 * });
 */
 var ExponentialBackoff = class extends BaseRetryPolicy {
+	/**
+	* Maximum number of attempts before the policy returns `max-attempts-reached`.
+	*/
 	maxAttempts;
+	/**
+	* Base delay in milliseconds used in `baseDelayMs * 2 ** (attempt - 1)`.
+	*/
 	baseDelayMs;
+	/**
+	* Upper cap for computed delay, applied with `Math.min`.
+	*/
 	maxDelayMs;
 	/**
 	* Creates an exponential backoff retry policy.

package/dist/exponential-backoff.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"exponential-backoff.mjs","names":[],"sources":["../src/exponential-backoff.ts"],"sourcesContent":["/**\n * Exponential backoff retry strategy.\n *\n * @module\n */\n\nimport { BaseRetryPolicy } from \"./index.js\";\nimport type { RetryDecision, RetryDecisionInput } from \"./types.js\";\n\n/**\n * Configuration for `ExponentialBackoff`.\n */\nexport interface ExponentialBackoffOptions {\n  maxAttempts: number;\n  baseDelayMs: number;\n  maxDelayMs: number;\n}\n\n/**\n * Retries with exponential delay growth up to a max cap.\n *\n * @example\n * const policy = new ExponentialBackoff({\n *   maxAttempts: 5,\n *   baseDelayMs: 100,\n *   maxDelayMs: 2_000,\n * });\n */\nexport class ExponentialBackoff extends BaseRetryPolicy {\n  private readonly maxAttempts: number;\n  private readonly baseDelayMs: number;\n  private readonly maxDelayMs: number;\n\n  /**\n   * Creates an exponential backoff retry policy.\n   */\n  constructor(options: ExponentialBackoffOptions) {\n    super();\n    this.maxAttempts = options.maxAttempts;\n    this.baseDelayMs = options.baseDelayMs;\n    this.maxDelayMs = options.maxDelayMs;\n  }\n\n  /**\n   * Computes retry decision for the current attempt.\n   */\n  public next(input: RetryDecisionInput): RetryDecision {\n    if (input.attempt >= this.maxAttempts) {\n      return { shouldRetry: false, delayMs: 0, reason: \"max-attempts-reached\" };\n    }\n\n    const exponent = Math.max(0, input.attempt - 1);\n    const delayMs = Math.min(this.maxDelayMs, this.baseDelayMs * 2 ** exponent);\n\n    return { shouldRetry: true, delayMs, reason: \"retry\" };\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AA4BA,IAAa,qBAAb,cAAwC,gBAAgB;CACtD;CACA;CACA;;;;CAKA,YAAY,SAAoC;AAC9C,SAAO;AACP,OAAK,cAAc,QAAQ;AAC3B,OAAK,cAAc,QAAQ;AAC3B,OAAK,aAAa,QAAQ;;;;;CAM5B,KAAY,OAA0C;AACpD,MAAI,MAAM,WAAW,KAAK,YACxB,QAAO;GAAE,aAAa;GAAO,SAAS;GAAG,QAAQ;GAAwB;EAG3E,MAAM,WAAW,KAAK,IAAI,GAAG,MAAM,UAAU,EAAE;AAG/C,SAAO;GAAE,aAAa;GAAM,SAFZ,KAAK,IAAI,KAAK,YAAY,KAAK,cAAc,KAAK,SAAS;GAEtC,QAAQ;GAAS"}
+{"version":3,"file":"exponential-backoff.mjs","names":[],"sources":["../src/exponential-backoff.ts"],"sourcesContent":["/**\n * Exponential backoff retry strategy.\n *\n * @module @zap-studio/retry/exponential-backoff\n */\n\nimport { BaseRetryPolicy } from \"./index.js\";\nimport type { RetryDecision, RetryDecisionInput } from \"./types.js\";\n\n/**\n * Configuration for `ExponentialBackoff`.\n */\nexport interface ExponentialBackoffOptions {\n  /**\n   * Maximum number of attempts (including the first) before giving up.\n   */\n  maxAttempts: number;\n  /**\n   * Initial delay in milliseconds, doubled each retry until capped.\n   */\n  baseDelayMs: number;\n  /**\n   * Hard upper bound in milliseconds for computed exponential delay.\n   */\n  maxDelayMs: number;\n}\n\n/**\n * Retries with exponential delay growth up to a max cap.\n *\n * @example\n * const policy = new ExponentialBackoff({\n *   maxAttempts: 5,\n *   baseDelayMs: 100,\n *   maxDelayMs: 2_000,\n * });\n */\nexport class ExponentialBackoff extends BaseRetryPolicy {\n  /**\n   * Maximum number of attempts before the policy returns `max-attempts-reached`.\n   */\n  private readonly maxAttempts: number;\n  /**\n   * Base delay in milliseconds used in `baseDelayMs * 2 ** (attempt - 1)`.\n   */\n  private readonly baseDelayMs: number;\n  /**\n   * Upper cap for computed delay, applied with `Math.min`.\n   */\n  private readonly maxDelayMs: number;\n\n  /**\n   * Creates an exponential backoff retry policy.\n   */\n  constructor(options: ExponentialBackoffOptions) {\n    super();\n    this.maxAttempts = options.maxAttempts;\n    this.baseDelayMs = options.baseDelayMs;\n    this.maxDelayMs = options.maxDelayMs;\n  }\n\n  /**\n   * Computes retry decision for the current attempt.\n   */\n  public next(input: RetryDecisionInput): RetryDecision {\n    if (input.attempt >= this.maxAttempts) {\n      return { shouldRetry: false, delayMs: 0, reason: \"max-attempts-reached\" };\n    }\n\n    const exponent = Math.max(0, input.attempt - 1);\n    const delayMs = Math.min(this.maxDelayMs, this.baseDelayMs * 2 ** exponent);\n\n    return { shouldRetry: true, delayMs, reason: \"retry\" };\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAqCA,IAAa,qBAAb,cAAwC,gBAAgB;;;;CAItD;;;;CAIA;;;;CAIA;;;;CAKA,YAAY,SAAoC;AAC9C,SAAO;AACP,OAAK,cAAc,QAAQ;AAC3B,OAAK,cAAc,QAAQ;AAC3B,OAAK,aAAa,QAAQ;;;;;CAM5B,KAAY,OAA0C;AACpD,MAAI,MAAM,WAAW,KAAK,YACxB,QAAO;GAAE,aAAa;GAAO,SAAS;GAAG,QAAQ;GAAwB;EAG3E,MAAM,WAAW,KAAK,IAAI,GAAG,MAAM,UAAU,EAAE;AAG/C,SAAO;GAAE,aAAa;GAAM,SAFZ,KAAK,IAAI,KAAK,YAAY,KAAK,cAAc,KAAK,SAAS;GAEtC,QAAQ;GAAS"}

package/dist/fixed-delay.d.mts

@@ -6,7 +6,13 @@ import { BaseRetryPolicy } from "./index.mjs";
 * Configuration for `FixedDelay`.
 */
 interface FixedDelayOptions {
+  /**
+  * Maximum number of attempts (including the first) before giving up.
+  */
   maxAttempts: number;
+  /**
+  * Constant delay in milliseconds before each retry after a failure.
+  */
   delayMs: number;
 }
 /**
@@ -19,7 +25,13 @@ interface FixedDelayOptions {
 * });
 */
 declare class FixedDelay extends BaseRetryPolicy {
+  /**
+  * Maximum number of attempts before the policy returns `max-attempts-reached`.
+  */
   private readonly maxAttempts;
+  /**
+  * Constant delay in milliseconds before each subsequent attempt.
+  */
   private readonly delayMs;
   /**
   * Creates a fixed-delay retry policy.

package/dist/fixed-delay.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"fixed-delay.d.mts","names":[],"sources":["../src/fixed-delay.ts"],"mappings":";;;;;;AA0BA;UAdiB,iBAAA;EACf,WAAA;EACA,OAAA;AAAA;;;;;;;;;;cAYW,UAAA,SAAmB,eAAA;EAAA,iBACb,WAAA;EAAA,iBACA,OAAA;;;;EAKjB,WAAA,CAAY,OAAA,EAAS,iBAAA;;;;EASrB,IAAA,CAAY,KAAA,EAAO,kBAAA,GAAqB,aAAA;AAAA"}
+{"version":3,"file":"fixed-delay.d.mts","names":[],"sources":["../src/fixed-delay.ts"],"mappings":";;;;;;AAgCA;UApBiB,iBAAA;;;;EAIf,WAAA;;;;EAIA,OAAA;AAAA;;;;;;;;;;cAYW,UAAA,SAAmB,eAAA;;;;mBAIb,WAAA;;;;mBAIA,OAAA;;;;EAKjB,WAAA,CAAY,OAAA,EAAS,iBAAA;;;;EASrB,IAAA,CAAY,KAAA,EAAO,kBAAA,GAAqB,aAAA;AAAA"}

package/dist/fixed-delay.mjs

@@ -3,7 +3,7 @@ import { BaseRetryPolicy } from "./index.mjs";
 /**
 * Fixed-delay retry strategy.
 *
-* @module
+* @module @zap-studio/retry/fixed-delay
 */
 /**
 * Retries with a constant delay between attempts.
@@ -15,7 +15,13 @@ import { BaseRetryPolicy } from "./index.mjs";
 * });
 */
 var FixedDelay = class extends BaseRetryPolicy {
+	/**
+	* Maximum number of attempts before the policy returns `max-attempts-reached`.
+	*/
 	maxAttempts;
+	/**
+	* Constant delay in milliseconds before each subsequent attempt.
+	*/
 	delayMs;
 	/**
 	* Creates a fixed-delay retry policy.

package/dist/fixed-delay.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"fixed-delay.mjs","names":[],"sources":["../src/fixed-delay.ts"],"sourcesContent":["/**\n * Fixed-delay retry strategy.\n *\n * @module\n */\n\nimport { BaseRetryPolicy } from \"./index.js\";\nimport type { RetryDecision, RetryDecisionInput } from \"./types.js\";\n\n/**\n * Configuration for `FixedDelay`.\n */\nexport interface FixedDelayOptions {\n  maxAttempts: number;\n  delayMs: number;\n}\n\n/**\n * Retries with a constant delay between attempts.\n *\n * @example\n * const policy = new FixedDelay({\n *   maxAttempts: 3,\n *   delayMs: 250,\n * });\n */\nexport class FixedDelay extends BaseRetryPolicy {\n  private readonly maxAttempts: number;\n  private readonly delayMs: number;\n\n  /**\n   * Creates a fixed-delay retry policy.\n   */\n  constructor(options: FixedDelayOptions) {\n    super();\n    this.maxAttempts = options.maxAttempts;\n    this.delayMs = options.delayMs;\n  }\n\n  /**\n   * Computes retry decision for the current attempt.\n   */\n  public next(input: RetryDecisionInput): RetryDecision {\n    if (input.attempt >= this.maxAttempts) {\n      return { shouldRetry: false, delayMs: 0, reason: \"max-attempts-reached\" };\n    }\n\n    return { shouldRetry: true, delayMs: this.delayMs, reason: \"retry\" };\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA0BA,IAAa,aAAb,cAAgC,gBAAgB;CAC9C;CACA;;;;CAKA,YAAY,SAA4B;AACtC,SAAO;AACP,OAAK,cAAc,QAAQ;AAC3B,OAAK,UAAU,QAAQ;;;;;CAMzB,KAAY,OAA0C;AACpD,MAAI,MAAM,WAAW,KAAK,YACxB,QAAO;GAAE,aAAa;GAAO,SAAS;GAAG,QAAQ;GAAwB;AAG3E,SAAO;GAAE,aAAa;GAAM,SAAS,KAAK;GAAS,QAAQ;GAAS"}
+{"version":3,"file":"fixed-delay.mjs","names":[],"sources":["../src/fixed-delay.ts"],"sourcesContent":["/**\n * Fixed-delay retry strategy.\n *\n * @module @zap-studio/retry/fixed-delay\n */\n\nimport { BaseRetryPolicy } from \"./index.js\";\nimport type { RetryDecision, RetryDecisionInput } from \"./types.js\";\n\n/**\n * Configuration for `FixedDelay`.\n */\nexport interface FixedDelayOptions {\n  /**\n   * Maximum number of attempts (including the first) before giving up.\n   */\n  maxAttempts: number;\n  /**\n   * Constant delay in milliseconds before each retry after a failure.\n   */\n  delayMs: number;\n}\n\n/**\n * Retries with a constant delay between attempts.\n *\n * @example\n * const policy = new FixedDelay({\n *   maxAttempts: 3,\n *   delayMs: 250,\n * });\n */\nexport class FixedDelay extends BaseRetryPolicy {\n  /**\n   * Maximum number of attempts before the policy returns `max-attempts-reached`.\n   */\n  private readonly maxAttempts: number;\n  /**\n   * Constant delay in milliseconds before each subsequent attempt.\n   */\n  private readonly delayMs: number;\n\n  /**\n   * Creates a fixed-delay retry policy.\n   */\n  constructor(options: FixedDelayOptions) {\n    super();\n    this.maxAttempts = options.maxAttempts;\n    this.delayMs = options.delayMs;\n  }\n\n  /**\n   * Computes retry decision for the current attempt.\n   */\n  public next(input: RetryDecisionInput): RetryDecision {\n    if (input.attempt >= this.maxAttempts) {\n      return { shouldRetry: false, delayMs: 0, reason: \"max-attempts-reached\" };\n    }\n\n    return { shouldRetry: true, delayMs: this.delayMs, reason: \"retry\" };\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAgCA,IAAa,aAAb,cAAgC,gBAAgB;;;;CAI9C;;;;CAIA;;;;CAKA,YAAY,SAA4B;AACtC,SAAO;AACP,OAAK,cAAc,QAAQ;AAC3B,OAAK,UAAU,QAAQ;;;;;CAMzB,KAAY,OAA0C;AACpD,MAAI,MAAM,WAAW,KAAK,YACxB,QAAO;GAAE,aAAa;GAAO,SAAS;GAAG,QAAQ;GAAwB;AAG3E,SAAO;GAAE,aAAa;GAAM,SAAS,KAAK;GAAS,QAAQ;GAAS"}

package/dist/index.d.mts

@@ -1,7 +1,14 @@
-import { t as RetryError } from "./error-CWRADATN.mjs";
+import { r as RetryError } from "./errors-fWo_KyVO.mjs";
 import { RetryDecision, RetryDecisionInput, RetryExhaustedInput, RetryPolicy, RetryRunOptions, RetryRunResult } from "./types.mjs";
 
 //#region src/index.d.ts
+/**
+* Base class for implementing retry policies and running retry orchestration.
+*
+* Extend this class and implement {@link BaseRetryPolicy.next} to define retry
+* behavior, then call {@link BaseRetryPolicy.run} to execute operations with that
+* policy.
+*/
 declare abstract class BaseRetryPolicy<TError = unknown, TData = unknown> implements RetryPolicy<TError, TData> {
   /**
   * Returns the retry decision for a failed attempt.
@@ -20,6 +27,14 @@ declare abstract class BaseRetryPolicy<TError = unknown, TData = unknown> implem
   * @throws Any error thrown by an overriding policy implementation.
   */
   onExhausted(input: RetryExhaustedInput<TError, TData>): RetryError;
+  /**
+  * Runs retry orchestration in non-throw mode.
+  *
+  * @param execute - Async function to execute per attempt.
+  * @param options - Runner settings with `throwOnExhausted: false`.
+  * @returns A discriminated result union containing success value or terminal error.
+  * @throws Any error thrown by `next`, `onExhausted`, or a custom `sleep`.
+  */
   run<T>(execute: (attempt: number) => Promise<T>, options: RetryRunOptions & {
     throwOnExhausted: false;
   }): Promise<RetryRunResult<T>>;
@@ -32,6 +47,7 @@ declare abstract class BaseRetryPolicy<TError = unknown, TData = unknown> implem
   * @throws {RetryError} When retries are exhausted and `onExhausted` returns the
   *   terminal retry error. The default implementation returns `RetryError` with the last
   *   execution failure available on `RetryError.lastError`.
+  * @throws {AbortError} When `options.signal` is already aborted or aborts while retrying.
   * @throws Any error thrown by `next`, by `onExhausted`, or by a custom `sleep`
   *   function.
   */

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;uBAgBsB,eAAA,+CAA8D,WAAA,CAClF,MAAA,EACA,KAAA;;;;;;;WAQgB,IAAA,CAAK,KAAA,EAAO,kBAAA,CAAmB,MAAA,EAAQ,KAAA,IAAS,aAAA;;;;;;;;;;EAWhE,WAAA,CAAmB,KAAA,EAAO,mBAAA,CAAoB,MAAA,EAAQ,KAAA,IAAS,UAAA;EAQ/D,GAAA,GAAA,CACE,OAAA,GAAU,OAAA,aAAoB,OAAA,CAAQ,CAAA,GACtC,OAAA,EAAS,eAAA;IAAoB,gBAAA;EAAA,IAC5B,OAAA,CAAQ,cAAA,CAAe,CAAA;;;;;;;;;;;;;EAc1B,GAAA,GAAA,CACE,OAAA,GAAU,OAAA,aAAoB,OAAA,CAAQ,CAAA,GACtC,OAAA,GAAU,eAAA;IAAoB,gBAAA;EAAA,IAC7B,OAAA,CAAQ,CAAA;AAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;;;;;uBA0BsB,eAAA,+CAA8D,WAAA,CAClF,MAAA,EACA,KAAA;;;;;;;WAQgB,IAAA,CAAK,KAAA,EAAO,kBAAA,CAAmB,MAAA,EAAQ,KAAA,IAAS,aAAA;;;;;;;;;;EAWhE,WAAA,CAAmB,KAAA,EAAO,mBAAA,CAAoB,MAAA,EAAQ,KAAA,IAAS,UAAA;;;;;;;;;EAgB/D,GAAA,GAAA,CACE,OAAA,GAAU,OAAA,aAAoB,OAAA,CAAQ,CAAA,GACtC,OAAA,EAAS,eAAA;IAAoB,gBAAA;EAAA,IAC5B,OAAA,CAAQ,cAAA,CAAe,CAAA;;;;;;;;;;;;;;EAe1B,GAAA,GAAA,CACE,OAAA,GAAU,OAAA,aAAoB,OAAA,CAAQ,CAAA,GACtC,OAAA,GAAU,eAAA;IAAoB,gBAAA;EAAA,IAC7B,OAAA,CAAQ,CAAA;AAAA"}

package/dist/index.mjs

@@ -1,9 +1,19 @@
-import { RetryError } from "./error.mjs";
+import { RetryError } from "./errors.mjs";
+import { runResultMode } from "./result-mode.mjs";
+import { defaultSleep } from "./sleep.mjs";
+import { runThrowMode } from "./throw-mode.mjs";
 //#region src/index.ts
 /**
 * Retry runner base class and shared orchestration implementation.
 *
-* @module
+* @module @zap-studio/retry
+*/
+/**
+* Base class for implementing retry policies and running retry orchestration.
+*
+* Extend this class and implement {@link BaseRetryPolicy.next} to define retry
+* behavior, then call {@link BaseRetryPolicy.run} to execute operations with that
+* policy.
 */
 var BaseRetryPolicy = class {
 	/**
@@ -33,6 +43,8 @@ var BaseRetryPolicy = class {
 	* @throws Any error thrown by `next`, by `onExhausted`, or by a custom `sleep`
 	*   function. When `throwOnExhausted` is `false`, exhaustion itself is returned
 	*   as `{ ok: false }` instead of thrown.
+	*   Cancellation is returned as `{ ok: false, error: AbortError }` in non-throw
+	*   mode (not wrapped in `RetryError`).
 	*
 	* @example
 	* const result = await policy.run(doWork, { throwOnExhausted: false });
@@ -40,44 +52,11 @@ var BaseRetryPolicy = class {
 	*/
 	async run(execute, options = {}) {
 		const sleep = options.sleep ?? defaultSleep;
-		let attempt = 1;
-		let lastError;
-		while (true) try {
-			const value = await execute(attempt);
-			if (options.throwOnExhausted === false) return {
-				ok: true,
-				value
-			};
-			return value;
-		} catch (error) {
-			lastError = error;
-			const decision = this.next({
-				attempt,
-				error
-			});
-			if (!decision.shouldRetry) {
-				const terminalError = this.onExhausted({
-					attempts: attempt,
-					error: lastError
-				});
-				if (options.throwOnExhausted === false) return {
-					ok: false,
-					error: terminalError,
-					attempts: attempt
-				};
-				throw terminalError;
-			}
-			await sleep(decision.delayMs);
-			attempt += 1;
-		}
+		const signal = options.signal;
+		if (options.throwOnExhausted === false) return runResultMode(this, execute, sleep, signal);
+		return runThrowMode(this, execute, sleep, signal);
 	}
 };
-/**
-* Default delay implementation used by `run(...)` when no custom sleep function is provided.
-*/
-async function defaultSleep(delayMs) {
-	await new Promise((resolve) => setTimeout(resolve, delayMs));
-}
 //#endregion
 export { BaseRetryPolicy };
 

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * Retry runner base class and shared orchestration implementation.\n *\n * @module\n */\n\nimport { RetryError } from \"./error.js\";\nimport type {\n  RetryDecision,\n  RetryDecisionInput,\n  RetryExhaustedInput,\n  RetryPolicy,\n  RetryRunOptions,\n  RetryRunResult,\n} from \"./types.js\";\n\nexport abstract class BaseRetryPolicy<TError = unknown, TData = unknown> implements RetryPolicy<\n  TError,\n  TData\n> {\n  /**\n   * Returns the retry decision for a failed attempt.\n   *\n   * @param input - Attempt context used to compute retry behavior.\n   * @throws Any error thrown by a concrete retry policy implementation.\n   */\n  public abstract next(input: RetryDecisionInput<TError, TData>): RetryDecision;\n\n  /**\n   * Builds the terminal error thrown or returned when retries are exhausted.\n   *\n   * Override this when you need custom terminal error types.\n   *\n   * @param input - Exhaustion context.\n   * @returns `RetryError` by default.\n   * @throws Any error thrown by an overriding policy implementation.\n   */\n  public onExhausted(input: RetryExhaustedInput<TError, TData>): RetryError {\n    return new RetryError(\"Retry policy exhausted all attempts.\", {\n      attempts: input.attempts,\n      lastError: input.error,\n      lastData: input.data,\n    });\n  }\n\n  public async run<T>(\n    execute: (attempt: number) => Promise<T>,\n    options: RetryRunOptions & { throwOnExhausted: false },\n  ): Promise<RetryRunResult<T>>;\n\n  /**\n   * Runs retry orchestration and throws terminal error on exhaustion.\n   *\n   * @param execute - Async function to execute per attempt.\n   * @param options - Optional runner settings.\n   * @returns The successful execution value.\n   * @throws {RetryError} When retries are exhausted and `onExhausted` returns the\n   *   terminal retry error. The default implementation returns `RetryError` with the last\n   *   execution failure available on `RetryError.lastError`.\n   * @throws Any error thrown by `next`, by `onExhausted`, or by a custom `sleep`\n   *   function.\n   */\n  public async run<T>(\n    execute: (attempt: number) => Promise<T>,\n    options?: RetryRunOptions & { throwOnExhausted?: true },\n  ): Promise<T>;\n\n  /**\n   * Runs retry orchestration in non-throw mode.\n   *\n   * When `throwOnExhausted` is `false`, returns a discriminated result union.\n   *\n   * @param execute - Async function to execute per attempt.\n   * @param options - Runner settings.\n   * @returns Success value or terminal result object based on option mode.\n   * @throws Any error thrown by `next`, by `onExhausted`, or by a custom `sleep`\n   *   function. When `throwOnExhausted` is `false`, exhaustion itself is returned\n   *   as `{ ok: false }` instead of thrown.\n   *\n   * @example\n   * const result = await policy.run(doWork, { throwOnExhausted: false });\n   * if (!result.ok) console.error(result.error);\n   */\n  public async run<T>(\n    execute: (attempt: number) => Promise<T>,\n    options: RetryRunOptions = {},\n  ): Promise<T | RetryRunResult<T>> {\n    const sleep = options.sleep ?? defaultSleep;\n    let attempt = 1;\n    let lastError: TError | undefined;\n\n    while (true) {\n      try {\n        const value = await execute(attempt);\n        if (options.throwOnExhausted === false) {\n          return { ok: true, value };\n        }\n        return value;\n      } catch (error) {\n        lastError = error as TError;\n        const decision = this.next({\n          attempt,\n          error: error as TError,\n        });\n\n        if (!decision.shouldRetry) {\n          const terminalError = this.onExhausted({\n            attempts: attempt,\n            error: lastError,\n          });\n          if (options.throwOnExhausted === false) {\n            return {\n              ok: false,\n              error: terminalError,\n              attempts: attempt,\n            };\n          }\n          throw terminalError;\n        }\n\n        await sleep(decision.delayMs);\n        attempt += 1;\n      }\n    }\n  }\n}\n\n/**\n * Default delay implementation used by `run(...)` when no custom sleep function is provided.\n */\nasync function defaultSleep(delayMs: number): Promise<void> {\n  await new Promise((resolve) => setTimeout(resolve, delayMs));\n}\n"],"mappings":";;;;;;;AAgBA,IAAsB,kBAAtB,MAGE;;;;;;;;;;CAkBA,YAAmB,OAAuD;AACxE,SAAO,IAAI,WAAW,wCAAwC;GAC5D,UAAU,MAAM;GAChB,WAAW,MAAM;GACjB,UAAU,MAAM;GACjB,CAAC;;;;;;;;;;;;;;;;;;CAyCJ,MAAa,IACX,SACA,UAA2B,EAAE,EACG;EAChC,MAAM,QAAQ,QAAQ,SAAS;EAC/B,IAAI,UAAU;EACd,IAAI;AAEJ,SAAO,KACL,KAAI;GACF,MAAM,QAAQ,MAAM,QAAQ,QAAQ;AACpC,OAAI,QAAQ,qBAAqB,MAC/B,QAAO;IAAE,IAAI;IAAM;IAAO;AAE5B,UAAO;WACA,OAAO;AACd,eAAY;GACZ,MAAM,WAAW,KAAK,KAAK;IACzB;IACO;IACR,CAAC;AAEF,OAAI,CAAC,SAAS,aAAa;IACzB,MAAM,gBAAgB,KAAK,YAAY;KACrC,UAAU;KACV,OAAO;KACR,CAAC;AACF,QAAI,QAAQ,qBAAqB,MAC/B,QAAO;KACL,IAAI;KACJ,OAAO;KACP,UAAU;KACX;AAEH,UAAM;;AAGR,SAAM,MAAM,SAAS,QAAQ;AAC7B,cAAW;;;;;;;AASnB,eAAe,aAAa,SAAgC;AAC1D,OAAM,IAAI,SAAS,YAAY,WAAW,SAAS,QAAQ,CAAC"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * Retry runner base class and shared orchestration implementation.\n *\n * @module @zap-studio/retry\n */\n\nimport { RetryError } from \"./errors.js\";\nimport { runResultMode } from \"./result-mode.js\";\nimport { defaultSleep } from \"./sleep.js\";\nimport { runThrowMode } from \"./throw-mode.js\";\nimport type {\n  RetryDecision,\n  RetryDecisionInput,\n  RetryExhaustedInput,\n  RetryPolicy,\n  RetryRunOptions,\n  RetryRunResult,\n} from \"./types.js\";\n\n/**\n * Base class for implementing retry policies and running retry orchestration.\n *\n * Extend this class and implement {@link BaseRetryPolicy.next} to define retry\n * behavior, then call {@link BaseRetryPolicy.run} to execute operations with that\n * policy.\n */\nexport abstract class BaseRetryPolicy<TError = unknown, TData = unknown> implements RetryPolicy<\n  TError,\n  TData\n> {\n  /**\n   * Returns the retry decision for a failed attempt.\n   *\n   * @param input - Attempt context used to compute retry behavior.\n   * @throws Any error thrown by a concrete retry policy implementation.\n   */\n  public abstract next(input: RetryDecisionInput<TError, TData>): RetryDecision;\n\n  /**\n   * Builds the terminal error thrown or returned when retries are exhausted.\n   *\n   * Override this when you need custom terminal error types.\n   *\n   * @param input - Exhaustion context.\n   * @returns `RetryError` by default.\n   * @throws Any error thrown by an overriding policy implementation.\n   */\n  public onExhausted(input: RetryExhaustedInput<TError, TData>): RetryError {\n    return new RetryError(\"Retry policy exhausted all attempts.\", {\n      attempts: input.attempts,\n      lastError: input.error,\n      lastData: input.data,\n    });\n  }\n\n  /**\n   * Runs retry orchestration in non-throw mode.\n   *\n   * @param execute - Async function to execute per attempt.\n   * @param options - Runner settings with `throwOnExhausted: false`.\n   * @returns A discriminated result union containing success value or terminal error.\n   * @throws Any error thrown by `next`, `onExhausted`, or a custom `sleep`.\n   */\n  public async run<T>(\n    execute: (attempt: number) => Promise<T>,\n    options: RetryRunOptions & { throwOnExhausted: false },\n  ): Promise<RetryRunResult<T>>;\n\n  /**\n   * Runs retry orchestration and throws terminal error on exhaustion.\n   *\n   * @param execute - Async function to execute per attempt.\n   * @param options - Optional runner settings.\n   * @returns The successful execution value.\n   * @throws {RetryError} When retries are exhausted and `onExhausted` returns the\n   *   terminal retry error. The default implementation returns `RetryError` with the last\n   *   execution failure available on `RetryError.lastError`.\n   * @throws {AbortError} When `options.signal` is already aborted or aborts while retrying.\n   * @throws Any error thrown by `next`, by `onExhausted`, or by a custom `sleep`\n   *   function.\n   */\n  public async run<T>(\n    execute: (attempt: number) => Promise<T>,\n    options?: RetryRunOptions & { throwOnExhausted?: true },\n  ): Promise<T>;\n\n  /**\n   * Runs retry orchestration in non-throw mode.\n   *\n   * When `throwOnExhausted` is `false`, returns a discriminated result union.\n   *\n   * @param execute - Async function to execute per attempt.\n   * @param options - Runner settings.\n   * @returns Success value or terminal result object based on option mode.\n   * @throws Any error thrown by `next`, by `onExhausted`, or by a custom `sleep`\n   *   function. When `throwOnExhausted` is `false`, exhaustion itself is returned\n   *   as `{ ok: false }` instead of thrown.\n   *   Cancellation is returned as `{ ok: false, error: AbortError }` in non-throw\n   *   mode (not wrapped in `RetryError`).\n   *\n   * @example\n   * const result = await policy.run(doWork, { throwOnExhausted: false });\n   * if (!result.ok) console.error(result.error);\n   */\n  public async run<T>(\n    execute: (attempt: number) => Promise<T>,\n    options: RetryRunOptions = {},\n  ): Promise<T | RetryRunResult<T>> {\n    const sleep = options.sleep ?? defaultSleep;\n    const signal = options.signal;\n    if (options.throwOnExhausted === false) {\n      return runResultMode(this, execute, sleep, signal);\n    }\n\n    return runThrowMode(this, execute, sleep, signal);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AA0BA,IAAsB,kBAAtB,MAGE;;;;;;;;;;CAkBA,YAAmB,OAAuD;AACxE,SAAO,IAAI,WAAW,wCAAwC;GAC5D,UAAU,MAAM;GAChB,WAAW,MAAM;GACjB,UAAU,MAAM;GACjB,CAAC;;;;;;;;;;;;;;;;;;;;CAoDJ,MAAa,IACX,SACA,UAA2B,EAAE,EACG;EAChC,MAAM,QAAQ,QAAQ,SAAS;EAC/B,MAAM,SAAS,QAAQ;AACvB,MAAI,QAAQ,qBAAqB,MAC/B,QAAO,cAAc,MAAM,SAAS,OAAO,OAAO;AAGpD,SAAO,aAAa,MAAM,SAAS,OAAO,OAAO"}

package/dist/result-mode.d.mts

@@ -0,0 +1,24 @@
+import { r as RetryError } from "./errors-fWo_KyVO.mjs";
+import { RetryDecision, RetryDecisionInput, RetryExhaustedInput, RetryRunResult } from "./types.mjs";
+
+//#region src/result-mode.d.ts
+/**
+* Runs the non-throw retry loop, returning
+* `RetryRunResult`.
+*
+* @param policy - Object providing `next` and `onExhausted` (same contract as
+*   `BaseRetryPolicy`).
+* @param execute - Async work callback per attempt.
+* @param sleep - Delay function between retries.
+* @param signal - Optional cancel signal.
+* @returns Terminal success or failure object.
+* @throws Any error thrown by `next`, `onExhausted`, or a non-abort `sleep`
+*   failure.
+*/
+declare function runResultMode<T, TError, TData>(policy: {
+  next: (input: RetryDecisionInput<TError, TData>) => RetryDecision;
+  onExhausted: (input: RetryExhaustedInput<TError, TData>) => RetryError;
+}, execute: (attempt: number) => Promise<T>, sleep: (delayMs: number) => Promise<void>, signal?: AbortSignal): Promise<RetryRunResult<T>>;
+//#endregion
+export { runResultMode };
+//# sourceMappingURL=result-mode.d.mts.map

package/dist/result-mode.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-mode.d.mts","names":[],"sources":["../src/result-mode.ts"],"mappings":";;;;;;AA6BA;;;;;;;;;;;iBAAsB,aAAA,kBAAA,CACpB,MAAA;EACE,IAAA,GAAO,KAAA,EAAO,kBAAA,CAAmB,MAAA,EAAQ,KAAA,MAAW,aAAA;EACpD,WAAA,GAAc,KAAA,EAAO,mBAAA,CAAoB,MAAA,EAAQ,KAAA,MAAW,UAAA;AAAA,GAE9D,OAAA,GAAU,OAAA,aAAoB,OAAA,CAAQ,CAAA,GACtC,KAAA,GAAQ,OAAA,aAAoB,OAAA,QAC5B,MAAA,GAAS,WAAA,GACR,OAAA,CAAQ,cAAA,CAAe,CAAA"}

package/dist/result-mode.mjs

@@ -0,0 +1,145 @@
+import { sleepWithAbortSignal, toAbortError } from "./abort.mjs";
+//#region src/result-mode.ts
+/**
+* Result-mode execution path for `BaseRetryPolicy.run` when
+* `throwOnExhausted: false` is set.
+*
+* @module @zap-studio/retry/result-mode
+*/
+/**
+* Runs the non-throw retry loop, returning
+* `RetryRunResult`.
+*
+* @param policy - Object providing `next` and `onExhausted` (same contract as
+*   `BaseRetryPolicy`).
+* @param execute - Async work callback per attempt.
+* @param sleep - Delay function between retries.
+* @param signal - Optional cancel signal.
+* @returns Terminal success or failure object.
+* @throws Any error thrown by `next`, `onExhausted`, or a non-abort `sleep`
+*   failure.
+*/
+async function runResultMode(policy, execute, sleep, signal) {
+	let attempt = 1;
+	while (true) {
+		const earlyAbortResult = abortResult(signal, Math.max(0, attempt - 1));
+		if (earlyAbortResult) return earlyAbortResult;
+		const execution = await runAttempt(execute, attempt);
+		if (execution.ok) return {
+			ok: true,
+			value: execution.value
+		};
+		const failure = await handleFailure(policy, {
+			attempt,
+			error: execution.error,
+			sleep,
+			signal
+		});
+		if (failure) return failure;
+		attempt += 1;
+	}
+}
+/**
+* Runs one `execute(attempt)` call and returns either a success value or a
+* captured error without rethrowing.
+*
+* @param execute - User work callback.
+* @param attempt - One-based attempt number passed to `execute`.
+* @returns A tagged success with `value` or a tagged failure with `error`.
+*/
+async function runAttempt(execute, attempt) {
+	try {
+		return {
+			ok: true,
+			value: await execute(attempt)
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error
+		};
+	}
+}
+/**
+* After a failed attempt, applies abort rules, `next`, optional delay, and
+* either returns a terminal `RetryRunResult` or `undefined` to continue.
+*
+* @param policy - Retry policy hooks (`next`, `onExhausted`) matching
+*   `BaseRetryPolicy`.
+* @param params - Failure context for the current attempt.
+* @param params.attempt - Current attempt number.
+* @param params.error - Error thrown by the attempt.
+* @param params.sleep - Delay function between retries.
+* @param params.signal - Optional abort signal.
+* @returns Terminal non-throw result if the loop should stop, otherwise
+*   `undefined` to schedule another attempt.
+* @throws Any error thrown by `next`, `onExhausted`, or a custom `sleep` when
+*   the error is not an abort.
+*/
+async function handleFailure(policy, params) {
+	const { attempt, error, sleep, signal } = params;
+	const postExecuteAbortResult = abortResult(signal, attempt);
+	if (postExecuteAbortResult) return postExecuteAbortResult;
+	const decision = policy.next({
+		attempt,
+		error
+	});
+	if (!decision.shouldRetry) return {
+		ok: false,
+		error: policy.onExhausted({
+			attempts: attempt,
+			error
+		}),
+		attempts: attempt
+	};
+	if (decision.delayMs > 0) {
+		const sleepAbortResult = await waitForDelay(sleep, decision.delayMs, signal, attempt);
+		if (sleepAbortResult) return sleepAbortResult;
+	}
+}
+/**
+* When `signal` is already aborted, builds the terminal `{ ok: false }` object
+* with a normalized `AbortError` on `error` (not wrapped in `RetryError`).
+*
+* @param signal - Optional abort signal; only acts when `aborted` is set.
+* @param attempts - Number of finished attempts to report in the result.
+* @returns Failure result or `undefined` if not aborted.
+*/
+function abortResult(signal, attempts) {
+	if (!signal?.aborted) return;
+	return {
+		ok: false,
+		error: toAbortError(signal.reason),
+		attempts
+	};
+}
+/**
+* Awaits inter-attempt delay in result mode, mapping an abort during wait to
+* a terminal result instead of throwing when `throwOnExhausted` is false.
+*
+* @param sleep - Custom or default sleep implementation.
+* @param delayMs - Milliseconds to wait.
+* @param signal - If set, `sleep` is raced with the abort signal.
+* @param attempts - Attempt count to attach if the wait ends in abort.
+* @returns A terminal result when canceled during the wait, otherwise
+*   `undefined`.
+* @throws The underlying `sleep` rejection when it is not an abort.
+*/
+async function waitForDelay(sleep, delayMs, signal, attempts) {
+	if (!signal) {
+		await sleep(delayMs);
+		return;
+	}
+	try {
+		await sleepWithAbortSignal(sleep, delayMs, signal);
+		return;
+	} catch (error) {
+		const aborted = abortResult(signal, attempts);
+		if (aborted) return aborted;
+		throw error;
+	}
+}
+//#endregion
+export { runResultMode };
+
+//# sourceMappingURL=result-mode.mjs.map

package/dist/result-mode.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-mode.mjs","names":[],"sources":["../src/result-mode.ts"],"sourcesContent":["/**\n * Result-mode execution path for `BaseRetryPolicy.run` when\n * `throwOnExhausted: false` is set.\n *\n * @module @zap-studio/retry/result-mode\n */\n\nimport { sleepWithAbortSignal, toAbortError } from \"./abort.js\";\nimport type { RetryError } from \"./errors.js\";\nimport type {\n  RetryDecision,\n  RetryDecisionInput,\n  RetryExhaustedInput,\n  RetryRunResult,\n} from \"./types.js\";\n\n/**\n * Runs the non-throw retry loop, returning\n * `RetryRunResult`.\n *\n * @param policy - Object providing `next` and `onExhausted` (same contract as\n *   `BaseRetryPolicy`).\n * @param execute - Async work callback per attempt.\n * @param sleep - Delay function between retries.\n * @param signal - Optional cancel signal.\n * @returns Terminal success or failure object.\n * @throws Any error thrown by `next`, `onExhausted`, or a non-abort `sleep`\n *   failure.\n */\nexport async function runResultMode<T, TError, TData>(\n  policy: {\n    next: (input: RetryDecisionInput<TError, TData>) => RetryDecision;\n    onExhausted: (input: RetryExhaustedInput<TError, TData>) => RetryError;\n  },\n  execute: (attempt: number) => Promise<T>,\n  sleep: (delayMs: number) => Promise<void>,\n  signal?: AbortSignal,\n): Promise<RetryRunResult<T>> {\n  let attempt = 1;\n\n  while (true) {\n    const earlyAbortResult = abortResult(signal, Math.max(0, attempt - 1));\n    if (earlyAbortResult) return earlyAbortResult;\n\n    const execution = await runAttempt(execute, attempt);\n    if (execution.ok) {\n      return { ok: true, value: execution.value };\n    }\n\n    const failure = await handleFailure(policy, {\n      attempt,\n      error: execution.error as TError,\n      sleep,\n      signal,\n    });\n    if (failure) return failure;\n\n    attempt += 1;\n  }\n}\n\n/**\n * Runs one `execute(attempt)` call and returns either a success value or a\n * captured error without rethrowing.\n *\n * @param execute - User work callback.\n * @param attempt - One-based attempt number passed to `execute`.\n * @returns A tagged success with `value` or a tagged failure with `error`.\n */\nasync function runAttempt<T>(\n  execute: (attempt: number) => Promise<T>,\n  attempt: number,\n): Promise<{ ok: true; value: T } | { ok: false; error: unknown }> {\n  try {\n    return {\n      ok: true,\n      value: await execute(attempt),\n    };\n  } catch (error) {\n    return {\n      ok: false,\n      error,\n    };\n  }\n}\n\n/**\n * After a failed attempt, applies abort rules, `next`, optional delay, and\n * either returns a terminal `RetryRunResult` or `undefined` to continue.\n *\n * @param policy - Retry policy hooks (`next`, `onExhausted`) matching\n *   `BaseRetryPolicy`.\n * @param params - Failure context for the current attempt.\n * @param params.attempt - Current attempt number.\n * @param params.error - Error thrown by the attempt.\n * @param params.sleep - Delay function between retries.\n * @param params.signal - Optional abort signal.\n * @returns Terminal non-throw result if the loop should stop, otherwise\n *   `undefined` to schedule another attempt.\n * @throws Any error thrown by `next`, `onExhausted`, or a custom `sleep` when\n *   the error is not an abort.\n */\nasync function handleFailure<TError, TData>(\n  policy: {\n    next: (input: RetryDecisionInput<TError, TData>) => RetryDecision;\n    onExhausted: (input: RetryExhaustedInput<TError, TData>) => RetryError;\n  },\n  params: {\n    attempt: number;\n    error: TError;\n    sleep: (delayMs: number) => Promise<void>;\n    signal: AbortSignal | undefined;\n  },\n): Promise<RetryRunResult<never> | undefined> {\n  const { attempt, error, sleep, signal } = params;\n  const postExecuteAbortResult = abortResult(signal, attempt);\n  if (postExecuteAbortResult) return postExecuteAbortResult;\n\n  const decision = policy.next({\n    attempt,\n    error,\n  });\n\n  if (!decision.shouldRetry) {\n    const terminalError = policy.onExhausted({\n      attempts: attempt,\n      error,\n    });\n\n    return {\n      ok: false,\n      error: terminalError,\n      attempts: attempt,\n    };\n  }\n\n  if (decision.delayMs > 0) {\n    const sleepAbortResult = await waitForDelay(sleep, decision.delayMs, signal, attempt);\n    if (sleepAbortResult) return sleepAbortResult;\n  }\n\n  return;\n}\n\n/**\n * When `signal` is already aborted, builds the terminal `{ ok: false }` object\n * with a normalized `AbortError` on `error` (not wrapped in `RetryError`).\n *\n * @param signal - Optional abort signal; only acts when `aborted` is set.\n * @param attempts - Number of finished attempts to report in the result.\n * @returns Failure result or `undefined` if not aborted.\n */\nfunction abortResult(\n  signal: AbortSignal | undefined,\n  attempts: number,\n): RetryRunResult<never> | undefined {\n  if (!signal?.aborted) {\n    return;\n  }\n\n  return {\n    ok: false,\n    error: toAbortError(signal.reason),\n    attempts,\n  };\n}\n\n/**\n * Awaits inter-attempt delay in result mode, mapping an abort during wait to\n * a terminal result instead of throwing when `throwOnExhausted` is false.\n *\n * @param sleep - Custom or default sleep implementation.\n * @param delayMs - Milliseconds to wait.\n * @param signal - If set, `sleep` is raced with the abort signal.\n * @param attempts - Attempt count to attach if the wait ends in abort.\n * @returns A terminal result when canceled during the wait, otherwise\n *   `undefined`.\n * @throws The underlying `sleep` rejection when it is not an abort.\n */\nasync function waitForDelay(\n  sleep: (delayMs: number) => Promise<void>,\n  delayMs: number,\n  signal: AbortSignal | undefined,\n  attempts: number,\n): Promise<RetryRunResult<never> | undefined> {\n  if (!signal) {\n    await sleep(delayMs);\n    return;\n  }\n\n  try {\n    await sleepWithAbortSignal(sleep, delayMs, signal);\n    return;\n  } catch (error) {\n    const aborted = abortResult(signal, attempts);\n    if (aborted) {\n      return aborted;\n    }\n    throw error;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AA6BA,eAAsB,cACpB,QAIA,SACA,OACA,QAC4B;CAC5B,IAAI,UAAU;AAEd,QAAO,MAAM;EACX,MAAM,mBAAmB,YAAY,QAAQ,KAAK,IAAI,GAAG,UAAU,EAAE,CAAC;AACtE,MAAI,iBAAkB,QAAO;EAE7B,MAAM,YAAY,MAAM,WAAW,SAAS,QAAQ;AACpD,MAAI,UAAU,GACZ,QAAO;GAAE,IAAI;GAAM,OAAO,UAAU;GAAO;EAG7C,MAAM,UAAU,MAAM,cAAc,QAAQ;GAC1C;GACA,OAAO,UAAU;GACjB;GACA;GACD,CAAC;AACF,MAAI,QAAS,QAAO;AAEpB,aAAW;;;;;;;;;;;AAYf,eAAe,WACb,SACA,SACiE;AACjE,KAAI;AACF,SAAO;GACL,IAAI;GACJ,OAAO,MAAM,QAAQ,QAAQ;GAC9B;UACM,OAAO;AACd,SAAO;GACL,IAAI;GACJ;GACD;;;;;;;;;;;;;;;;;;;AAoBL,eAAe,cACb,QAIA,QAM4C;CAC5C,MAAM,EAAE,SAAS,OAAO,OAAO,WAAW;CAC1C,MAAM,yBAAyB,YAAY,QAAQ,QAAQ;AAC3D,KAAI,uBAAwB,QAAO;CAEnC,MAAM,WAAW,OAAO,KAAK;EAC3B;EACA;EACD,CAAC;AAEF,KAAI,CAAC,SAAS,YAMZ,QAAO;EACL,IAAI;EACJ,OAPoB,OAAO,YAAY;GACvC,UAAU;GACV;GACD,CAAC;EAKA,UAAU;EACX;AAGH,KAAI,SAAS,UAAU,GAAG;EACxB,MAAM,mBAAmB,MAAM,aAAa,OAAO,SAAS,SAAS,QAAQ,QAAQ;AACrF,MAAI,iBAAkB,QAAO;;;;;;;;;;;AAcjC,SAAS,YACP,QACA,UACmC;AACnC,KAAI,CAAC,QAAQ,QACX;AAGF,QAAO;EACL,IAAI;EACJ,OAAO,aAAa,OAAO,OAAO;EAClC;EACD;;;;;;;;;;;;;;AAeH,eAAe,aACb,OACA,SACA,QACA,UAC4C;AAC5C,KAAI,CAAC,QAAQ;AACX,QAAM,MAAM,QAAQ;AACpB;;AAGF,KAAI;AACF,QAAM,qBAAqB,OAAO,SAAS,OAAO;AAClD;UACO,OAAO;EACd,MAAM,UAAU,YAAY,QAAQ,SAAS;AAC7C,MAAI,QACF,QAAO;AAET,QAAM"}

package/dist/sleep.d.mts

@@ -0,0 +1,17 @@
+//#region src/sleep.d.ts
+/**
+* Default delay implementation used by `BaseRetryPolicy.run` when no custom
+* `sleep` is provided.
+*
+* @module @zap-studio/retry/sleep
+*/
+/**
+* Awaits a timer-based delay, unless `delayMs` is non-positive.
+*
+* @param delayMs - Milliseconds to wait before resolving.
+* @returns Promise that resolves when the delay completes.
+*/
+declare function defaultSleep(delayMs: number): Promise<void>;
+//#endregion
+export { defaultSleep };
+//# sourceMappingURL=sleep.d.mts.map

package/dist/sleep.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.d.mts","names":[],"sources":["../src/sleep.ts"],"mappings":";;AAaA;;;;;;;;;;;iBAAsB,YAAA,CAAa,OAAA,WAAkB,OAAA"}

package/dist/sleep.mjs

@@ -0,0 +1,21 @@
+//#region src/sleep.ts
+/**
+* Default delay implementation used by `BaseRetryPolicy.run` when no custom
+* `sleep` is provided.
+*
+* @module @zap-studio/retry/sleep
+*/
+/**
+* Awaits a timer-based delay, unless `delayMs` is non-positive.
+*
+* @param delayMs - Milliseconds to wait before resolving.
+* @returns Promise that resolves when the delay completes.
+*/
+async function defaultSleep(delayMs) {
+	if (delayMs <= 0) return;
+	await new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+//#endregion
+export { defaultSleep };
+
+//# sourceMappingURL=sleep.mjs.map

package/dist/sleep.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.mjs","names":[],"sources":["../src/sleep.ts"],"sourcesContent":["/**\n * Default delay implementation used by `BaseRetryPolicy.run` when no custom\n * `sleep` is provided.\n *\n * @module @zap-studio/retry/sleep\n */\n\n/**\n * Awaits a timer-based delay, unless `delayMs` is non-positive.\n *\n * @param delayMs - Milliseconds to wait before resolving.\n * @returns Promise that resolves when the delay completes.\n */\nexport async function defaultSleep(delayMs: number): Promise<void> {\n  if (delayMs <= 0) {\n    return;\n  }\n\n  await new Promise((resolve) => setTimeout(resolve, delayMs));\n}\n"],"mappings":";;;;;;;;;;;;;AAaA,eAAsB,aAAa,SAAgC;AACjE,KAAI,WAAW,EACb;AAGF,OAAM,IAAI,SAAS,YAAY,WAAW,SAAS,QAAQ,CAAC"}

package/dist/throw-mode.d.mts

@@ -0,0 +1,26 @@
+import { r as RetryError } from "./errors-fWo_KyVO.mjs";
+import { RetryDecision, RetryDecisionInput, RetryExhaustedInput } from "./types.mjs";
+
+//#region src/throw-mode.d.ts
+/**
+* Runs the throw-mode retry loop: throws `RetryError` on exhaustion and
+* `AbortError` when `signal` aborts.
+*
+* @param policy - Object providing `next` and `onExhausted` (same contract as
+*   `BaseRetryPolicy`).
+* @param execute - Async work callback per attempt.
+* @param sleep - Delay function between retries.
+* @param signal - Optional cancel signal.
+* @returns Resolves to the first successful return value.
+* @throws {RetryError} When retries are exhausted and `onExhausted` returns
+*   the terminal error.
+* @throws {AbortError} When `signal` is already aborted or aborts while waiting.
+* @throws Any error thrown by `next`, `onExhausted`, or `sleep`.
+*/
+declare function runThrowMode<T, TError, TData>(policy: {
+  next: (input: RetryDecisionInput<TError, TData>) => RetryDecision;
+  onExhausted: (input: RetryExhaustedInput<TError, TData>) => RetryError;
+}, execute: (attempt: number) => Promise<T>, sleep: (delayMs: number) => Promise<void>, signal?: AbortSignal): Promise<T>;
+//#endregion
+export { runThrowMode };
+//# sourceMappingURL=throw-mode.d.mts.map

package/dist/throw-mode.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"throw-mode.d.mts","names":[],"sources":["../src/throw-mode.ts"],"mappings":";;;;;;AA0BA;;;;;;;;;;;;;iBAAsB,YAAA,kBAAA,CACpB,MAAA;EACE,IAAA,GAAO,KAAA,EAAO,kBAAA,CAAmB,MAAA,EAAQ,KAAA,MAAW,aAAA;EACpD,WAAA,GAAc,KAAA,EAAO,mBAAA,CAAoB,MAAA,EAAQ,KAAA,MAAW,UAAA;AAAA,GAE9D,OAAA,GAAU,OAAA,aAAoB,OAAA,CAAQ,CAAA,GACtC,KAAA,GAAQ,OAAA,aAAoB,OAAA,QAC5B,MAAA,GAAS,WAAA,GACR,OAAA,CAAQ,CAAA"}

package/dist/throw-mode.mjs

@@ -0,0 +1,50 @@
+import { sleepWithAbortSignal, throwIfAborted } from "./abort.mjs";
+//#region src/throw-mode.ts
+/**
+* Throw-mode execution path for `BaseRetryPolicy.run` (default when
+* `throwOnExhausted` is not `false`).
+*
+* @module @zap-studio/retry/throw-mode
+*/
+/**
+* Runs the throw-mode retry loop: throws `RetryError` on exhaustion and
+* `AbortError` when `signal` aborts.
+*
+* @param policy - Object providing `next` and `onExhausted` (same contract as
+*   `BaseRetryPolicy`).
+* @param execute - Async work callback per attempt.
+* @param sleep - Delay function between retries.
+* @param signal - Optional cancel signal.
+* @returns Resolves to the first successful return value.
+* @throws {RetryError} When retries are exhausted and `onExhausted` returns
+*   the terminal error.
+* @throws {AbortError} When `signal` is already aborted or aborts while waiting.
+* @throws Any error thrown by `next`, `onExhausted`, or `sleep`.
+*/
+async function runThrowMode(policy, execute, sleep, signal) {
+	let attempt = 1;
+	while (true) {
+		throwIfAborted(signal);
+		try {
+			return await execute(attempt);
+		} catch (error) {
+			throwIfAborted(signal);
+			const typedError = error;
+			const decision = policy.next({
+				attempt,
+				error: typedError
+			});
+			if (!decision.shouldRetry) throw policy.onExhausted({
+				attempts: attempt,
+				error: typedError
+			});
+			if (decision.delayMs > 0) if (signal) await sleepWithAbortSignal(sleep, decision.delayMs, signal);
+			else await sleep(decision.delayMs);
+			attempt += 1;
+		}
+	}
+}
+//#endregion
+export { runThrowMode };
+
+//# sourceMappingURL=throw-mode.mjs.map

package/dist/throw-mode.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"throw-mode.mjs","names":[],"sources":["../src/throw-mode.ts"],"sourcesContent":["/**\n * Throw-mode execution path for `BaseRetryPolicy.run` (default when\n * `throwOnExhausted` is not `false`).\n *\n * @module @zap-studio/retry/throw-mode\n */\n\nimport { sleepWithAbortSignal, throwIfAborted } from \"./abort.js\";\nimport { RetryError } from \"./errors.js\";\nimport type { RetryDecision, RetryDecisionInput, RetryExhaustedInput } from \"./types.js\";\n\n/**\n * Runs the throw-mode retry loop: throws `RetryError` on exhaustion and\n * `AbortError` when `signal` aborts.\n *\n * @param policy - Object providing `next` and `onExhausted` (same contract as\n *   `BaseRetryPolicy`).\n * @param execute - Async work callback per attempt.\n * @param sleep - Delay function between retries.\n * @param signal - Optional cancel signal.\n * @returns Resolves to the first successful return value.\n * @throws {RetryError} When retries are exhausted and `onExhausted` returns\n *   the terminal error.\n * @throws {AbortError} When `signal` is already aborted or aborts while waiting.\n * @throws Any error thrown by `next`, `onExhausted`, or `sleep`.\n */\nexport async function runThrowMode<T, TError, TData>(\n  policy: {\n    next: (input: RetryDecisionInput<TError, TData>) => RetryDecision;\n    onExhausted: (input: RetryExhaustedInput<TError, TData>) => RetryError;\n  },\n  execute: (attempt: number) => Promise<T>,\n  sleep: (delayMs: number) => Promise<void>,\n  signal?: AbortSignal,\n): Promise<T> {\n  let attempt = 1;\n\n  while (true) {\n    throwIfAborted(signal);\n\n    try {\n      return await execute(attempt);\n    } catch (error) {\n      throwIfAborted(signal);\n\n      const typedError = error as TError;\n      const decision = policy.next({\n        attempt,\n        error: typedError,\n      });\n\n      if (!decision.shouldRetry) {\n        throw policy.onExhausted({\n          attempts: attempt,\n          error: typedError,\n        });\n      }\n\n      if (decision.delayMs > 0) {\n        if (signal) {\n          await sleepWithAbortSignal(sleep, decision.delayMs, signal);\n        } else {\n          await sleep(decision.delayMs);\n        }\n      }\n\n      attempt += 1;\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AA0BA,eAAsB,aACpB,QAIA,SACA,OACA,QACY;CACZ,IAAI,UAAU;AAEd,QAAO,MAAM;AACX,iBAAe,OAAO;AAEtB,MAAI;AACF,UAAO,MAAM,QAAQ,QAAQ;WACtB,OAAO;AACd,kBAAe,OAAO;GAEtB,MAAM,aAAa;GACnB,MAAM,WAAW,OAAO,KAAK;IAC3B;IACA,OAAO;IACR,CAAC;AAEF,OAAI,CAAC,SAAS,YACZ,OAAM,OAAO,YAAY;IACvB,UAAU;IACV,OAAO;IACR,CAAC;AAGJ,OAAI,SAAS,UAAU,EACrB,KAAI,OACF,OAAM,qBAAqB,OAAO,SAAS,SAAS,OAAO;OAE3D,OAAM,MAAM,SAAS,QAAQ;AAIjC,cAAW"}

package/dist/types.d.mts

@@ -1,4 +1,4 @@
-import { t as RetryError } from "./error-CWRADATN.mjs";
+import { r as RetryError, t as AbortError } from "./errors-fWo_KyVO.mjs";
 
 //#region src/types.d.ts
 /**
@@ -28,25 +28,59 @@ interface RetryPolicy<TError = unknown, TData = unknown> {
 * Decision returned by a retry policy for a specific attempt.
 */
 interface RetryDecision {
+  /**
+  * When `true`, the runner may schedule another attempt (subject to
+  * `delayMs` and the runner's abort rules).
+  */
   readonly shouldRetry: boolean;
+  /**
+  * Milliseconds to wait before the next attempt when `shouldRetry` is `true`.
+  */
   readonly delayMs: number;
+  /**
+  * Optional machine-readable reason for the decision.
+  */
   readonly reason?: "retry" | "max-attempts-reached" | "policy-declined";
 }
 /**
 * Input passed to `RetryPolicy.next(...)` for each failed attempt.
 */
 interface RetryDecisionInput<TError = unknown, TData = unknown> {
+  /**
+  * One-based attempt number for the current failure.
+  */
   readonly attempt: number;
+  /**
+  * Optional policy-level maximum attempts, when a policy wants to pass it
+  * through to `next`.
+  */
   readonly maxAttempts?: number;
+  /**
+  * Error raised by the most recent `execute(attempt)` call, when a failure
+  * occurred.
+  */
   readonly error?: TError;
+  /**
+  * Optional data captured alongside the failure, when a policy populates
+  * it.
+  */
   readonly data?: TData;
 }
 /**
 * Input passed to `RetryPolicy.onExhausted(...)` when retries stop.
 */
 interface RetryExhaustedInput<TError = unknown, TData = unknown> {
+  /**
+  * Count of completed attempts that led to stopping retries.
+  */
   readonly attempts: number;
+  /**
+  * Last execution error, when available.
+  */
   readonly error?: TError;
+  /**
+  * Last captured data, when a policy or runner supplies it.
+  */
   readonly data?: TData;
 }
 /**
@@ -59,17 +93,51 @@ interface RetryRunOptions {
   * @throws Any error thrown or rejected by the custom delay implementation.
   */
   readonly sleep?: (delayMs: number) => Promise<void>;
+  /**
+  * Abort signal used to cancel retry orchestration.
+  *
+  * When aborted, the runner stops retrying and terminates immediately.
+  */
+  readonly signal?: AbortSignal;
+  /**
+  * When `true`, the runner throws a `RetryError` when retries are exhausted.
+  *
+  * When `false`, the runner returns a `RetryRunResult` discriminated union.
+  *
+  * @default true
+  */
   readonly throwOnExhausted?: boolean;
 }
 /**
 * Result union returned by non-throw runner mode.
+*
+* - Success: `ok: true` with the resolved `value`.
+* - Failure: `ok: false` with terminal `error` and completed `attempts` count
+*   (exhaustion or abort).
 */
 type RetryRunResult<T> = {
+  /**
+  * Discriminator for a successful run.
+  */
   ok: true;
+  /**
+  * Successful return value from the final attempt.
+  */
   value: T;
 } | {
+  /**
+  * Discriminator for a failed or aborted run.
+  */
   ok: false;
-  error: RetryError;
+  /**
+  * Terminal error: `RetryError` when retries are exhausted, or
+  * `AbortError` when the run is canceled (non-throw path uses the same
+  * instances as throw mode, not wrapped).
+  */
+  error: RetryError | AbortError;
+  /**
+  * Number of attempts that completed before the terminal outcome.
+  */
   attempts: number;
 };
 //#endregion

package/dist/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../src/types.ts"],"mappings":";;;;;;;;;;;;UAiBiB,WAAA;;;;;;EAMf,IAAA,CAAK,KAAA,EAAO,kBAAA,CAAmB,MAAA,EAAQ,KAAA,IAAS,aAAA;;;;;;EAMhD,WAAA,CAAY,KAAA,EAAO,mBAAA,CAAoB,MAAA,EAAQ,KAAA,IAAS,UAAA;AAAA;AAM1D;;;AAAA,UAAiB,aAAA;EAAA,SACN,WAAA;EAAA,SACA,OAAA;EAAA,SACA,MAAA;AAAA;;AAMX;;UAAiB,kBAAA;EAAA,SACN,OAAA;EAAA,SACA,WAAA;EAAA,SACA,KAAA,GAAQ,MAAA;EAAA,SACR,IAAA,GAAO,KAAA;AAAA;;;;UAMD,mBAAA;EAAA,SACN,QAAA;EAAA,SACA,KAAA,GAAQ,MAAA;EAAA,SACR,IAAA,GAAO,KAAA;AAAA;;;;UAMD,eAAA;EANC;AAMlB;;;;EANkB,SAYP,KAAA,IAAS,OAAA,aAAoB,OAAA;EAAA,SAC7B,gBAAA;AAAA;;;;KAMC,cAAA;EAEN,EAAA;EACA,KAAA,EAAO,CAAA;AAAA;EAGP,EAAA;EACA,KAAA,EAAO,UAAA;EACP,QAAA;AAAA"}
+{"version":3,"file":"types.d.mts","names":[],"sources":["../src/types.ts"],"mappings":";;;;;;;;;;;;UAiBiB,WAAA;;;;;;EAMf,IAAA,CAAK,KAAA,EAAO,kBAAA,CAAmB,MAAA,EAAQ,KAAA,IAAS,aAAA;;;;;;EAMhD,WAAA,CAAY,KAAA,EAAO,mBAAA,CAAoB,MAAA,EAAQ,KAAA,IAAS,UAAA;AAAA;AAM1D;;;AAAA,UAAiB,aAAA;;;;;WAKN,WAAA;EAcX;;;EAAA,SAVW,OAAA;;;;WAIA,MAAA;AAAA;;;;UAMM,kBAAA;;;;WAIN,OAAA;;;;;WAKA,WAAA;;;AAkCX;;WA7BW,KAAA,GAAQ,MAAA;EAyCC;;;;EAAA,SApCT,IAAA,GAAO,KAAA;AAAA;;;;UAMD,mBAAA;;;;WAIN,QAAA;;;;WAIA,KAAA,GAAQ,MAAA;;;;WAIR,IAAA,GAAO,KAAA;AAAA;;;;UAMD,eAAA;;;;;;WAMN,KAAA,IAAS,OAAA,aAAoB,OAAA;;;;;;WAM7B,MAAA,GAAS,WAAA;;;;;;;;WAQT,gBAAA;AAAA;;;;;;;;KAUC,cAAA;;;;EAKN,EAAA;;;;EAIA,KAAA,EAAO,CAAA;AAAA;;;;EAMP,EAAA;;;;;;EAMA,KAAA,EAAO,UAAA,GAAa,UAAA;;;;EAIpB,QAAA;AAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zap-studio/retry",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "private": false,
   "description": "Composable retry policies for resilient async operations.",
   "keywords": [
@@ -30,9 +30,13 @@
   "types": "./dist/index.d.mts",
   "exports": {
     ".": "./dist/index.mjs",
-    "./error": "./dist/error.mjs",
+    "./abort": "./dist/abort.mjs",
+    "./errors": "./dist/errors.mjs",
     "./exponential-backoff": "./dist/exponential-backoff.mjs",
     "./fixed-delay": "./dist/fixed-delay.mjs",
+    "./result-mode": "./dist/result-mode.mjs",
+    "./sleep": "./dist/sleep.mjs",
+    "./throw-mode": "./dist/throw-mode.mjs",
     "./types": "./dist/types.mjs",
     "./package.json": "./package.json"
   },
@@ -40,6 +44,12 @@
     "access": "public"
   },
   "devDependencies": {
+    "@types/async-retry": "^1.4.9",
+    "@types/promise-retry": "^1.1.6",
+    "async-retry": "^1.3.3",
+    "exponential-backoff": "^3.1.3",
+    "p-retry": "^8.0.0",
+    "promise-retry": "^2.0.1",
     "typescript": "^6.0.3",
     "vite-plus": "^0.1.19",
     "@zap-studio/typescript": "0.0.0"

package/dist/error-CWRADATN.d.mts

@@ -1,44 +0,0 @@
-//#region src/error.d.ts
-/**
-* Terminal error types used by retry policies and runners.
-*
-* @module
-*/
-/**
-* Context payload attached to `RetryError`.
-*/
-interface RetryErrorContext {
-  readonly attempts: number;
-  readonly lastError?: unknown;
-  readonly lastData?: unknown;
-}
-/**
-* Error thrown when retries are exhausted.
-*
-* @example
-* throw new RetryError("Retry exhausted", {
-*   attempts: 3,
-*   lastError: new Error("network"),
-* });
-*/
-declare class RetryError extends Error {
-  /**
-  * Total attempts performed before exhaustion.
-  */
-  readonly attempts: number;
-  /**
-  * Last captured error from execution.
-  */
-  readonly lastError?: unknown;
-  /**
-  * Last captured data value, when available.
-  */
-  readonly lastData?: unknown;
-  /**
-  * Creates a RetryError with structured terminal context.
-  */
-  constructor(message: string, context: RetryErrorContext);
-}
-//#endregion
-export { RetryErrorContext as n, RetryError as t };
-//# sourceMappingURL=error-CWRADATN.d.mts.map

package/dist/error-CWRADATN.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"error-CWRADATN.d.mts","names":[],"sources":["../src/error.ts"],"mappings":";;AASA;;;;;;;UAAiB,iBAAA;EAAA,SACN,QAAA;EAAA,SACA,SAAA;EAAA,SACA,QAAA;AAAA;;;;;;;;;;cAYE,UAAA,SAAmB,KAAA;EAiBQ;;;EAAA,SAbtB,QAAA;;;;WAIA,SAAA;;;;WAIA,QAAA;;;;EAKhB,WAAA,CAAY,OAAA,UAAiB,OAAA,EAAS,iBAAA;AAAA"}

package/dist/error.d.mts

@@ -1,2 +0,0 @@
-import { n as RetryErrorContext, t as RetryError } from "./error-CWRADATN.mjs";
-export { RetryError, RetryErrorContext };

package/dist/error.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"error.mjs","names":[],"sources":["../src/error.ts"],"sourcesContent":["/**\n * Terminal error types used by retry policies and runners.\n *\n * @module\n */\n\n/**\n * Context payload attached to `RetryError`.\n */\nexport interface RetryErrorContext {\n  readonly attempts: number;\n  readonly lastError?: unknown;\n  readonly lastData?: unknown;\n}\n\n/**\n * Error thrown when retries are exhausted.\n *\n * @example\n * throw new RetryError(\"Retry exhausted\", {\n *   attempts: 3,\n *   lastError: new Error(\"network\"),\n * });\n */\nexport class RetryError extends Error {\n  /**\n   * Total attempts performed before exhaustion.\n   */\n  public readonly attempts: number;\n  /**\n   * Last captured error from execution.\n   */\n  public readonly lastError?: unknown;\n  /**\n   * Last captured data value, when available.\n   */\n  public readonly lastData?: unknown;\n\n  /**\n   * Creates a RetryError with structured terminal context.\n   */\n  constructor(message: string, context: RetryErrorContext) {\n    super(message);\n    this.name = \"RetryError\";\n    this.attempts = context.attempts;\n    this.lastError = context.lastError;\n    this.lastData = context.lastData;\n  }\n}\n"],"mappings":";;;;;;;;;;AAwBA,IAAa,aAAb,cAAgC,MAAM;;;;CAIpC;;;;CAIA;;;;CAIA;;;;CAKA,YAAY,SAAiB,SAA4B;AACvD,QAAM,QAAQ;AACd,OAAK,OAAO;AACZ,OAAK,WAAW,QAAQ;AACxB,OAAK,YAAY,QAAQ;AACzB,OAAK,WAAW,QAAQ"}