npm - @zap-studio/retry - Versions diffs - 1.0.0 → 1.2.0 - Mend

@zap-studio/retry 1.0.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/CHANGELOG.md +14 -0
package/README.md +44 -6
package/dist/base-policy.d.ts.map +1 -1
package/dist/base-policy.js +49 -21
package/dist/base-policy.js.map +1 -1
package/dist/exponential-backoff.d.ts +7 -0
package/dist/exponential-backoff.d.ts.map +1 -1
package/dist/exponential-backoff.js +9 -2
package/dist/exponential-backoff.js.map +1 -1
package/dist/index.d.ts +2 -1
package/dist/index.js +2 -1
package/dist/jitter.d.ts +48 -0
package/dist/jitter.d.ts.map +1 -0
package/dist/jitter.js +24 -0
package/dist/jitter.js.map +1 -0
package/dist/linear-backoff.d.ts +7 -0
package/dist/linear-backoff.d.ts.map +1 -1
package/dist/linear-backoff.js +9 -2
package/dist/linear-backoff.js.map +1 -1
package/dist/types.d.ts +19 -0
package/dist/types.d.ts.map +1 -1
package/package.json +5 -1

package/CHANGELOG.md CHANGED Viewed

@@ -4,6 +4,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [1.2.0]
+### Added
+`runRetryPolicy(...)` gains an optional `logger?: Logger` option (from `@zap-studio/logger`). When provided, it logs each retry decision at `debug` (attempt, delay, reason), exhaustion at `warn`, and cancellation at `debug`. Omitting it keeps zero logging overhead. See [Logging](https://www.zapstudio.dev/retry/logging).
+## [1.1.0]
+### Added
+`exponentialBackoff(...)` and `linearBackoff(...)` gain an optional `jitter?: "full" | "equal" | JitterOptions` option, applied to the computed delay after it's capped at `maxDelayMs`. `"full"` randomizes across `[0, delayMs]`; `"equal"` keeps a floor at half the delay, randomizing across `[delayMs/2, delayMs]`. Pass `{ mode, random }` to override the random source, useful for deterministic tests.
+New export: `applyJitter(delayMs, jitter?)`, also available from the `./jitter` subpath. See [Jitter](https://www.zapstudio.dev/retry/jitter).
 ## [1.0.0]
 ### Added

package/README.md CHANGED Viewed

@@ -13,31 +13,40 @@ npm install @zap-studio/retry
 ## Features
 - **Built-in policies**: `fixedDelay(...)`, `linearBackoff(...)`, and `exponentialBackoff(...)`.
+- **Jitter**: `"full"` or `"equal"` jitter on `exponentialBackoff`/`linearBackoff`, to avoid synchronized retries against a shared upstream.
 - **A shared runner** via `runRetryPolicy(policy, execute, options?)` with attempt-aware callbacks and custom sleep injection.
 - **Structured terminal errors**: `RetryError` on exhaustion, `AbortError` on cancellation.
 - **Non-throw mode** (`throwOnExhausted: false`) returns a `RetryRunResult` instead of throwing.
 - **Cancellation** through `AbortSignal`, checked before, between, and during retries.
 - **Custom policies** as plain objects implementing `RetryPolicy` — just a `next(...)` function, no subclassing.
+- **Optional logging** via a `logger?: Logger` option ([`@zap-studio/logger`](https://www.npmjs.com/package/@zap-studio/logger)) — omit it and there's zero logging overhead.
 - **Tree-shakeable** — policies are functions returning plain objects, not classes; unused policies are dropped by any modern bundler.
 ## Quick Start
 ```ts
+import { ConsoleLogger } from "@zap-studio/logger";
 import { exponentialBackoff, runRetryPolicy } from "@zap-studio/retry";
 import { $fetch } from "@zap-studio/fetch";
+const logger = new ConsoleLogger({ minLevel: "debug" });
 const policy = exponentialBackoff({
   maxAttempts: 5,
   baseDelayMs: 100,
   maxDelayMs: 2_000,
 });
-const data = await runRetryPolicy(policy, async () => {
-  const response = await $fetch("https://api.example.com/users", {
-    throwOnFetchError: true,
-  });
-  return await response.json();
-});
+const data = await runRetryPolicy(
+  policy,
+  async () => {
+    const response = await $fetch("https://api.example.com/users", {
+      throwOnFetchError: true,
+    });
+    return await response.json();
+  },
+  { logger }
+);
 ```
 ## Built-in Policies
@@ -65,6 +74,19 @@ const linear = linearBackoff({
 const fixed = fixedDelay({ maxAttempts: 4, delayMs: 300 });
 ```
+## Jitter
+`"full"` or `"equal"` jitter on `exponentialBackoff`/`linearBackoff`, applied to the delay after it's capped, to avoid synchronized retries against a shared upstream.
+```ts
+const policy = exponentialBackoff({
+  maxAttempts: 5,
+  baseDelayMs: 100,
+  maxDelayMs: 2_000,
+  jitter: "full",
+});
+```
 ## Shared Runner
 Via `runRetryPolicy(policy, execute, options?)` with attempt-aware callbacks and custom sleep injection.
@@ -147,6 +169,22 @@ const stepDelay = (maxAttempts: number, stepMs: number): RetryPolicy => ({
 const data = await runRetryPolicy(stepDelay(5, 100), execute);
 ```
+## Logging
+Pass a `logger?: Logger` from [`@zap-studio/logger`](https://www.npmjs.com/package/@zap-studio/logger) to `runRetryPolicy(...)` to observe retry decisions, exhaustion, and cancellation. Omit it and nothing is logged.
+```ts
+import { ConsoleLogger } from "@zap-studio/logger";
+import { exponentialBackoff, runRetryPolicy } from "@zap-studio/retry";
+const logger = new ConsoleLogger({ minLevel: "debug" });
+const policy = exponentialBackoff({ maxAttempts: 5, baseDelayMs: 100 });
+await runRetryPolicy(policy, execute, { logger });
+```
+Each retry decision logs at `debug` (attempt, delay, reason), exhaustion logs at `warn`, and cancellation logs at `debug`.
 ## Runtime Support
 | Runtime            | Minimum version                         |

package/dist/base-policy.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"base-policy.d.ts","names":[],"sources":["../src/base-policy.ts"],"mappings":";;;;;;;;;;;;;;;~~cA4Ba~~,eAAsB,oBAAkB;;;;;;;;;;;;;~~iBA8YrC~~,eACd,GACA,eAAe,QAAQ,OACvB,iBAEA,QAAQ,YAAY,QAAQ,QAC5B,UAAU,oBAAoB,QAAQ,IACtC,SAAS;EAAoB;IAC5B,QAAQ,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgCV,eACd,GACA,eAAe,QAAQ,OACvB,iBAEA,QAAQ,YAAY,QAAQ,QAC5B,UAAU,oBAAoB,QAAQ,IACtC,UAAU;EAAoB;IAC7B,QAAQ"}
1	+ {"version":3,"file":"base-policy.d.ts","names":[],"sources":["../src/base-policy.ts"],"mappings":";;;;;;;;;;;;;;;cA+Ba,eAAsB,oBAAkB;;;;;;;;;;;;;iBAicrC,eACd,GACA,eAAe,QAAQ,OACvB,iBAEA,QAAQ,YAAY,QAAQ,QAC5B,UAAU,oBAAoB,QAAQ,IACtC,SAAS;EAAoB;IAC5B,QAAQ,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgCV,eACd,GACA,eAAe,QAAQ,OACvB,iBAEA,QAAQ,YAAY,QAAQ,QAC5B,UAAU,oBAAoB,QAAQ,IACtC,UAAU;EAAoB;IAC7B,QAAQ"}

package/dist/base-policy.js CHANGED Viewed

@@ -1,11 +1,6 @@
 import { AbortError, RetryError } from "./errors.js";
 //#region src/base-policy.ts
 /**
-* Retry runner base class and shared orchestration implementation.
-*
-* @module @zap-studio/retry/base-policy
-*/
-/**
 * Awaits a timer-based delay, unless `delayMs` is non-positive.
 *
 * @param delayMs - Milliseconds to wait before resolving.
@@ -42,10 +37,12 @@ const toAbortError = (reason) => {
 * Throws when the provided abort signal is already aborted.
 *
 * @param signal - Optional abort signal to inspect.
+* @param logger - Optional logger; logs the abort at `debug` before throwing.
 * @throws {AbortError} When the signal is aborted.
 */
-const throwIfAborted = (signal) => {
+const throwIfAborted = (signal, logger) => {
 	if (signal?.aborted !== true) return;
+	logger?.debug("retry aborted", { reason: signal.reason });
 	throw toAbortError(signal.reason);
 };
 /**
@@ -72,6 +69,25 @@ const sleepWithAbortSignal = async (sleep, delayMs, signal) => {
 	}
 };
 /**
+* Logs a `next(...)` decision: `debug` when retrying, `warn` when exhausted.
+* Shared by both the throw-mode and non-throw retry loops.
+*/
+const logRetryDecision = (logger, attempt, decision, error) => {
+	if (decision.shouldRetry) {
+		logger?.debug("retry scheduled", {
+			attempt,
+			delayMs: decision.delayMs,
+			reason: decision.reason
+		});
+		return;
+	}
+	logger?.warn("retry policy exhausted", {
+		attempts: attempt,
+		error,
+		reason: decision.reason
+	});
+};
+/**
 * Runs the throw-mode retry loop: throws `RetryError` on exhaustion and
 * `AbortError` when `signal` aborts.
 *
@@ -79,6 +95,8 @@ const sleepWithAbortSignal = async (sleep, delayMs, signal) => {
 * @param execute - Async work callback per attempt.
 * @param sleep - Delay function between retries.
 * @param signal - Optional cancel signal.
+* @param logger - Optional logger; logs each retry decision at `debug` and
+*   exhaustion at `warn`.
 * @returns Resolves to the first successful return value.
 * @throws {RetryError} When retries are exhausted and `onExhausted` returns
 *   the terminal error.
@@ -87,19 +105,20 @@ const sleepWithAbortSignal = async (sleep, delayMs, signal) => {
 *   rethrows the original caught value immediately, bypassing retry, when
 *   `policy.isKnownError` rejects it as outside this policy's error domain.
 */
-const runThrowMode = async (policy, execute, sleep, signal) => {
+const runThrowMode = async (policy, execute, sleep, signal, logger) => {
 	let attempt = 1;
 	while (true) {
-		throwIfAborted(signal);
+		throwIfAborted(signal, logger);
 		try {
 			return await execute(attempt);
 		} catch (error) {
-			throwIfAborted(signal);
+			throwIfAborted(signal, logger);
 			if (!policy.isKnownError(error)) throw error;
 			const decision = policy.next({
 				attempt,
 				error
 			});
+			logRetryDecision(logger, attempt, decision, error);
 			if (!decision.shouldRetry) throw policy.onExhausted({
 				attempts: attempt,
 				error
@@ -115,10 +134,12 @@ const runThrowMode = async (policy, execute, sleep, signal) => {
 *
 * @param signal - Optional abort signal; only acts when `aborted` is set.
 * @param attempts - Number of finished attempts to report in the result.
+* @param logger - Optional logger; logs the abort at `debug`.
 * @returns Failure result or `undefined` if not aborted.
 */
-const buildAbortResult = (signal, attempts) => {
+const buildAbortResult = (signal, attempts, logger) => {
 	if (signal?.aborted !== true) return;
+	logger?.debug("retry aborted", { reason: signal.reason });
 	return {
 		attempts,
 		error: toAbortError(signal.reason),
@@ -154,11 +175,12 @@ const runAttempt = async (execute, attempt) => {
 * @param delayMs - Milliseconds to wait.
 * @param signal - If set, `sleep` is raced with the abort signal.
 * @param attempts - Attempt count to attach if the wait ends in abort.
+* @param logger - Optional logger; logs an abort ending the wait at `debug`.
 * @returns A terminal result when canceled during the wait, otherwise
 *   `undefined`.
 * @throws {Error} The underlying `sleep` rejection when it is not an abort.
 */
-const waitForDelay = async (sleep, delayMs, signal, attempts) => {
+const waitForDelay = async (sleep, delayMs, signal, attempts, logger) => {
 	if (signal === void 0) {
 		await sleep(delayMs);
 		return;
@@ -167,7 +189,7 @@ const waitForDelay = async (sleep, delayMs, signal, attempts) => {
 		await sleepWithAbortSignal(sleep, delayMs, signal);
 		return;
 	} catch (error) {
-		const aborted = buildAbortResult(signal, attempts);
+		const aborted = buildAbortResult(signal, attempts, logger);
 		if (aborted !== void 0) return aborted;
 		throw error;
 	}
@@ -182,19 +204,22 @@ const waitForDelay = async (sleep, delayMs, signal, attempts) => {
 * @param params.error - Error thrown by the attempt.
 * @param params.sleep - Delay function between retries.
 * @param params.signal - Optional abort signal.
+* @param params.logger - Optional logger; logs each retry decision at
+*   `debug`, exhaustion at `warn`, and cancellation at `debug`.
 * @returns Terminal non-throw result if the loop should stop, otherwise
 *   `undefined` to schedule another attempt.
 * @throws {Error} Any error thrown by `next`, `onExhausted`, or a custom `sleep` when
 *   the error is not an abort.
 */
 const handleFailure = async (policy, params) => {
-	const { attempt, error, sleep, signal } = params;
-	const abortResult = buildAbortResult(signal, attempt);
+	const { attempt, error, sleep, signal, logger } = params;
+	const abortResult = buildAbortResult(signal, attempt, logger);
 	if (abortResult !== void 0) return abortResult;
 	const decision = policy.next({
 		attempt,
 		error
 	});
+	logRetryDecision(logger, attempt, decision, error);
 	if (!decision.shouldRetry) return {
 		attempts: attempt,
 		error: policy.onExhausted({
@@ -204,7 +229,7 @@ const handleFailure = async (policy, params) => {
 		ok: false
 	};
 	if (decision.delayMs > 0) {
-		const delayAbortResult = await waitForDelay(sleep, decision.delayMs, signal, attempt);
+		const delayAbortResult = await waitForDelay(sleep, decision.delayMs, signal, attempt, logger);
 		if (delayAbortResult !== void 0) return delayAbortResult;
 	}
 };
@@ -216,6 +241,8 @@ const handleFailure = async (policy, params) => {
 * @param execute - Async work callback per attempt.
 * @param sleep - Delay function between retries.
 * @param signal - Optional cancel signal.
+* @param logger - Optional logger; logs each retry decision at `debug`,
+*   exhaustion at `warn`, and cancellation at `debug`.
 * @returns Terminal success or failure object. When `policy.isKnownError`
 *   rejects a caught value as outside this policy's error domain, the
 *   original value is wrapped in a `RetryError` and returned on
@@ -223,17 +250,17 @@ const handleFailure = async (policy, params) => {
 * @throws {Error} Any error thrown by `next`, `onExhausted`, or a non-abort `sleep`
 *   failure.
 */
-const runResultMode = async (policy, execute, sleep, signal) => {
+const runResultMode = async (policy, execute, sleep, signal, logger) => {
 	let attempt = 1;
 	while (true) {
-		const abortResult = buildAbortResult(signal, Math.max(0, attempt - 1));
+		const abortResult = buildAbortResult(signal, Math.max(0, attempt - 1), logger);
 		if (abortResult !== void 0) return abortResult;
 		const execution = await runAttempt(execute, attempt);
 		if (execution.ok) return {
 			ok: true,
 			value: execution.value
 		};
-		const attemptAbortResult = buildAbortResult(signal, attempt);
+		const attemptAbortResult = buildAbortResult(signal, attempt, logger);
 		if (attemptAbortResult !== void 0) return attemptAbortResult;
 		if (!policy.isKnownError(execution.error)) return {
 			attempts: attempt,
@@ -246,6 +273,7 @@ const runResultMode = async (policy, execute, sleep, signal) => {
 		const failure = await handleFailure(policy, {
 			attempt,
 			error: execution.error,
+			logger,
 			signal,
 			sleep
 		});
@@ -291,14 +319,14 @@ const defaultIsKnownError = (error) => error instanceof Error;
 */
 async function runRetryPolicy(policy, execute, options = {}) {
 	const sleep = options.sleep ?? defaultSleep;
-	const { signal } = options;
+	const { signal, logger } = options;
 	const resolvedPolicy = {
 		isKnownError: (error) => policy.isKnownError ? policy.isKnownError(error) : defaultIsKnownError(error),
 		next: (input) => policy.next(input),
 		onExhausted: (input) => policy.onExhausted ? policy.onExhausted(input) : defaultOnExhausted(input)
 	};
-	if (options.throwOnExhausted === false) return await runResultMode(resolvedPolicy, execute, sleep, signal);
-	return await runThrowMode(resolvedPolicy, execute, sleep, signal);
+	if (options.throwOnExhausted === false) return await runResultMode(resolvedPolicy, execute, sleep, signal, logger);
+	return await runThrowMode(resolvedPolicy, execute, sleep, signal, logger);
 }
 //#endregion
 export { defaultSleep, runRetryPolicy };

package/dist/base-policy.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"base-policy.js","names":[],"sources":["../src/base-policy.ts"],"sourcesContent":["/*\n Retry runner base class and shared orchestration implementation.\n \n @module @zap-studio/retry/base-policy\n /\n\nimport { AbortError, RetryError } from \"./errors.js\";\nimport type {\n ResolvedRetryPolicy,\n RetryExhaustedInput,\n RetryPolicy,\n RetryRunOptions,\n RetryRunResult,\n} from \"./types.js\";\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 \n @example\n * ```ts\n * import { defaultSleep } from \"@zap-studio/retry\";\n \n await defaultSleep(250); // waits 250ms\n * ```\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\n/\n Normalizes an abort `reason` into an `AbortError`.\n /\nconst 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 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 /\nconst throwIfAborted = (signal?: AbortSignal): void => {\n if (signal?.aborted !== true) {\n return;\n }\n\n throw toAbortError(signal.reason);\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 /\nconst sleepWithAbortSignal = async (\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 // oxlint-disable-next-line promise/avoid-new -- AbortSignal callback is adapted into the race promise.\n new Promise<never>((_resolve, 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\n/\n Runs the throw-mode retry loop: throws `RetryError` on exhaustion and\n * `AbortError` when `signal` aborts.\n \n @param policy - Resolved retry policy providing `next` and `onExhausted`.\n * @param execute - Async work callback per attempt.\n * @param sleep - Delay function between retries.\n * @param signal - Optional cancel signal.\n * @returns Resolves to the first successful return value.\n * @throws {RetryError} When retries are exhausted and `onExhausted` returns\n * the terminal error.\n * @throws {AbortError} When `signal` is already aborted or aborts while waiting.\n * @throws {Error} Any error thrown by `next`, `onExhausted`, or `sleep`. Also\n * rethrows the original caught value immediately, bypassing retry, when\n * `policy.isKnownError` rejects it as outside this policy's error domain.\n /\nconst runThrowMode = async <T, TError extends Error, TData>(\n policy: ResolvedRetryPolicy<TError, TData>,\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 // oxlint-disable-next-line no-await-in-loop -- Retry attempts must run sequentially.\n return await execute(attempt);\n } catch (error) {\n throwIfAborted(signal);\n\n if (!policy.isKnownError(error)) {\n throw error;\n }\n\n const decision = policy.next({\n attempt,\n error,\n });\n\n if (!decision.shouldRetry) {\n throw policy.onExhausted({\n attempts: attempt,\n error,\n });\n }\n\n if (decision.delayMs > 0) {\n // oxlint-disable-next-line no-await-in-loop -- Delay belongs between sequential retry attempts.\n await (signal === undefined\n ? sleep(decision.delayMs)\n : sleepWithAbortSignal(sleep, decision.delayMs, signal));\n }\n\n attempt += 1;\n }\n }\n};\n\n/\n When `signal` is already aborted, builds the terminal `{ ok: false }` object\n * with a normalized `AbortError` on `error`.\n \n @param signal - Optional abort signal; only acts when `aborted` is set.\n * @param attempts - Number of finished attempts to report in the result.\n * @returns Failure result or `undefined` if not aborted.\n /\nconst buildAbortResult = (\n signal: AbortSignal \| undefined,\n attempts: number\n): RetryRunResult<never> \| undefined => {\n if (signal?.aborted !== true) {\n return undefined;\n }\n\n return {\n attempts,\n error: toAbortError(signal.reason),\n ok: false,\n };\n};\n\n/\n Runs one `execute(attempt)` call and returns either a success value or a\n * captured error without rethrowing.\n \n @param execute - User work callback.\n * @param attempt - One-based attempt number passed to `execute`.\n * @returns A tagged success with `value` or a tagged failure with `error`.\n /\nconst runAttempt = async <T>(\n execute: (attempt: number) => Promise<T>,\n attempt: number\n): Promise<{ ok: true; value: T } \| { ok: false; error: unknown }> => {\n try {\n return {\n ok: true,\n value: await execute(attempt),\n };\n } catch (error) {\n return {\n error,\n ok: false,\n };\n }\n};\n\n/\n Awaits inter-attempt delay in result mode, mapping an abort during wait to\n * a terminal result instead of throwing when `throwOnExhausted` is false.\n \n @param sleep - Custom or default sleep implementation.\n * @param delayMs - Milliseconds to wait.\n * @param signal - If set, `sleep` is raced with the abort signal.\n * @param attempts - Attempt count to attach if the wait ends in abort.\n * @returns A terminal result when canceled during the wait, otherwise\n * `undefined`.\n * @throws {Error} The underlying `sleep` rejection when it is not an abort.\n /\nconst waitForDelay = async (\n sleep: (delayMs: number) => Promise<void>,\n delayMs: number,\n signal: AbortSignal \| undefined,\n attempts: number\n): Promise<RetryRunResult<never> \| undefined> => {\n if (signal === undefined) {\n await sleep(delayMs);\n return undefined;\n }\n\n try {\n await sleepWithAbortSignal(sleep, delayMs, signal);\n return undefined;\n } catch (error) {\n const aborted = buildAbortResult(signal, attempts);\n if (aborted !== undefined) {\n return aborted;\n }\n throw error;\n }\n};\n\n/\n After a failed attempt, applies abort rules, `next`, optional delay, and\n * either returns a terminal `RetryRunResult` or `undefined` to continue.\n \n @param policy - Resolved retry policy hooks (`next`, `onExhausted`).\n * @param params - Failure context for the current attempt.\n * @param params.attempt - Current attempt number.\n * @param params.error - Error thrown by the attempt.\n * @param params.sleep - Delay function between retries.\n * @param params.signal - Optional abort signal.\n * @returns Terminal non-throw result if the loop should stop, otherwise\n * `undefined` to schedule another attempt.\n * @throws {Error} Any error thrown by `next`, `onExhausted`, or a custom `sleep` when\n * the error is not an abort.\n /\nconst handleFailure = async <TError extends Error, TData>(\n policy: ResolvedRetryPolicy<TError, TData>,\n params: {\n attempt: number;\n error: TError;\n sleep: (delayMs: number) => Promise<void>;\n signal: AbortSignal \| undefined;\n }\n): Promise<RetryRunResult<never> \| undefined> => {\n const { attempt, error, sleep, signal } = params;\n const abortResult = buildAbortResult(signal, attempt);\n if (abortResult !== undefined) {\n return abortResult;\n }\n\n const decision = policy.next({\n attempt,\n error,\n });\n\n if (!decision.shouldRetry) {\n const terminalError = policy.onExhausted({\n attempts: attempt,\n error,\n });\n\n return {\n attempts: attempt,\n error: terminalError,\n ok: false,\n };\n }\n\n if (decision.delayMs > 0) {\n const delayAbortResult = await waitForDelay(\n sleep,\n decision.delayMs,\n signal,\n attempt\n );\n if (delayAbortResult !== undefined) {\n return delayAbortResult;\n }\n }\n\n return undefined;\n};\n\n/\n Runs the non-throw retry loop, returning\n * `RetryRunResult`.\n \n @param policy - Resolved retry policy providing `next` and `onExhausted`.\n * @param execute - Async work callback per attempt.\n * @param sleep - Delay function between retries.\n * @param signal - Optional cancel signal.\n * @returns Terminal success or failure object. When `policy.isKnownError`\n * rejects a caught value as outside this policy's error domain, the\n * original value is wrapped in a `RetryError` and returned on\n * `result.error` immediately, bypassing retry — never thrown.\n * @throws {Error} Any error thrown by `next`, `onExhausted`, or a non-abort `sleep`\n * failure.\n /\nconst runResultMode = async <T, TError extends Error, TData>(\n policy: ResolvedRetryPolicy<TError, TData>,\n execute: (attempt: number) => Promise<T>,\n sleep: (delayMs: number) => Promise<void>,\n signal?: AbortSignal\n): Promise<RetryRunResult<T>> => {\n let attempt = 1;\n\n while (true) {\n const abortResult = buildAbortResult(signal, Math.max(0, attempt - 1));\n if (abortResult !== undefined) {\n return abortResult;\n }\n\n // oxlint-disable-next-line no-await-in-loop -- Retry attempts must run sequentially.\n const execution = await runAttempt(execute, attempt);\n if (execution.ok) {\n return { ok: true, value: execution.value };\n }\n\n const attemptAbortResult = buildAbortResult(signal, attempt);\n if (attemptAbortResult !== undefined) {\n return attemptAbortResult;\n }\n\n if (!policy.isKnownError(execution.error)) {\n return {\n attempts: attempt,\n error: new RetryError(\"Retry policy encountered an unknown error.\", {\n attempts: attempt,\n lastError: execution.error,\n }),\n ok: false,\n };\n }\n\n // oxlint-disable-next-line no-await-in-loop -- Failure handling belongs to the current sequential attempt.\n const failure = await handleFailure(policy, {\n attempt,\n error: execution.error,\n signal,\n sleep,\n });\n if (failure !== undefined) {\n return failure;\n }\n\n attempt += 1;\n }\n};\n\n/\n Default `onExhausted` used when a policy omits it: wraps the exhaustion\n * context in a generic `RetryError`.\n /\nconst defaultOnExhausted = <TError extends Error, TData>(\n input: RetryExhaustedInput<TError, TData>\n): RetryError =>\n new RetryError(\"Retry policy exhausted all attempts.\", {\n attempts: input.attempts,\n lastData: input.data,\n lastError: input.error,\n });\n\n/\n Default `isKnownError` used when a policy omits it: accepts any `Error`\n * instance and rejects everything else.\n /\n// oxlint-disable-next-line typescript/no-unnecessary-type-parameters -- TError only appears in the return predicate; needed so callers infer the right narrowed type.\nconst defaultIsKnownError = <TError extends Error>(\n error: unknown\n): error is TError => error instanceof Error;\n\n/\n Runs retry orchestration in non-throw mode.\n \n @param policy - Retry policy: `next` is required, `onExhausted` and\n * `isKnownError` fall back to their defaults when omitted.\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 * When `policy.isKnownError` rejects a caught value, it is wrapped in a\n * `RetryError` and returned as the terminal failure instead of thrown.\n * @throws {Error} Any error thrown by `next`, `onExhausted`, or a custom `sleep`.\n /\nexport function runRetryPolicy<\n T,\n TError extends Error = Error,\n TData = unknown,\n>(\n policy: RetryPolicy<TError, TData>,\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 policy - Retry policy: `next` is required, `onExhausted` and\n * `isKnownError` fall back to their defaults when omitted.\n * @param execute - Async function to execute per attempt.\n * @param options - Optional runner settings.\n * @returns The successful execution value.\n * @throws {RetryError} When retries are exhausted and `onExhausted` returns the\n * terminal retry error. The default implementation returns `RetryError` with the last\n * execution failure available on `RetryError.lastError`.\n * @throws {AbortError} When `options.signal` is already aborted or aborts while retrying.\n * @throws {Error} Any error thrown by `next`, by `onExhausted`, or by a custom `sleep`\n * function.\n \n @example\n * ```ts\n * import { runRetryPolicy } from \"@zap-studio/retry\";\n * import type { RetryPolicy } from \"@zap-studio/retry\";\n \n const linearBackoff: RetryPolicy = {\n * next: ({ attempt }) =>\n * attempt < 3\n * ? { shouldRetry: true, delayMs: attempt * 100, reason: \"retry\" }\n * : { shouldRetry: false, delayMs: 0, reason: \"max-attempts-reached\" },\n * };\n \n const data = await runRetryPolicy(linearBackoff, async () => fetchFlakyResource());\n * ```\n /\nexport function runRetryPolicy<\n T,\n TError extends Error = Error,\n TData = unknown,\n>(\n policy: RetryPolicy<TError, TData>,\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 policy - Retry policy: `next` is required, `onExhausted` and\n * `isKnownError` fall back to their defaults when omitted.\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 {Error} Any error thrown by `next`, by `onExhausted`, or by a custom `sleep`\n * function. When `throwOnExhausted` is `false`, exhaustion itself is returned\n * as `{ ok: false }` instead of thrown.\n * Cancellation is returned as `{ ok: false, error: AbortError }` in non-throw\n * mode. A value rejected by `policy.isKnownError` is wrapped in a\n * `RetryError` and returned the same way in non-throw mode; in throw mode\n * it is rethrown as-is.\n \n @example\n * const result = await runRetryPolicy(policy, doWork, { throwOnExhausted: false });\n * if (!result.ok) console.error(result.error);\n */\nexport async function runRetryPolicy<\n T,\n TError extends Error = Error,\n TData = unknown,\n>(\n policy: RetryPolicy<TError, TData>,\n execute: (attempt: number) => Promise<T>,\n options: RetryRunOptions = {}\n): Promise<T \| RetryRunResult<T>> {\n const sleep = options.sleep ?? defaultSleep;\n const { signal } = options;\n const resolvedPolicy: ResolvedRetryPolicy<TError, TData> = {\n isKnownError: (error): error is TError =>\n policy.isKnownError\n ? policy.isKnownError(error)\n : defaultIsKnownError(error),\n next: (input) => policy.next(input),\n onExhausted: (input) =>\n policy.onExhausted\n ? policy.onExhausted(input)\n : defaultOnExhausted(input),\n };\n\n if (options.throwOnExhausted === false) {\n return await runResultMode(resolvedPolicy, execute, sleep, signal);\n }\n\n return await runThrowMode(resolvedPolicy, execute, sleep, signal);\n}\n"],"mappings":"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"}
1	+ {"version":3,"file":"base-policy.js","names":[],"sources":["../src/base-policy.ts"],"sourcesContent":["/*\n Retry runner base class and shared orchestration implementation.\n \n @module @zap-studio/retry/base-policy\n /\n\nimport type { Logger } from \"@zap-studio/logger\";\n\nimport { AbortError, RetryError } from \"./errors.js\";\nimport type {\n ResolvedRetryPolicy,\n RetryDecision,\n RetryExhaustedInput,\n RetryPolicy,\n RetryRunOptions,\n RetryRunResult,\n} from \"./types.js\";\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 \n @example\n * ```ts\n * import { defaultSleep } from \"@zap-studio/retry\";\n \n await defaultSleep(250); // waits 250ms\n * ```\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\n/\n Normalizes an abort `reason` into an `AbortError`.\n /\nconst 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 Throws when the provided abort signal is already aborted.\n \n @param signal - Optional abort signal to inspect.\n * @param logger - Optional logger; logs the abort at `debug` before throwing.\n * @throws {AbortError} When the signal is aborted.\n /\nconst throwIfAborted = (signal?: AbortSignal, logger?: Logger): void => {\n if (signal?.aborted !== true) {\n return;\n }\n\n logger?.debug(\"retry aborted\", { reason: signal.reason });\n throw toAbortError(signal.reason);\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 /\nconst sleepWithAbortSignal = async (\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 // oxlint-disable-next-line promise/avoid-new -- AbortSignal callback is adapted into the race promise.\n new Promise<never>((_resolve, 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\n/\n Logs a `next(...)` decision: `debug` when retrying, `warn` when exhausted.\n * Shared by both the throw-mode and non-throw retry loops.\n /\nconst logRetryDecision = (\n logger: Logger \| undefined,\n attempt: number,\n decision: RetryDecision,\n error: unknown\n): void => {\n if (decision.shouldRetry) {\n logger?.debug(\"retry scheduled\", {\n attempt,\n delayMs: decision.delayMs,\n reason: decision.reason,\n });\n return;\n }\n\n logger?.warn(\"retry policy exhausted\", {\n attempts: attempt,\n error,\n reason: decision.reason,\n });\n};\n\n/\n Runs the throw-mode retry loop: throws `RetryError` on exhaustion and\n * `AbortError` when `signal` aborts.\n \n @param policy - Resolved retry policy providing `next` and `onExhausted`.\n * @param execute - Async work callback per attempt.\n * @param sleep - Delay function between retries.\n * @param signal - Optional cancel signal.\n * @param logger - Optional logger; logs each retry decision at `debug` and\n * exhaustion at `warn`.\n * @returns Resolves to the first successful return value.\n * @throws {RetryError} When retries are exhausted and `onExhausted` returns\n * the terminal error.\n * @throws {AbortError} When `signal` is already aborted or aborts while waiting.\n * @throws {Error} Any error thrown by `next`, `onExhausted`, or `sleep`. Also\n * rethrows the original caught value immediately, bypassing retry, when\n * `policy.isKnownError` rejects it as outside this policy's error domain.\n /\nconst runThrowMode = async <T, TError extends Error, TData>(\n policy: ResolvedRetryPolicy<TError, TData>,\n execute: (attempt: number) => Promise<T>,\n sleep: (delayMs: number) => Promise<void>,\n signal?: AbortSignal,\n logger?: Logger\n): Promise<T> => {\n let attempt = 1;\n\n while (true) {\n throwIfAborted(signal, logger);\n\n try {\n // oxlint-disable-next-line no-await-in-loop -- Retry attempts must run sequentially.\n return await execute(attempt);\n } catch (error) {\n throwIfAborted(signal, logger);\n\n if (!policy.isKnownError(error)) {\n throw error;\n }\n\n const decision = policy.next({\n attempt,\n error,\n });\n logRetryDecision(logger, attempt, decision, error);\n\n if (!decision.shouldRetry) {\n throw policy.onExhausted({\n attempts: attempt,\n error,\n });\n }\n\n if (decision.delayMs > 0) {\n // oxlint-disable-next-line no-await-in-loop -- Delay belongs between sequential retry attempts.\n await (signal === undefined\n ? sleep(decision.delayMs)\n : sleepWithAbortSignal(sleep, decision.delayMs, signal));\n }\n\n attempt += 1;\n }\n }\n};\n\n/\n When `signal` is already aborted, builds the terminal `{ ok: false }` object\n * with a normalized `AbortError` on `error`.\n \n @param signal - Optional abort signal; only acts when `aborted` is set.\n * @param attempts - Number of finished attempts to report in the result.\n * @param logger - Optional logger; logs the abort at `debug`.\n * @returns Failure result or `undefined` if not aborted.\n /\nconst buildAbortResult = (\n signal: AbortSignal \| undefined,\n attempts: number,\n logger?: Logger\n): RetryRunResult<never> \| undefined => {\n if (signal?.aborted !== true) {\n return undefined;\n }\n\n logger?.debug(\"retry aborted\", { reason: signal.reason });\n\n return {\n attempts,\n error: toAbortError(signal.reason),\n ok: false,\n };\n};\n\n/\n Runs one `execute(attempt)` call and returns either a success value or a\n * captured error without rethrowing.\n \n @param execute - User work callback.\n * @param attempt - One-based attempt number passed to `execute`.\n * @returns A tagged success with `value` or a tagged failure with `error`.\n /\nconst runAttempt = async <T>(\n execute: (attempt: number) => Promise<T>,\n attempt: number\n): Promise<{ ok: true; value: T } \| { ok: false; error: unknown }> => {\n try {\n return {\n ok: true,\n value: await execute(attempt),\n };\n } catch (error) {\n return {\n error,\n ok: false,\n };\n }\n};\n\n/\n Awaits inter-attempt delay in result mode, mapping an abort during wait to\n * a terminal result instead of throwing when `throwOnExhausted` is false.\n \n @param sleep - Custom or default sleep implementation.\n * @param delayMs - Milliseconds to wait.\n * @param signal - If set, `sleep` is raced with the abort signal.\n * @param attempts - Attempt count to attach if the wait ends in abort.\n * @param logger - Optional logger; logs an abort ending the wait at `debug`.\n * @returns A terminal result when canceled during the wait, otherwise\n * `undefined`.\n * @throws {Error} The underlying `sleep` rejection when it is not an abort.\n /\nconst waitForDelay = async (\n sleep: (delayMs: number) => Promise<void>,\n delayMs: number,\n signal: AbortSignal \| undefined,\n attempts: number,\n logger?: Logger\n): Promise<RetryRunResult<never> \| undefined> => {\n if (signal === undefined) {\n await sleep(delayMs);\n return undefined;\n }\n\n try {\n await sleepWithAbortSignal(sleep, delayMs, signal);\n return undefined;\n } catch (error) {\n const aborted = buildAbortResult(signal, attempts, logger);\n if (aborted !== undefined) {\n return aborted;\n }\n throw error;\n }\n};\n\n/\n After a failed attempt, applies abort rules, `next`, optional delay, and\n * either returns a terminal `RetryRunResult` or `undefined` to continue.\n \n @param policy - Resolved retry policy hooks (`next`, `onExhausted`).\n * @param params - Failure context for the current attempt.\n * @param params.attempt - Current attempt number.\n * @param params.error - Error thrown by the attempt.\n * @param params.sleep - Delay function between retries.\n * @param params.signal - Optional abort signal.\n * @param params.logger - Optional logger; logs each retry decision at\n * `debug`, exhaustion at `warn`, and cancellation at `debug`.\n * @returns Terminal non-throw result if the loop should stop, otherwise\n * `undefined` to schedule another attempt.\n * @throws {Error} Any error thrown by `next`, `onExhausted`, or a custom `sleep` when\n * the error is not an abort.\n /\nconst handleFailure = async <TError extends Error, TData>(\n policy: ResolvedRetryPolicy<TError, TData>,\n params: {\n attempt: number;\n error: TError;\n sleep: (delayMs: number) => Promise<void>;\n signal: AbortSignal \| undefined;\n logger: Logger \| undefined;\n }\n): Promise<RetryRunResult<never> \| undefined> => {\n const { attempt, error, sleep, signal, logger } = params;\n const abortResult = buildAbortResult(signal, attempt, logger);\n if (abortResult !== undefined) {\n return abortResult;\n }\n\n const decision = policy.next({\n attempt,\n error,\n });\n logRetryDecision(logger, attempt, decision, error);\n\n if (!decision.shouldRetry) {\n const terminalError = policy.onExhausted({\n attempts: attempt,\n error,\n });\n\n return {\n attempts: attempt,\n error: terminalError,\n ok: false,\n };\n }\n\n if (decision.delayMs > 0) {\n const delayAbortResult = await waitForDelay(\n sleep,\n decision.delayMs,\n signal,\n attempt,\n logger\n );\n if (delayAbortResult !== undefined) {\n return delayAbortResult;\n }\n }\n\n return undefined;\n};\n\n/\n Runs the non-throw retry loop, returning\n * `RetryRunResult`.\n \n @param policy - Resolved retry policy providing `next` and `onExhausted`.\n * @param execute - Async work callback per attempt.\n * @param sleep - Delay function between retries.\n * @param signal - Optional cancel signal.\n * @param logger - Optional logger; logs each retry decision at `debug`,\n * exhaustion at `warn`, and cancellation at `debug`.\n * @returns Terminal success or failure object. When `policy.isKnownError`\n * rejects a caught value as outside this policy's error domain, the\n * original value is wrapped in a `RetryError` and returned on\n * `result.error` immediately, bypassing retry — never thrown.\n * @throws {Error} Any error thrown by `next`, `onExhausted`, or a non-abort `sleep`\n * failure.\n /\nconst runResultMode = async <T, TError extends Error, TData>(\n policy: ResolvedRetryPolicy<TError, TData>,\n execute: (attempt: number) => Promise<T>,\n sleep: (delayMs: number) => Promise<void>,\n signal?: AbortSignal,\n logger?: Logger\n): Promise<RetryRunResult<T>> => {\n let attempt = 1;\n\n while (true) {\n const abortResult = buildAbortResult(\n signal,\n Math.max(0, attempt - 1),\n logger\n );\n if (abortResult !== undefined) {\n return abortResult;\n }\n\n // oxlint-disable-next-line no-await-in-loop -- Retry attempts must run sequentially.\n const execution = await runAttempt(execute, attempt);\n if (execution.ok) {\n return { ok: true, value: execution.value };\n }\n\n const attemptAbortResult = buildAbortResult(signal, attempt, logger);\n if (attemptAbortResult !== undefined) {\n return attemptAbortResult;\n }\n\n if (!policy.isKnownError(execution.error)) {\n return {\n attempts: attempt,\n error: new RetryError(\"Retry policy encountered an unknown error.\", {\n attempts: attempt,\n lastError: execution.error,\n }),\n ok: false,\n };\n }\n\n // oxlint-disable-next-line no-await-in-loop -- Failure handling belongs to the current sequential attempt.\n const failure = await handleFailure(policy, {\n attempt,\n error: execution.error,\n logger,\n signal,\n sleep,\n });\n if (failure !== undefined) {\n return failure;\n }\n\n attempt += 1;\n }\n};\n\n/\n Default `onExhausted` used when a policy omits it: wraps the exhaustion\n * context in a generic `RetryError`.\n /\nconst defaultOnExhausted = <TError extends Error, TData>(\n input: RetryExhaustedInput<TError, TData>\n): RetryError =>\n new RetryError(\"Retry policy exhausted all attempts.\", {\n attempts: input.attempts,\n lastData: input.data,\n lastError: input.error,\n });\n\n/\n Default `isKnownError` used when a policy omits it: accepts any `Error`\n * instance and rejects everything else.\n /\n// oxlint-disable-next-line typescript/no-unnecessary-type-parameters -- TError only appears in the return predicate; needed so callers infer the right narrowed type.\nconst defaultIsKnownError = <TError extends Error>(\n error: unknown\n): error is TError => error instanceof Error;\n\n/\n Runs retry orchestration in non-throw mode.\n \n @param policy - Retry policy: `next` is required, `onExhausted` and\n * `isKnownError` fall back to their defaults when omitted.\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 * When `policy.isKnownError` rejects a caught value, it is wrapped in a\n * `RetryError` and returned as the terminal failure instead of thrown.\n * @throws {Error} Any error thrown by `next`, `onExhausted`, or a custom `sleep`.\n /\nexport function runRetryPolicy<\n T,\n TError extends Error = Error,\n TData = unknown,\n>(\n policy: RetryPolicy<TError, TData>,\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 policy - Retry policy: `next` is required, `onExhausted` and\n * `isKnownError` fall back to their defaults when omitted.\n * @param execute - Async function to execute per attempt.\n * @param options - Optional runner settings.\n * @returns The successful execution value.\n * @throws {RetryError} When retries are exhausted and `onExhausted` returns the\n * terminal retry error. The default implementation returns `RetryError` with the last\n * execution failure available on `RetryError.lastError`.\n * @throws {AbortError} When `options.signal` is already aborted or aborts while retrying.\n * @throws {Error} Any error thrown by `next`, by `onExhausted`, or by a custom `sleep`\n * function.\n \n @example\n * ```ts\n * import { runRetryPolicy } from \"@zap-studio/retry\";\n * import type { RetryPolicy } from \"@zap-studio/retry\";\n \n const linearBackoff: RetryPolicy = {\n * next: ({ attempt }) =>\n * attempt < 3\n * ? { shouldRetry: true, delayMs: attempt * 100, reason: \"retry\" }\n * : { shouldRetry: false, delayMs: 0, reason: \"max-attempts-reached\" },\n * };\n \n const data = await runRetryPolicy(linearBackoff, async () => fetchFlakyResource());\n * ```\n /\nexport function runRetryPolicy<\n T,\n TError extends Error = Error,\n TData = unknown,\n>(\n policy: RetryPolicy<TError, TData>,\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 policy - Retry policy: `next` is required, `onExhausted` and\n * `isKnownError` fall back to their defaults when omitted.\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 {Error} Any error thrown by `next`, by `onExhausted`, or by a custom `sleep`\n * function. When `throwOnExhausted` is `false`, exhaustion itself is returned\n * as `{ ok: false }` instead of thrown.\n * Cancellation is returned as `{ ok: false, error: AbortError }` in non-throw\n * mode. A value rejected by `policy.isKnownError` is wrapped in a\n * `RetryError` and returned the same way in non-throw mode; in throw mode\n * it is rethrown as-is.\n \n @example\n * const result = await runRetryPolicy(policy, doWork, { throwOnExhausted: false });\n * if (!result.ok) console.error(result.error);\n */\nexport async function runRetryPolicy<\n T,\n TError extends Error = Error,\n TData = unknown,\n>(\n policy: RetryPolicy<TError, TData>,\n execute: (attempt: number) => Promise<T>,\n options: RetryRunOptions = {}\n): Promise<T \| RetryRunResult<T>> {\n const sleep = options.sleep ?? defaultSleep;\n const { signal, logger } = options;\n const resolvedPolicy: ResolvedRetryPolicy<TError, TData> = {\n isKnownError: (error): error is TError =>\n policy.isKnownError\n ? policy.isKnownError(error)\n : defaultIsKnownError(error),\n next: (input) => policy.next(input),\n onExhausted: (input) =>\n policy.onExhausted\n ? policy.onExhausted(input)\n : defaultOnExhausted(input),\n };\n\n if (options.throwOnExhausted === false) {\n return await runResultMode(resolvedPolicy, execute, sleep, signal, logger);\n }\n\n return await runThrowMode(resolvedPolicy, execute, sleep, signal, logger);\n}\n"],"mappings":"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"}

package/dist/exponential-backoff.d.ts CHANGED Viewed

@@ -1,4 +1,5 @@
 import { RetryPolicy } from "./types.js";
+import { JitterMode, JitterOptions } from "./jitter.js";
 //#region src/exponential-backoff.d.ts
 /**
  * Configuration for `exponentialBackoff(...)`.
@@ -8,6 +9,7 @@ import { RetryPolicy } from "./types.js";
  *   maxAttempts: 5,
  *   baseDelayMs: 100,
  *   maxDelayMs: 2_000,
+ *   jitter: "full",
  * };
  */
 interface ExponentialBackoffOptions {
@@ -23,6 +25,11 @@ interface ExponentialBackoffOptions {
    * Hard upper bound in milliseconds for computed exponential delay.
    */
   maxDelayMs: number;
+  /**
+   * Optional jitter applied to the computed delay, after capping at
+   * `maxDelayMs`.
+   */
+  jitter?: JitterMode | JitterOptions;
 }
 /**
  * Creates a retry policy with exponential delay growth up to a max cap.

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

	@@ -1 +1 @@
1	- {"version":3,"file":"exponential-backoff.d.ts","names":[],"sources":["../src/exponential-backoff.ts"],"mappings":"~~;;;;;;;;;;;;UAsBiB~~;;;;EAIf;;;;EAIA;;;;EAIA;;;;;;;;;;;;~~cAaW~~,qBACX,SAAS,8BACR"}
1	+ {"version":3,"file":"exponential-backoff.d.ts","names":[],"sources":["../src/exponential-backoff.ts"],"mappings":";;;;;;;;;;;;;;UAyBiB;;;;EAIf;;;;EAIA;;;;EAIA;;;;;EAKA,SAAS,aAAa;;;;;;;;;;;;cAaX,qBACX,SAAS,8BACR"}

package/dist/exponential-backoff.js CHANGED Viewed

@@ -1,5 +1,11 @@
+import { applyJitter } from "./jitter.js";
 //#region src/exponential-backoff.ts
 /**
+* Exponential backoff retry strategy.
+*
+* @module @zap-studio/retry/exponential-backoff
+*/
+/**
 * Creates a retry policy with exponential delay growth up to a max cap.
 *
 * @example
@@ -10,7 +16,7 @@
 * });
 */
 const exponentialBackoff = (options) => {
-	const { maxAttempts, baseDelayMs, maxDelayMs } = options;
+	const { maxAttempts, baseDelayMs, maxDelayMs, jitter } = options;
 	return {
 	/**
 	* Computes retry decision for the current attempt.
@@ -22,8 +28,9 @@ next(input) {
 			shouldRetry: false
 		};
 		const exponent = Math.max(0, input.attempt - 1);
+		const cappedDelayMs = Math.min(maxDelayMs, baseDelayMs * 2 ** exponent);
 		return {
-			delayMs: Math.min(maxDelayMs, baseDelayMs * 2 ** exponent),
+			delayMs: applyJitter(cappedDelayMs, jitter),
 			reason: "retry",
 			shouldRetry: true
 		};

package/dist/exponential-backoff.js.map CHANGED Viewed

	@@ -1 +1 @@
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 type {\n RetryDecision,\n RetryDecisionInput,\n RetryPolicy,\n} from \"./types.js\";\n\n/\n Configuration for `exponentialBackoff(...)`.\n \n @example\n * const options: ExponentialBackoffOptions = {\n * maxAttempts: 5,\n * baseDelayMs: 100,\n * maxDelayMs: 2_000,\n * };\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 Creates a retry policy with exponential delay growth up to a max cap.\n \n @example\n * const policy = exponentialBackoff({\n * maxAttempts: 5,\n * baseDelayMs: 100,\n * maxDelayMs: 2_000,\n * });\n /\nexport const exponentialBackoff = (\n options: ExponentialBackoffOptions\n): RetryPolicy => {\n const { maxAttempts, baseDelayMs, maxDelayMs } = options;\n\n return {\n /\n Computes retry decision for the current attempt.\n /\n next(input: RetryDecisionInput): RetryDecision {\n if (input.attempt >= maxAttempts) {\n return {\n delayMs: 0,\n reason: \"max-attempts-reached\",\n shouldRetry: false,\n };\n }\n\n const exponent = Math.max(0, input.attempt - 1);\n const ~~delayMs~~ = Math.min(maxDelayMs, baseDelayMs 2 ** exponent);\n\n return { delayMs, reason: \"retry\", shouldRetry: true };\n },\n };\n};\n"],"mappings":"~~;;;;;;;;;;;AA+CA~~,MAAa,sBACX,YACgB;CAChB,MAAM,EAAE,aAAa,aAAa,~~eAAe~~;~~CAEjD~~,OAAO;;;;AAIL,KAAK,OAA0C;EAC7C,IAAI,MAAM,WAAW,aACnB,OAAO;GACL,SAAS;GACT,QAAQ;GACR,aAAa;EACf;EAGF,MAAM,WAAW,KAAK,IAAI,GAAG,MAAM,UAAU,CAAC;~~EAG9C~~,~~OAAO;GAAE~~,~~SAFO~~,KAAK,IAAI,YAAY,cAAc,KAAK,~~QAEzC~~;GAAG,QAAQ;GAAS,aAAa;EAAK;CACvD,EACF;AACF"}
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 { applyJitter } from \"./jitter.js\";\nimport type { JitterMode, JitterOptions } from \"./jitter.js\";\nimport type {\n RetryDecision,\n RetryDecisionInput,\n RetryPolicy,\n} from \"./types.js\";\n\n/\n Configuration for `exponentialBackoff(...)`.\n \n @example\n * const options: ExponentialBackoffOptions = {\n * maxAttempts: 5,\n * baseDelayMs: 100,\n * maxDelayMs: 2_000,\n * jitter: \"full\",\n * };\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 Optional jitter applied to the computed delay, after capping at\n * `maxDelayMs`.\n /\n jitter?: JitterMode \| JitterOptions;\n}\n\n/\n Creates a retry policy with exponential delay growth up to a max cap.\n \n @example\n * const policy = exponentialBackoff({\n * maxAttempts: 5,\n * baseDelayMs: 100,\n * maxDelayMs: 2_000,\n * });\n /\nexport const exponentialBackoff = (\n options: ExponentialBackoffOptions\n): RetryPolicy => {\n const { maxAttempts, baseDelayMs, maxDelayMs, jitter } = options;\n\n return {\n /\n Computes retry decision for the current attempt.\n /\n next(input: RetryDecisionInput): RetryDecision {\n if (input.attempt >= maxAttempts) {\n return {\n delayMs: 0,\n reason: \"max-attempts-reached\",\n shouldRetry: false,\n };\n }\n\n const exponent = Math.max(0, input.attempt - 1);\n const cappedDelayMs = Math.min(maxDelayMs, baseDelayMs 2 ** exponent);\n const delayMs = applyJitter(cappedDelayMs, jitter);\n\n return { delayMs, reason: \"retry\", shouldRetry: true };\n },\n };\n};\n"],"mappings":";;;;;;;;;;;;;;;;;AAuDA,MAAa,sBACX,YACgB;CAChB,MAAM,EAAE,aAAa,aAAa,YAAY,WAAW;CAEzD,OAAO;;;;AAIL,KAAK,OAA0C;EAC7C,IAAI,MAAM,WAAW,aACnB,OAAO;GACL,SAAS;GACT,QAAQ;GACR,aAAa;EACf;EAGF,MAAM,WAAW,KAAK,IAAI,GAAG,MAAM,UAAU,CAAC;EAC9C,MAAM,gBAAgB,KAAK,IAAI,YAAY,cAAc,KAAK,QAAQ;EAGtE,OAAO;GAAE,SAFO,YAAY,eAAe,MAE5B;GAAG,QAAQ;GAAS,aAAa;EAAK;CACvD,EACF;AACF"}

package/dist/index.d.ts CHANGED Viewed

@@ -1,7 +1,8 @@
 import { i as RetryErrorContext, n as AbortErrorContext, r as RetryError, t as AbortError } from "./errors-CS5UPJWs.js";
 import { RetryDecision, RetryDecisionInput, RetryExhaustedInput, RetryPolicy, RetryRunOptions, RetryRunResult } from "./types.js";
 import { defaultSleep, runRetryPolicy } from "./base-policy.js";
+import { JitterMode, JitterOptions, applyJitter } from "./jitter.js";
 import { ExponentialBackoffOptions, exponentialBackoff } from "./exponential-backoff.js";
 import { FixedDelayOptions, fixedDelay } from "./fixed-delay.js";
 import { LinearBackoffOptions, linearBackoff } from "./linear-backoff.js";
-export { AbortError, type AbortErrorContext, type ExponentialBackoffOptions, type FixedDelayOptions, type LinearBackoffOptions, type RetryDecision, type RetryDecisionInput, RetryError, type RetryErrorContext, type RetryExhaustedInput, type RetryPolicy, type RetryRunOptions, type RetryRunResult, defaultSleep, exponentialBackoff, fixedDelay, linearBackoff, runRetryPolicy };
+export { AbortError, type AbortErrorContext, type ExponentialBackoffOptions, type FixedDelayOptions, type JitterMode, type JitterOptions, type LinearBackoffOptions, type RetryDecision, type RetryDecisionInput, RetryError, type RetryErrorContext, type RetryExhaustedInput, type RetryPolicy, type RetryRunOptions, type RetryRunResult, applyJitter, defaultSleep, exponentialBackoff, fixedDelay, linearBackoff, runRetryPolicy };

package/dist/index.js CHANGED Viewed

@@ -1,6 +1,7 @@
 import { AbortError, RetryError } from "./errors.js";
 import { defaultSleep, runRetryPolicy } from "./base-policy.js";
+import { applyJitter } from "./jitter.js";
 import { exponentialBackoff } from "./exponential-backoff.js";
 import { fixedDelay } from "./fixed-delay.js";
 import { linearBackoff } from "./linear-backoff.js";
-export { AbortError, RetryError, defaultSleep, exponentialBackoff, fixedDelay, linearBackoff, runRetryPolicy };
+export { AbortError, RetryError, applyJitter, defaultSleep, exponentialBackoff, fixedDelay, linearBackoff, runRetryPolicy };

package/dist/jitter.d.ts ADDED Viewed

@@ -0,0 +1,48 @@
+//#region src/jitter.d.ts
+/**
+ * Jitter strategies applied to a computed backoff delay.
+ *
+ * @module @zap-studio/retry/jitter
+ */
+/**
+ * Supported jitter strategies.
+ *
+ * - `"full"`: `random(0, delayMs)` — max spread, best thundering-herd
+ *   protection.
+ * - `"equal"`: `delayMs/2 + random(0, delayMs/2)` — keeps a floor at half
+ *   the computed delay, less spread than full jitter.
+ */
+type JitterMode = "equal" | "full";
+/**
+ * Configuration for jitter application.
+ *
+ * @example
+ * const jitter: JitterOptions = { mode: "full" };
+ */
+interface JitterOptions {
+  /**
+   * Jitter strategy to apply.
+   */
+  mode: JitterMode;
+  /**
+   * Random source in `[0, 1)`, overridable for deterministic tests.
+   *
+   * @default Math.random
+   */
+  random?: () => number;
+}
+/**
+ * Applies a jitter strategy to a computed delay.
+ *
+ * @param delayMs - Delay in milliseconds before jitter.
+ * @param jitter - Jitter mode shorthand, full `JitterOptions`, or `undefined`
+ *   to leave `delayMs` untouched.
+ * @returns Jittered delay in milliseconds, rounded to the nearest integer.
+ *
+ * @example
+ * const delayMs = applyJitter(1000, "full"); // 0-1000
+ */
+declare const applyJitter: (delayMs: number, jitter?: JitterMode | JitterOptions) => number;
+//#endregion
+export { JitterMode, JitterOptions, applyJitter };
+//# sourceMappingURL=jitter.d.ts.map

package/dist/jitter.d.ts.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"jitter.d.ts","names":[],"sources":["../src/jitter.ts"],"mappings":";;;;;;;;;;;;;;KAcY;;;;;;;UAQK;;;;EAIf,MAAM;;;;;;EAMN;;;;;;;;;;;;;cAcW,cACX,iBACA,SAAS,aAAa"}

package/dist/jitter.js ADDED Viewed

@@ -0,0 +1,24 @@
+//#region src/jitter.ts
+/**
+* Applies a jitter strategy to a computed delay.
+*
+* @param delayMs - Delay in milliseconds before jitter.
+* @param jitter - Jitter mode shorthand, full `JitterOptions`, or `undefined`
+*   to leave `delayMs` untouched.
+* @returns Jittered delay in milliseconds, rounded to the nearest integer.
+*
+* @example
+* const delayMs = applyJitter(1000, "full"); // 0-1000
+*/
+const applyJitter = (delayMs, jitter) => {
+	if (jitter === void 0) return delayMs;
+	const mode = typeof jitter === "string" ? jitter : jitter.mode;
+	const random = (typeof jitter === "string" ? void 0 : jitter.random) ?? Math.random;
+	if (mode === "full") return Math.round(random() * delayMs);
+	const half = delayMs / 2;
+	return Math.round(half + random() * half);
+};
+//#endregion
+export { applyJitter };
+//# sourceMappingURL=jitter.js.map

package/dist/jitter.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"jitter.js","names":[],"sources":["../src/jitter.ts"],"sourcesContent":["/**\n * Jitter strategies applied to a computed backoff delay.\n *\n * @module @zap-studio/retry/jitter\n */\n\n/**\n * Supported jitter strategies.\n *\n * - `\"full\"`: `random(0, delayMs)` — max spread, best thundering-herd\n * protection.\n * - `\"equal\"`: `delayMs/2 + random(0, delayMs/2)` — keeps a floor at half\n * the computed delay, less spread than full jitter.\n */\nexport type JitterMode = \"equal\" | \"full\";\n\n/**\n * Configuration for jitter application.\n *\n * @example\n * const jitter: JitterOptions = { mode: \"full\" };\n */\nexport interface JitterOptions {\n /**\n * Jitter strategy to apply.\n */\n mode: JitterMode;\n /**\n * Random source in `[0, 1)`, overridable for deterministic tests.\n *\n * @default Math.random\n */\n random?: () => number;\n}\n\n/**\n * Applies a jitter strategy to a computed delay.\n *\n * @param delayMs - Delay in milliseconds before jitter.\n * @param jitter - Jitter mode shorthand, full `JitterOptions`, or `undefined`\n * to leave `delayMs` untouched.\n * @returns Jittered delay in milliseconds, rounded to the nearest integer.\n *\n * @example\n * const delayMs = applyJitter(1000, \"full\"); // 0-1000\n */\nexport const applyJitter = (\n delayMs: number,\n jitter?: JitterMode | JitterOptions\n): number => {\n if (jitter === undefined) {\n return delayMs;\n }\n\n const mode = typeof jitter === \"string\" ? jitter : jitter.mode;\n const random =\n (typeof jitter === \"string\" ? undefined : jitter.random) ?? Math.random;\n\n if (mode === \"full\") {\n return Math.round(random() * delayMs);\n }\n\n const half = delayMs / 2;\n return Math.round(half + random() * half);\n};\n"],"mappings":";;;;;;;;;;;;AA8CA,MAAa,eACX,SACA,WACW;CACX,IAAI,WAAW,KAAA,GACb,OAAO;CAGT,MAAM,OAAO,OAAO,WAAW,WAAW,SAAS,OAAO;CAC1D,MAAM,UACH,OAAO,WAAW,WAAW,KAAA,IAAY,OAAO,WAAW,KAAK;CAEnE,IAAI,SAAS,QACX,OAAO,KAAK,MAAM,OAAO,IAAI,OAAO;CAGtC,MAAM,OAAO,UAAU;CACvB,OAAO,KAAK,MAAM,OAAO,OAAO,IAAI,IAAI;AAC1C"}

package/dist/linear-backoff.d.ts CHANGED Viewed

@@ -1,4 +1,5 @@
 import { RetryPolicy } from "./types.js";
+import { JitterMode, JitterOptions } from "./jitter.js";
 //#region src/linear-backoff.d.ts
 /**
  * Configuration for `linearBackoff(...)`.
@@ -9,6 +10,7 @@ import { RetryPolicy } from "./types.js";
  *   baseDelayMs: 100,
  *   incrementMs: 100,
  *   maxDelayMs: 2_000,
+ *   jitter: "equal",
  * };
  */
 interface LinearBackoffOptions {
@@ -28,6 +30,11 @@ interface LinearBackoffOptions {
    * Hard upper bound in milliseconds for computed linear delay.
    */
   maxDelayMs: number;
+  /**
+   * Optional jitter applied to the computed delay, after capping at
+   * `maxDelayMs`.
+   */
+  jitter?: JitterMode | JitterOptions;
 }
 /**
  * Creates a retry policy with linear delay growth up to a max cap.

package/dist/linear-backoff.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"linear-backoff.d.ts","names":[],"sources":["../src/linear-backoff.ts"],"mappings":"~~;;;;;;;;;;;;;UAuBiB~~;;;;EAIf;;;;EAIA;;;;EAIA;;;;EAIA;;;;;;;;;;;;;~~cAcW~~,gBAAiB,SAAS,yBAAuB"}
1	+ {"version":3,"file":"linear-backoff.d.ts","names":[],"sources":["../src/linear-backoff.ts"],"mappings":";;;;;;;;;;;;;;;UA0BiB;;;;EAIf;;;;EAIA;;;;EAIA;;;;EAIA;;;;;EAKA,SAAS,aAAa;;;;;;;;;;;;;cAcX,gBAAiB,SAAS,yBAAuB"}

package/dist/linear-backoff.js CHANGED Viewed

@@ -1,5 +1,11 @@
+import { applyJitter } from "./jitter.js";
 //#region src/linear-backoff.ts
 /**
+* Linear backoff retry strategy.
+*
+* @module @zap-studio/retry/linear-backoff
+*/
+/**
 * Creates a retry policy with linear delay growth up to a max cap.
 *
 * @example
@@ -11,7 +17,7 @@
 * });
 */
 const linearBackoff = (options) => {
-	const { maxAttempts, baseDelayMs, incrementMs, maxDelayMs } = options;
+	const { maxAttempts, baseDelayMs, incrementMs, maxDelayMs, jitter } = options;
 	return {
 	/**
 	* Computes retry decision for the current attempt.
@@ -22,8 +28,9 @@ next(input) {
 			reason: "max-attempts-reached",
 			shouldRetry: false
 		};
+		const cappedDelayMs = Math.min(maxDelayMs, baseDelayMs + incrementMs * (input.attempt - 1));
 		return {
-			delayMs: Math.min(maxDelayMs, baseDelayMs + incrementMs * (input.attempt - 1)),
+			delayMs: applyJitter(cappedDelayMs, jitter),
 			reason: "retry",
 			shouldRetry: true
 		};

package/dist/linear-backoff.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"linear-backoff.js","names":[],"sources":["../src/linear-backoff.ts"],"sourcesContent":["/*\n Linear backoff retry strategy.\n \n @module @zap-studio/retry/linear-backoff\n /\n\nimport type {\n RetryDecision,\n RetryDecisionInput,\n RetryPolicy,\n} from \"./types.js\";\n\n/\n Configuration for `linearBackoff(...)`.\n \n @example\n * const options: LinearBackoffOptions = {\n * maxAttempts: 5,\n * baseDelayMs: 100,\n * incrementMs: 100,\n * maxDelayMs: 2_000,\n * };\n /\nexport interface LinearBackoffOptions {\n /\n Maximum number of attempts (including the first) before giving up.\n /\n maxAttempts: number;\n /\n Delay in milliseconds after the first failed attempt.\n /\n baseDelayMs: number;\n /\n Amount added to the delay for each subsequent retry.\n /\n incrementMs: number;\n /\n Hard upper bound in milliseconds for computed linear delay.\n /\n maxDelayMs: number;\n}\n\n/\n Creates a retry policy with linear delay growth up to a max cap.\n \n @example\n * const policy = linearBackoff({\n * maxAttempts: 5,\n * baseDelayMs: 100,\n * incrementMs: 100,\n * maxDelayMs: 2_000,\n * });\n /\nexport const linearBackoff = (options: LinearBackoffOptions): RetryPolicy => {\n const { maxAttempts, baseDelayMs, incrementMs, maxDelayMs } = options;\n\n return {\n /\n Computes retry decision for the current attempt.\n /\n next(input: RetryDecisionInput): RetryDecision {\n if (input.attempt >= maxAttempts) {\n return {\n delayMs: 0,\n reason: \"max-attempts-reached\",\n shouldRetry: false,\n };\n }\n\n const ~~delayMs~~ = Math.min(\n maxDelayMs,\n baseDelayMs + incrementMs (input.attempt - 1)\n );\n\n return { delayMs, reason: \"retry\", shouldRetry: true };\n },\n };\n};\n"],"mappings":"~~;;;;;;;;;;;;AAqDA~~,MAAa,iBAAiB,YAA+C;CAC3E,MAAM,EAAE,aAAa,aAAa,aAAa,~~eAAe~~;~~CAE9D~~,OAAO;;;;AAIL,KAAK,OAA0C;EAC7C,IAAI,MAAM,WAAW,aACnB,OAAO;GACL,SAAS;GACT,QAAQ;GACR,aAAa;EACf;~~EAQF~~,~~OAAO;GAAE~~,~~SALO~~,KAAK,~~IACnB~~,YACA,cAAc,eAAe,MAAM,UAAU,~~EAGhC~~;GAAG,QAAQ;GAAS,aAAa;EAAK;CACvD,EACF;AACF"}
1	+ {"version":3,"file":"linear-backoff.js","names":[],"sources":["../src/linear-backoff.ts"],"sourcesContent":["/*\n Linear backoff retry strategy.\n \n @module @zap-studio/retry/linear-backoff\n /\n\nimport { applyJitter } from \"./jitter.js\";\nimport type { JitterMode, JitterOptions } from \"./jitter.js\";\nimport type {\n RetryDecision,\n RetryDecisionInput,\n RetryPolicy,\n} from \"./types.js\";\n\n/\n Configuration for `linearBackoff(...)`.\n \n @example\n * const options: LinearBackoffOptions = {\n * maxAttempts: 5,\n * baseDelayMs: 100,\n * incrementMs: 100,\n * maxDelayMs: 2_000,\n * jitter: \"equal\",\n * };\n /\nexport interface LinearBackoffOptions {\n /\n Maximum number of attempts (including the first) before giving up.\n /\n maxAttempts: number;\n /\n Delay in milliseconds after the first failed attempt.\n /\n baseDelayMs: number;\n /\n Amount added to the delay for each subsequent retry.\n /\n incrementMs: number;\n /\n Hard upper bound in milliseconds for computed linear delay.\n /\n maxDelayMs: number;\n /\n Optional jitter applied to the computed delay, after capping at\n * `maxDelayMs`.\n /\n jitter?: JitterMode \| JitterOptions;\n}\n\n/\n Creates a retry policy with linear delay growth up to a max cap.\n \n @example\n * const policy = linearBackoff({\n * maxAttempts: 5,\n * baseDelayMs: 100,\n * incrementMs: 100,\n * maxDelayMs: 2_000,\n * });\n /\nexport const linearBackoff = (options: LinearBackoffOptions): RetryPolicy => {\n const { maxAttempts, baseDelayMs, incrementMs, maxDelayMs, jitter } = options;\n\n return {\n /\n Computes retry decision for the current attempt.\n /\n next(input: RetryDecisionInput): RetryDecision {\n if (input.attempt >= maxAttempts) {\n return {\n delayMs: 0,\n reason: \"max-attempts-reached\",\n shouldRetry: false,\n };\n }\n\n const cappedDelayMs = Math.min(\n maxDelayMs,\n baseDelayMs + incrementMs (input.attempt - 1)\n );\n const delayMs = applyJitter(cappedDelayMs, jitter);\n\n return { delayMs, reason: \"retry\", shouldRetry: true };\n },\n };\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AA6DA,MAAa,iBAAiB,YAA+C;CAC3E,MAAM,EAAE,aAAa,aAAa,aAAa,YAAY,WAAW;CAEtE,OAAO;;;;AAIL,KAAK,OAA0C;EAC7C,IAAI,MAAM,WAAW,aACnB,OAAO;GACL,SAAS;GACT,QAAQ;GACR,aAAa;EACf;EAGF,MAAM,gBAAgB,KAAK,IACzB,YACA,cAAc,eAAe,MAAM,UAAU,EAC/C;EAGA,OAAO;GAAE,SAFO,YAAY,eAAe,MAE5B;GAAG,QAAQ;GAAS,aAAa;EAAK;CACvD,EACF;AACF"}

package/dist/types.d.ts CHANGED Viewed

@@ -1,4 +1,5 @@
 import { r as RetryError, t as AbortError } from "./errors-CS5UPJWs.js";
+import { Logger } from "@zap-studio/logger";
 //#region src/types.d.ts
 /**
  * Retry policy contract consumed by `runRetryPolicy(...)`.
@@ -47,8 +48,19 @@ interface RetryPolicy<TError extends Error = Error, TData = unknown> {
  * functions, used internally once `runRetryPolicy` has applied defaults.
  */
 interface ResolvedRetryPolicy<TError extends Error, TData> {
+  /**
+   * Returns the retry decision for a failed attempt.
+   */
   next: RetryPolicy<TError, TData>["next"];
+  /**
+   * Builds the terminal error used when retries are exhausted. Always
+   * present here, unlike on `RetryPolicy` where it's optional.
+   */
   onExhausted: (input: RetryExhaustedInput<TError, TData>) => RetryError;
+  /**
+   * Narrows a caught `unknown` value into `TError`. Always present here,
+   * unlike on `RetryPolicy` where it's optional.
+   */
   isKnownError: (error: unknown) => error is TError;
 }
 /**
@@ -146,6 +158,13 @@ interface RetryRunOptions {
    * @default true
    */
   readonly throwOnExhausted?: boolean;
+  /**
+   * Optional logger for retry internals. When omitted, nothing is logged.
+   *
+   * Logs each retry decision at `debug`, exhaustion at `warn`, and
+   * cancellation at `debug`.
+   */
+  readonly logger?: Logger;
 }
 /**
  * Result union returned by non-throw runner mode.

package/dist/types.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"mappings":"~~;;;;;;;;;;;;;;;UAqBiB~~,YAAY,eAAe,QAAQ,OAAO;;;;;;EAMzD,OAAO,OAAO,mBAAmB,QAAQ,WAAW;;;;;;;;EAQpD,eAAe,OAAO,oBAAoB,QAAQ,WAAW;;;;;;;;;;;;;EAa7D,gBAAgB,mBAAmB,SAAS;;;;;;UAO7B,oBAAoB,eAAe,OAAO~~;EACzD~~,MAAM,YAAY,QAAQ~~;EAC1B~~,cAAc,OAAO,oBAAoB,QAAQ,WAAW~~;EAC5D~~,eAAe,mBAAmB,SAAS;;;;;;;;UAS5B;;;;;WAKN;;;;WAIA;;;;WAIA;;;;;;;;UASM,mBACf,eAAe,QAAQ,OACvB;;;;WAKS;;;;;WAKA;;;;;WAKA,QAAQ;;;;;WAKR,OAAO;;;;;;;;UASD,oBACf,eAAe,QAAQ,OACvB;;;;WAKS;;;;WAIA,QAAQ;;;;WAIR,OAAO;;;;;;;;UASD;;;;;;WAMN,SAAS,oBAAoB;;;;;;WAM7B,SAAS;;;;;;;;WAQT;;;;;;;;;;;;;~~KAcC~~,eAAe;;;;EAKrB;;;;EAIA,OAAO;;;;;EAMP;;;;;EAKA,OAAO,aAAa;;;;EAIpB"}
1	+ {"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";;;;;;;;;;;;;;;;UAuBiB,YAAY,eAAe,QAAQ,OAAO;;;;;;EAMzD,OAAO,OAAO,mBAAmB,QAAQ,WAAW;;;;;;;;EAQpD,eAAe,OAAO,oBAAoB,QAAQ,WAAW;;;;;;;;;;;;;EAa7D,gBAAgB,mBAAmB,SAAS;;;;;;UAO7B,oBAAoB,eAAe,OAAO;;;;EAIzD,MAAM,YAAY,QAAQ;;;;;EAK1B,cAAc,OAAO,oBAAoB,QAAQ,WAAW;;;;;EAK5D,eAAe,mBAAmB,SAAS;;;;;;;;UAS5B;;;;;WAKN;;;;WAIA;;;;WAIA;;;;;;;;UASM,mBACf,eAAe,QAAQ,OACvB;;;;WAKS;;;;;WAKA;;;;;WAKA,QAAQ;;;;;WAKR,OAAO;;;;;;;;UASD,oBACf,eAAe,QAAQ,OACvB;;;;WAKS;;;;WAIA,QAAQ;;;;WAIR,OAAO;;;;;;;;UASD;;;;;;WAMN,SAAS,oBAAoB;;;;;;WAM7B,SAAS;;;;;;;;WAQT;;;;;;;WAOA,SAAS;;;;;;;;;;;;;KAcR,eAAe;;;;EAKrB;;;;EAIA,OAAO;;;;;EAMP;;;;;EAKA,OAAO,aAAa;;;;EAIpB"}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@zap-studio/retry",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "private": false,
   "description": "Composable, tree-shakeable retry policies for resilient async operations.",
   "keywords": [
@@ -35,6 +35,7 @@
     "./errors": "./dist/errors.js",
     "./exponential-backoff": "./dist/exponential-backoff.js",
     "./fixed-delay": "./dist/fixed-delay.js",
+    "./jitter": "./dist/jitter.js",
     "./linear-backoff": "./dist/linear-backoff.js",
     "./types": "./dist/types.js",
     "./package.json": "./package.json"
@@ -42,6 +43,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@zap-studio/logger": "1.0.0"
+  },
   "devDependencies": {
     "tsdown": "^0.22.14",
     "typescript": "^7.0.2",