@nodii/retry 0.0.0 → 0.1.0

package/dist/jitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jitter.js","sourceRoot":"","sources":["../src/jitter.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAKrB;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CACzB,CAAS,EACT,QAAwB,EACxB,MAAgB,EAChB,GAAyE;IAEzE,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjC,sCAAsC;QACtC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACrD,CAAC;IACD,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,MAAM;YACT,OAAO,CAAC,CAAC;QACX,KAAK,MAAM;YACT,UAAU;YACV,OAAO,MAAM,EAAE,GAAG,CAAC,CAAC;QACtB,KAAK,OAAO;YACV,qEAAqE;YACrE,OAAO,CAAC,GAAG,CAAC,GAAG,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACpC,KAAK,cAAc,CAAC,CAAC,CAAC;YACpB,2DAA2D;YAC3D,2DAA2D;YAC3D,MAAM,EAAE,GAAG,GAAG,CAAC,WAAW,CAAC;YAC3B,MAAM,EAAE,GAAG,GAAG,CAAC,eAAe,GAAG,CAAC,CAAC;YACnC,MAAM,IAAI,GAAG,EAAE,GAAG,EAAE,CAAC;YACrB,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/C,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,uBAAuB,CACrC,MAAmB,EACnB,OAAe,EACf,IAAoD;IAEpD,MAAM,MAAM,GAAG,mBAAmB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpD,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE;QAC/D,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,eAAe,EAAE,IAAI,CAAC,eAAe,IAAI,MAAM,CAAC,WAAW;KAC5D,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,MAAM,CAAC,mBAAmB;QACxC,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAC1C,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAmB,EACnB,KAAa,EACb,IAA4B;IAE5B,MAAM,MAAM,GAAG,IAAI,EAAE,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC;IAC3C,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC;IAClC,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC;QAClD,MAAM,CAAC,GAAG,uBAAuB,CAAC,MAAM,EAAE,OAAO,EAAE;YACjD,MAAM;YACN,eAAe,EAAE,QAAQ;SAC1B,CAAC,CAAC;QACH,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACZ,QAAQ,GAAG,CAAC,CAAC;IACf,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/policy.d.ts

@@ -0,0 +1,95 @@
+/**
+ * How the un-jittered delay grows with the attempt index.
+ *
+ * - `"exponential"` — `base · multiplier^(attempt-1)`. `multiplier: 1` gives a
+ *   CONSTANT delay (the six fixed-sleep sites).
+ * - `"linear"` — `base · attempt`. Exists because
+ *   `@nodii/outbox-dispatcher`'s claim query cools a row down by
+ *   `interval '1 minute' * publish_attempts`, which is linear, not
+ *   exponential. Modelling it as exponential would silently change the
+ *   dispatcher's re-claim schedule.
+ */
+export type GrowthKind = "exponential" | "linear";
+/**
+ * Jitter strategies.
+ *
+ * `d` below is the growth-computed, cap-clamped delay for the attempt.
+ *
+ * - `"none"` — `d`. What 11 of the 14 surveyed sites do today.
+ * - `"equal"` — `d/2 + U(0, d/2)` → `[d/2, d)`. **The default** (see README
+ *   § "Why equal jitter").
+ * - `"full"` — `U(0, d)` → `[0, d)`. Maximum dispersal, no floor.
+ * - `{ kind: "proportional", pct }` — `d · (1 + pct·U(-1, 1))` →
+ *   `[d(1-pct), d(1+pct))`. The shape both live jitter sites use
+ *   (role-catalog `pct: 0.125`, replica cold-start `pct: 0.2`), so their
+ *   migration can be behaviour-preserving.
+ * - `"decorrelated"` — `min(cap, U(base, 3·previous))`, seeded at `base`.
+ *   A self-contained recurrence: it IGNORES `growth` / `multiplier` entirely
+ *   and derives each delay from the previous one. Nothing in the fleet does
+ *   this today; it is offered, never defaulted.
+ */
+export type JitterStrategy = "none" | "full" | "equal" | "decorrelated" | {
+    kind: "proportional";
+    pct: number;
+};
+export interface RetryPolicy {
+    /**
+     * Total attempts INCLUDING the first (so `3` = 1 initial + 2 retries, which
+     * is what `@nodii/onboarding` means by `MAX_ATTEMPTS = 3`).
+     *
+     * `0` = retry INDEFINITELY — `@nodii/replica-consumer`'s cold-start backfill
+     * default, where giving up means silently dropping the backfill. The cap
+     * then bounds each DELAY, never the attempt count.
+     */
+    maxAttempts: number;
+    /** Delay before the FIRST retry, ms. Must be finite and >= 0. */
+    baseDelayMs: number;
+    /** Growth factor for `"exponential"`. `1` = constant. Ignored by `"linear"`. */
+    multiplier: number;
+    /** Ceiling on a single delay, ms. `Infinity` = uncapped. */
+    maxDelayMs: number;
+    /** How the un-jittered delay grows with the attempt index. */
+    growth: GrowthKind;
+    /** Jitter applied to the capped delay. */
+    jitter: JitterStrategy;
+    /**
+     * When `true`, jitter may push the delay ABOVE `maxDelayMs`.
+     *
+     * Both live jitter sites apply jitter AFTER the cap and never re-clamp, so
+     * `@nodii/role-catalog` can sleep 33.75s against a declared 30s cap and
+     * `@nodii/replica-consumer` can sleep 36s against the same declared cap.
+     * That is a bug: a cap that the code is allowed to exceed is not a cap. The
+     * DEFAULT here is `false` (clamp last — the cap holds unconditionally).
+     *
+     * Set `true` only to make a migration byte-for-byte behaviour-preserving
+     * against one of those two sites, and say so in the migration note.
+     */
+    allowJitterAboveCap: boolean;
+}
+/**
+ * Fleet default. Deliberately conservative: equal jitter (a growing FLOOR plus
+ * dispersal), a 30s ceiling (the value 3 of the 4 capped sites already use),
+ * and a finite attempt budget so a misconfigured caller cannot spin forever.
+ */
+export declare const DEFAULT_POLICY: RetryPolicy;
+/** Thrown by {@link resolvePolicy} on a policy that cannot produce sane delays. */
+export declare class InvalidRetryPolicyError extends Error {
+    constructor(message: string);
+}
+/**
+ * Fill a partial policy from {@link DEFAULT_POLICY} and VALIDATE it.
+ *
+ * Validation is not decoration: an unvalidated `multiplier: 0` silently turns
+ * every retry after the first into a zero-delay hot loop against a dependency
+ * that is already failing.
+ */
+export declare function resolvePolicy(partial?: Partial<RetryPolicy>): RetryPolicy;
+/**
+ * The un-jittered, cap-clamped delay for a 1-based `attempt`.
+ *
+ * `attempt` is the index of the RETRY about to be scheduled: `1` is the delay
+ * between the first failure and the second try, so `attempt === 1` yields
+ * `baseDelayMs`.
+ */
+export declare function baseDelayForAttempt(policy: RetryPolicy, attempt: number): number;
+//# sourceMappingURL=policy.d.ts.map

package/dist/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAqBA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG,QAAQ,CAAC;AAElD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,MAAM,GACN,OAAO,GACP,cAAc,GACd;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1C,MAAM,WAAW,WAAW;IAC1B;;;;;;;OAOG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,MAAM,EAAE,UAAU,CAAC;IACnB,0CAA0C;IAC1C,MAAM,EAAE,cAAc,CAAC;IACvB;;;;;;;;;;;OAWG;IACH,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,WAQ5B,CAAC;AAEF,mFAAmF;AACnF,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAUD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,WAAW,CAuDzE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,GACd,MAAM,CAuBR"}

package/dist/policy.js

@@ -0,0 +1,121 @@
+// The retry policy — the ONE shape that covers the union of what the fleet's
+// hand-rolled backoffs actually do.
+//
+// The requirements here are not invented. They are the union of the 14
+// hand-rolled implementations found inside ts/* on origin/main (see README
+// § "The survey"), which between them need:
+//
+//   - exponential growth   (approval 250ms×2, role-catalog 100ms×2,
+//                           replica cold-start 1000ms×2, replica apply 100ms×2)
+//   - LINEAR growth        (outbox-dispatcher's SQL cooldown is
+//                           `interval '1 minute' * publish_attempts`, i.e.
+//                           1,2,3,… minutes — NOT expressible as base·mult^n)
+//   - CONSTANT growth      (six fixed sleeps: 200ms, 250ms, pollMs, ttl/2, …)
+//   - a delay cap          (60s / 30s / uncapped)
+//   - a max-attempts cap   (3, 5, 8, 30 — and 0 = "retry indefinitely",
+//                           which replica-consumer's cold start relies on)
+//   - no jitter            (11 of 14 sites)
+//   - PROPORTIONAL jitter  (role-catalog ±12.5%, replica cold-start ±20%)
+//
+// Anything not in that list is not in this type.
+/**
+ * Fleet default. Deliberately conservative: equal jitter (a growing FLOOR plus
+ * dispersal), a 30s ceiling (the value 3 of the 4 capped sites already use),
+ * and a finite attempt budget so a misconfigured caller cannot spin forever.
+ */
+export const DEFAULT_POLICY = {
+    maxAttempts: 5,
+    baseDelayMs: 100,
+    multiplier: 2,
+    maxDelayMs: 30_000,
+    growth: "exponential",
+    jitter: "equal",
+    allowJitterAboveCap: false,
+};
+/** Thrown by {@link resolvePolicy} on a policy that cannot produce sane delays. */
+export class InvalidRetryPolicyError extends Error {
+    constructor(message) {
+        super(`invalid retry policy: ${message}`);
+        this.name = "InvalidRetryPolicyError";
+    }
+}
+function requireFiniteNonNegative(name, v) {
+    if (typeof v !== "number" || Number.isNaN(v) || v < 0) {
+        throw new InvalidRetryPolicyError(`${name} must be a number >= 0 (got ${v})`);
+    }
+}
+/**
+ * Fill a partial policy from {@link DEFAULT_POLICY} and VALIDATE it.
+ *
+ * Validation is not decoration: an unvalidated `multiplier: 0` silently turns
+ * every retry after the first into a zero-delay hot loop against a dependency
+ * that is already failing.
+ */
+export function resolvePolicy(partial) {
+    const p = { ...DEFAULT_POLICY, ...partial };
+    if (typeof p.maxAttempts !== "number" ||
+        !Number.isInteger(p.maxAttempts) ||
+        p.maxAttempts < 0) {
+        throw new InvalidRetryPolicyError(`maxAttempts must be an integer >= 0 (0 = unbounded) (got ${p.maxAttempts})`);
+    }
+    requireFiniteNonNegative("baseDelayMs", p.baseDelayMs);
+    if (!Number.isFinite(p.baseDelayMs)) {
+        throw new InvalidRetryPolicyError("baseDelayMs must be finite");
+    }
+    requireFiniteNonNegative("maxDelayMs", p.maxDelayMs);
+    if (typeof p.multiplier !== "number" ||
+        Number.isNaN(p.multiplier) ||
+        p.multiplier < 1) {
+        throw new InvalidRetryPolicyError(`multiplier must be >= 1 (got ${p.multiplier}) — a multiplier < 1 SHRINKS the delay each attempt, turning backoff into a hot loop`);
+    }
+    if (p.growth !== "exponential" && p.growth !== "linear") {
+        throw new InvalidRetryPolicyError(`growth must be "exponential" | "linear" (got ${String(p.growth)})`);
+    }
+    if (typeof p.jitter === "object") {
+        if (p.jitter === null || p.jitter.kind !== "proportional") {
+            throw new InvalidRetryPolicyError(`unknown jitter strategy ${JSON.stringify(p.jitter)}`);
+        }
+        const { pct } = p.jitter;
+        if (typeof pct !== "number" || Number.isNaN(pct) || pct < 0 || pct > 1) {
+            throw new InvalidRetryPolicyError(`proportional jitter pct must be a FRACTION in [0, 1] (got ${pct}) — note @nodii/replica-consumer carries two conflicting units for this field: start.ts uses 0.2 and define-replica.ts/init.ts use 25`);
+        }
+    }
+    else if (p.jitter !== "none" &&
+        p.jitter !== "full" &&
+        p.jitter !== "equal" &&
+        p.jitter !== "decorrelated") {
+        throw new InvalidRetryPolicyError(`unknown jitter strategy ${String(p.jitter)}`);
+    }
+    return p;
+}
+/**
+ * The un-jittered, cap-clamped delay for a 1-based `attempt`.
+ *
+ * `attempt` is the index of the RETRY about to be scheduled: `1` is the delay
+ * between the first failure and the second try, so `attempt === 1` yields
+ * `baseDelayMs`.
+ */
+export function baseDelayForAttempt(policy, attempt) {
+    if (!Number.isInteger(attempt) || attempt < 1) {
+        throw new InvalidRetryPolicyError(`attempt must be an integer >= 1 (got ${attempt})`);
+    }
+    // A zero base is a zero delay at every attempt — `0 · multiplier^n` is 0 for
+    // any finite factor. Handled FIRST because `multiplier^n` overflows to
+    // Infinity for large n and `0 * Infinity` is NaN, which the guard below
+    // would otherwise resolve to the CAP. (Caught by its own test: the
+    // counting-only sites — replica-consumer + telemetry apply retries — declare
+    // baseDelayMs 0 because their spacing comes from Redis PEL redelivery, and
+    // silently promoting that to a 30s cap would be a fabricated sleep.)
+    if (policy.baseDelayMs === 0)
+        return 0;
+    const raw = policy.growth === "linear"
+        ? policy.baseDelayMs * attempt
+        : policy.baseDelayMs * policy.multiplier ** (attempt - 1);
+    // Genuine overflow: `base · mult^n` exceeds Number.MAX_VALUE for large n.
+    // The sequence is monotone non-decreasing, so anything past the cap IS the
+    // cap.
+    if (!Number.isFinite(raw))
+        return policy.maxDelayMs;
+    return Math.min(raw, policy.maxDelayMs);
+}
+//# sourceMappingURL=policy.js.map

package/dist/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"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"}

package/dist/run.d.ts

@@ -0,0 +1,83 @@
+import { type ShouldRetry } from "./classify.js";
+import { type RandomFn } from "./jitter.js";
+import { type RetryPolicy } from "./policy.js";
+/**
+ * Injectable sleep — THE clock seam. Tests pass a recorder that returns
+ * immediately, so a suite that exercises a 30s cap still finishes in
+ * milliseconds. A test suite that actually waits 30s is a test suite that
+ * gets muted.
+ */
+export type SleepFn = (ms: number, signal?: AbortSignal) => Promise<void>;
+/** Default sleep: `setTimeout`, `unref`'d where available, abort-aware. */
+export declare const defaultSleep: SleepFn;
+/** State passed into each attempt. */
+export interface AttemptContext {
+    /** 1-based index of the attempt about to run. */
+    attempt: number;
+    /**
+     * Is this the LAST attempt the budget allows? Always `false` when
+     * `maxAttempts === 0` (unbounded). Correct at the boundary — see
+     * `./attempts.ts` for why that sentence needs saying.
+     */
+    isFinalAttempt: boolean;
+    /** Retries left after this one; `Infinity` when unbounded. */
+    remaining: number;
+    /** The error that ended the previous attempt, if any. */
+    previousError: unknown;
+}
+/** Payload for the `onRetry` telemetry hook. */
+export interface RetryEvent {
+    /** 1-based index of the attempt that just FAILED. */
+    attempt: number;
+    /** 1-based index of the attempt that will run after the delay. */
+    nextAttempt: number;
+    /** The delay actually slept, ms (post-jitter, post-clamp). */
+    delayMs: number;
+    /** The error that triggered the retry. */
+    error: unknown;
+}
+/** Payload for the `onExhausted` hook. */
+export interface ExhaustedEvent {
+    /** Attempts actually made. */
+    attempts: number;
+    /** The final error. */
+    error: unknown;
+}
+export interface RetryOptions {
+    /** Partial policy; unset fields come from `DEFAULT_POLICY`. */
+    policy?: Partial<RetryPolicy>;
+    /** Terminal-vs-transient seam. Default {@link retryAll}. */
+    shouldRetry?: ShouldRetry;
+    /** Fired BEFORE each backoff sleep. Telemetry only — it cannot veto. */
+    onRetry?: (event: RetryEvent) => void | Promise<void>;
+    /** Fired once when the attempt budget is spent. */
+    onExhausted?: (event: ExhaustedEvent) => void | Promise<void>;
+    /** Clock seam. Default {@link defaultSleep}. */
+    sleep?: SleepFn;
+    /** RNG seam for jitter. Default `Math.random`. */
+    random?: RandomFn;
+    /** Aborts the backoff sleep AND stops further attempts. */
+    signal?: AbortSignal;
+    /**
+     * Wrap the final error in {@link RetryExhaustedError}. Default `false` —
+     * the LAST error is rethrown as-is so caller `instanceof` checks survive.
+     */
+    wrapExhausted?: boolean;
+}
+/**
+ * Run `fn` under a retry policy.
+ *
+ * Guarantees, each of which has a test that goes red when the guard is broken:
+ *   - exactly `maxAttempts` invocations of `fn` in the worst case
+ *     (`maxAttempts: 0` = unbounded);
+ *   - exactly `attempts - 1` sleeps, whose durations match
+ *     `backoffSequence(policy, …)`;
+ *   - NO sleep after the final attempt (a trailing sleep is a wasted
+ *     shutdown-delay and hides the failure by the length of the cap);
+ *   - `shouldRetry === false` short-circuits with ZERO further sleeps;
+ *   - `NonRetryableError` bypasses `shouldRetry` entirely;
+ *   - an `onRetry` that throws never converts a retryable failure into a
+ *     crash (telemetry must not be load-bearing).
+ */
+export declare function retry<T>(fn: (ctx: AttemptContext) => T | Promise<T>, opts?: RetryOptions): Promise<T>;
+//# sourceMappingURL=run.d.ts.map

package/dist/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAY,MAAM,eAAe,CAAC;AAE3D,OAAO,EAAE,KAAK,QAAQ,EAA2B,MAAM,aAAa,CAAC;AAErE,OAAO,EAAE,KAAK,WAAW,EAAiB,MAAM,aAAa,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1E,2EAA2E;AAC3E,eAAO,MAAM,YAAY,EAAE,OAkBvB,CAAC;AAEL,sCAAsC;AACtC,MAAM,WAAW,cAAc;IAC7B,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,cAAc,EAAE,OAAO,CAAC;IACxB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,gDAAgD;AAChD,MAAM,WAAW,UAAU;IACzB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,0CAA0C;AAC1C,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,uBAAuB;IACvB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC9B,4DAA4D;IAC5D,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,wEAAwE;IACxE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,mDAAmD;IACnD,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,gDAAgD;IAChD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,kDAAkD;IAClD,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,KAAK,CAAC,CAAC,EAC3B,EAAE,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC3C,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC,CAAC,CAAC,CAgFZ"}

package/dist/run.js

@@ -0,0 +1,113 @@
+import { retryAll } from "./classify.js";
+import { NonRetryableError, RetryExhaustedError } from "./errors.js";
+import { jitteredDelayForAttempt } from "./jitter.js";
+import { isFinalAttempt, remainingAttempts } from "./attempts.js";
+import { resolvePolicy } from "./policy.js";
+/** Default sleep: `setTimeout`, `unref`'d where available, abort-aware. */
+export const defaultSleep = (ms, signal) => new Promise((resolve) => {
+    if (signal?.aborted) {
+        resolve();
+        return;
+    }
+    const t = setTimeout(resolve, ms);
+    // Node/Bun timers expose unref(); browsers do not. Never let a pending
+    // backoff hold a process open past its work.
+    t.unref?.();
+    signal?.addEventListener("abort", () => {
+        clearTimeout(t);
+        resolve();
+    }, { once: true });
+});
+/**
+ * Run `fn` under a retry policy.
+ *
+ * Guarantees, each of which has a test that goes red when the guard is broken:
+ *   - exactly `maxAttempts` invocations of `fn` in the worst case
+ *     (`maxAttempts: 0` = unbounded);
+ *   - exactly `attempts - 1` sleeps, whose durations match
+ *     `backoffSequence(policy, …)`;
+ *   - NO sleep after the final attempt (a trailing sleep is a wasted
+ *     shutdown-delay and hides the failure by the length of the cap);
+ *   - `shouldRetry === false` short-circuits with ZERO further sleeps;
+ *   - `NonRetryableError` bypasses `shouldRetry` entirely;
+ *   - an `onRetry` that throws never converts a retryable failure into a
+ *     crash (telemetry must not be load-bearing).
+ */
+export async function retry(fn, opts = {}) {
+    const policy = resolvePolicy(opts.policy);
+    const shouldRetry = opts.shouldRetry ?? retryAll;
+    const sleep = opts.sleep ?? defaultSleep;
+    const random = opts.random ?? Math.random;
+    let previousError = undefined;
+    let previousDelayMs = policy.baseDelayMs;
+    // ONE termination guard, deliberately. An earlier draft also bounded the
+    // loop with `attempt <= maxAttempts`; mutation testing proved that condition
+    // unreachable — `isFinalAttempt` always breaks first — i.e. it was dead code
+    // that no test could kill. Two guards for one invariant means one of them is
+    // untested by construction, so the redundant one is gone. `isFinalAttempt`
+    // is `false` forever when `maxAttempts === 0`, which IS the unbounded case.
+    for (let attempt = 1;; attempt++) {
+        const final = isFinalAttempt(attempt, policy.maxAttempts);
+        try {
+            return await fn({
+                attempt,
+                isFinalAttempt: final,
+                remaining: remainingAttempts(attempt, policy.maxAttempts),
+                previousError,
+            });
+        }
+        catch (err) {
+            previousError = err;
+            // The operation's own terminal verdict outranks the caller's predicate.
+            if (err instanceof NonRetryableError)
+                throw err;
+            if (final)
+                break;
+            if (!shouldRetry(err, { attempt, maxAttempts: policy.maxAttempts })) {
+                throw err;
+            }
+            if (opts.signal?.aborted)
+                throw err;
+            const delayMs = jitteredDelayForAttempt(policy, attempt, {
+                random,
+                previousDelayMs,
+            });
+            previousDelayMs = delayMs;
+            if (opts.onRetry) {
+                try {
+                    await opts.onRetry({
+                        attempt,
+                        nextAttempt: attempt + 1,
+                        delayMs,
+                        error: err,
+                    });
+                }
+                catch {
+                    // Telemetry is never load-bearing: a failing metrics sink must not
+                    // turn a retryable error into a crash. Same posture as
+                    // replica-consumer's guarded audit emit.
+                }
+            }
+            await sleep(delayMs, opts.signal);
+            // Aborted DURING the sleep — stop, surface the last real error rather
+            // than inventing an abort error the caller has no handler for.
+            if (opts.signal?.aborted)
+                throw err;
+        }
+    }
+    // Budget spent.
+    const attempts = policy.maxAttempts;
+    if (opts.onExhausted) {
+        try {
+            await opts.onExhausted({ attempts, error: previousError });
+        }
+        catch {
+            // as above
+        }
+    }
+    if (opts.wrapExhausted) {
+        throw new RetryExhaustedError(attempts, previousError);
+    }
+    throw previousError;
+}
+//# sourceMappingURL=run.js.map

package/dist/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAiB,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,EAAoB,aAAa,EAAE,MAAM,aAAa,CAAC;AAU9D,2EAA2E;AAC3E,MAAM,CAAC,MAAM,YAAY,GAAY,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,CAClD,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;IAC5B,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;QACpB,OAAO,EAAE,CAAC;QACV,OAAO;IACT,CAAC;IACD,MAAM,CAAC,GAAkC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IACjE,uEAAuE;IACvE,6CAA6C;IAC5C,CAAuC,CAAC,KAAK,EAAE,EAAE,CAAC;IACnD,MAAM,EAAE,gBAAgB,CACtB,OAAO,EACP,GAAG,EAAE;QACH,YAAY,CAAC,CAAC,CAAC,CAAC;QAChB,OAAO,EAAE,CAAC;IACZ,CAAC,EACD,EAAE,IAAI,EAAE,IAAI,EAAE,CACf,CAAC;AACJ,CAAC,CAAC,CAAC;AA4DL;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,EAA2C,EAC3C,OAAqB,EAAE;IAEvB,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,QAAQ,CAAC;IACjD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,YAAY,CAAC;IACzC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC;IAE1C,IAAI,aAAa,GAAY,SAAS,CAAC;IACvC,IAAI,eAAe,GAAG,MAAM,CAAC,WAAW,CAAC;IAEzC,yEAAyE;IACzE,6EAA6E;IAC7E,6EAA6E;IAC7E,6EAA6E;IAC7E,2EAA2E;IAC3E,4EAA4E;IAC5E,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;QAClC,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;QAC1D,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,CAAC;gBACd,OAAO;gBACP,cAAc,EAAE,KAAK;gBACrB,SAAS,EAAE,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,WAAW,CAAC;gBACzD,aAAa;aACd,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,aAAa,GAAG,GAAG,CAAC;YAEpB,wEAAwE;YACxE,IAAI,GAAG,YAAY,iBAAiB;gBAAE,MAAM,GAAG,CAAC;YAEhD,IAAI,KAAK;gBAAE,MAAM;YAEjB,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;gBACpE,MAAM,GAAG,CAAC;YACZ,CAAC;YAED,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO;gBAAE,MAAM,GAAG,CAAC;YAEpC,MAAM,OAAO,GAAG,uBAAuB,CAAC,MAAM,EAAE,OAAO,EAAE;gBACvD,MAAM;gBACN,eAAe;aAChB,CAAC,CAAC;YACH,eAAe,GAAG,OAAO,CAAC;YAE1B,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACjB,IAAI,CAAC;oBACH,MAAM,IAAI,CAAC,OAAO,CAAC;wBACjB,OAAO;wBACP,WAAW,EAAE,OAAO,GAAG,CAAC;wBACxB,OAAO;wBACP,KAAK,EAAE,GAAG;qBACX,CAAC,CAAC;gBACL,CAAC;gBAAC,MAAM,CAAC;oBACP,mEAAmE;oBACnE,uDAAuD;oBACvD,yCAAyC;gBAC3C,CAAC;YACH,CAAC;YAED,MAAM,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YAElC,sEAAsE;YACtE,+DAA+D;YAC/D,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO;gBAAE,MAAM,GAAG,CAAC;QACtC,CAAC;IACH,CAAC;IAED,gBAAgB;IAChB,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC;IACpC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACrB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,WAAW,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC,CAAC;QAC7D,CAAC;QAAC,MAAM,CAAC;YACP,WAAW;QACb,CAAC;IACH,CAAC;IACD,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;QACvB,MAAM,IAAI,mBAAmB,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;IACzD,CAAC;IACD,MAAM,aAAa,CAAC;AACtB,CAAC"}

package/package.json

@@ -1,10 +1,39 @@
 {
   "name": "@nodii/retry",
-  "version": "0.0.0",
-  "description": "Placeholder claim \u2014 real package ships from cognion-nucleus/nodii-libs via trusted publishing.",
-  "main": "index.js",
-  "license": "UNLICENSED",
+  "version": "0.1.0",
+  "description": "The retry / exponential-backoff / jitter policy for the Nodii microservice stack, as a real package. Consolidates 14 hand-rolled backoff implementations that had drifted across the shared libraries themselves (250ms/2x/60s no-jitter, 100ms/2x/30s ±12.5%, 1000ms/2x/30s ±20%, a linear 1-min-per-attempt SQL cooldown, and six fixed sleeps) into one injectable-clock policy with a shouldRetry seam, an onRetry telemetry hook, and a BullMQ attemptsMade post-increment adapter.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.13",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cognion-nucleus/nodii-libs.git",
+    "directory": "ts/retry"
   }
-}
+}

package/index.js

@@ -1 +0,0 @@
-// placeholder — real package ships from nodii-libs release.yml