@zap-studio/retry 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# @zap-studio/retry
+
+## 0.1.0
+
+### Added
+
+- Introduced a transport-agnostic `RetryPolicy` contract with `RetryDecisionInput` and `RetryDecision`.
+- Added required `onExhausted` hook to `RetryPolicy` for policy-specific terminal error shaping.
+- Added shared `BaseRetryPolicy` abstract class to centralize default `onExhausted` behavior.
+- Added `BaseRetryPolicy.run(execute, options)` runner method to execute retry policies with minimal boilerplate.
+- Added `throwOnExhausted` runner option with non-throw `RetryRunResult<T>` mode.
+- Added `ExponentialBackoff` policy with bounded exponential delay via `baseDelayMs`, `maxDelayMs`, and `maxAttempts`.
+- Added `FixedDelay` policy with constant delay and bounded attempts.
+- Added `RetryError` for exhausted-retry failures with structured attempt/error/data context.
+
+### Documentation
+
+- Documented throwable behavior on `RetryPolicy`, `BaseRetryPolicy.run`, and related contracts with explicit `@throws` tags for policy, exhaustion, and custom `sleep` failures.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexandre Trotel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,162 @@
+# @zap-studio/retry
+
+Composable retry policy primitives for HTTP clients and async workflows.
+
+## Installation
+
+```bash
+npm install @zap-studio/retry
+```
+
+## Usage
+
+```ts
+import { ExponentialBackoff } from "@zap-studio/retry/exponential-backoff";
+import { FixedDelay } from "@zap-studio/retry/fixed-delay";
+import { $fetch } from "@zap-studio/fetch";
+
+const exponential = new ExponentialBackoff({
+  maxAttempts: 5,
+  baseDelayMs: 100,
+  maxDelayMs: 2_000,
+});
+
+const data = await exponential.run(async () => {
+  const response = await $fetch("https://api.example.com/users", {
+    throwOnFetchError: true,
+  });
+  return await response.json();
+});
+```
+
+## Handling Errors
+
+`run(...)` throws when retries are exhausted.
+
+By default, policies extending `BaseRetryPolicy` throw `RetryError`.
+
+```ts
+import { RetryError } from "@zap-studio/retry/error";
+
+try {
+  const data = await exponential.run(async () => {
+    const response = await $fetch("https://api.example.com/users", {
+      throwOnFetchError: true,
+    });
+    return await response.json();
+  });
+  console.log(data);
+} catch (error) {
+  if (error instanceof RetryError) {
+    console.error("Retries exhausted:", error.attempts);
+    console.error("Last error:", error.lastError);
+  } else {
+    throw error;
+  }
+}
+```
+
+To handle exhaustion without throwing, pass `throwOnExhausted: false`:
+
+```ts
+const result = await exponential.run(
+  async () => {
+    const response = await $fetch("https://api.example.com/users", {
+      throwOnFetchError: true,
+    });
+    return await response.json();
+  },
+  { throwOnExhausted: false },
+);
+
+if (!result.ok) {
+  console.error("Retries exhausted:", result.attempts);
+  console.error("Last error:", result.error.lastError);
+} else {
+  console.log(result.value);
+}
+```
+
+## Choosing The Right Policy
+
+Use `ExponentialBackoff` for transient network instability and shared upstream services.
+
+```ts
+const unstableNetworkPolicy = new ExponentialBackoff({
+  maxAttempts: 6,
+  baseDelayMs: 100,
+  maxDelayMs: 2_000,
+});
+```
+
+Use `FixedDelay` for stable, predictable retry intervals in controlled environments.
+
+```ts
+const predictableIntervalPolicy = new FixedDelay({
+  maxAttempts: 4,
+  delayMs: 300,
+});
+```
+
+## Custom Policies
+
+Extend `BaseRetryPolicy` when the built-in policies do not match your retry rules.
+
+You implement `next(...)` only; the base class supplies `onExhausted` with a default
+`RetryError` and keeps the shared `run(...)` orchestration (override `onExhausted` when
+you need a different terminal error).
+
+```ts
+import { BaseRetryPolicy } from "@zap-studio/retry";
+import type { RetryDecision, RetryDecisionInput } from "@zap-studio/retry/types";
+
+class LinearBackoff extends BaseRetryPolicy {
+  constructor(
+    private readonly maxAttempts: number,
+    private readonly stepMs: number,
+  ) {
+    super();
+  }
+
+  public next(input: RetryDecisionInput): RetryDecision {
+    if (input.attempt >= this.maxAttempts) {
+      return {
+        shouldRetry: false,
+        delayMs: 0,
+        reason: "max-attempts-reached",
+      };
+    }
+
+    return {
+      shouldRetry: true,
+      delayMs: input.attempt * this.stepMs,
+      reason: "retry",
+    };
+  }
+}
+
+const policy = new LinearBackoff(5, 250);
+const value = await policy.run(doWork);
+```
+
+## RetryError
+
+Use `RetryError` when an orchestrator exhausts retries and needs to surface final context.
+
+```ts
+import { RetryError } from "@zap-studio/retry/error";
+
+throw new RetryError("Retry policy exhausted all attempts.", {
+  attempts: attempt,
+  lastError: error,
+  lastData: data,
+});
+```
+
+Policies implement `onExhausted(input)` to return the terminal error used by the built-in runner.
+
+`ExponentialBackoff` and `FixedDelay` inherit the default implementation from `BaseRetryPolicy`.
+
+## License
+
+MIT

package/dist/error-CWRADATN.d.mts

@@ -0,0 +1,44 @@
+//#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

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

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

package/dist/error.mjs

@@ -0,0 +1,38 @@
+//#region src/error.ts
+/**
+* Error thrown when retries are exhausted.
+*
+* @example
+* throw new RetryError("Retry exhausted", {
+*   attempts: 3,
+*   lastError: new Error("network"),
+* });
+*/
+var RetryError = class extends Error {
+	/**
+	* Total attempts performed before exhaustion.
+	*/
+	attempts;
+	/**
+	* Last captured error from execution.
+	*/
+	lastError;
+	/**
+	* Last captured data value, when available.
+	*/
+	lastData;
+	/**
+	* Creates a RetryError with structured terminal context.
+	*/
+	constructor(message, context) {
+		super(message);
+		this.name = "RetryError";
+		this.attempts = context.attempts;
+		this.lastError = context.lastError;
+		this.lastData = context.lastData;
+	}
+};
+//#endregion
+export { RetryError };
+
+//# sourceMappingURL=error.mjs.map

package/dist/error.mjs.map

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

package/dist/exponential-backoff.d.mts

@@ -0,0 +1,38 @@
+import { RetryDecision, RetryDecisionInput } from "./types.mjs";
+import { BaseRetryPolicy } from "./index.mjs";
+
+//#region src/exponential-backoff.d.ts
+/**
+* Configuration for `ExponentialBackoff`.
+*/
+interface ExponentialBackoffOptions {
+  maxAttempts: number;
+  baseDelayMs: number;
+  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 {
+  private readonly maxAttempts;
+  private readonly baseDelayMs;
+  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.mts.map

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

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

package/dist/exponential-backoff.mjs

@@ -0,0 +1,51 @@
+import { BaseRetryPolicy } from "./index.mjs";
+//#region src/exponential-backoff.ts
+/**
+* Exponential backoff retry strategy.
+*
+* @module
+*/
+/**
+* Retries with exponential delay growth up to a max cap.
+*
+* @example
+* const policy = new ExponentialBackoff({
+*   maxAttempts: 5,
+*   baseDelayMs: 100,
+*   maxDelayMs: 2_000,
+* });
+*/
+var ExponentialBackoff = class extends BaseRetryPolicy {
+	maxAttempts;
+	baseDelayMs;
+	maxDelayMs;
+	/**
+	* Creates an exponential backoff retry policy.
+	*/
+	constructor(options) {
+		super();
+		this.maxAttempts = options.maxAttempts;
+		this.baseDelayMs = options.baseDelayMs;
+		this.maxDelayMs = options.maxDelayMs;
+	}
+	/**
+	* Computes retry decision for the current attempt.
+	*/
+	next(input) {
+		if (input.attempt >= this.maxAttempts) return {
+			shouldRetry: false,
+			delayMs: 0,
+			reason: "max-attempts-reached"
+		};
+		const exponent = Math.max(0, input.attempt - 1);
+		return {
+			shouldRetry: true,
+			delayMs: Math.min(this.maxDelayMs, this.baseDelayMs * 2 ** exponent),
+			reason: "retry"
+		};
+	}
+};
+//#endregion
+export { ExponentialBackoff };
+
+//# sourceMappingURL=exponential-backoff.mjs.map

package/dist/exponential-backoff.mjs.map

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

package/dist/fixed-delay.d.mts

@@ -0,0 +1,35 @@
+import { RetryDecision, RetryDecisionInput } from "./types.mjs";
+import { BaseRetryPolicy } from "./index.mjs";
+
+//#region src/fixed-delay.d.ts
+/**
+* Configuration for `FixedDelay`.
+*/
+interface FixedDelayOptions {
+  maxAttempts: number;
+  delayMs: number;
+}
+/**
+* Retries with a constant delay between attempts.
+*
+* @example
+* const policy = new FixedDelay({
+*   maxAttempts: 3,
+*   delayMs: 250,
+* });
+*/
+declare class FixedDelay extends BaseRetryPolicy {
+  private readonly maxAttempts;
+  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.mts.map

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

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

package/dist/fixed-delay.mjs

@@ -0,0 +1,47 @@
+import { BaseRetryPolicy } from "./index.mjs";
+//#region src/fixed-delay.ts
+/**
+* Fixed-delay retry strategy.
+*
+* @module
+*/
+/**
+* Retries with a constant delay between attempts.
+*
+* @example
+* const policy = new FixedDelay({
+*   maxAttempts: 3,
+*   delayMs: 250,
+* });
+*/
+var FixedDelay = class extends BaseRetryPolicy {
+	maxAttempts;
+	delayMs;
+	/**
+	* Creates a fixed-delay retry policy.
+	*/
+	constructor(options) {
+		super();
+		this.maxAttempts = options.maxAttempts;
+		this.delayMs = options.delayMs;
+	}
+	/**
+	* Computes retry decision for the current attempt.
+	*/
+	next(input) {
+		if (input.attempt >= this.maxAttempts) return {
+			shouldRetry: false,
+			delayMs: 0,
+			reason: "max-attempts-reached"
+		};
+		return {
+			shouldRetry: true,
+			delayMs: this.delayMs,
+			reason: "retry"
+		};
+	}
+};
+//#endregion
+export { FixedDelay };
+
+//# sourceMappingURL=fixed-delay.mjs.map

package/dist/fixed-delay.mjs.map

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

package/dist/index.d.mts

@@ -0,0 +1,44 @@
+import { t as RetryError } from "./error-CWRADATN.mjs";
+import { RetryDecision, RetryDecisionInput, RetryExhaustedInput, RetryPolicy, RetryRunOptions, RetryRunResult } from "./types.mjs";
+
+//#region src/index.d.ts
+declare abstract class BaseRetryPolicy<TError = unknown, TData = unknown> implements RetryPolicy<TError, TData> {
+  /**
+  * Returns the retry decision for a failed attempt.
+  *
+  * @param input - Attempt context used to compute retry behavior.
+  * @throws Any error thrown by a concrete retry policy implementation.
+  */
+  abstract next(input: RetryDecisionInput<TError, TData>): RetryDecision;
+  /**
+  * Builds the terminal error thrown or returned when retries are exhausted.
+  *
+  * Override this when you need custom terminal error types.
+  *
+  * @param input - Exhaustion context.
+  * @returns `RetryError` by default.
+  * @throws Any error thrown by an overriding policy implementation.
+  */
+  onExhausted(input: RetryExhaustedInput<TError, TData>): RetryError;
+  run<T>(execute: (attempt: number) => Promise<T>, options: RetryRunOptions & {
+    throwOnExhausted: false;
+  }): Promise<RetryRunResult<T>>;
+  /**
+  * Runs retry orchestration and throws terminal error on exhaustion.
+  *
+  * @param execute - Async function to execute per attempt.
+  * @param options - Optional runner settings.
+  * @returns The successful execution value.
+  * @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 Any error thrown by `next`, by `onExhausted`, or by a custom `sleep`
+  *   function.
+  */
+  run<T>(execute: (attempt: number) => Promise<T>, options?: RetryRunOptions & {
+    throwOnExhausted?: true | undefined;
+  }): Promise<T>;
+}
+//#endregion
+export { BaseRetryPolicy };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

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

package/dist/index.mjs

@@ -0,0 +1,84 @@
+import { RetryError } from "./error.mjs";
+//#region src/index.ts
+/**
+* Retry runner base class and shared orchestration implementation.
+*
+* @module
+*/
+var BaseRetryPolicy = class {
+	/**
+	* Builds the terminal error thrown or returned when retries are exhausted.
+	*
+	* Override this when you need custom terminal error types.
+	*
+	* @param input - Exhaustion context.
+	* @returns `RetryError` by default.
+	* @throws Any error thrown by an overriding policy implementation.
+	*/
+	onExhausted(input) {
+		return new RetryError("Retry policy exhausted all attempts.", {
+			attempts: input.attempts,
+			lastError: input.error,
+			lastData: input.data
+		});
+	}
+	/**
+	* Runs retry orchestration in non-throw mode.
+	*
+	* When `throwOnExhausted` is `false`, returns a discriminated result union.
+	*
+	* @param execute - Async function to execute per attempt.
+	* @param options - Runner settings.
+	* @returns Success value or terminal result object based on option mode.
+	* @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.
+	*
+	* @example
+	* const result = await policy.run(doWork, { throwOnExhausted: false });
+	* if (!result.ok) console.error(result.error);
+	*/
+	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;
+		}
+	}
+};
+/**
+* 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 };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +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 | undefined },\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"}

package/dist/types.d.mts

@@ -0,0 +1,77 @@
+import { t as RetryError } from "./error-CWRADATN.mjs";
+
+//#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 Any error thrown by the policy implementation.
+  */
+  next(input: RetryDecisionInput<TError, TData>): RetryDecision;
+  /**
+  * Builds the terminal error used when retries are exhausted.
+  *
+  * @throws 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 {
+  readonly shouldRetry: boolean;
+  readonly delayMs: number;
+  readonly reason?: "retry" | "max-attempts-reached" | "policy-declined";
+}
+/**
+* Input passed to `RetryPolicy.next(...)` for each failed attempt.
+*/
+interface RetryDecisionInput<TError = unknown, TData = unknown> {
+  readonly attempt: number;
+  readonly maxAttempts?: number | undefined;
+  readonly error?: TError;
+  readonly data?: TData;
+}
+/**
+* Input passed to `RetryPolicy.onExhausted(...)` when retries stop.
+*/
+interface RetryExhaustedInput<TError = unknown, TData = unknown> {
+  readonly attempts: number;
+  readonly error?: TError;
+  readonly data?: TData;
+}
+/**
+* Options for `BaseRetryPolicy.run(...)`.
+*/
+interface RetryRunOptions {
+  /**
+  * Delay function used between retry attempts.
+  *
+  * @throws Any error thrown or rejected by the custom delay implementation.
+  */
+  readonly sleep?: ((delayMs: number) => Promise<void>) | undefined;
+  readonly throwOnExhausted?: boolean | undefined;
+}
+/**
+* Result union returned by non-throw runner mode.
+*/
+type RetryRunResult<T> = {
+  ok: true;
+  value: T;
+} | {
+  ok: false;
+  error: RetryError;
+  attempts: number;
+};
+//#endregion
+export { RetryDecision, RetryDecisionInput, RetryExhaustedInput, RetryPolicy, RetryRunOptions, RetryRunResult };
+//# sourceMappingURL=types.d.mts.map

package/dist/types.d.mts.map

@@ -0,0 +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,KAAU,OAAA,aAAoB,OAAA;EAAA,SAC9B,gBAAA;AAAA;;;;KAMC,cAAA;EAEN,EAAA;EACA,KAAA,EAAO,CAAA;AAAA;EAGP,EAAA;EACA,KAAA,EAAO,UAAA;EACP,QAAA;AAAA"}

package/dist/types.mjs

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@zap-studio/retry",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Composable retry policies for resilient async operations.",
+  "keywords": [
+    "backoff",
+    "exponential backoff",
+    "fetch",
+    "http",
+    "resilience",
+    "retry",
+    "typescript"
+  ],
+  "homepage": "https://www.zapstudio.dev/packages/retry",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zap-studio/monorepo.git",
+    "directory": "packages/retry"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./error": "./dist/error.mjs",
+    "./exponential-backoff": "./dist/exponential-backoff.mjs",
+    "./fixed-delay": "./dist/fixed-delay.mjs",
+    "./types": "./dist/types.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "vite-plus": "^0.1.19",
+    "@zap-studio/typescript": "0.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "test": "vp test run",
+    "test:watch": "vp test watch"
+  }
+}