@zap-studio/retry 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @zap-studio/retry
 
+## 0.2.0
+
+### Changed
+
+- Optimize retry runner hot paths by splitting throw/non-throw execution flows and skipping sleep calls when delay is non-positive.
+- Add `AbortSignal` support to `run(...)` so retry orchestration can be canceled before or between attempts.
+- Add retry benchmarking coverage with core and ecosystem scenarios, including real-world and fair-mode comparisons.
+- Add abort-focused ecosystem benchmarks comparing signal overhead and immediate cancellation behavior.
+- Expand TSDoc coverage for new runner internals added in this release.
+
 ## 0.1.2
 
 ### Changed

package/README.md

@@ -77,6 +77,51 @@ if (!result.ok) {
 }
 ```
 
+## Cancellation With AbortSignal
+
+Use `signal` in `run(...)` options to stop retrying early.
+
+```ts
+const controller = new AbortController();
+
+const promise = exponential.run(
+  async () => {
+    const response = await $fetch("https://api.example.com/users", {
+      throwOnFetchError: true,
+    });
+    return await response.json();
+  },
+  { signal: controller.signal },
+);
+
+controller.abort(new Error("Request canceled"));
+
+await promise;
+```
+
+In non-throw mode, abort is returned as `{ ok: false }`:
+
+```ts
+const controller = new AbortController();
+
+const result = await exponential.run(
+  async () => {
+    const response = await $fetch("https://api.example.com/users", {
+      throwOnFetchError: true,
+    });
+    return await response.json();
+  },
+  {
+    signal: controller.signal,
+    throwOnExhausted: false,
+  },
+);
+
+if (!result.ok) {
+  console.error("Retry stopped:", result.error);
+}
+```
+
 ## Choosing The Right Policy
 
 Use `ExponentialBackoff` for transient network instability and shared upstream services.

package/dist/{error-CWRADATN.d.mts → error-CVW4I654.d.mts}

@@ -2,7 +2,7 @@
 /**
 * Terminal error types used by retry policies and runners.
 *
-* @module
+* @module @zap-studio/retry/error
 */
 /**
 * Context payload attached to `RetryError`.
@@ -41,4 +41,4 @@ declare class RetryError extends Error {
 }
 //#endregion
 export { RetryErrorContext as n, RetryError as t };
-//# sourceMappingURL=error-CWRADATN.d.mts.map
+//# sourceMappingURL=error-CVW4I654.d.mts.map

package/dist/{error-CWRADATN.d.mts.map → error-CVW4I654.d.mts.map}

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

package/dist/error.d.mts

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

package/dist/error.mjs.map

@@ -1 +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"}
+{"version":3,"file":"error.mjs","names":[],"sources":["../src/error.ts"],"sourcesContent":["/**\n * Terminal error types used by retry policies and runners.\n *\n * @module @zap-studio/retry/error\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.mjs

@@ -3,7 +3,7 @@ import { BaseRetryPolicy } from "./index.mjs";
 /**
 * Exponential backoff retry strategy.
 *
-* @module
+* @module @zap-studio/retry/exponential-backoff
 */
 /**
 * Retries with exponential delay growth up to a max cap.

package/dist/exponential-backoff.mjs.map

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

@@ -3,7 +3,7 @@ import { BaseRetryPolicy } from "./index.mjs";
 /**
 * Fixed-delay retry strategy.
 *
-* @module
+* @module @zap-studio/retry/fixed-delay
 */
 /**
 * Retries with a constant delay between attempts.

package/dist/fixed-delay.mjs.map

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

@@ -1,7 +1,14 @@
-import { t as RetryError } from "./error-CWRADATN.mjs";
+import { t as RetryError } from "./error-CVW4I654.mjs";
 import { RetryDecision, RetryDecisionInput, RetryExhaustedInput, RetryPolicy, RetryRunOptions, RetryRunResult } from "./types.mjs";
 
 //#region src/index.d.ts
+/**
+* Base class for implementing retry policies and running retry orchestration.
+*
+* Extend this class and implement {@link BaseRetryPolicy.next} to define retry
+* behavior, then call {@link BaseRetryPolicy.run} to execute operations with that
+* policy.
+*/
 declare abstract class BaseRetryPolicy<TError = unknown, TData = unknown> implements RetryPolicy<TError, TData> {
   /**
   * Returns the retry decision for a failed attempt.
@@ -20,6 +27,14 @@ declare abstract class BaseRetryPolicy<TError = unknown, TData = unknown> implem
   * @throws Any error thrown by an overriding policy implementation.
   */
   onExhausted(input: RetryExhaustedInput<TError, TData>): RetryError;
+  /**
+  * Runs retry orchestration in non-throw mode.
+  *
+  * @param execute - Async function to execute per attempt.
+  * @param options - Runner settings with `throwOnExhausted: false`.
+  * @returns A discriminated result union containing success value or terminal error.
+  * @throws Any error thrown by `next`, `onExhausted`, or a custom `sleep`.
+  */
   run<T>(execute: (attempt: number) => Promise<T>, options: RetryRunOptions & {
     throwOnExhausted: false;
   }): Promise<RetryRunResult<T>>;
@@ -32,13 +47,43 @@ 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 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 };
+export { BaseRetryPolicy, defaultSleep };
 //# 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":";;;;uBAgBsB,eAAA,+CAA8D,WAAA,CAClF,MAAA,EACA,KAAA;;;;;;;WAQgB,IAAA,CAAK,KAAA,EAAO,kBAAA,CAAmB,MAAA,EAAQ,KAAA,IAAS,aAAA;;;;;;;;;;EAWhE,WAAA,CAAmB,KAAA,EAAO,mBAAA,CAAoB,MAAA,EAAQ,KAAA,IAAS,UAAA;EAQ/D,GAAA,GAAA,CACE,OAAA,GAAU,OAAA,aAAoB,OAAA,CAAQ,CAAA,GACtC,OAAA,EAAS,eAAA;IAAoB,gBAAA;EAAA,IAC5B,OAAA,CAAQ,cAAA,CAAe,CAAA;;;;;;;;;;;;;EAc1B,GAAA,GAAA,CACE,OAAA,GAAU,OAAA,aAAoB,OAAA,CAAQ,CAAA,GACtC,OAAA,GAAU,eAAA;IAAoB,gBAAA;EAAA,IAC7B,OAAA,CAAQ,CAAA;AAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;;;;;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"}

package/dist/index.mjs

@@ -3,7 +3,14 @@ import { RetryError } from "./error.mjs";
 /**
 * Retry runner base class and shared orchestration implementation.
 *
-* @module
+* @module @zap-studio/retry
+*/
+/**
+* Base class for implementing retry policies and running retry orchestration.
+*
+* Extend this class and implement {@link BaseRetryPolicy.next} to define retry
+* behavior, then call {@link BaseRetryPolicy.run} to execute operations with that
+* policy.
 */
 var BaseRetryPolicy = class {
 	/**
@@ -33,6 +40,7 @@ var BaseRetryPolicy = class {
 	* @throws Any error thrown by `next`, by `onExhausted`, or by a custom `sleep`
 	*   function. When `throwOnExhausted` is `false`, exhaustion itself is returned
 	*   as `{ ok: false }` instead of thrown.
+	*   Abort errors are also returned as `{ ok: false }` in non-throw mode.
 	*
 	* @example
 	* const result = await policy.run(doWork, { throwOnExhausted: false });
@@ -40,45 +48,179 @@ var BaseRetryPolicy = class {
 	*/
 	async run(execute, options = {}) {
 		const sleep = options.sleep ?? defaultSleep;
+		const signal = options.signal;
+		if (options.throwOnExhausted === false) return this.runResultMode(execute, sleep, signal);
+		return this.runThrowMode(execute, sleep, signal);
+	}
+	/**
+	* 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`.
+	*/
+	async runThrowMode(execute, sleep, signal) {
 		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({
+		while (true) {
+			throwIfAborted(signal);
+			try {
+				return await execute(attempt);
+			} catch (error) {
+				throwIfAborted(signal);
+				const typedError = error;
+				const decision = this.next({
+					attempt,
+					error: typedError
+				});
+				if (!decision.shouldRetry) throw this.onExhausted({
 					attempts: attempt,
-					error: lastError
+					error: typedError
+				});
+				if (decision.delayMs > 0) if (signal) await sleepWithAbortSignal(sleep, decision.delayMs, signal);
+				else await sleep(decision.delayMs);
+				attempt += 1;
+			}
+		}
+	}
+	/**
+	* 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`.
+	*/
+	async runResultMode(execute, sleep, signal) {
+		let attempt = 1;
+		while (true) {
+			if (signal?.aborted) {
+				const attempts = Math.max(0, attempt - 1);
+				return {
+					ok: false,
+					error: toRetryError(signal.reason, attempts),
+					attempts
+				};
+			}
+			try {
+				return {
+					ok: true,
+					value: await execute(attempt)
+				};
+			} catch (error) {
+				if (signal?.aborted) {
+					const attempts = Math.max(0, attempt - 1);
+					return {
+						ok: false,
+						error: toRetryError(signal.reason, attempts),
+						attempts
+					};
+				}
+				const typedError = error;
+				const decision = this.next({
+					attempt,
+					error: typedError
 				});
-				if (options.throwOnExhausted === false) return {
+				if (!decision.shouldRetry) return {
 					ok: false,
-					error: terminalError,
+					error: this.onExhausted({
+						attempts: attempt,
+						error: typedError
+					}),
 					attempts: attempt
 				};
-				throw terminalError;
+				if (decision.delayMs > 0) if (signal) try {
+					await sleepWithAbortSignal(sleep, decision.delayMs, signal);
+				} catch (error) {
+					if (signal.aborted) return {
+						ok: false,
+						error: toRetryError(signal.reason, attempt),
+						attempts: attempt
+					};
+					throw error;
+				}
+				else await sleep(decision.delayMs);
+				attempt += 1;
 			}
-			await sleep(decision.delayMs);
-			attempt += 1;
 		}
 	}
 };
 /**
 * Default delay implementation used by `run(...)` when no custom sleep function is provided.
+*
+* Returns immediately when `delayMs` is non-positive.
 */
 async function defaultSleep(delayMs) {
+	if (delayMs <= 0) return;
 	await new Promise((resolve) => setTimeout(resolve, delayMs));
 }
+/**
+* Throws an abort error when the provided signal is already aborted.
+*
+* @param signal - Optional cancellation signal.
+* @throws {Error} Abort reason converted to an `Error`.
+*/
+function throwIfAborted(signal) {
+	if (!signal?.aborted) return;
+	throw toAbortError(signal.reason);
+}
+/**
+* Normalizes an abort reason value into an `Error` instance.
+*
+* @param reason - Abort reason from `AbortSignal.reason`.
+* @returns Normalized error instance.
+*/
+function toAbortError(reason) {
+	if (reason instanceof Error) return reason;
+	if (typeof reason === "string" && reason.length > 0) return new Error(reason);
+	if (reason === void 0) return /* @__PURE__ */ new Error("Retry aborted.");
+	try {
+		return /* @__PURE__ */ new Error(`Retry aborted: ${JSON.stringify(reason)}`);
+	} catch {
+		return /* @__PURE__ */ new Error("Retry aborted.");
+	}
+}
+/**
+* Converts an abort reason into a `RetryError` for non-throw runner mode.
+*
+* @param reason - Abort reason from `AbortSignal.reason`.
+* @returns Retry terminal error value.
+*/
+function toRetryError(reason, attempts) {
+	const abortError = toAbortError(reason);
+	return new RetryError(abortError.message, {
+		attempts,
+		lastError: abortError
+	});
+}
+/**
+* Awaits delay sleep while also observing cancellation via `AbortSignal`.
+*
+* @param sleep - Delay function.
+* @param delayMs - Delay duration in milliseconds.
+* @param signal - Cancellation signal.
+* @throws {Error} Abort reason converted to an `Error` when canceled.
+*/
+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 { BaseRetryPolicy };
+export { BaseRetryPolicy, defaultSleep };
 
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

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

package/dist/types.d.mts

@@ -1,4 +1,4 @@
-import { t as RetryError } from "./error-CWRADATN.mjs";
+import { t as RetryError } from "./error-CVW4I654.mjs";
 
 //#region src/types.d.ts
 /**
@@ -59,6 +59,19 @@ interface RetryRunOptions {
   * @throws Any error thrown or rejected by the custom delay implementation.
   */
   readonly sleep?: (delayMs: number) => Promise<void>;
+  /**
+  * Abort signal used to cancel retry orchestration.
+  *
+  * When aborted, the runner stops retrying and terminates immediately.
+  */
+  readonly signal?: AbortSignal;
+  /**
+  * When `true`, the runner throws a `RetryError` when retries are exhausted.
+  *
+  * When `false`, the runner returns a `RetryRunResult` discriminated union.
+  *
+  * @default false
+  */
   readonly throwOnExhausted?: boolean;
 }
 /**

package/dist/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../src/types.ts"],"mappings":";;;;;;;;;;;;UAiBiB,WAAA;;;;;;EAMf,IAAA,CAAK,KAAA,EAAO,kBAAA,CAAmB,MAAA,EAAQ,KAAA,IAAS,aAAA;;;;;;EAMhD,WAAA,CAAY,KAAA,EAAO,mBAAA,CAAoB,MAAA,EAAQ,KAAA,IAAS,UAAA;AAAA;AAM1D;;;AAAA,UAAiB,aAAA;EAAA,SACN,WAAA;EAAA,SACA,OAAA;EAAA,SACA,MAAA;AAAA;;AAMX;;UAAiB,kBAAA;EAAA,SACN,OAAA;EAAA,SACA,WAAA;EAAA,SACA,KAAA,GAAQ,MAAA;EAAA,SACR,IAAA,GAAO,KAAA;AAAA;;;;UAMD,mBAAA;EAAA,SACN,QAAA;EAAA,SACA,KAAA,GAAQ,MAAA;EAAA,SACR,IAAA,GAAO,KAAA;AAAA;;;;UAMD,eAAA;EANC;AAMlB;;;;EANkB,SAYP,KAAA,IAAS,OAAA,aAAoB,OAAA;EAAA,SAC7B,gBAAA;AAAA;;;;KAMC,cAAA;EAEN,EAAA;EACA,KAAA,EAAO,CAAA;AAAA;EAGP,EAAA;EACA,KAAA,EAAO,UAAA;EACP,QAAA;AAAA"}
+{"version":3,"file":"types.d.mts","names":[],"sources":["../src/types.ts"],"mappings":";;;;;;;;;;;;UAiBiB,WAAA;;;;;;EAMf,IAAA,CAAK,KAAA,EAAO,kBAAA,CAAmB,MAAA,EAAQ,KAAA,IAAS,aAAA;;;;;;EAMhD,WAAA,CAAY,KAAA,EAAO,mBAAA,CAAoB,MAAA,EAAQ,KAAA,IAAS,UAAA;AAAA;AAM1D;;;AAAA,UAAiB,aAAA;EAAA,SACN,WAAA;EAAA,SACA,OAAA;EAAA,SACA,MAAA;AAAA;;AAMX;;UAAiB,kBAAA;EAAA,SACN,OAAA;EAAA,SACA,WAAA;EAAA,SACA,KAAA,GAAQ,MAAA;EAAA,SACR,IAAA,GAAO,KAAA;AAAA;;;;UAMD,mBAAA;EAAA,SACN,QAAA;EAAA,SACA,KAAA,GAAQ,MAAA;EAAA,SACR,IAAA,GAAO,KAAA;AAAA;;;;UAMD,eAAA;EANC;AAMlB;;;;EANkB,SAYP,KAAA,IAAS,OAAA,aAAoB,OAAA;;;;;;WAM7B,MAAA,GAAS,WAAA;EAQT;AAMX;;;;;;EANW,SAAA,gBAAA;AAAA;;;;KAMC,cAAA;EAEN,EAAA;EACA,KAAA,EAAO,CAAA;AAAA;EAGP,EAAA;EACA,KAAA,EAAO,UAAA;EACP,QAAA;AAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zap-studio/retry",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "private": false,
   "description": "Composable retry policies for resilient async operations.",
   "keywords": [
@@ -40,6 +40,12 @@
     "access": "public"
   },
   "devDependencies": {
+    "@types/async-retry": "^1.4.9",
+    "@types/promise-retry": "^1.1.6",
+    "async-retry": "^1.3.3",
+    "exponential-backoff": "^3.1.3",
+    "p-retry": "^8.0.0",
+    "promise-retry": "^2.0.1",
     "typescript": "^6.0.3",
     "vite-plus": "^0.1.19",
     "@zap-studio/typescript": "0.0.0"