@zap-studio/retry 1.2.0 → 2.0.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@ 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).
 
+## [2.0.0]
+
+### Added
+
+Native OpenTelemetry support. Unlike `fetch`, `webhooks`, and `permit`, this package never creates its own span — a retry loop wraps someone else's operation, so each decision is recorded as an event (`retry.scheduled`/`retry.exhausted`) on whatever span is already active, plus a `retry.attempts` counter tagged by outcome. See [OpenTelemetry](https://www.zapstudio.dev/retry/opentelemetry).
+
+### Changed
+
+**Breaking:** `@opentelemetry/api` is now a required peer dependency. It's tiny, side-effect-free, and a no-op until an app registers a real SDK, so nothing changes at runtime for consumers who don't set one up — but the package won't resolve without it installed: `npm install @opentelemetry/api`.
+
+## [1.2.1]
+
+### Changed
+
+`@zap-studio/logger` is now an optional peer dependency instead of a regular dependency. Every import from it is type-only (`import type { Logger }`), so it was never pulled in at runtime — pass any object matching the `Logger` shape (including `pino`) with no install required. Existing consumers of `logger?: Logger` are unaffected.
+
 ## [1.2.0]
 
 ### Added

package/README.md

@@ -4,6 +4,16 @@ Composable retry policy primitives for HTTP clients and async workflows.
 
 Full documentation: [zapstudio.dev/retry](https://www.zapstudio.dev/retry)
 
+## Motivation
+
+A hand-written retry loop is usually a `for` loop with `setTimeout`, and it is easy to get wrong in ways that only show up under load. Without jitter, every client that lost connection to a service retries at the exact same moment once it comes back, causing a new spike right when the service is trying to recover.
+
+Without cancellation, a retry loop can keep running — and keep hitting the network — after the result is no longer needed, for example after a user navigates away.
+
+`@zap-studio/retry` gives you this behavior as a built-in option, instead of something you write from scratch. `exponentialBackoff` and `linearBackoff` support jitter (`"full"` or `"equal"`, the same strategies AWS recommends) through the `jitter` option — turn it on and delays are randomized instead of fixed.
+
+Every retry loop also accepts an `AbortSignal`, checked before each attempt and while waiting between attempts, so an abort stops the next attempt or delay from starting; it does not interrupt an attempt that is already running. You get retry policies as values you configure once and reuse, instead of logic you have to get right from scratch in every project.
+
 ## Installation
 
 ```bash
@@ -185,6 +195,28 @@ await runRetryPolicy(policy, execute, { logger });
 
 Each retry decision logs at `debug` (attempt, delay, reason), exhaustion logs at `warn`, and cancellation logs at `debug`.
 
+## OpenTelemetry
+
+`@opentelemetry/api` is a required peer dependency — tiny, side-effect-free, and a no-op until an app registers a real SDK, so installing it costs nothing at runtime for consumers who never set one up.
+
+Unlike `fetch`, `webhooks`, and `permit`, this package never creates its own span — a retry loop wraps someone else's operation, so each decision is recorded as an **event** on whatever span is already active (e.g. a caller's `fetch` span), plus a `retry.attempts` counter tagged by outcome:
+
+```bash
+npm install @opentelemetry/api
+```
+
+```ts
+import { exponentialBackoff, runRetryPolicy } from "@zap-studio/retry";
+
+const policy = exponentialBackoff({ maxAttempts: 5, baseDelayMs: 100 });
+
+// If a span is active when this runs (e.g. inside a caller's own span, or
+// nested inside a @zap-studio/fetch call), each retry adds a
+// "retry.scheduled" or "retry.exhausted" event to it. If not, it's a no-op
+// — no wiring required either way.
+await runRetryPolicy(policy, execute);
+```
+
 ## Runtime Support
 
 | Runtime            | Minimum version                         |

package/dist/base-policy-CiDqMVSD.js

@@ -0,0 +1,381 @@
+import { AbortError, RetryError } from "./errors.js";
+import { metrics, trace } from "@opentelemetry/api";
+//#region package.json
+var name = "@zap-studio/retry";
+var version = "2.0.0";
+//#endregion
+//#region src/_otel.ts
+/**
+* Internal OpenTelemetry wiring for the retry package: the attempts counter.
+* Kept out of `base-policy.ts` so retry orchestration doesn't get tangled
+* with metrics concerns. Span events are added directly to whatever span is
+* already active (e.g. a caller's fetch span), so this package never
+* creates its own tracer.
+*
+* @module @zap-studio/retry/otel
+*/
+/**
+* Records one retry decision, tagged with `retry.decision: "retry" |
+* "exhausted"`.
+*
+* Resolves the meter and counter fresh on every call instead of caching
+* them at module scope: unlike `trace.getTracer()`, `metrics.getMeter()`
+* has no proxy indirection — a reference grabbed before an app registers
+* its `MeterProvider` (the common case, since ESM imports resolve before
+* the importing module's own SDK-bootstrap code runs) would stay a no-op
+* forever. Repeated `createCounter` calls with the same name are cheap and
+* idempotent, so this costs nothing meaningful.
+*/
+const recordRetryAttempt = (decision) => {
+	metrics.getMeter(name, version).createCounter("retry.attempts", { description: "Number of retry decisions made, tagged by outcome." }).add(1, { "retry.decision": decision });
+};
+//#endregion
+//#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.
+* @returns Promise that resolves when the delay completes.
+*
+* @example
+* ```ts
+* import { defaultSleep } from "@zap-studio/retry";
+*
+* await defaultSleep(250); // waits 250ms
+* ```
+*/
+const defaultSleep = async (delayMs) => {
+	if (delayMs <= 0) return;
+	await new Promise((resolve) => {
+		setTimeout(resolve, delayMs);
+	});
+};
+/**
+* Normalizes an abort `reason` into an `AbortError`.
+*/
+const toAbortError = (reason) => {
+	if (reason instanceof AbortError) return reason;
+	if (reason instanceof Error) return new AbortError(reason.message, { cause: reason });
+	if (typeof reason === "string" && reason.length > 0) return new AbortError(reason);
+	if (reason === void 0) return new AbortError("Retry aborted.");
+	try {
+		return new AbortError(`Retry aborted: ${JSON.stringify(reason)}`);
+	} catch {
+		return new AbortError("Retry aborted.");
+	}
+};
+/**
+* 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, logger) => {
+	if (signal?.aborted !== true) return;
+	logger?.debug("retry aborted", { reason: signal.reason });
+	throw toAbortError(signal.reason);
+};
+/**
+* Waits for delay sleep while observing cancellation through an abort signal.
+*
+* @param sleep - Sleep function used to await `delayMs`.
+* @param delayMs - Delay duration in milliseconds.
+* @param signal - Abort signal to observe while waiting.
+* @returns Promise that resolves when delay finishes.
+* @throws {AbortError} When the signal aborts before or during wait.
+*/
+const sleepWithAbortSignal = async (sleep, delayMs, signal) => {
+	if (signal.aborted) throw toAbortError(signal.reason);
+	let onAbort;
+	try {
+		await Promise.race([sleep(delayMs), new Promise((_resolve, reject) => {
+			onAbort = () => {
+				reject(toAbortError(signal.reason));
+			};
+			signal.addEventListener("abort", onAbort, { once: true });
+		})]);
+	} finally {
+		if (onAbort) signal.removeEventListener("abort", onAbort);
+	}
+};
+/**
+* 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
+		});
+		trace.getActiveSpan()?.addEvent("retry.scheduled", {
+			attempt,
+			"retry.delay_ms": decision.delayMs,
+			"retry.reason": decision.reason ?? ""
+		});
+		recordRetryAttempt("retry");
+		return;
+	}
+	logger?.warn("retry policy exhausted", {
+		attempts: attempt,
+		error,
+		reason: decision.reason
+	});
+	trace.getActiveSpan()?.addEvent("retry.exhausted", {
+		attempt,
+		"retry.reason": decision.reason ?? ""
+	});
+	recordRetryAttempt("exhausted");
+};
+/**
+* Runs the throw-mode retry loop: throws `RetryError` on exhaustion and
+* `AbortError` when `signal` aborts.
+*
+* @param policy - Resolved retry policy providing `next` and `onExhausted`.
+* @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.
+* @throws {AbortError} When `signal` is already aborted or aborts while waiting.
+* @throws {Error} Any error thrown by `next`, `onExhausted`, or `sleep`. Also
+*   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, logger) => {
+	let attempt = 1;
+	while (true) {
+		throwIfAborted(signal, logger);
+		try {
+			return await execute(attempt);
+		} catch (error) {
+			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
+			});
+			if (decision.delayMs > 0) await (signal === void 0 ? sleep(decision.delayMs) : sleepWithAbortSignal(sleep, decision.delayMs, signal));
+			attempt += 1;
+		}
+	}
+};
+/**
+* When `signal` is already aborted, builds the terminal `{ ok: false }` object
+* with a normalized `AbortError` on `error`.
+*
+* @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, logger) => {
+	if (signal?.aborted !== true) return;
+	logger?.debug("retry aborted", { reason: signal.reason });
+	return {
+		attempts,
+		error: toAbortError(signal.reason),
+		ok: false
+	};
+};
+/**
+* Runs one `execute(attempt)` call and returns either a success value or a
+* captured error without rethrowing.
+*
+* @param execute - User work callback.
+* @param attempt - One-based attempt number passed to `execute`.
+* @returns A tagged success with `value` or a tagged failure with `error`.
+*/
+const runAttempt = async (execute, attempt) => {
+	try {
+		return {
+			ok: true,
+			value: await execute(attempt)
+		};
+	} catch (error) {
+		return {
+			error,
+			ok: false
+		};
+	}
+};
+/**
+* Awaits inter-attempt delay in result mode, mapping an abort during wait to
+* a terminal result instead of throwing when `throwOnExhausted` is false.
+*
+* @param sleep - Custom or default sleep implementation.
+* @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, logger) => {
+	if (signal === void 0) {
+		await sleep(delayMs);
+		return;
+	}
+	try {
+		await sleepWithAbortSignal(sleep, delayMs, signal);
+		return;
+	} catch (error) {
+		const aborted = buildAbortResult(signal, attempts, logger);
+		if (aborted !== void 0) return aborted;
+		throw error;
+	}
+};
+/**
+* After a failed attempt, applies abort rules, `next`, optional delay, and
+* either returns a terminal `RetryRunResult` or `undefined` to continue.
+*
+* @param policy - Resolved retry policy hooks (`next`, `onExhausted`).
+* @param params - Failure context for the current attempt.
+* @param params.attempt - Current attempt number.
+* @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, 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({
+			attempts: attempt,
+			error
+		}),
+		ok: false
+	};
+	if (decision.delayMs > 0) {
+		const delayAbortResult = await waitForDelay(sleep, decision.delayMs, signal, attempt, logger);
+		if (delayAbortResult !== void 0) return delayAbortResult;
+	}
+};
+/**
+* Runs the non-throw retry loop, returning
+* `RetryRunResult`.
+*
+* @param policy - Resolved retry policy providing `next` and `onExhausted`.
+* @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
+*   `result.error` immediately, bypassing retry — never thrown.
+* @throws {Error} Any error thrown by `next`, `onExhausted`, or a non-abort `sleep`
+*   failure.
+*/
+const runResultMode = async (policy, execute, sleep, signal, logger) => {
+	let attempt = 1;
+	while (true) {
+		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, logger);
+		if (attemptAbortResult !== void 0) return attemptAbortResult;
+		if (!policy.isKnownError(execution.error)) return {
+			attempts: attempt,
+			error: new RetryError("Retry policy encountered an unknown error.", {
+				attempts: attempt,
+				lastError: execution.error
+			}),
+			ok: false
+		};
+		const failure = await handleFailure(policy, {
+			attempt,
+			error: execution.error,
+			logger,
+			signal,
+			sleep
+		});
+		if (failure !== void 0) return failure;
+		attempt += 1;
+	}
+};
+/**
+* Default `onExhausted` used when a policy omits it: wraps the exhaustion
+* context in a generic `RetryError`.
+*/
+const defaultOnExhausted = (input) => new RetryError("Retry policy exhausted all attempts.", {
+	attempts: input.attempts,
+	lastData: input.data,
+	lastError: input.error
+});
+/**
+* Default `isKnownError` used when a policy omits it: accepts any `Error`
+* instance and rejects everything else.
+*/
+const defaultIsKnownError = (error) => error instanceof Error;
+/**
+* Runs retry orchestration in non-throw mode.
+*
+* When `throwOnExhausted` is `false`, returns a discriminated result union.
+*
+* @param policy - Retry policy: `next` is required, `onExhausted` and
+*   `isKnownError` fall back to their defaults when omitted.
+* @param execute - Async function to execute per attempt.
+* @param options - Runner settings.
+* @returns Success value or terminal result object based on option mode.
+* @throws {Error} 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.
+*   Cancellation is returned as `{ ok: false, error: AbortError }` in non-throw
+*   mode. A value rejected by `policy.isKnownError` is wrapped in a
+*   `RetryError` and returned the same way in non-throw mode; in throw mode
+*   it is rethrown as-is.
+*
+* @example
+* const result = await runRetryPolicy(policy, doWork, { throwOnExhausted: false });
+* if (!result.ok) console.error(result.error);
+*/
+async function runRetryPolicy(policy, execute, options = {}) {
+	const sleep = options.sleep ?? defaultSleep;
+	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, logger);
+	return await runThrowMode(resolvedPolicy, execute, sleep, signal, logger);
+}
+//#endregion
+export { runRetryPolicy as n, defaultSleep as t };
+
+//# sourceMappingURL=base-policy-CiDqMVSD.js.map

package/dist/base-policy-CiDqMVSD.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-policy-CiDqMVSD.js","names":["pkg.name","pkg.version"],"sources":["../package.json","../src/_otel.ts","../src/base-policy.ts"],"sourcesContent":["","/**\n * Internal OpenTelemetry wiring for the retry package: the attempts counter.\n * Kept out of `base-policy.ts` so retry orchestration doesn't get tangled\n * with metrics concerns. Span events are added directly to whatever span is\n * already active (e.g. a caller's fetch span), so this package never\n * creates its own tracer.\n *\n * @module @zap-studio/retry/otel\n */\n\nimport { metrics } from \"@opentelemetry/api\";\n\nimport pkg from \"../package.json\" with { type: \"json\" };\n\n/**\n * Records one retry decision, tagged with `retry.decision: \"retry\" |\n * \"exhausted\"`.\n *\n * Resolves the meter and counter fresh on every call instead of caching\n * them at module scope: unlike `trace.getTracer()`, `metrics.getMeter()`\n * has no proxy indirection — a reference grabbed before an app registers\n * its `MeterProvider` (the common case, since ESM imports resolve before\n * the importing module's own SDK-bootstrap code runs) would stay a no-op\n * forever. Repeated `createCounter` calls with the same name are cheap and\n * idempotent, so this costs nothing meaningful.\n */\nexport const recordRetryAttempt = (decision: \"exhausted\" | \"retry\"): void => {\n  metrics\n    .getMeter(pkg.name, pkg.version)\n    .createCounter(\"retry.attempts\", {\n      description: \"Number of retry decisions made, tagged by outcome.\",\n    })\n    .add(1, { \"retry.decision\": decision });\n};\n","/**\n * Retry runner base class and shared orchestration implementation.\n *\n * @module @zap-studio/retry/base-policy\n */\n\nimport { trace } from \"@opentelemetry/api\";\nimport type { Logger } from \"@zap-studio/logger\";\n\nimport { recordRetryAttempt } from \"./_otel.js\";\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    trace.getActiveSpan()?.addEvent(\"retry.scheduled\", {\n      attempt,\n      \"retry.delay_ms\": decision.delayMs,\n      \"retry.reason\": decision.reason ?? \"\",\n    });\n    recordRetryAttempt(\"retry\");\n    return;\n  }\n\n  logger?.warn(\"retry policy exhausted\", {\n    attempts: attempt,\n    error,\n    reason: decision.reason,\n  });\n  trace.getActiveSpan()?.addEvent(\"retry.exhausted\", {\n    attempt,\n    \"retry.reason\": decision.reason ?? \"\",\n  });\n  recordRetryAttempt(\"exhausted\");\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/base-policy.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"base-policy.d.ts","names":[],"sources":["../src/base-policy.ts"],"mappings":";;;;;;;;;;;;;;;cAiCa,eAAsB,oBAAkB;;;;;;;;;;;;;iBA4crC,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

@@ -1,334 +1,3 @@
-import { AbortError, RetryError } from "./errors.js";
-//#region src/base-policy.ts
-/**
-* Awaits a timer-based delay, unless `delayMs` is non-positive.
-*
-* @param delayMs - Milliseconds to wait before resolving.
-* @returns Promise that resolves when the delay completes.
-*
-* @example
-* ```ts
-* import { defaultSleep } from "@zap-studio/retry";
-*
-* await defaultSleep(250); // waits 250ms
-* ```
-*/
-const defaultSleep = async (delayMs) => {
-	if (delayMs <= 0) return;
-	await new Promise((resolve) => {
-		setTimeout(resolve, delayMs);
-	});
-};
-/**
-* Normalizes an abort `reason` into an `AbortError`.
-*/
-const toAbortError = (reason) => {
-	if (reason instanceof AbortError) return reason;
-	if (reason instanceof Error) return new AbortError(reason.message, { cause: reason });
-	if (typeof reason === "string" && reason.length > 0) return new AbortError(reason);
-	if (reason === void 0) return new AbortError("Retry aborted.");
-	try {
-		return new AbortError(`Retry aborted: ${JSON.stringify(reason)}`);
-	} catch {
-		return new AbortError("Retry aborted.");
-	}
-};
-/**
-* 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, logger) => {
-	if (signal?.aborted !== true) return;
-	logger?.debug("retry aborted", { reason: signal.reason });
-	throw toAbortError(signal.reason);
-};
-/**
-* Waits for delay sleep while observing cancellation through an abort signal.
-*
-* @param sleep - Sleep function used to await `delayMs`.
-* @param delayMs - Delay duration in milliseconds.
-* @param signal - Abort signal to observe while waiting.
-* @returns Promise that resolves when delay finishes.
-* @throws {AbortError} When the signal aborts before or during wait.
-*/
-const sleepWithAbortSignal = async (sleep, delayMs, signal) => {
-	if (signal.aborted) throw toAbortError(signal.reason);
-	let onAbort;
-	try {
-		await Promise.race([sleep(delayMs), new Promise((_resolve, reject) => {
-			onAbort = () => {
-				reject(toAbortError(signal.reason));
-			};
-			signal.addEventListener("abort", onAbort, { once: true });
-		})]);
-	} finally {
-		if (onAbort) signal.removeEventListener("abort", onAbort);
-	}
-};
-/**
-* 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.
-*
-* @param policy - Resolved retry policy providing `next` and `onExhausted`.
-* @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.
-* @throws {AbortError} When `signal` is already aborted or aborts while waiting.
-* @throws {Error} Any error thrown by `next`, `onExhausted`, or `sleep`. Also
-*   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, logger) => {
-	let attempt = 1;
-	while (true) {
-		throwIfAborted(signal, logger);
-		try {
-			return await execute(attempt);
-		} catch (error) {
-			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
-			});
-			if (decision.delayMs > 0) await (signal === void 0 ? sleep(decision.delayMs) : sleepWithAbortSignal(sleep, decision.delayMs, signal));
-			attempt += 1;
-		}
-	}
-};
-/**
-* When `signal` is already aborted, builds the terminal `{ ok: false }` object
-* with a normalized `AbortError` on `error`.
-*
-* @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, logger) => {
-	if (signal?.aborted !== true) return;
-	logger?.debug("retry aborted", { reason: signal.reason });
-	return {
-		attempts,
-		error: toAbortError(signal.reason),
-		ok: false
-	};
-};
-/**
-* Runs one `execute(attempt)` call and returns either a success value or a
-* captured error without rethrowing.
-*
-* @param execute - User work callback.
-* @param attempt - One-based attempt number passed to `execute`.
-* @returns A tagged success with `value` or a tagged failure with `error`.
-*/
-const runAttempt = async (execute, attempt) => {
-	try {
-		return {
-			ok: true,
-			value: await execute(attempt)
-		};
-	} catch (error) {
-		return {
-			error,
-			ok: false
-		};
-	}
-};
-/**
-* Awaits inter-attempt delay in result mode, mapping an abort during wait to
-* a terminal result instead of throwing when `throwOnExhausted` is false.
-*
-* @param sleep - Custom or default sleep implementation.
-* @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, logger) => {
-	if (signal === void 0) {
-		await sleep(delayMs);
-		return;
-	}
-	try {
-		await sleepWithAbortSignal(sleep, delayMs, signal);
-		return;
-	} catch (error) {
-		const aborted = buildAbortResult(signal, attempts, logger);
-		if (aborted !== void 0) return aborted;
-		throw error;
-	}
-};
-/**
-* After a failed attempt, applies abort rules, `next`, optional delay, and
-* either returns a terminal `RetryRunResult` or `undefined` to continue.
-*
-* @param policy - Resolved retry policy hooks (`next`, `onExhausted`).
-* @param params - Failure context for the current attempt.
-* @param params.attempt - Current attempt number.
-* @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, 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({
-			attempts: attempt,
-			error
-		}),
-		ok: false
-	};
-	if (decision.delayMs > 0) {
-		const delayAbortResult = await waitForDelay(sleep, decision.delayMs, signal, attempt, logger);
-		if (delayAbortResult !== void 0) return delayAbortResult;
-	}
-};
-/**
-* Runs the non-throw retry loop, returning
-* `RetryRunResult`.
-*
-* @param policy - Resolved retry policy providing `next` and `onExhausted`.
-* @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
-*   `result.error` immediately, bypassing retry — never thrown.
-* @throws {Error} Any error thrown by `next`, `onExhausted`, or a non-abort `sleep`
-*   failure.
-*/
-const runResultMode = async (policy, execute, sleep, signal, logger) => {
-	let attempt = 1;
-	while (true) {
-		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, logger);
-		if (attemptAbortResult !== void 0) return attemptAbortResult;
-		if (!policy.isKnownError(execution.error)) return {
-			attempts: attempt,
-			error: new RetryError("Retry policy encountered an unknown error.", {
-				attempts: attempt,
-				lastError: execution.error
-			}),
-			ok: false
-		};
-		const failure = await handleFailure(policy, {
-			attempt,
-			error: execution.error,
-			logger,
-			signal,
-			sleep
-		});
-		if (failure !== void 0) return failure;
-		attempt += 1;
-	}
-};
-/**
-* Default `onExhausted` used when a policy omits it: wraps the exhaustion
-* context in a generic `RetryError`.
-*/
-const defaultOnExhausted = (input) => new RetryError("Retry policy exhausted all attempts.", {
-	attempts: input.attempts,
-	lastData: input.data,
-	lastError: input.error
-});
-/**
-* Default `isKnownError` used when a policy omits it: accepts any `Error`
-* instance and rejects everything else.
-*/
-const defaultIsKnownError = (error) => error instanceof Error;
-/**
-* Runs retry orchestration in non-throw mode.
-*
-* When `throwOnExhausted` is `false`, returns a discriminated result union.
-*
-* @param policy - Retry policy: `next` is required, `onExhausted` and
-*   `isKnownError` fall back to their defaults when omitted.
-* @param execute - Async function to execute per attempt.
-* @param options - Runner settings.
-* @returns Success value or terminal result object based on option mode.
-* @throws {Error} 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.
-*   Cancellation is returned as `{ ok: false, error: AbortError }` in non-throw
-*   mode. A value rejected by `policy.isKnownError` is wrapped in a
-*   `RetryError` and returned the same way in non-throw mode; in throw mode
-*   it is rethrown as-is.
-*
-* @example
-* const result = await runRetryPolicy(policy, doWork, { throwOnExhausted: false });
-* if (!result.ok) console.error(result.error);
-*/
-async function runRetryPolicy(policy, execute, options = {}) {
-	const sleep = options.sleep ?? defaultSleep;
-	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, logger);
-	return await runThrowMode(resolvedPolicy, execute, sleep, signal, logger);
-}
-//#endregion
+import { n as runRetryPolicy, t as defaultSleep } from "./base-policy-CiDqMVSD.js";
+import "./errors.js";
 export { defaultSleep, runRetryPolicy };
-
-//# sourceMappingURL=base-policy.js.map

package/dist/index.js

@@ -1,5 +1,5 @@
+import { n as runRetryPolicy, t as defaultSleep } from "./base-policy-CiDqMVSD.js";
 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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zap-studio/retry",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "private": false,
   "description": "Composable, tree-shakeable retry policies for resilient async operations.",
   "keywords": [
@@ -43,15 +43,26 @@
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "@zap-studio/logger": "1.0.0"
-  },
   "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/context-async-hooks": "^2.10.0",
+    "@opentelemetry/sdk-metrics": "^2.10.0",
+    "@opentelemetry/sdk-trace-base": "^2.10.0",
     "tsdown": "^0.22.14",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10",
+    "@zap-studio/logger": "2.0.0",
     "@zap-studio/typescript": "0.0.0"
   },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@zap-studio/logger": "2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@zap-studio/logger": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=18.0.0"
   }

package/dist/base-policy.js.map

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