@zap-studio/retry 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @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

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,14 @@ 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.
@@ -99,7 +110,8 @@ controller.abort(new Error("Request canceled"));
 await promise;
 ```
 
-In non-throw mode, abort is returned as `{ ok: false }`:
+In non-throw mode, abort is returned as `{ ok: false }` with `AbortError` on
+`result.error`:
 
 ```ts
 const controller = new AbortController();
@@ -189,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

@@ -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 @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  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

@@ -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 @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  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,4 +1,4 @@
-import { t as RetryError } from "./error-CVW4I654.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
@@ -47,43 +47,14 @@ 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 {Error} When `options.signal` is already aborted or aborts while retrying.
+  * @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.
   */
   run<T>(execute: (attempt: number) => Promise<T>, options?: RetryRunOptions & {
     throwOnExhausted?: true;
   }): Promise<T>;
-  /**
-  * Runs retry orchestration in throwing mode.
-  *
-  * This path is selected when `throwOnExhausted` is not `false`.
-  *
-  * @param execute - Async function to execute per attempt.
-  * @param sleep - Delay function used between retry attempts.
-  * @returns The successful execution value.
-  * @throws {RetryError} Terminal error returned by `onExhausted(...)`.
-  * @throws Any error thrown by `next`, by `onExhausted`, or by `sleep`.
-  */
-  private runThrowMode;
-  /**
-  * Runs retry orchestration in non-throw mode.
-  *
-  * This path is selected when `throwOnExhausted` is `false`.
-  *
-  * @param execute - Async function to execute per attempt.
-  * @param sleep - Delay function used between retry attempts.
-  * @returns A discriminated result union containing success value or terminal error.
-  * @throws Any error thrown by `next`, by `onExhausted`, or by `sleep`.
-  */
-  private runResultMode;
 }
-/**
-* Default delay implementation used by `run(...)` when no custom sleep function is provided.
-*
-* Returns immediately when `delayMs` is non-positive.
-*/
-declare function defaultSleep(delayMs: number): Promise<void>;
 //#endregion
-export { BaseRetryPolicy, defaultSleep };
+export { BaseRetryPolicy };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;;;;;uBAuBsB,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;;;;;;;;;;;;UA2CG,YAAA;EAmDA;AA+EhB;;;;;;;;;EA/EgB,QAAA,aAAA;AAAA;;;;;;iBA+EM,YAAA,CAAa,OAAA,WAAkB,OAAA"}
+{"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"}