@zap-studio/retry 0.3.1 → 1.0.0

package/CHANGELOG.md

@@ -1,19 +1,63 @@
-## @zap-studio/retry@0.3.1
+# Changelog
 
-### Migrate to ultracite lint/format
+All notable changes to this project will be documented in this file.
 
-Internal formatting and lint cleanup only. No public API or behavior change.
+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.0.0]
+
+### Added
 
-# @zap-studio/retry
+`RetryPolicy` gains an optional `isKnownError?: (error: unknown) => error is TError` hook that `BaseRetryPolicy.run(...)` now calls before handing a caught value to `next(...)`/`onExhausted(...)`. `BaseRetryPolicy.isKnownError` default checks `error instanceof Error`.
 
-## 0.3.0
+- Override `isKnownError` when `TError` is a narrower subclass (an HTTP error, a domain-specific error) to get real narrowing instead of an `instanceof Error` assumption, and to stop unrelated `Error` types from being retried as if they belonged to your domain.
 
-### Breaking
+See [Narrow the Error Domain](https://www.zapstudio.dev/retry/custom-policies#narrow-the-error-domain) for the override pattern.
 
-- **Subpath for error types:** use `@zap-studio/retry/errors` (plural) for `RetryError`, `AbortError`, and related types. A prior JSR `error` subpath that pointed at a non-existent `error.ts` entry is removed; update deep imports from `@zap-studio/retry/error` to `@zap-studio/retry/errors`.
+New built-in policy: `linearBackoff(options)` adds a fixed `incrementMs` to the delay after each failed attempt, capped at `maxDelayMs` — steadier growth than `exponentialBackoff`, more spacing than `fixedDelay`. See [linearBackoff](https://www.zapstudio.dev/retry/linear-backoff).
 
 ### Changed
 
+- **Breaking:** `TError` is now constrained to `TError extends Error` and defaults to `Error` (was `TError = unknown`) on `RetryPolicy`, `RetryDecisionInput`, `RetryExhaustedInput`, and `BaseRetryPolicy`.
+- **Breaking behavior change:** a rejection with a non-`Error` value (a thrown string, plain object, `undefined`, ...) now bypasses retry entirely on the attempt that produced it — it no longer reaches `next(...)`, and no delay/backoff is applied. Previously any thrown value was passed through to the policy unchanged. In throw mode, `run(...)` rethrows the value as-is; with `throwOnExhausted: false`, it's wrapped in a `RetryError` and returned on `result.error` — `run(...)` never throws in that mode.
+- **Breaking:** Policies are plain objects instead of classes, for tree-shaking — bundlers can drop an unused policy factory and its defaults entirely, which isn't possible across a shared class hierarchy. `ExponentialBackoff`/`FixedDelay` classes are replaced by `exponentialBackoff(options)`/`fixedDelay(options)` factory functions that return a `RetryPolicy`. Migrate `new ExponentialBackoff(opts)` to `exponentialBackoff(opts)`, and `new FixedDelay(opts)` to `fixedDelay(opts)`.
+- **Breaking:** `RetryPolicy.onExhausted` is now optional (previously required); omit it to use the same default `RetryError` that `BaseRetryPolicy.onExhausted` used to build.
+
+### Removed
+
+- **Breaking:** `BaseRetryPolicy` is removed. Retry orchestration is now the standalone function `runRetryPolicy(policy, execute, options?)`, which accepts any object satisfying `RetryPolicy` — no subclassing required. Migrate `policy.run(execute, options)` to `runRetryPolicy(policy, execute, options)`. A custom policy that previously extended `BaseRetryPolicy` and overrode `next`/`onExhausted`/`isKnownError` becomes an object literal implementing the same members; see [Custom Policies](https://www.zapstudio.dev/retry/custom-policies).
+
+### Removed
+
+Collapsed abort/sleep orchestration internals out of the public API.
+
+- Removed the `./abort` and `./sleep` subpath exports.
+- Removed the public `sleepWithAbortSignal`, `throwIfAborted`, and `toAbortError` exports — they were orchestration internals with no consumer outside the retry loop, not standalone utilities.
+- `defaultSleep` is unaffected and still exported from `@zap-studio/retry` (no dedicated subpath).
+
+## [0.3.2]
+
+### Added
+
+The package root now re-exports the full public API, so everything can be imported from `@zap-studio/retry` directly (`BaseRetryPolicy`, `ExponentialBackoff`, `FixedDelay`, `RetryError`, `AbortError`, abort helpers, `defaultSleep`, and all public types). All exports are side-effect free and tree-shakeable; granular subpath imports keep working.
+
+- `BaseRetryPolicy` moved from the entrypoint into its own module, available as the new `./base-policy` subpath.
+
+### Removed
+
+- Removed the `./result-mode` and `./throw-mode` subpath exports. Both were orchestration internals (`runResultMode`, `runThrowMode`) and are no longer part of the public API.
+
+## [0.3.1]
+
+### Changed
+
+Internal formatting and lint cleanup only. No public API or behavior change.
+
+## [0.3.0]
+
+### Changed
+
+- **Breaking:** Subpath for error types: use `@zap-studio/retry/errors` (plural) for `RetryError`, `AbortError`, and related types. A prior JSR `error` subpath that pointed at a non-existent `error.ts` entry is removed; update deep imports from `@zap-studio/retry/error` to `@zap-studio/retry/errors`.
 - Add dedicated `AbortError` and normalize cancellation paths so retry internals throw/return `RetryError` or `AbortError` instead of plain `Error`.
 - Expose `defaultSleep` from the `@zap-studio/retry/sleep` subpath only (the main entry does not re-export it; `run` still uses it internally when `sleep` is omitted).
 - Align non-throw exhaustion metadata so `result.attempts` and `result.error.attempts` stay consistent for `RetryError` outcomes.
@@ -24,7 +68,7 @@ Internal formatting and lint cleanup only. No public API or behavior change.
 - Add exhaustive TSDoc for `result-mode` and other `src` modules, including private helpers, policy option and state fields, and `RetryRunResult` union members.
 - Rework test layout into `sleep`, `throw-mode`, `result-mode`, and `index` test files with a shared `sequence-policy` fixture, replacing the prior combined `index` and `abort` test files.
 
-## 0.2.0
+## [0.2.0]
 
 ### Changed
 
@@ -34,13 +78,13 @@ Internal formatting and lint cleanup only. No public API or behavior change.
 - Add abort-focused ecosystem benchmarks comparing signal overhead and immediate cancellation behavior.
 - Expand TSDoc coverage for new runner internals added in this release.
 
-## 0.1.2
+## [0.1.2]
 
 ### Changed
 
 - Expand TSDoc coverage across retry modules and exported contracts for stronger JSR documentation completeness.
 
-## 0.1.1
+## [0.1.1]
 
 ### Fixed
 
@@ -50,7 +94,7 @@ Internal formatting and lint cleanup only. No public API or behavior change.
 
 - e9903c5: Removed redundant `| undefined` unions from public retry option and decision types.
 
-## 0.1.0
+## [0.1.0]
 
 ### Added
 
@@ -62,7 +106,4 @@ Internal formatting and lint cleanup only. No public API or behavior change.
 - Added `ExponentialBackoff` policy with bounded exponential delay via `baseDelayMs`, `maxDelayMs`, and `maxAttempts`.
 - Added `FixedDelay` policy with constant delay and bounded attempts.
 - Added `RetryError` for exhausted-retry failures with structured attempt/error/data context.
-
-### Documentation
-
 - Documented throwable behavior on `RetryPolicy`, `BaseRetryPolicy.run`, and related contracts with explicit `@throws` tags for policy, exhaustion, and custom `sleep` failures.

package/README.md

@@ -2,26 +2,37 @@
 
 Composable retry policy primitives for HTTP clients and async workflows.
 
+Full documentation: [zapstudio.dev/retry](https://www.zapstudio.dev/retry)
+
 ## Installation
 
 ```bash
 npm install @zap-studio/retry
 ```
 
-## Usage
+## Features
+
+- **Built-in policies**: `fixedDelay(...)`, `linearBackoff(...)`, and `exponentialBackoff(...)`.
+- **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.
+- **Tree-shakeable** — policies are functions returning plain objects, not classes; unused policies are dropped by any modern bundler.
+
+## Quick Start
 
 ```ts
-import { ExponentialBackoff } from "@zap-studio/retry/exponential-backoff";
-import { FixedDelay } from "@zap-studio/retry/fixed-delay";
+import { exponentialBackoff, runRetryPolicy } from "@zap-studio/retry";
 import { $fetch } from "@zap-studio/fetch";
 
-const exponential = new ExponentialBackoff({
+const policy = exponentialBackoff({
   maxAttempts: 5,
   baseDelayMs: 100,
   maxDelayMs: 2_000,
 });
 
-const data = await exponential.run(async () => {
+const data = await runRetryPolicy(policy, async () => {
   const response = await $fetch("https://api.example.com/users", {
     throwOnFetchError: true,
   });
@@ -29,189 +40,124 @@ const data = await exponential.run(async () => {
 });
 ```
 
-## Handling Errors
-
-`run(...)` throws when retries are exhausted.
+## Built-in Policies
 
-By default, policies extending `BaseRetryPolicy` throw `RetryError` on exhaustion and `AbortError` on cancellation.
+`fixedDelay(...)`, `linearBackoff(...)`, and `exponentialBackoff(...)`.
 
 ```ts
-import { AbortError, RetryError } from "@zap-studio/retry/errors";
+import {
+  exponentialBackoff,
+  fixedDelay,
+  linearBackoff,
+} from "@zap-studio/retry";
 
-try {
-  const data = await exponential.run(async () => {
-    const response = await $fetch("https://api.example.com/users", {
-      throwOnFetchError: true,
-    });
-    return await response.json();
-  });
-  console.log(data);
-} catch (error) {
-  if (error instanceof RetryError) {
-    console.error("Retries exhausted:", error.attempts);
-    console.error("Last error:", error.lastError);
-  } else if (error instanceof AbortError) {
-    console.error("Retry aborted:", error.message);
-  } else {
-    throw error;
-  }
-}
+const exponential = exponentialBackoff({
+  maxAttempts: 5,
+  baseDelayMs: 100,
+  maxDelayMs: 2_000,
+});
+const linear = linearBackoff({
+  maxAttempts: 5,
+  baseDelayMs: 100,
+  incrementMs: 100,
+  maxDelayMs: 2_000,
+});
+const fixed = fixedDelay({ maxAttempts: 4, delayMs: 300 });
 ```
 
-To handle exhaustion without throwing, pass `throwOnExhausted: false`:
+## Shared Runner
 
-```ts
-const result = await exponential.run(
-  async () => {
-    const response = await $fetch("https://api.example.com/users", {
-      throwOnFetchError: true,
-    });
-    return await response.json();
-  },
-  { throwOnExhausted: false }
-);
+Via `runRetryPolicy(policy, execute, options?)` with attempt-aware callbacks and custom sleep injection.
 
-if (!result.ok) {
-  console.error("Retries exhausted:", result.attempts);
-  console.error("Last error:", result.error.lastError);
-} else {
-  console.log(result.value);
-}
+```ts
+await runRetryPolicy(policy, execute, {
+  sleep: (delayMs) => customSleep(delayMs),
+});
 ```
 
-## Default sleep
+## Structured Terminal Errors
 
-`BaseRetryPolicy.run` automatically applies a delay between retry attempts when no custom `sleep` function is provided in the options.
-
-That default is the `defaultSleep` helper, exported from `@zap-studio/retry/sleep`.
-
-By default, this delay mechanism relies on the native JavaScript `setTimeout`, meaning retries are scheduled using the standard event loop timing rather than any custom or blocking implementation.
-
-## Cancellation With AbortSignal
-
-Use `signal` in `run(...)` options to stop retrying early.
+`RetryError` on exhaustion, `AbortError` on cancellation.
 
 ```ts
-const controller = new AbortController();
-
-const promise = exponential.run(
-  async () => {
-    const response = await $fetch("https://api.example.com/users", {
-      throwOnFetchError: true,
-    });
-    return await response.json();
-  },
-  { signal: controller.signal }
-);
+import { AbortError, RetryError, runRetryPolicy } from "@zap-studio/retry";
 
-controller.abort(new Error("Request canceled"));
-
-await promise;
+try {
+  await runRetryPolicy(policy, execute);
+} catch (error) {
+  if (error instanceof RetryError)
+    console.error(error.attempts, error.lastError);
+  if (error instanceof AbortError) console.error(error.message);
+}
 ```
 
-In non-throw mode, abort is returned as `{ ok: false }` with `AbortError` on `result.error`:
+## Non-throw Mode
 
-```ts
-const controller = new AbortController();
+`throwOnExhausted: false` returns a `RetryRunResult` instead of throwing.
 
-const result = await exponential.run(
-  async () => {
-    const response = await $fetch("https://api.example.com/users", {
-      throwOnFetchError: true,
-    });
-    return await response.json();
-  },
-  {
-    signal: controller.signal,
-    throwOnExhausted: false,
-  }
-);
+```ts
+const result = await runRetryPolicy(policy, execute, {
+  throwOnExhausted: false,
+});
 
 if (!result.ok) {
-  console.error("Retry stopped:", result.error);
+  console.error(result.error);
+} else {
+  console.log(result.value);
 }
 ```
 
-## Choosing The Right Policy
+## Cancellation
 
-Use `ExponentialBackoff` for transient network instability and shared upstream services.
+Through `AbortSignal`, checked before, between, and during retries.
 
 ```ts
-const unstableNetworkPolicy = new ExponentialBackoff({
-  maxAttempts: 6,
-  baseDelayMs: 100,
-  maxDelayMs: 2_000,
-});
-```
+const controller = new AbortController();
 
-Use `FixedDelay` for stable, predictable retry intervals in controlled environments.
+const promise = runRetryPolicy(policy, execute, { signal: controller.signal });
 
-```ts
-const predictableIntervalPolicy = new FixedDelay({
-  maxAttempts: 4,
-  delayMs: 300,
-});
+controller.abort(new Error("Request canceled"));
 ```
 
 ## Custom Policies
 
-Extend `BaseRetryPolicy` when the built-in policies do not match your retry rules.
-
-You implement `next(...)` only; the base class supplies `onExhausted` with a default `RetryError` and keeps the shared `run(...)` orchestration (override `onExhausted` when you need a different terminal error).
+As plain objects implementing `RetryPolicy` — just a `next(...)` function, no subclassing.
 
 ```ts
-import { BaseRetryPolicy } from "@zap-studio/retry";
+import { runRetryPolicy } from "@zap-studio/retry";
 import type {
   RetryDecision,
   RetryDecisionInput,
-} from "@zap-studio/retry/types";
-
-class LinearBackoff extends BaseRetryPolicy {
-  constructor(
-    private readonly maxAttempts: number,
-    private readonly stepMs: number
-  ) {
-    super();
-  }
-
-  public next(input: RetryDecisionInput): RetryDecision {
-    if (input.attempt >= this.maxAttempts) {
-      return {
-        shouldRetry: false,
-        delayMs: 0,
-        reason: "max-attempts-reached",
-      };
-    }
+  RetryPolicy,
+} from "@zap-studio/retry";
 
+const stepDelay = (maxAttempts: number, stepMs: number): RetryPolicy => ({
+  next(input: RetryDecisionInput): RetryDecision {
+    if (input.attempt >= maxAttempts) {
+      return { shouldRetry: false, delayMs: 0, reason: "max-attempts-reached" };
+    }
     return {
       shouldRetry: true,
-      delayMs: input.attempt * this.stepMs,
+      delayMs: input.attempt * stepMs,
       reason: "retry",
     };
-  }
-}
+  },
+});
 
-const policy = new LinearBackoff(5, 250);
-const value = await policy.run(doWork);
+const data = await runRetryPolicy(stepDelay(5, 100), execute);
 ```
 
-## RetryError
-
-Use `RetryError` when an orchestrator exhausts retries and needs to surface final context.
-
-```ts
-import { RetryError } from "@zap-studio/retry/errors";
-
-throw new RetryError("Retry policy exhausted all attempts.", {
-  attempts: attempt,
-  lastError: error,
-  lastData: data,
-});
-```
+## Runtime Support
 
-Policies implement `onExhausted(input)` to return the terminal error used by the built-in runner.
+| Runtime            | Minimum version                         |
+| ------------------ | --------------------------------------- |
+| Node.js            | 18.0.0                                  |
+| Bun                | 1.0.0                                   |
+| Deno               | 1.42                                    |
+| Cloudflare Workers | Any current release                     |
+| Browsers           | Chrome/Edge 98, Firefox 97, Safari 15.4 |
 
-`ExponentialBackoff` and `FixedDelay` inherit the default implementation from `BaseRetryPolicy`.
+Cancellation relies on `AbortSignal.reason`, which sets the browser minimums above. Deno 1.42 is the first release that can install packages from JSR (`deno add jsr:@zap-studio/retry`).
 
 ## License
 

package/dist/base-policy.d.ts

@@ -0,0 +1,67 @@
+import { RetryPolicy, RetryRunOptions, RetryRunResult } from "./types.js";
+//#region src/base-policy.d.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
+ * ```
+ */
+declare const defaultSleep: (delayMs: number) => Promise<void>;
+/**
+ * Runs retry orchestration in non-throw mode.
+ *
+ * @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 with `throwOnExhausted: false`.
+ * @returns A discriminated result union containing success value or terminal error.
+ *   When `policy.isKnownError` rejects a caught value, it is wrapped in a
+ *   `RetryError` and returned as the terminal failure instead of thrown.
+ * @throws {Error} Any error thrown by `next`, `onExhausted`, or a custom `sleep`.
+ */
+declare function runRetryPolicy<T, TError extends Error = Error, TData = unknown>(policy: RetryPolicy<TError, TData>, execute: (attempt: number) => Promise<T>, options: RetryRunOptions & {
+  throwOnExhausted: false;
+}): Promise<RetryRunResult<T>>;
+/**
+ * Runs retry orchestration and throws terminal error on exhaustion.
+ *
+ * @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 - Optional runner settings.
+ * @returns The successful execution value.
+ * @throws {RetryError} When retries are exhausted and `onExhausted` returns the
+ *   terminal retry error. The default implementation returns `RetryError` with the last
+ *   execution failure available on `RetryError.lastError`.
+ * @throws {AbortError} When `options.signal` is already aborted or aborts while retrying.
+ * @throws {Error} Any error thrown by `next`, by `onExhausted`, or by a custom `sleep`
+ *   function.
+ *
+ * @example
+ * ```ts
+ * import { runRetryPolicy } from "@zap-studio/retry";
+ * import type { RetryPolicy } from "@zap-studio/retry";
+ *
+ * const linearBackoff: RetryPolicy = {
+ *   next: ({ attempt }) =>
+ *     attempt < 3
+ *       ? { shouldRetry: true, delayMs: attempt * 100, reason: "retry" }
+ *       : { shouldRetry: false, delayMs: 0, reason: "max-attempts-reached" },
+ * };
+ *
+ * const data = await runRetryPolicy(linearBackoff, async () => fetchFlakyResource());
+ * ```
+ */
+declare function runRetryPolicy<T, TError extends Error = Error, TData = unknown>(policy: RetryPolicy<TError, TData>, execute: (attempt: number) => Promise<T>, options?: RetryRunOptions & {
+  throwOnExhausted?: true;
+}): Promise<T>;
+//#endregion
+export { defaultSleep, runRetryPolicy };
+//# sourceMappingURL=base-policy.d.ts.map

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

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