@gkoos/caracal 0.1.0

package/dist/circuit-breaker-BSkcV0W_.d.ts

@@ -0,0 +1,296 @@
+import { d as ExecutionContext, P as Policy } from './types-Tf9T76C7.js';
+
+declare class BulkheadRejectedError extends Error {
+    readonly coordination: "local" | "distributed";
+    readonly policyName: string;
+    readonly scope: string;
+    readonly reason: string;
+    constructor(coordination: "local" | "distributed", policyName: string, scope: string, reason: string);
+}
+interface LocalBulkheadOptions {
+    readonly name: string;
+    readonly limit: number;
+    readonly queue?: {
+        readonly limit: number;
+        readonly timeoutMs: number;
+    };
+}
+/** Policy-specific capability supplied by caracal/redis. */
+interface BulkheadCoordinator {
+    command(identity: {
+        name: string;
+        operation: string;
+        scope: string;
+    }, action: "acquire" | "renew" | "release", token: string, leaseMs: number, limit: number): Promise<{
+        allowed: boolean;
+        occupancy: number;
+    }>;
+}
+interface DistributedBulkheadOptions {
+    readonly name: string;
+    readonly limit: number;
+    readonly coordinator: BulkheadCoordinator;
+    readonly scope: (context: ExecutionContext) => string;
+    readonly leaseMs?: number;
+}
+declare function local$1(options: LocalBulkheadOptions): Policy & {
+    readonly coordination: "local";
+    snapshot(): {
+        coordination: "local";
+        occupancy: number;
+        waiting: number;
+    };
+};
+declare function distributed$1(options: DistributedBulkheadOptions): Policy & {
+    readonly coordination: "distributed";
+};
+declare const bulkhead: Readonly<{
+    local: typeof local$1;
+    distributed: typeof distributed$1;
+}>;
+
+type BreakerState = "closed" | "open" | "half-open";
+/** Classification of an attempt outcome for circuit-breaker purposes. */
+type BreakerOutcome = "success" | "failure" | "ignored";
+/**
+ * Called after every attempt that the breaker observes.  Returning "ignored"
+ * means the outcome neither counts toward nor clears failures.
+ */
+type BreakerClassifier = (error: unknown, isSuccess: boolean) => BreakerOutcome;
+interface LocalBreakerOptions {
+    /** Identifies this policy in events and introspection. */
+    readonly name: string;
+    /**
+     * Minimum number of observations in the window before the breaker may open.
+     * Default: 5.
+     */
+    readonly minimumThroughput?: number;
+    /**
+     * Fraction of failures (0–1 exclusive) that triggers opening.
+     * Default: 0.5.
+     */
+    readonly failureThreshold?: number;
+    /**
+     * How long (ms) the breaker stays open before entering half-open.
+     * Default: 10 000.
+     */
+    readonly openMs?: number;
+    /**
+     * Number of consecutive successes needed to close from half-open.
+     * Default: 1.
+     */
+    readonly halfOpenSuccesses?: number;
+    /**
+     * Maximum concurrent probes allowed in half-open state.
+     * Default: 1.
+     */
+    readonly halfOpenProbes?: number;
+    /**
+     * Sliding-window size (number of observations retained).
+     * Default: 100.
+     */
+    readonly windowSize?: number;
+    /** Custom outcome classifier. Defaults to the adapter classification; retryable counts as failure. */
+    readonly classify?: BreakerClassifier;
+}
+interface BreakerSnapshot {
+    readonly coordination: "local";
+    readonly state: BreakerState;
+    readonly failures: number;
+    readonly successes: number;
+    readonly observations: number;
+    /** Only meaningful in half-open; number of probes currently in-flight. */
+    readonly probesInFlight: number;
+    /** Only meaningful in half-open; consecutive successes so far this epoch. */
+    readonly halfOpenSuccesses: number;
+}
+declare class CircuitOpenError extends Error {
+    readonly policyName: string;
+    readonly coordination: "local" | "distributed";
+    readonly scope: string;
+    constructor(policyName: string, coordination: "local" | "distributed", scope: string);
+}
+type LocalBreakerPolicy = Policy & {
+    readonly coordination: "local";
+    snapshot(): BreakerSnapshot;
+};
+declare function local(options: LocalBreakerOptions): LocalBreakerPolicy;
+interface BreakerIdentity {
+    readonly name: string;
+    readonly operation: string;
+    readonly scope: string;
+}
+type ObserveResult = {
+    readonly type: "stale";
+    readonly currentGeneration: number;
+} | {
+    readonly type: "observed";
+    readonly generation: number;
+    readonly windowTotal: number;
+    readonly windowFailures: number;
+} | {
+    readonly type: "opened";
+    readonly newGeneration: number;
+    readonly windowTotal: number;
+    readonly windowFailures: number;
+};
+type AdmitProbeResult = {
+    readonly type: "rejected";
+    readonly reason: "closed" | "open" | "probe-limit";
+    readonly generation: number;
+} | {
+    readonly type: "admitted";
+    readonly generation: number;
+    readonly probeCount: number;
+    readonly stateChanged: boolean;
+};
+type SettleProbeResult = {
+    readonly type: "stale";
+    readonly generation: number;
+} | {
+    readonly type: "settled";
+    readonly state: BreakerState;
+    readonly generation: number;
+} | {
+    readonly type: "transitioned";
+    readonly newState: BreakerState;
+    readonly newGeneration: number;
+    readonly previousState: "half-open";
+};
+/**
+ * Policy-specific coordinator capability for `circuitBreaker.distributed()`.
+ * The Redis implementation lives in `@gkoos/caracal/redis`; the memory implementation
+ * lives in `test/support/memory-coordinator` and must not be a production export.
+ */
+interface BreakerCoordinator {
+    readState(identity: BreakerIdentity): Promise<{
+        state: BreakerState;
+        generation: number;
+    } | null>;
+    observe(identity: BreakerIdentity, params: {
+        readonly generation: number;
+        readonly outcome: "success" | "failure";
+        readonly uuid: string;
+        readonly windowTtlMs: number;
+        readonly minimumThroughput: number;
+        readonly failureThresholdNumerator: number;
+        readonly windowSize: number;
+        readonly openMs: number;
+    }): Promise<ObserveResult>;
+    admitProbe(identity: BreakerIdentity, params: {
+        readonly probeToken: string;
+        readonly openMs: number;
+        readonly halfOpenProbes: number;
+        readonly probeLeaseTtlMs: number;
+    }): Promise<AdmitProbeResult>;
+    settleProbe(identity: BreakerIdentity, params: {
+        readonly probeToken: string;
+        readonly outcome: "success" | "failure";
+        readonly generation: number;
+        readonly halfOpenSuccesses: number;
+        readonly openMs: number;
+        /**
+         * Observation retention period, used as a floor for the CLOSED cleanup
+         * TTL: the state hash must not expire before the window it governs, or
+         * retained members would outlive their epoch.  Optional so that custom
+         * coordinators keep compiling; the policy always supplies it and the
+         * Redis coordinator falls back to `openMs × 2` when it is missing.
+         */
+        readonly windowTtlMs?: number;
+    }): Promise<SettleProbeResult>;
+}
+/**
+ * Distributed (Redis-backed) circuit breaker options.
+ *
+ * The defaults are mutually consistent.  Overriding one timer or count usually
+ * means revisiting the related ones; see the Redis coordination guide
+ * (`docs/redis.md`, "Keeping the breaker knobs consistent") for the constraints
+ * and the symptoms of getting them wrong.
+ */
+interface DistributedBreakerOptions {
+    /** Identifies this policy in events and introspection. */
+    readonly name: string;
+    /** Redis-backed coordinator.  See `redisCircuitBreakerCoordinator` in `@gkoos/caracal/redis`. */
+    readonly coordinator: BreakerCoordinator;
+    /**
+     * Maps an execution context to the coordination scope key.
+     * `scope: ctx => 'process'` is NOT local mode, it's still Redis-backed
+     * with full coordinator-failure semantics.
+     */
+    readonly scope: (context: ExecutionContext) => string;
+    /**
+     * Minimum observations in the window before the breaker may open.  Default: 20.
+     *
+     * Requires `windowSize >= minimumThroughput`; a smaller window can never
+     * reach this count, so the breaker would never open.
+     */
+    readonly minimumThroughput?: number;
+    /** Failure fraction (0–1 exclusive) that triggers opening.  Default: 0.5. */
+    readonly failureThreshold?: number;
+    /**
+     * Sliding-window size (observation count).  Default: 100.
+     *
+     * Must be at least `minimumThroughput`: the count cap trims the window, so a
+     * smaller window keeps the observed total below the opening threshold and the
+     * breaker never opens.
+     */
+    readonly windowSize?: number;
+    /**
+     * Observation retention period in ms.  Observations older than this are
+     * pruned regardless of `windowSize`.  Default: max(openMs × 3, 60_000).
+     *
+     * Must be long enough to accumulate `minimumThroughput` observations at your
+     * traffic rate.  If pruning fires first the window never fills and the
+     * breaker never opens; the default is a proxy for that, not a measurement.
+     */
+    readonly windowTtlMs?: number;
+    /** How long (ms) the breaker stays open before half-open.  Default: 30_000. */
+    readonly openMs?: number;
+    /** Maximum concurrent half-open probes per scope.  Default: 3. */
+    readonly halfOpenProbes?: number;
+    /**
+     * Probe successes needed to close from half-open.  Default: 2.
+     *
+     * Any probe failure resets progress back to OPEN, so a value that is large
+     * relative to the probe rate keeps traffic throttled long after the
+     * downstream recovered.
+     */
+    readonly halfOpenSuccesses?: number;
+    /**
+     * Probe token TTL in ms.  A dead worker's probe expires without blocking
+     * recovery.  Default: openMs × 2.
+     *
+     * Must exceed the slowest probe settle time (at least `timeoutMs`): if a live
+     * token expires mid-probe the slot is re-issued, more than `halfOpenProbes`
+     * probes run concurrently, and the late settle is dropped as stale.  It is
+     * also the worst case a HALF_OPEN window stalls while crashed workers hold
+     * every slot, so do not make it arbitrarily large.
+     */
+    readonly probeLeaseTtlMs?: number;
+    /**
+     * What to do when the coordinator is unreachable and the last known state
+     * for the scope was CLOSED (or no prior successful read has occurred).
+     * `"fail-open"` allows the attempt through (default).
+     * `"fail-closed"` rejects it with CircuitOpenError.
+     *
+     * If the last successfully-read state was OPEN or HALF_OPEN the attempt is
+     * always rejected, regardless of this setting.  Admitting work into a
+     * known-open breaker removes the protection it exists to provide.
+     *
+     * Coordinator unavailability during probe admission (after a successful
+     * readState that returned OPEN/HALF_OPEN) also always fails closed.
+     */
+    readonly onCoordinatorError?: "fail-open" | "fail-closed";
+    /** Custom outcome classifier.  Defaults to the adapter classification; retryable counts as failure. */
+    readonly classify?: BreakerClassifier;
+}
+type DistributedBreakerPolicy = Policy & {
+    readonly coordination: "distributed";
+};
+declare function distributed(options: DistributedBreakerOptions): DistributedBreakerPolicy;
+declare const circuitBreaker: Readonly<{
+    local: typeof local;
+    distributed: typeof distributed;
+}>;
+
+export { type AdmitProbeResult as A, type BreakerClassifier as B, CircuitOpenError as C, type DistributedBreakerOptions as D, type LocalBreakerOptions as L, type ObserveResult as O, type SettleProbeResult as S, type BreakerCoordinator as a, type BreakerIdentity as b, type BreakerOutcome as c, type BreakerSnapshot as d, type BreakerState as e, type BulkheadCoordinator as f, BulkheadRejectedError as g, type DistributedBulkheadOptions as h, type LocalBulkheadOptions as i, bulkhead as j, circuitBreaker as k };

package/dist/fetch.d.ts

@@ -0,0 +1,58 @@
+import { O as OperationCapabilities, C as Classification, A as Adapter } from './types-Tf9T76C7.js';
+import { R as RetryContext } from './retry-BFP_k3Hg.js';
+
+type FetchOperationArgs = Readonly<{
+    url: RequestInfo | URL;
+    options?: RequestInit;
+}>;
+type FetchReplay = OperationCapabilities["replay"] | ((args: FetchOperationArgs) => OperationCapabilities["replay"]);
+interface FetchAdapterOptions {
+    readonly fetch?: typeof globalThis.fetch;
+    readonly replay?: FetchReplay;
+    readonly classifyResponse?: (response: Response) => Classification;
+    readonly classifyError?: (error: unknown) => Classification;
+}
+/**
+ * Creates a fetch adapter with conservative per-request replay traits.
+ * It performs no implicit retry or timeout; those remain operation policies.
+ */
+declare function fetchAdapter(options?: FetchAdapterOptions): Adapter<FetchOperationArgs, Response>;
+
+/**
+ * Parses `Retry-After` (delta-seconds or HTTP-date) from a settled fetch
+ * outcome. Reads the response from `context.result`, or from
+ * `context.error` when a custom fetch implementation throws a
+ * response-bearing error.
+ *
+ * Returns `undefined` when no usable header is present. Malformed values
+ * are ignored rather than thrown.
+ */
+declare function retryAfterMs(context: RetryContext, now?: number): number | undefined;
+/** Options for `createRetryAfterDelay`. */
+interface RetryAfterDelayOptions {
+    /** Base of the exponential backoff in ms. Default: 100. */
+    readonly baseMs?: number;
+    /** Exponential growth factor (>= 1). Default: 2. */
+    readonly factor?: number;
+    /** Ceiling applied to the deterministic wait in ms. Default: 30 000. */
+    readonly maxDelayMs?: number;
+    /** Additive jitter as a fraction of the wait, within [0, 1]. Default: 0.1. */
+    readonly jitterRatio?: number;
+}
+/** A `RetryDelay` that reads `Retry-After` from the settled outcome. */
+type RetryAfterDelay = (attempt: number, context: RetryContext) => number;
+/**
+ * Builds a `RetryDelay` that waits for the longer of exponential backoff
+ * and the `Retry-After` the server sent, then adds additive jitter.
+ *
+ * Jitter only ever lengthens the wait, so a server-provided minimum is
+ * never retried early.
+ */
+declare function createRetryAfterDelay(options?: RetryAfterDelayOptions): RetryAfterDelay;
+/**
+ * Ready-to-use default: `retry({ maxAttempts: 3, delay: retryAfterDelay })`.
+ * Use `createRetryAfterDelay()` to change the pacing.
+ */
+declare const retryAfterDelay: RetryAfterDelay;
+
+export { type FetchAdapterOptions, type FetchOperationArgs, type FetchReplay, type RetryAfterDelay, type RetryAfterDelayOptions, createRetryAfterDelay, fetchAdapter, retryAfterDelay, retryAfterMs };

package/dist/fetch.js

@@ -0,0 +1,117 @@
+// src/adapters/fetch/adapter.ts
+function requestMethod(args) {
+  if (args.options?.method !== void 0) {
+    return args.options.method.toUpperCase();
+  }
+  if (args.url instanceof Request) {
+    return args.url.method.toUpperCase();
+  }
+  return "GET";
+}
+function defaultReplay(args) {
+  const method = requestMethod(args);
+  if (method === "GET" || method === "HEAD") {
+    return "safe";
+  }
+  if (method === "POST" || method === "PATCH") {
+    return "unsafe";
+  }
+  return "unknown";
+}
+function defaultResponseClassification(response) {
+  return response.status >= 500 || response.status === 408 || response.status === 429 ? "retryable" : "success";
+}
+function urlSignal(url) {
+  return url instanceof Request ? url.signal : void 0;
+}
+function combinedSignal(first, second, third) {
+  const signals = [first, second, third].filter(
+    (signal) => signal !== void 0
+  );
+  if (signals.length === 0) {
+    return void 0;
+  }
+  return signals.length === 1 ? signals[0] : AbortSignal.any(signals);
+}
+function fetchAdapter(options = {}) {
+  const fetchImplementation = options.fetch ?? globalThis.fetch;
+  if (fetchImplementation === void 0) {
+    throw new Error("fetch is not available; provide FetchAdapterOptions.fetch");
+  }
+  return Object.freeze({
+    capabilities(args) {
+      const configured = options.replay;
+      const replay = typeof configured === "function" ? configured(args) : configured ?? defaultReplay(args);
+      return { abort: "supported", replay };
+    },
+    async execute(args, context) {
+      const signal = combinedSignal(
+        urlSignal(args.url),
+        args.options?.signal ?? void 0,
+        context.signal
+      );
+      return fetchImplementation(args.url, { ...args.options, signal });
+    },
+    classify(outcome) {
+      if (outcome.status === "failure") {
+        return options.classifyError?.(outcome.error) ?? "retryable";
+      }
+      return options.classifyResponse?.(outcome.value) ?? defaultResponseClassification(outcome.value);
+    }
+  });
+}
+
+// src/adapters/fetch/retry-after.ts
+var DEFAULTS = {
+  baseMs: 100,
+  factor: 2,
+  maxDelayMs: 3e4,
+  jitterRatio: 0.1
+};
+var deltaSecondsPattern = /^\d+$/;
+function headersOf(value) {
+  if (typeof value !== "object" || value === null) return void 0;
+  const headers = value.headers;
+  if (typeof headers !== "object" || headers === null) return void 0;
+  const get = headers.get;
+  return typeof get === "function" ? headers : void 0;
+}
+function retryAfterMs(context, now = Date.now()) {
+  const headers = headersOf(context.result) ?? headersOf(context.error);
+  if (headers === void 0) return void 0;
+  const value = headers.get("retry-after")?.trim();
+  if (!value) return void 0;
+  if (deltaSecondsPattern.test(value)) {
+    const seconds = Number(value);
+    return Number.isSafeInteger(seconds) ? seconds * 1e3 : void 0;
+  }
+  const timestamp = Date.parse(value);
+  return Number.isNaN(timestamp) ? void 0 : Math.max(0, timestamp - now);
+}
+function createRetryAfterDelay(options = {}) {
+  const baseMs = options.baseMs ?? DEFAULTS.baseMs;
+  const factor = options.factor ?? DEFAULTS.factor;
+  const maxDelayMs = options.maxDelayMs ?? DEFAULTS.maxDelayMs;
+  const jitterRatio = options.jitterRatio ?? DEFAULTS.jitterRatio;
+  if (!Number.isFinite(baseMs) || baseMs < 0)
+    throw new RangeError("retryAfterDelay baseMs must be finite and >= 0");
+  if (!Number.isFinite(factor) || factor < 1)
+    throw new RangeError("retryAfterDelay factor must be finite and >= 1");
+  if (!Number.isFinite(maxDelayMs) || maxDelayMs < 0)
+    throw new RangeError("retryAfterDelay maxDelayMs must be finite and >= 0");
+  if (!Number.isFinite(jitterRatio) || jitterRatio < 0 || jitterRatio > 1)
+    throw new RangeError("retryAfterDelay jitterRatio must be within [0, 1]");
+  return (attempt, context) => {
+    const backoff = Math.min(baseMs * factor ** (attempt - 1), maxDelayMs);
+    const base = Math.min(
+      Math.max(backoff, retryAfterMs(context) ?? 0),
+      maxDelayMs
+    );
+    return base + Math.random() * base * jitterRatio;
+  };
+}
+var retryAfterDelay = createRetryAfterDelay();
+
+export { createRetryAfterDelay, fetchAdapter, retryAfterDelay, retryAfterMs };
+//# sourceMappingURL=fetch.js.map
+//# sourceMappingURL=fetch.js.map

package/dist/fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters/fetch/adapter.ts","../src/adapters/fetch/retry-after.ts"],"names":[],"mappings":"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","file":"fetch.js","sourcesContent":["import type {\n  Adapter,\n  Classification,\n  ExecutionContext,\n  OperationCapabilities,\n  Outcome,\n} from \"../../core/types.js\"\n\nexport type FetchOperationArgs = Readonly<{\n  url: RequestInfo | URL\n  options?: RequestInit\n}>\n\nexport type FetchReplay =\n  | OperationCapabilities[\"replay\"]\n  | ((args: FetchOperationArgs) => OperationCapabilities[\"replay\"])\n\nexport interface FetchAdapterOptions {\n  readonly fetch?: typeof globalThis.fetch\n  readonly replay?: FetchReplay\n  readonly classifyResponse?: (response: Response) => Classification\n  readonly classifyError?: (error: unknown) => Classification\n}\n\nfunction requestMethod(args: FetchOperationArgs): string {\n  if (args.options?.method !== undefined) {\n    return args.options.method.toUpperCase()\n  }\n\n  if (args.url instanceof Request) {\n    return args.url.method.toUpperCase()\n  }\n\n  return \"GET\"\n}\n\nfunction defaultReplay(\n  args: FetchOperationArgs,\n): OperationCapabilities[\"replay\"] {\n  const method = requestMethod(args)\n  if (method === \"GET\" || method === \"HEAD\") {\n    return \"safe\"\n  }\n\n  if (method === \"POST\" || method === \"PATCH\") {\n    return \"unsafe\"\n  }\n\n  return \"unknown\"\n}\n\nfunction defaultResponseClassification(response: Response): Classification {\n  return response.status >= 500 ||\n    response.status === 408 ||\n    response.status === 429\n    ? \"retryable\"\n    : \"success\"\n}\n\nfunction urlSignal(url: RequestInfo | URL): AbortSignal | undefined {\n  return url instanceof Request ? url.signal : undefined\n}\n\nfunction combinedSignal(\n  first: AbortSignal | undefined,\n  second: AbortSignal | undefined,\n  third: AbortSignal | undefined,\n): AbortSignal | undefined {\n  const signals = [first, second, third].filter(\n    (signal): signal is AbortSignal => signal !== undefined,\n  )\n  if (signals.length === 0) {\n    return undefined\n  }\n\n  return signals.length === 1 ? signals[0] : AbortSignal.any(signals)\n}\n\n/**\n * Creates a fetch adapter with conservative per-request replay traits.\n * It performs no implicit retry or timeout; those remain operation policies.\n */\nexport function fetchAdapter(\n  options: FetchAdapterOptions = {},\n): Adapter<FetchOperationArgs, Response> {\n  const fetchImplementation = options.fetch ?? globalThis.fetch\n  if (fetchImplementation === undefined) {\n    throw new Error(\"fetch is not available; provide FetchAdapterOptions.fetch\")\n  }\n\n  return Object.freeze({\n    capabilities(args: FetchOperationArgs): OperationCapabilities {\n      const configured = options.replay\n      const replay =\n        typeof configured === \"function\"\n          ? configured(args)\n          : (configured ?? defaultReplay(args))\n      return { abort: \"supported\", replay }\n    },\n    async execute(\n      args: FetchOperationArgs,\n      context: ExecutionContext,\n    ): Promise<Response> {\n      const signal = combinedSignal(\n        urlSignal(args.url),\n        args.options?.signal ?? undefined,\n        context.signal,\n      )\n      return fetchImplementation(args.url, { ...args.options, signal })\n    },\n    classify(outcome: Outcome<Response>): Classification {\n      if (outcome.status === \"failure\") {\n        return options.classifyError?.(outcome.error) ?? \"retryable\"\n      }\n\n      return (\n        options.classifyResponse?.(outcome.value) ??\n        defaultResponseClassification(outcome.value)\n      )\n    },\n  })\n}\n","import type { RetryContext } from \"../../core/retry.js\"\n\n/**\n * Opt-in retry pacing for `@gkoos/caracal/fetch` that honours the HTTP\n * `Retry-After` header. It is protocol-specific, so it lives with the\n * adapter rather than in the protocol-agnostic core.\n */\n\nconst DEFAULTS = {\n  baseMs: 100,\n  factor: 2,\n  maxDelayMs: 30_000,\n  jitterRatio: 0.1,\n} as const\n\nconst deltaSecondsPattern = /^\\d+$/\n\n/**\n * Structurally extracts a `Headers`-like object. `instanceof Response` is\n * unreliable across realms and custom fetch implementations.\n */\nfunction headersOf(value: unknown): Headers | undefined {\n  if (typeof value !== \"object\" || value === null) return undefined\n  const headers = (value as { headers?: unknown }).headers\n  if (typeof headers !== \"object\" || headers === null) return undefined\n  const get = (headers as { get?: unknown }).get\n  return typeof get === \"function\" ? (headers as Headers) : undefined\n}\n\n/**\n * Parses `Retry-After` (delta-seconds or HTTP-date) from a settled fetch\n * outcome. Reads the response from `context.result`, or from\n * `context.error` when a custom fetch implementation throws a\n * response-bearing error.\n *\n * Returns `undefined` when no usable header is present. Malformed values\n * are ignored rather than thrown.\n */\nexport function retryAfterMs(\n  context: RetryContext,\n  now: number = Date.now(),\n): number | undefined {\n  const headers = headersOf(context.result) ?? headersOf(context.error)\n  if (headers === undefined) return undefined\n\n  const value = headers.get(\"retry-after\")?.trim()\n  if (!value) return undefined\n\n  if (deltaSecondsPattern.test(value)) {\n    const seconds = Number(value)\n    return Number.isSafeInteger(seconds) ? seconds * 1000 : undefined\n  }\n\n  const timestamp = Date.parse(value)\n  return Number.isNaN(timestamp) ? undefined : Math.max(0, timestamp - now)\n}\n\n/** Options for `createRetryAfterDelay`. */\nexport interface RetryAfterDelayOptions {\n  /** Base of the exponential backoff in ms. Default: 100. */\n  readonly baseMs?: number\n  /** Exponential growth factor (>= 1). Default: 2. */\n  readonly factor?: number\n  /** Ceiling applied to the deterministic wait in ms. Default: 30 000. */\n  readonly maxDelayMs?: number\n  /** Additive jitter as a fraction of the wait, within [0, 1]. Default: 0.1. */\n  readonly jitterRatio?: number\n}\n\n/** A `RetryDelay` that reads `Retry-After` from the settled outcome. */\nexport type RetryAfterDelay = (attempt: number, context: RetryContext) => number\n\n/**\n * Builds a `RetryDelay` that waits for the longer of exponential backoff\n * and the `Retry-After` the server sent, then adds additive jitter.\n *\n * Jitter only ever lengthens the wait, so a server-provided minimum is\n * never retried early.\n */\nexport function createRetryAfterDelay(\n  options: RetryAfterDelayOptions = {},\n): RetryAfterDelay {\n  const baseMs = options.baseMs ?? DEFAULTS.baseMs\n  const factor = options.factor ?? DEFAULTS.factor\n  const maxDelayMs = options.maxDelayMs ?? DEFAULTS.maxDelayMs\n  const jitterRatio = options.jitterRatio ?? DEFAULTS.jitterRatio\n\n  if (!Number.isFinite(baseMs) || baseMs < 0)\n    throw new RangeError(\"retryAfterDelay baseMs must be finite and >= 0\")\n  if (!Number.isFinite(factor) || factor < 1)\n    throw new RangeError(\"retryAfterDelay factor must be finite and >= 1\")\n  if (!Number.isFinite(maxDelayMs) || maxDelayMs < 0)\n    throw new RangeError(\"retryAfterDelay maxDelayMs must be finite and >= 0\")\n  if (!Number.isFinite(jitterRatio) || jitterRatio < 0 || jitterRatio > 1)\n    throw new RangeError(\"retryAfterDelay jitterRatio must be within [0, 1]\")\n\n  return (attempt, context) => {\n    const backoff = Math.min(baseMs * factor ** (attempt - 1), maxDelayMs)\n    const base = Math.min(\n      Math.max(backoff, retryAfterMs(context) ?? 0),\n      maxDelayMs,\n    )\n    return base + Math.random() * base * jitterRatio\n  }\n}\n\n/**\n * Ready-to-use default: `retry({ maxAttempts: 3, delay: retryAfterDelay })`.\n * Use `createRetryAfterDelay()` to change the pacing.\n */\nexport const retryAfterDelay: RetryAfterDelay = createRetryAfterDelay()\n"]}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export { A as AdmitProbeResult, B as BreakerClassifier, a as BreakerCoordinator, b as BreakerIdentity, c as BreakerOutcome, d as BreakerSnapshot, e as BreakerState, f as BulkheadCoordinator, g as BulkheadRejectedError, C as CircuitOpenError, D as DistributedBreakerOptions, h as DistributedBulkheadOptions, L as LocalBreakerOptions, i as LocalBulkheadOptions, O as ObserveResult, S as SettleProbeResult, j as bulkhead, k as circuitBreaker } from './circuit-breaker-BSkcV0W_.js';
+import { a as OperationOptions, b as Operation, P as Policy } from './types-Tf9T76C7.js';
+export { A as Adapter, C as Classification, E as EventSink, c as EventSinks, d as ExecutionContext, e as ExecutionMetadata, N as Next, O as OperationCapabilities, f as OperationEvent, g as OperationExecuteOptions, h as Outcome, i as OutcomeClassifier } from './types-Tf9T76C7.js';
+export { R as RetryContext, a as RetryDelay, b as RetryOptions, r as retry } from './retry-BFP_k3Hg.js';
+
+/** Creates a named, protocol-agnostic operation. */
+declare function operation<Args, Result>(options: OperationOptions<Args, Result>): Operation<Args, Result>;
+
+declare class TimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+interface TimeoutOptions {
+    readonly ms: number;
+}
+/** Bounds caller wait time and requests cancellation only when the adapter supports it. */
+declare function timeout(options: TimeoutOptions): Policy;
+
+export { Operation, OperationOptions, Policy, TimeoutError, type TimeoutOptions, operation, timeout };