@zap-studio/retry 0.3.0 → 0.3.2

package/dist/errors-BVZjP1Q5.d.ts

@@ -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-BVZjP1Q5.d.ts.map

package/dist/errors-BVZjP1Q5.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors-BVZjP1Q5.d.ts","names":[],"sources":["../src/errors.ts"],"mappings":";;;;;;;;;UAWiB;;;;WAIN;;;;WAIA;;;;WAIA;;;;;UAMM;;;;WAIN;;;;;;;;;;;cAYE,mBAAmB;;;;WAId;;;;WAIA;;;;WAIA;;;;EAKhB,YAAY,iBAAiB,SAAS;;;;;cAY3B,mBAAmB;;;;oBAIL;;;;;EAMzB,YAAY,iBAAiB,UAAS"}

package/dist/{errors.d.mts → errors.d.ts}

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

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

@@ -53,4 +53,4 @@ var AbortError = class extends Error {
 //#endregion
 export { AbortError, RetryError };
 
-//# sourceMappingURL=errors.mjs.map
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","names":[],"sources":["../src/errors.ts"],"sourcesContent":["// oxlint-disable max-classes-per-file -- Public retry error types are intentionally colocated.\n\n/**\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":";;;;;;;;;;AA6CA,IAAa,aAAb,cAAgC,MAAM;;;;CAIpC;;;;CAIA;;;;CAIA;;;;CAKA,YAAY,SAAiB,SAA4B;EACvD,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,WAAW,QAAQ;EACxB,KAAK,YAAY,QAAQ;EACzB,KAAK,WAAW,QAAQ;CAC1B;AACF;;;;AAKA,IAAa,aAAb,cAAgC,MAAM;;;;CAIpC;;;;;CAMA,YAAY,SAAiB,UAA6B,CAAC,GAAG;EAC5D,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,QAAQ,QAAQ;CACvB;AACF"}

package/dist/exponential-backoff.d.ts

@@ -0,0 +1,55 @@
+import { RetryDecision, RetryDecisionInput } from "./types.js";
+import { BaseRetryPolicy } from "./base-policy.js";
+//#region src/exponential-backoff.d.ts
+/**
+ * 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;
+}
+/**
+ * Retries with exponential delay growth up to a max cap.
+ *
+ * @example
+ * const policy = new ExponentialBackoff({
+ *   maxAttempts: 5,
+ *   baseDelayMs: 100,
+ *   maxDelayMs: 2_000,
+ * });
+ */
+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.
+   */
+  constructor(options: ExponentialBackoffOptions);
+  /**
+   * Computes retry decision for the current attempt.
+   */
+  next(input: RetryDecisionInput): RetryDecision;
+}
+//#endregion
+export { ExponentialBackoff, ExponentialBackoffOptions };
+//# sourceMappingURL=exponential-backoff.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exponential-backoff.d.ts","names":[],"sources":["../src/exponential-backoff.ts"],"mappings":";;;;;;UAYiB;;;;EAIf;;;;EAIA;;;;EAIA;;;;;;;;;;;;cAaW,2BAA2B;;;;mBAIrB;;;;mBAIA;;;;mBAIA;;;;EAKjB,YAAY,SAAS;;;;EAUrB,KAAY,OAAO,qBAAqB"}

package/dist/{exponential-backoff.mjs → exponential-backoff.js}

@@ -1,4 +1,4 @@
-import { BaseRetryPolicy } from "./index.mjs";
+import { t as BaseRetryPolicy } from "./base-policy-Dn3TOJd3.js";
 //#region src/exponential-backoff.ts
 /**
 * Exponential backoff retry strategy.
@@ -42,19 +42,19 @@ var ExponentialBackoff = class extends BaseRetryPolicy {
 	*/
 	next(input) {
 		if (input.attempt >= this.maxAttempts) return {
-			shouldRetry: false,
 			delayMs: 0,
-			reason: "max-attempts-reached"
+			reason: "max-attempts-reached",
+			shouldRetry: false
 		};
 		const exponent = Math.max(0, input.attempt - 1);
 		return {
-			shouldRetry: true,
 			delayMs: Math.min(this.maxDelayMs, this.baseDelayMs * 2 ** exponent),
-			reason: "retry"
+			reason: "retry",
+			shouldRetry: true
 		};
 	}
 };
 //#endregion
 export { ExponentialBackoff };
 
-//# sourceMappingURL=exponential-backoff.mjs.map
+//# sourceMappingURL=exponential-backoff.js.map

package/dist/exponential-backoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exponential-backoff.js","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 \"./base-policy.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 { delayMs: 0, reason: \"max-attempts-reached\", shouldRetry: false };\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 { delayMs, reason: \"retry\", shouldRetry: true };\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAqCA,IAAa,qBAAb,cAAwC,gBAAgB;;;;CAItD;;;;CAIA;;;;CAIA;;;;CAKA,YAAY,SAAoC;EAC9C,MAAM;EACN,KAAK,cAAc,QAAQ;EAC3B,KAAK,cAAc,QAAQ;EAC3B,KAAK,aAAa,QAAQ;CAC5B;;;;CAKA,KAAY,OAA0C;EACpD,IAAI,MAAM,WAAW,KAAK,aACxB,OAAO;GAAE,SAAS;GAAG,QAAQ;GAAwB,aAAa;EAAM;EAG1E,MAAM,WAAW,KAAK,IAAI,GAAG,MAAM,UAAU,CAAC;EAG9C,OAAO;GAAE,SAFO,KAAK,IAAI,KAAK,YAAY,KAAK,cAAc,KAAK,QAEnD;GAAG,QAAQ;GAAS,aAAa;EAAK;CACvD;AACF"}

package/dist/fixed-delay.d.ts

@@ -0,0 +1,46 @@
+import { RetryDecision, RetryDecisionInput } from "./types.js";
+import { BaseRetryPolicy } from "./base-policy.js";
+//#region src/fixed-delay.d.ts
+/**
+ * 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;
+}
+/**
+ * Retries with a constant delay between attempts.
+ *
+ * @example
+ * const policy = new FixedDelay({
+ *   maxAttempts: 3,
+ *   delayMs: 250,
+ * });
+ */
+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.
+   */
+  constructor(options: FixedDelayOptions);
+  /**
+   * Computes retry decision for the current attempt.
+   */
+  next(input: RetryDecisionInput): RetryDecision;
+}
+//#endregion
+export { FixedDelay, FixedDelayOptions };
+//# sourceMappingURL=fixed-delay.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fixed-delay.d.ts","names":[],"sources":["../src/fixed-delay.ts"],"mappings":";;;;;;UAYiB;;;;EAIf;;;;EAIA;;;;;;;;;;;cAYW,mBAAmB;;;;mBAIb;;;;mBAIA;;;;EAKjB,YAAY,SAAS;;;;EASrB,KAAY,OAAO,qBAAqB"}

package/dist/{fixed-delay.mjs → fixed-delay.js}

@@ -1,4 +1,4 @@
-import { BaseRetryPolicy } from "./index.mjs";
+import { t as BaseRetryPolicy } from "./base-policy-Dn3TOJd3.js";
 //#region src/fixed-delay.ts
 /**
 * Fixed-delay retry strategy.
@@ -36,18 +36,18 @@ var FixedDelay = class extends BaseRetryPolicy {
 	*/
 	next(input) {
 		if (input.attempt >= this.maxAttempts) return {
-			shouldRetry: false,
 			delayMs: 0,
-			reason: "max-attempts-reached"
+			reason: "max-attempts-reached",
+			shouldRetry: false
 		};
 		return {
-			shouldRetry: true,
 			delayMs: this.delayMs,
-			reason: "retry"
+			reason: "retry",
+			shouldRetry: true
 		};
 	}
 };
 //#endregion
 export { FixedDelay };
 
-//# sourceMappingURL=fixed-delay.mjs.map
+//# sourceMappingURL=fixed-delay.js.map

package/dist/fixed-delay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixed-delay.js","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 \"./base-policy.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 { delayMs: 0, reason: \"max-attempts-reached\", shouldRetry: false };\n    }\n\n    return { delayMs: this.delayMs, reason: \"retry\", shouldRetry: true };\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAgCA,IAAa,aAAb,cAAgC,gBAAgB;;;;CAI9C;;;;CAIA;;;;CAKA,YAAY,SAA4B;EACtC,MAAM;EACN,KAAK,cAAc,QAAQ;EAC3B,KAAK,UAAU,QAAQ;CACzB;;;;CAKA,KAAY,OAA0C;EACpD,IAAI,MAAM,WAAW,KAAK,aACxB,OAAO;GAAE,SAAS;GAAG,QAAQ;GAAwB,aAAa;EAAM;EAG1E,OAAO;GAAE,SAAS,KAAK;GAAS,QAAQ;GAAS,aAAa;EAAK;CACrE;AACF"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import { i as RetryErrorContext, n as AbortErrorContext, r as RetryError, t as AbortError } from "./errors-BVZjP1Q5.js";
+import { sleepWithAbortSignal, throwIfAborted, toAbortError } from "./abort.js";
+import { RetryDecision, RetryDecisionInput, RetryExhaustedInput, RetryPolicy, RetryRunOptions, RetryRunResult } from "./types.js";
+import { BaseRetryPolicy } from "./base-policy.js";
+import { ExponentialBackoff, ExponentialBackoffOptions } from "./exponential-backoff.js";
+import { FixedDelay, FixedDelayOptions } from "./fixed-delay.js";
+import { defaultSleep } from "./sleep.js";
+export { AbortError, type AbortErrorContext, BaseRetryPolicy, ExponentialBackoff, type ExponentialBackoffOptions, FixedDelay, type FixedDelayOptions, type RetryDecision, type RetryDecisionInput, RetryError, type RetryErrorContext, type RetryExhaustedInput, type RetryPolicy, type RetryRunOptions, type RetryRunResult, defaultSleep, sleepWithAbortSignal, throwIfAborted, toAbortError };

package/dist/index.js

@@ -0,0 +1,7 @@
+import { AbortError, RetryError } from "./errors.js";
+import { sleepWithAbortSignal, throwIfAborted, toAbortError } from "./abort.js";
+import { t as BaseRetryPolicy } from "./base-policy-Dn3TOJd3.js";
+import { defaultSleep } from "./sleep.js";
+import { ExponentialBackoff } from "./exponential-backoff.js";
+import { FixedDelay } from "./fixed-delay.js";
+export { AbortError, BaseRetryPolicy, ExponentialBackoff, FixedDelay, RetryError, defaultSleep, sleepWithAbortSignal, throwIfAborted, toAbortError };

package/dist/sleep.d.ts

@@ -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 const defaultSleep: (delayMs: number) => Promise<void>;
+//#endregion
+export { defaultSleep };
+//# sourceMappingURL=sleep.d.ts.map

package/dist/sleep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.d.ts","names":[],"sources":["../src/sleep.ts"],"mappings":";;;;;;;;;;;;;cAaa,eAAsB,oBAAkB"}

package/dist/{sleep.mjs → sleep.js}

@@ -11,11 +11,13 @@
 * @param delayMs - Milliseconds to wait before resolving.
 * @returns Promise that resolves when the delay completes.
 */
-async function defaultSleep(delayMs) {
+const defaultSleep = async (delayMs) => {
 	if (delayMs <= 0) return;
-	await new Promise((resolve) => setTimeout(resolve, delayMs));
-}
+	await new Promise((resolve) => {
+		setTimeout(resolve, delayMs);
+	});
+};
 //#endregion
 export { defaultSleep };
 
-//# sourceMappingURL=sleep.mjs.map
+//# sourceMappingURL=sleep.js.map

package/dist/sleep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.js","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 const defaultSleep = async (delayMs: number): Promise<void> => {\n  if (delayMs <= 0) {\n    return;\n  }\n\n  // oxlint-disable-next-line promise/avoid-new -- Timer sleep requires adapting callback API to a promise.\n  await new Promise<void>((resolve) => {\n    setTimeout(resolve, delayMs);\n  });\n};\n"],"mappings":";;;;;;;;;;;;;AAaA,MAAa,eAAe,OAAO,YAAmC;CACpE,IAAI,WAAW,GACb;CAIF,MAAM,IAAI,SAAe,YAAY;EACnC,WAAW,SAAS,OAAO;CAC7B,CAAC;AACH"}

package/dist/types.d.ts

@@ -0,0 +1,143 @@
+import { r as RetryError, t as AbortError } from "./errors-BVZjP1Q5.js";
+//#region src/types.d.ts
+/**
+ * Retry policy contract used by `BaseRetryPolicy`.
+ *
+ * @example
+ * const policy: RetryPolicy = {
+ *   next: ({ attempt }) => ({ shouldRetry: attempt < 3, delayMs: 100 }),
+ *   onExhausted: ({ attempts }) => new RetryError("done", { attempts }),
+ * };
+ */
+interface RetryPolicy<TError = unknown, TData = unknown> {
+  /**
+   * Returns the retry decision for a failed attempt.
+   *
+   * @throws {Error} Any error thrown by the policy implementation.
+   */
+  next: (input: RetryDecisionInput<TError, TData>) => RetryDecision;
+  /**
+   * Builds the terminal error used when retries are exhausted.
+   *
+   * @throws {Error} Any error thrown by the policy implementation.
+   */
+  onExhausted: (input: RetryExhaustedInput<TError, TData>) => RetryError;
+}
+/**
+ * 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;
+}
+/**
+ * Options for `BaseRetryPolicy.run(...)`.
+ */
+interface RetryRunOptions {
+  /**
+   * Delay function used between retry attempts.
+   *
+   * @throws {Error} 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;
+  /**
+   * Terminal error: `RetryError` when retries are exhausted, or
+   * `AbortError` when the run is canceled.
+   */
+  error: RetryError | AbortError;
+  /**
+   * Number of attempts that completed before the terminal outcome.
+   */
+  attempts: number;
+};
+//#endregion
+export { RetryDecision, RetryDecisionInput, RetryExhaustedInput, RetryPolicy, RetryRunOptions, RetryRunResult };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";;;;;;;;;;;UAiBiB,YAAY,kBAAkB;;;;;;EAM7C,OAAO,OAAO,mBAAmB,QAAQ,WAAW;;;;;;EAMpD,cAAc,OAAO,oBAAoB,QAAQ,WAAW;;;;;UAM7C;;;;;WAKN;;;;WAIA;;;;WAIA;;;;;UAMM,mBAAmB,kBAAkB;;;;WAI3C;;;;;WAKA;;;;;WAKA,QAAQ;;;;;WAKR,OAAO;;;;;UAMD,oBAAoB,kBAAkB;;;;WAI5C;;;;WAIA,QAAQ;;;;WAIR,OAAO;;;;;UAMD;;;;;;WAMN,SAAS,oBAAoB;;;;;;WAM7B,SAAS;;;;;;;;WAQT;;;;;;;;;KAUC,eAAe;;;;EAKrB;;;;EAIA,OAAO;;;;;EAMP;;;;;EAKA,OAAO,aAAa;;;;EAIpB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zap-studio/retry",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "private": false,
   "description": "Composable retry policies for resilient async operations.",
   "keywords": [
@@ -27,39 +27,28 @@
   ],
   "type": "module",
   "sideEffects": false,
-  "types": "./dist/index.d.mts",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./dist/index.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",
+    ".": "./dist/index.js",
+    "./abort": "./dist/abort.js",
+    "./base-policy": "./dist/base-policy.js",
+    "./errors": "./dist/errors.js",
+    "./exponential-backoff": "./dist/exponential-backoff.js",
+    "./fixed-delay": "./dist/fixed-delay.js",
+    "./sleep": "./dist/sleep.js",
+    "./types": "./dist/types.js",
     "./package.json": "./package.json"
   },
   "publishConfig": {
     "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"
+    "@zap-studio/typescript": "workspace:*",
+    "tsdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
   },
   "engines": {
     "node": ">=18.0.0"
-  },
-  "scripts": {
-    "build": "vp pack",
-    "test": "vp test run",
-    "test:watch": "vp test watch"
   }
-}
+}

package/dist/abort.d.mts

@@ -1,30 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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.map

@@ -1 +0,0 @@
-{"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"}