@gkoos/caracal 0.1.0

package/dist/testing/index.d.ts

@@ -0,0 +1,45 @@
+import { O as OperationCapabilities, h as Outcome, C as Classification, A as Adapter } from '../types-Tf9T76C7.js';
+
+interface AdapterContractSuccess<Args, Result> {
+    readonly args: Args;
+    readonly assertResult?: (result: Result) => void | Promise<void>;
+}
+interface AdapterContractCapabilityCase<Args> {
+    readonly args: Args;
+    readonly expected: OperationCapabilities;
+}
+interface AdapterContractClassificationCase<Result> {
+    readonly outcome: Outcome<Result>;
+    readonly expected: Classification;
+}
+interface AdapterContractAbortCase<Args> {
+    readonly args: Args;
+    readonly verify: (controls: {
+        readonly controller: AbortController;
+        readonly execute: () => Promise<unknown>;
+    }) => void | Promise<void>;
+}
+interface AdapterContractOptions<Args, Result> {
+    readonly name: string;
+    readonly adapter: Adapter<Args, Result>;
+    readonly success: AdapterContractSuccess<Args, Result>;
+    readonly capabilities: readonly AdapterContractCapabilityCase<Args>[];
+    readonly classifications?: readonly AdapterContractClassificationCase<Result>[];
+    readonly abort?: AdapterContractAbortCase<Args>;
+}
+interface AdapterContractCheck {
+    readonly name: string;
+    run(): Promise<void>;
+}
+interface AdapterContractSuite {
+    readonly name: string;
+    readonly checks: readonly AdapterContractCheck[];
+}
+/**
+ * Returns runner-agnostic checks for a third-party adapter. Register each
+ * check with the application's test runner; this module imports no test runner.
+ */
+declare function defineAdapterContractSuite<Args, Result>(options: AdapterContractOptions<Args, Result>): AdapterContractSuite;
+declare function runAdapterContractSuite(suite: AdapterContractSuite): Promise<void>;
+
+export { type AdapterContractAbortCase, type AdapterContractCapabilityCase, type AdapterContractCheck, type AdapterContractClassificationCase, type AdapterContractOptions, type AdapterContractSuccess, type AdapterContractSuite, defineAdapterContractSuite, runAdapterContractSuite };

package/dist/testing/index.js

@@ -0,0 +1,101 @@
+import { operation } from '../chunk-5CXDW7W6.js';
+
+// test/harness/adapter-contract.ts
+function assertEqual(actual, expected, message) {
+  if (!Object.is(actual, expected)) {
+    throw new Error(
+      `${message}: expected ${String(expected)}, received ${String(actual)}`
+    );
+  }
+}
+function assertLifecycle(events) {
+  const types = events.map((event) => event.type);
+  const expected = [
+    "execution.started",
+    "attempt.started",
+    "attempt.settled",
+    "execution.settled"
+  ];
+  if (types.length !== expected.length || types.some((type, index) => type !== expected[index])) {
+    throw new Error(
+      `expected operation lifecycle ${expected.join(" -> ")}; received ${types.join(" -> ")}`
+    );
+  }
+}
+function defineAdapterContractSuite(options) {
+  const checks = options.capabilities.map(
+    (capabilityCase, index) => ({
+      name: `${options.name}: capabilities ${index + 1}`,
+      async run() {
+        const actual = options.adapter.capabilities(capabilityCase.args);
+        assertEqual(
+          actual.abort,
+          capabilityCase.expected.abort,
+          "abort capability"
+        );
+        assertEqual(
+          actual.replay,
+          capabilityCase.expected.replay,
+          "replay capability"
+        );
+      }
+    })
+  );
+  checks.push({
+    name: `${options.name}: successful operation lifecycle`,
+    async run() {
+      const events = [];
+      const subject = operation({
+        name: `adapter-contract:${options.name}`,
+        adapter: options.adapter,
+        events: { emit: (event) => events.push(event) }
+      });
+      const result = await subject.execute(options.success.args, {
+        executionId: "adapter-contract"
+      });
+      await options.success.assertResult?.(result);
+      assertLifecycle(events);
+    }
+  });
+  for (const [index, classificationCase] of (options.classifications ?? []).entries()) {
+    checks.push({
+      name: `${options.name}: classification ${index + 1}`,
+      async run() {
+        const actual = options.adapter.classify?.(classificationCase.outcome) ?? (classificationCase.outcome.status === "success" ? "success" : "failure");
+        assertEqual(
+          actual,
+          classificationCase.expected,
+          "outcome classification"
+        );
+      }
+    });
+  }
+  if (options.abort !== void 0) {
+    checks.push({
+      name: `${options.name}: abort behavior`,
+      async run() {
+        const controller = new AbortController();
+        const subject = operation({
+          name: `adapter-contract:${options.name}`,
+          adapter: options.adapter
+        });
+        await options.abort?.verify({
+          controller,
+          execute: () => subject.execute(options.abort?.args, {
+            signal: controller.signal
+          })
+        });
+      }
+    });
+  }
+  return Object.freeze({ name: options.name, checks: Object.freeze(checks) });
+}
+async function runAdapterContractSuite(suite) {
+  for (const check of suite.checks) {
+    await check.run();
+  }
+}
+
+export { defineAdapterContractSuite, runAdapterContractSuite };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../test/harness/adapter-contract.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { operation } from \"../../src/core/operation.js\"\nimport type {\n  Adapter,\n  Classification,\n  OperationCapabilities,\n  OperationEvent,\n  Outcome,\n} from \"../../src/core/types.js\"\n\nexport interface AdapterContractSuccess<Args, Result> {\n  readonly args: Args\n  readonly assertResult?: (result: Result) => void | Promise<void>\n}\n\nexport interface AdapterContractCapabilityCase<Args> {\n  readonly args: Args\n  readonly expected: OperationCapabilities\n}\n\nexport interface AdapterContractClassificationCase<Result> {\n  readonly outcome: Outcome<Result>\n  readonly expected: Classification\n}\n\nexport interface AdapterContractAbortCase<Args> {\n  readonly args: Args\n  readonly verify: (controls: {\n    readonly controller: AbortController\n    readonly execute: () => Promise<unknown>\n  }) => void | Promise<void>\n}\n\nexport interface AdapterContractOptions<Args, Result> {\n  readonly name: string\n  readonly adapter: Adapter<Args, Result>\n  readonly success: AdapterContractSuccess<Args, Result>\n  readonly capabilities: readonly AdapterContractCapabilityCase<Args>[]\n  readonly classifications?: readonly AdapterContractClassificationCase<Result>[]\n  readonly abort?: AdapterContractAbortCase<Args>\n}\n\nexport interface AdapterContractCheck {\n  readonly name: string\n  run(): Promise<void>\n}\n\nexport interface AdapterContractSuite {\n  readonly name: string\n  readonly checks: readonly AdapterContractCheck[]\n}\n\nfunction assertEqual<T>(actual: T, expected: T, message: string): void {\n  if (!Object.is(actual, expected)) {\n    throw new Error(\n      `${message}: expected ${String(expected)}, received ${String(actual)}`,\n    )\n  }\n}\n\nfunction assertLifecycle(events: readonly OperationEvent[]): void {\n  const types = events.map((event) => event.type)\n  const expected = [\n    \"execution.started\",\n    \"attempt.started\",\n    \"attempt.settled\",\n    \"execution.settled\",\n  ]\n  if (\n    types.length !== expected.length ||\n    types.some((type, index) => type !== expected[index])\n  ) {\n    throw new Error(\n      `expected operation lifecycle ${expected.join(\" -> \")}; received ${types.join(\" -> \")}`,\n    )\n  }\n}\n\n/**\n * Returns runner-agnostic checks for a third-party adapter. Register each\n * check with the application's test runner; this module imports no test runner.\n */\nexport function defineAdapterContractSuite<Args, Result>(\n  options: AdapterContractOptions<Args, Result>,\n): AdapterContractSuite {\n  const checks: AdapterContractCheck[] = options.capabilities.map(\n    (capabilityCase, index) => ({\n      name: `${options.name}: capabilities ${index + 1}`,\n      async run(): Promise<void> {\n        const actual = options.adapter.capabilities(capabilityCase.args)\n        assertEqual(\n          actual.abort,\n          capabilityCase.expected.abort,\n          \"abort capability\",\n        )\n        assertEqual(\n          actual.replay,\n          capabilityCase.expected.replay,\n          \"replay capability\",\n        )\n      },\n    }),\n  )\n\n  checks.push({\n    name: `${options.name}: successful operation lifecycle`,\n    async run(): Promise<void> {\n      const events: OperationEvent[] = []\n      const subject = operation({\n        name: `adapter-contract:${options.name}`,\n        adapter: options.adapter,\n        events: { emit: (event) => events.push(event) },\n      })\n      const result = await subject.execute(options.success.args, {\n        executionId: \"adapter-contract\",\n      })\n      await options.success.assertResult?.(result)\n      assertLifecycle(events)\n    },\n  })\n\n  for (const [index, classificationCase] of (\n    options.classifications ?? []\n  ).entries()) {\n    checks.push({\n      name: `${options.name}: classification ${index + 1}`,\n      async run(): Promise<void> {\n        const actual =\n          options.adapter.classify?.(classificationCase.outcome) ??\n          (classificationCase.outcome.status === \"success\"\n            ? \"success\"\n            : \"failure\")\n        assertEqual(\n          actual,\n          classificationCase.expected,\n          \"outcome classification\",\n        )\n      },\n    })\n  }\n\n  if (options.abort !== undefined) {\n    checks.push({\n      name: `${options.name}: abort behavior`,\n      async run(): Promise<void> {\n        const controller = new AbortController()\n        const subject = operation({\n          name: `adapter-contract:${options.name}`,\n          adapter: options.adapter,\n        })\n        await options.abort?.verify({\n          controller,\n          execute: () =>\n            subject.execute(options.abort?.args as Args, {\n              signal: controller.signal,\n            }),\n        })\n      },\n    })\n  }\n\n  return Object.freeze({ name: options.name, checks: Object.freeze(checks) })\n}\n\nexport async function runAdapterContractSuite(\n  suite: AdapterContractSuite,\n): Promise<void> {\n  for (const check of suite.checks) {\n    await check.run()\n  }\n}\n"]}

package/dist/types-Tf9T76C7.d.ts

@@ -0,0 +1,187 @@
+/** Traits that may vary for each invocation of an adapter. */
+type OperationCapabilities = Readonly<{
+    abort: "supported" | "unsupported";
+    replay: "safe" | "unsafe" | "unknown";
+}>;
+type Outcome<Result> = Readonly<{
+    status: "success";
+    value: Result;
+}> | Readonly<{
+    status: "failure";
+    error: unknown;
+}>;
+/** An adapter's interpretation of an outcome for resilience policies. */
+/** `retryable` is a failure eligible for the local retry policy. */
+type Classification = "success" | "failure" | "retryable" | "ignored";
+type OutcomeClassifier = (outcome: Outcome<unknown>) => Classification;
+interface Adapter<Args, Result> {
+    execute(args: Args, context: ExecutionContext): Promise<Result>;
+    capabilities(args: Args): OperationCapabilities;
+    classify?(outcome: Outcome<Result>): Classification;
+}
+type ExecutionMetadata = Readonly<Record<string, unknown>>;
+/**
+ * Immutable state for one attempt. Retry derives later attempt contexts from
+ * this value; an operation starts at attempt 1.
+ */
+interface ExecutionContext {
+    readonly operationName: string;
+    readonly executionId: string;
+    readonly attempt: number;
+    readonly signal: AbortSignal | undefined;
+    readonly metadata: ExecutionMetadata;
+    readonly capabilities: OperationCapabilities;
+    readonly classify: OutcomeClassifier;
+}
+type BreakerStateChangedEvent = Readonly<{
+    type: "breaker.state-changed";
+    at: number;
+    context: ExecutionContext;
+    coordination: "local" | "distributed";
+    policyName: string;
+    scope: string;
+    state: "open" | "half-open" | "closed";
+    previousState: "closed" | "open" | "half-open";
+    /** Present on distributed events; absent on local events. */
+    generation?: number;
+}>;
+type BreakerRejectedEvent = Readonly<{
+    type: "breaker.rejected";
+    at: number;
+    context: ExecutionContext;
+    coordination: "local" | "distributed";
+    policyName: string;
+    scope: string;
+    state: "open" | "half-open";
+    generation?: number;
+}>;
+type BreakerObservationEvent = Readonly<{
+    type: "breaker.observation";
+    at: number;
+    context: ExecutionContext;
+    coordination: "local" | "distributed";
+    policyName: string;
+    scope: string;
+    outcome: "success" | "failure";
+    generation?: number;
+}>;
+type BreakerProbeStartedEvent = Readonly<{
+    type: "breaker.probe-started";
+    at: number;
+    context: ExecutionContext;
+    coordination: "local" | "distributed";
+    policyName: string;
+    scope: string;
+    generation?: number;
+}>;
+type BreakerObservationStaleEvent = Readonly<{
+    type: "breaker.observation-stale";
+    at: number;
+    context: ExecutionContext;
+    coordination: "distributed";
+    policyName: string;
+    scope: string;
+    /** Generation of the attempt that was dropped. */
+    attemptGeneration: number;
+    /** Current generation in the coordinator at the time the stale result arrived. */
+    currentGeneration: number;
+}>;
+type BreakerCoordinatorErrorEvent = Readonly<{
+    type: "breaker.coordinator-error";
+    at: number;
+    context: ExecutionContext;
+    coordination: "distributed";
+    policyName: string;
+    scope: string;
+    operation: "admit" | "observe" | "settle-probe";
+    error: unknown;
+}>;
+type BreakerDegradedEvent = Readonly<{
+    type: "breaker.degraded";
+    at: number;
+    context: ExecutionContext;
+    coordination: "distributed";
+    policyName: string;
+    scope: string;
+    reason: "coordinator-unavailable";
+    behavior: "fail-open" | "fail-closed";
+}>;
+type OperationEvent = BreakerStateChangedEvent | BreakerRejectedEvent | BreakerObservationEvent | BreakerProbeStartedEvent | BreakerObservationStaleEvent | BreakerCoordinatorErrorEvent | BreakerDegradedEvent | Readonly<{
+    type: "bulkhead.admitted" | "bulkhead.rejected" | "bulkhead.waited" | "bulkhead.released" | "bulkhead.lease-lost" | "bulkhead.degraded";
+    at: number;
+    context: ExecutionContext;
+    coordination: "local" | "distributed";
+    policyName: string;
+    scope: string;
+    occupancy?: number;
+    reason?: string;
+}> | Readonly<{
+    type: "execution.started";
+    at: number;
+    context: ExecutionContext;
+}> | Readonly<{
+    type: "attempt.started";
+    at: number;
+    context: ExecutionContext;
+}> | Readonly<{
+    type: "attempt.settled";
+    at: number;
+    context: ExecutionContext;
+    outcome: Outcome<undefined>;
+    classification: Classification;
+}> | Readonly<{
+    type: "execution.settled";
+    at: number;
+    context: ExecutionContext;
+    outcome: Outcome<undefined>;
+}> | Readonly<{
+    type: "timeout.triggered";
+    at: number;
+    context: ExecutionContext;
+    timeoutMs: number;
+    abortRequested: boolean;
+}> | Readonly<{
+    type: "retry.scheduled";
+    at: number;
+    context: ExecutionContext;
+    nextAttempt: number;
+    delayMs: number;
+    outcome: Outcome<undefined>;
+    classification: Classification;
+}> | Readonly<{
+    type: "retry.exhausted";
+    at: number;
+    context: ExecutionContext;
+    outcome: Outcome<undefined>;
+    classification: Classification;
+}>;
+/** Output-only observability contract. Sinks cannot alter policy execution. */
+interface EventSink {
+    emit(event: OperationEvent): void;
+}
+type EventSinks = EventSink | readonly EventSink[];
+type OperationExecuteOptions = Readonly<{
+    signal?: AbortSignal;
+    metadata?: Readonly<Record<string, unknown>>;
+    executionId?: string;
+}>;
+type Next<Result> = (context: ExecutionContext) => Promise<Result>;
+/** A policy wraps execution; it is not a generic lifecycle hook system. */
+interface Policy {
+    /** Attempt-phase policies wrap each adapter call and must await underlying settlement. */
+    readonly phase?: "attempt";
+    readonly name: string;
+    execute<Result>(context: ExecutionContext, next: Next<Result>): Promise<Result>;
+}
+interface Operation<Args, Result> {
+    readonly name: string;
+    execute(args: Args, options?: OperationExecuteOptions): Promise<Result>;
+}
+interface OperationOptions<Args, Result> {
+    readonly name: string;
+    readonly adapter: Adapter<Args, Result>;
+    readonly policies?: readonly Policy[];
+    readonly events?: EventSinks;
+}
+
+export type { Adapter as A, Classification as C, EventSink as E, Next as N, OperationCapabilities as O, Policy as P, OperationOptions as a, Operation as b, EventSinks as c, ExecutionContext as d, ExecutionMetadata as e, OperationEvent as f, OperationExecuteOptions as g, Outcome as h, OutcomeClassifier as i };

package/package.json

@@ -0,0 +1,127 @@
+{
+  "name": "@gkoos/caracal",
+  "version": "0.1.0",
+  "description": "Scoped distributed resilience for asynchronous operations.",
+  "keywords": [
+    "resilience",
+    "circuit-breaker",
+    "bulkhead",
+    "retry",
+    "timeout",
+    "fault-tolerance",
+    "distributed-systems",
+    "redis",
+    "concurrency",
+    "typescript"
+  ],
+  "homepage": "https://github.com/gkoos/caracal#readme",
+  "bugs": {
+    "url": "https://github.com/gkoos/caracal/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gkoos/caracal.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Gabor Koos",
+    "email": "gabor@gaborkoos.com",
+    "url": "https://gaborkoos.com"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./redis": {
+      "types": "./dist/redis.d.ts",
+      "import": "./dist/redis.js"
+    },
+    "./fetch": {
+      "types": "./dist/fetch.d.ts",
+      "import": "./dist/fetch.js"
+    },
+    "./postgres": {
+      "types": "./dist/postgres.d.ts",
+      "import": "./dist/postgres.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rimraf dist coverage",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run test/unit",
+    "test:watch": "vitest",
+    "test:integration": "vitest run test/integration",
+    "test:property": "vitest run test/property",
+    "test:fuzz": "vitest run test/fuzz",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "lint": "biome lint .",
+    "check": "npm run format:check && npm run lint && npm run typecheck && npm run build && npm test",
+    "test:all": "npm run check && npm run test:property && npm run test:fuzz && npm run test:integration",
+    "redis:up": "docker compose up -d valkey",
+    "redis:down": "docker compose down",
+    "redis:logs": "docker compose logs -f valkey",
+    "test:integration:redis": "node scripts/test-redis.mjs",
+    "node:check": "node scripts/check-node-version.mjs",
+    "precheck": "npm run node:check",
+    "postgres:up": "docker compose up -d --wait postgres",
+    "postgres:down": "docker compose down",
+    "test:integration:postgres": "node scripts/test-postgres.mjs",
+    "redis:cluster:up": "docker compose -f compose.cluster.yaml up -d --wait",
+    "redis:cluster:logs": "docker compose -f compose.cluster.yaml logs -f valkey-cluster",
+    "redis:cluster:down": "docker compose -f compose.cluster.yaml down",
+    "test:integration:cluster": "node scripts/test-redis-cluster.mjs",
+    "bench": "npm run build && node scripts/bench.mjs",
+    "audit:bundle": "npm run build && node scripts/audit-bundle.mjs",
+    "changeset": "changeset",
+    "version": "changeset version"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.12",
+    "@changesets/cli": "^3.0.2",
+    "@types/node": "^22.0.0",
+    "@types/pg": "^8.23.1",
+    "fast-check": "^4.0.0",
+    "ioredis": "^5.11.1",
+    "pg": "^8.23.0",
+    "rimraf": "^6.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.23.13",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "ioredis": "^5.0.0",
+    "pg": ">=8.11 <9"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    }
+  }
+}

package/src/adapters/fetch/adapter.ts

@@ -0,0 +1,122 @@
+import type {
+  Adapter,
+  Classification,
+  ExecutionContext,
+  OperationCapabilities,
+  Outcome,
+} from "../../core/types.js"
+
+export type FetchOperationArgs = Readonly<{
+  url: RequestInfo | URL
+  options?: RequestInit
+}>
+
+export type FetchReplay =
+  | OperationCapabilities["replay"]
+  | ((args: FetchOperationArgs) => OperationCapabilities["replay"])
+
+export interface FetchAdapterOptions {
+  readonly fetch?: typeof globalThis.fetch
+  readonly replay?: FetchReplay
+  readonly classifyResponse?: (response: Response) => Classification
+  readonly classifyError?: (error: unknown) => Classification
+}
+
+function requestMethod(args: FetchOperationArgs): string {
+  if (args.options?.method !== undefined) {
+    return args.options.method.toUpperCase()
+  }
+
+  if (args.url instanceof Request) {
+    return args.url.method.toUpperCase()
+  }
+
+  return "GET"
+}
+
+function defaultReplay(
+  args: FetchOperationArgs,
+): OperationCapabilities["replay"] {
+  const method = requestMethod(args)
+  if (method === "GET" || method === "HEAD") {
+    return "safe"
+  }
+
+  if (method === "POST" || method === "PATCH") {
+    return "unsafe"
+  }
+
+  return "unknown"
+}
+
+function defaultResponseClassification(response: Response): Classification {
+  return response.status >= 500 ||
+    response.status === 408 ||
+    response.status === 429
+    ? "retryable"
+    : "success"
+}
+
+function urlSignal(url: RequestInfo | URL): AbortSignal | undefined {
+  return url instanceof Request ? url.signal : undefined
+}
+
+function combinedSignal(
+  first: AbortSignal | undefined,
+  second: AbortSignal | undefined,
+  third: AbortSignal | undefined,
+): AbortSignal | undefined {
+  const signals = [first, second, third].filter(
+    (signal): signal is AbortSignal => signal !== undefined,
+  )
+  if (signals.length === 0) {
+    return undefined
+  }
+
+  return signals.length === 1 ? signals[0] : AbortSignal.any(signals)
+}
+
+/**
+ * Creates a fetch adapter with conservative per-request replay traits.
+ * It performs no implicit retry or timeout; those remain operation policies.
+ */
+export function fetchAdapter(
+  options: FetchAdapterOptions = {},
+): Adapter<FetchOperationArgs, Response> {
+  const fetchImplementation = options.fetch ?? globalThis.fetch
+  if (fetchImplementation === undefined) {
+    throw new Error("fetch is not available; provide FetchAdapterOptions.fetch")
+  }
+
+  return Object.freeze({
+    capabilities(args: FetchOperationArgs): OperationCapabilities {
+      const configured = options.replay
+      const replay =
+        typeof configured === "function"
+          ? configured(args)
+          : (configured ?? defaultReplay(args))
+      return { abort: "supported", replay }
+    },
+    async execute(
+      args: FetchOperationArgs,
+      context: ExecutionContext,
+    ): Promise<Response> {
+      const signal = combinedSignal(
+        urlSignal(args.url),
+        args.options?.signal ?? undefined,
+        context.signal,
+      )
+      return fetchImplementation(args.url, { ...args.options, signal })
+    },
+    classify(outcome: Outcome<Response>): Classification {
+      if (outcome.status === "failure") {
+        return options.classifyError?.(outcome.error) ?? "retryable"
+      }
+
+      return (
+        options.classifyResponse?.(outcome.value) ??
+        defaultResponseClassification(outcome.value)
+      )
+    },
+  })
+}

package/src/adapters/fetch/index.ts

@@ -0,0 +1,15 @@
+export type {
+  FetchAdapterOptions,
+  FetchOperationArgs,
+  FetchReplay,
+} from "./adapter.js"
+export { fetchAdapter } from "./adapter.js"
+export {
+  createRetryAfterDelay,
+  retryAfterDelay,
+  retryAfterMs,
+} from "./retry-after.js"
+export type {
+  RetryAfterDelay,
+  RetryAfterDelayOptions,
+} from "./retry-after.js"