@verifyhash/retry 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 verifyhash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,145 @@
+# @verifyhash/retry
+
+Zero-dependency async **retry with exponential backoff + jitter** for
+Node.js, typed from birth (hand-written `index.d.ts` ships with the
+package). The backoff model is the AWS-recommended one: the un-jittered
+delay is `min(minDelay * factor^(attempt-1), maxDelay)`, and the default
+`'full'` jitter multiplies it by a uniform random in `[0, 1)` — so 10
+clients that all fail at once do NOT hammer the server again in lockstep.
+
+Its distinguishing feature is **determinism without fake timers**: the
+backoff math lives in a pure, exported `computeDelay(attempt, opts, rand)`
+(the random source is an argument), and `retry()` accepts an injectable
+`sleep(ms, signal)`. Your tests pass a stub sleep that records the requested
+delays and resolves immediately, plus a fixed `rand` — every backoff vector
+is exact and the whole suite runs in milliseconds. This library's own
+70-check suite does exactly that (`node test/index.test.js` finishes in
+under 100 ms with zero dev dependencies).
+
+**Who it's for:** Node.js developers wrapping flaky calls (HTTP, DNS,
+databases, rate-limited APIs) who want cancellation via a standard
+`AbortSignal` — including **mid-sleep**, where naive implementations keep a
+dead timer pending — and who want to unit-test their retry policy exactly
+instead of sprinkling `jest.useFakeTimers()` around.
+
+**Honest limits:** JavaScript cannot interrupt a promise that is already
+running, so aborting does NOT cancel an in-flight `fn()` call — the abort
+takes effect at the next boundary (mid-sleep or before the next attempt).
+If you need the attempt itself cancelled, pass the same signal into `fn`
+(e.g. to `fetch`). There is also no retry budget/deadline option; compose
+one with `shouldRetry` if you need it.
+
+## Install
+
+```sh
+npm install @verifyhash/retry
+```
+
+## Example
+
+```js
+const { retry, computeDelay } = require('@verifyhash/retry');
+
+// Retry a flaky call up to 5 times: 100ms, 200ms, 400ms, 800ms base delays
+// (each multiplied by Math.random() under the default 'full' jitter).
+const controller = new AbortController();
+const data = await retry(
+  (attempt) => fetchThing({ signal: controller.signal, attempt }),
+  {
+    attempts: 5,
+    minDelay: 100,
+    maxDelay: 2000,               // caps the un-jittered delay
+    signal: controller.signal,    // abort() rejects promptly, even mid-sleep
+    shouldRetry: (err) => err.code !== 'FATAL', // give up on fatal errors
+    onRetry: (err, attempt, delay) =>
+      console.warn(`attempt ${attempt} failed (${err.message}), retrying in ${delay}ms`),
+  }
+);
+
+// The pure calculator, pinned exactly in tests via an injected rand:
+computeDelay(3, { minDelay: 100, factor: 2, jitter: 'none' });      // 400
+computeDelay(3, { minDelay: 100, factor: 2 }, () => 0.5);           // 200 (full jitter, rand=0.5)
+computeDelay(10, { minDelay: 100, maxDelay: 30000, jitter: 'none' }); // 30000 (clamped from 51200)
+```
+
+Deterministic testing pattern (what this library's own suite does — no fake
+timers, no real waiting):
+
+```js
+const { retry } = require('@verifyhash/retry');
+
+const delays = [];
+const stubSleep = (ms) => { delays.push(ms); return Promise.resolve(); };
+
+let n = 0;
+const v = await retry(() => { if (++n < 3) throw new Error('boom'); return 42; },
+  { attempts: 5, minDelay: 100, jitter: 'none', sleep: stubSleep });
+// v === 42, delays === [100, 200] — exact, instant.
+```
+
+## API
+
+### `retry(fn, options?) → Promise`
+
+Calls `fn(attempt)` (attempt is 1-based) until it resolves. Resolves with
+`fn`'s value. Rejects with:
+
+- the **last error**, once `attempts` are exhausted;
+- the error itself, immediately, when `shouldRetry(error, attempt)` returns
+  false (no sleep happens);
+- an **AbortError-shaped error** (`name: 'AbortError'`, `code: 'ABORT_ERR'`)
+  when `options.signal` aborts — before the first attempt, mid-sleep (the
+  default sleep clears its pending timer), or between attempts. No further
+  attempts run after an abort. If the signal was aborted with an `Error`
+  reason (Node's default reason is a DOMException named `AbortError`), that
+  reason is the rejection, matching `fetch()` semantics.
+
+Options (all optional):
+
+| option        | default       | meaning |
+| ------------- | ------------- | ------- |
+| `attempts`    | `3`           | total tries including the first (integer ≥ 1) |
+| `minDelay`    | `100`         | base delay in ms before the first retry |
+| `maxDelay`    | `30000`       | cap on the un-jittered delay (must be ≥ `minDelay`) |
+| `factor`      | `2`           | exponential base (≥ 1; `1` = flat backoff) |
+| `jitter`      | `'full'`      | `'full'` = delay × `rand()`; `'none'` = exact |
+| `signal`      | —             | `AbortSignal`; see abort semantics above |
+| `shouldRetry` | retry all     | `(error, attempt) => boolean \| Promise<boolean>` |
+| `onRetry`     | —             | `(error, attempt, delay)` hook, fired before each sleep |
+| `sleep`       | real timer    | injectable `(ms, signal) => Promise<void>` |
+| `rand`        | `Math.random` | injectable random source in `[0, 1)` for `'full'` jitter |
+
+Invalid options (e.g. `attempts: 0`, `jitter: 'half'`, `maxDelay <
+minDelay`) reject with `RangeError`/`TypeError`. Because `fn` cannot be
+interrupted, a value `fn` resolves AFTER an abort is still delivered.
+
+### `computeDelay(attempt, options?, rand?) → number`
+
+Pure backoff calculator used by `retry` and exported for exact tests and
+custom schedulers: `min(minDelay * factor^(attempt-1), maxDelay)`,
+multiplied by `rand()` when `jitter` is `'full'`. `attempt` is the 1-based
+attempt that just failed (integer ≥ 1, else `RangeError`). Accepts the same
+`minDelay`/`maxDelay`/`factor`/`jitter` options as `retry` and returns
+milliseconds (fractional under `'full'` jitter — e.g. `rand = () => 0.999`
+at attempt 1 gives `99.9`).
+
+TypeScript users also get the exported types `RetryOptions`,
+`BackoffOptions`, `Jitter`, `SleepFn`, and `RandomSource`.
+
+## How to test
+
+```sh
+cd retry
+node test/index.test.js   # 70 checks, zero dependencies, < 100 ms
+```
+
+The suite pins golden vectors for `computeDelay` (growth, clamp, both jitter
+modes with fixed `rand`), success-after-N-failures, exhaustion,
+`shouldRetry` short-circuit (sync and async), the `onRetry` call log, and
+three abort paths (pre-start, mid-sleep via a stub sleep, and mid-sleep
+through the real default `setTimeout` sleep — aborted synchronously, so even
+that test never actually waits).
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Type declarations for @verifyhash/retry — zero-dependency async retry with
+ * exponential backoff + jitter, deterministic in tests via an injectable
+ * sleep(ms, signal) and a pure computeDelay(attempt, opts, rand).
+ *
+ * Hand-written against index.js — every runtime export is declared here.
+ */
+
+/** Jitter mode: 'full' (default, delay = rand() * capped) or 'none' (exact). */
+export type Jitter = 'none' | 'full';
+
+/** The pure backoff shape shared by computeDelay() and retry(). */
+export interface BackoffOptions {
+  /** Base delay in ms before the first retry. Default 100. */
+  minDelay?: number;
+  /** Cap in ms applied to the un-jittered exponential delay. Default 30000. */
+  maxDelay?: number;
+  /** Exponential base: delay grows by factor^(attempt-1). Default 2. */
+  factor?: number;
+  /** 'full' (default) multiplies the capped delay by rand(); 'none' is exact. */
+  jitter?: Jitter;
+}
+
+/** A random source for 'full' jitter: must return a number in [0, 1). */
+export type RandomSource = () => number;
+
+/**
+ * An injectable sleep. Must resolve after ~ms milliseconds and SHOULD reject
+ * promptly (with an AbortError-shaped error) if `signal` aborts first — the
+ * default implementation (real setTimeout) does exactly that. Test stubs may
+ * simply record `ms` and resolve immediately.
+ */
+export type SleepFn = (ms: number, signal?: AbortSignal) => Promise<void>;
+
+/** Options for retry(). */
+export interface RetryOptions extends BackoffOptions {
+  /** Total tries including the first (integer >= 1). Default 3. */
+  attempts?: number;
+  /**
+   * Abort: rejects the retry() promise promptly with an AbortError-shaped
+   * error (name 'AbortError', code 'ABORT_ERR') — before the first attempt,
+   * mid-sleep, or between attempts — and stops all future attempts. An fn()
+   * call already in flight is NOT interrupted (JavaScript cannot cancel a
+   * running promise); the abort takes effect at the next boundary.
+   */
+  signal?: AbortSignal;
+  /**
+   * Decide whether `error` (from 1-based attempt `attempt`) is retryable.
+   * Returning false rejects retry() with that error immediately. May be
+   * async. Default: retry every error.
+   */
+  shouldRetry?: (error: unknown, attempt: number) => boolean | Promise<boolean>;
+  /** Fired before each backoff sleep with the failure, attempt, and delay ms. */
+  onRetry?: (error: unknown, attempt: number, delay: number) => void;
+  /** Injectable sleep; default is a real setTimeout with abort wiring. */
+  sleep?: SleepFn;
+  /** Injectable random source for 'full' jitter; default Math.random. */
+  rand?: RandomSource;
+}
+
+/**
+ * Run `fn` (called with the 1-based attempt number) until it resolves,
+ * attempts are exhausted (rejects with the LAST error), shouldRetry returns
+ * false (rejects with that error), or `signal` aborts (rejects with an
+ * AbortError-shaped error). Resolves with fn's value.
+ */
+export function retry<T>(
+  fn: (attempt: number) => T | PromiseLike<T>,
+  options?: RetryOptions
+): Promise<T>;
+
+/**
+ * Pure backoff calculator: min(minDelay * factor^(attempt-1), maxDelay),
+ * multiplied by rand() under 'full' jitter. `attempt` is 1-based (integer
+ * >= 1, else RangeError). Returns milliseconds, fractional under 'full'.
+ */
+export function computeDelay(
+  attempt: number,
+  options?: BackoffOptions,
+  rand?: RandomSource
+): number;

package/index.js

@@ -0,0 +1,179 @@
+'use strict';
+
+/**
+ * @verifyhash/retry — zero-dependency async retry with exponential backoff
+ * and jitter, designed to be deterministic in tests WITHOUT fake timers:
+ *
+ *   - computeDelay(attempt, opts, rand) is a PURE function (rand injectable,
+ *     default Math.random) so every backoff value can be pinned exactly.
+ *   - retry(fn, opts) accepts an injectable sleep(ms, signal) (default: real
+ *     setTimeout with AbortSignal wiring), so tests pass a stub sleep that
+ *     records requested delays and resolves immediately.
+ *
+ * Backoff model (AWS-style):
+ *   raw    = minDelay * factor^(attempt - 1)
+ *   capped = min(raw, maxDelay)
+ *   delay  = capped                 when jitter === 'none'
+ *   delay  = rand() * capped        when jitter === 'full' (default)
+ *
+ * Abort semantics: an aborted signal rejects the retry() promise promptly
+ * with an AbortError-shaped error (name 'AbortError', code 'ABORT_ERR') —
+ * before the first attempt, mid-sleep (the default sleep clears its timer),
+ * or between attempts. LIMIT: JavaScript cannot interrupt a running promise,
+ * so an fn() call already in flight is not cancelled; the abort takes effect
+ * at the next boundary. If fn() has already resolved, its value is delivered
+ * even if the signal aborted meanwhile.
+ */
+
+const DEFAULT_ATTEMPTS = 3;
+const DEFAULT_MIN_DELAY = 100;
+const DEFAULT_MAX_DELAY = 30000;
+const DEFAULT_FACTOR = 2;
+const DEFAULT_JITTER = 'full';
+
+/**
+ * Build the AbortError-shaped rejection for an aborted signal.
+ * If the signal was aborted with an Error reason (Node's default reason is a
+ * DOMException named 'AbortError', which IS an Error), that reason is used
+ * directly — matching fetch() semantics. A non-Error custom reason is kept
+ * on the constructed error's `cause`.
+ */
+function makeAbortError(signal) {
+  const reason = signal ? signal.reason : undefined;
+  if (reason instanceof Error) return reason;
+  const err = new Error('The operation was aborted');
+  err.name = 'AbortError';
+  err.code = 'ABORT_ERR';
+  if (reason !== undefined) err.cause = reason;
+  return err;
+}
+
+/** Validate + default the backoff-shape options shared by computeDelay/retry. */
+function normalizeBackoff(options) {
+  if (options === null || typeof options !== 'object') {
+    throw new TypeError('options must be an object');
+  }
+  const minDelay = options.minDelay === undefined ? DEFAULT_MIN_DELAY : options.minDelay;
+  const maxDelay = options.maxDelay === undefined ? DEFAULT_MAX_DELAY : options.maxDelay;
+  const factor = options.factor === undefined ? DEFAULT_FACTOR : options.factor;
+  const jitter = options.jitter === undefined ? DEFAULT_JITTER : options.jitter;
+
+  if (typeof minDelay !== 'number' || !Number.isFinite(minDelay) || minDelay < 0) {
+    throw new RangeError('minDelay must be a finite number >= 0');
+  }
+  if (typeof maxDelay !== 'number' || !Number.isFinite(maxDelay) || maxDelay < minDelay) {
+    throw new RangeError('maxDelay must be a finite number >= minDelay');
+  }
+  if (typeof factor !== 'number' || !Number.isFinite(factor) || factor < 1) {
+    throw new RangeError('factor must be a finite number >= 1');
+  }
+  if (jitter !== 'none' && jitter !== 'full') {
+    throw new TypeError("jitter must be 'none' or 'full'");
+  }
+  return { minDelay, maxDelay, factor, jitter };
+}
+
+/**
+ * Pure backoff calculator. `attempt` is 1-based: the delay AFTER attempt N
+ * failed (so attempt 1 -> minDelay before the cap/jitter). `rand` must return
+ * a number in [0, 1) and defaults to Math.random; inject a fixed function for
+ * exact, deterministic vectors in tests.
+ *
+ * Returns a number of milliseconds (may be fractional under 'full' jitter).
+ */
+function computeDelay(attempt, options = {}, rand = Math.random) {
+  if (typeof attempt !== 'number' || !Number.isInteger(attempt) || attempt < 1) {
+    throw new RangeError('attempt must be an integer >= 1');
+  }
+  if (typeof rand !== 'function') {
+    throw new TypeError('rand must be a function returning a number in [0, 1)');
+  }
+  const { minDelay, maxDelay, factor, jitter } = normalizeBackoff(options);
+  const raw = minDelay * Math.pow(factor, attempt - 1);
+  const capped = Math.min(raw, maxDelay);
+  if (jitter === 'none') return capped;
+  return rand() * capped; // 'full' jitter: uniform in [0, capped)
+}
+
+/**
+ * Default sleep: real setTimeout with abort wiring. Resolves after `ms`
+ * milliseconds, or rejects promptly with an AbortError-shaped error if
+ * `signal` aborts first (the pending timer is cleared, so the process does
+ * not linger). Also rejects immediately if `signal` is already aborted.
+ */
+function defaultSleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal && signal.aborted) {
+      reject(makeAbortError(signal));
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(makeAbortError(signal));
+    };
+    const timer = setTimeout(() => {
+      if (signal) signal.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    if (signal) signal.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+/**
+ * Retry `fn` (called with the 1-based attempt number) until it resolves,
+ * `attempts` are exhausted (rejects with the LAST error), `shouldRetry`
+ * returns false (rejects with that error immediately), or `signal` aborts
+ * (rejects with an AbortError-shaped error and never runs another attempt).
+ *
+ * Options (all optional):
+ *   attempts    total tries including the first (integer >= 1, default 3)
+ *   minDelay    base delay in ms before the first retry (default 100)
+ *   maxDelay    cap in ms on the un-jittered delay (default 30000)
+ *   factor     exponential base (default 2)
+ *   jitter     'full' (default) | 'none'
+ *   signal     AbortSignal
+ *   shouldRetry(error, attempt) -> boolean | Promise<boolean> (default: retry all)
+ *   onRetry(error, attempt, delay)   hook fired before each sleep
+ *   sleep(ms, signal) -> Promise     injectable, default real setTimeout
+ *   rand() -> number in [0, 1)       injectable, default Math.random
+ */
+async function retry(fn, options = {}) {
+  if (typeof fn !== 'function') {
+    throw new TypeError('fn must be a function');
+  }
+  const backoff = normalizeBackoff(options);
+  const attempts = options.attempts === undefined ? DEFAULT_ATTEMPTS : options.attempts;
+  if (typeof attempts !== 'number' || !Number.isInteger(attempts) || attempts < 1) {
+    throw new RangeError('attempts must be an integer >= 1');
+  }
+  const signal = options.signal;
+  const sleep = options.sleep === undefined ? defaultSleep : options.sleep;
+  const rand = options.rand === undefined ? Math.random : options.rand;
+  const shouldRetry = options.shouldRetry === undefined ? () => true : options.shouldRetry;
+  const onRetry = options.onRetry;
+  if (typeof sleep !== 'function') throw new TypeError('sleep must be a function');
+  if (typeof rand !== 'function') throw new TypeError('rand must be a function');
+  if (typeof shouldRetry !== 'function') throw new TypeError('shouldRetry must be a function');
+  if (onRetry !== undefined && typeof onRetry !== 'function') {
+    throw new TypeError('onRetry must be a function');
+  }
+
+  let lastError;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    if (signal && signal.aborted) throw makeAbortError(signal);
+    try {
+      return await fn(attempt);
+    } catch (err) {
+      lastError = err;
+    }
+    if (signal && signal.aborted) throw makeAbortError(signal);
+    if (attempt >= attempts) break; // exhausted: fall through to reject
+    if (!(await shouldRetry(lastError, attempt))) break; // short-circuit
+    const delay = computeDelay(attempt, backoff, rand);
+    if (onRetry) onRetry(lastError, attempt, delay);
+    await sleep(delay, signal); // an abort mid-sleep rejects here
+  }
+  throw lastError;
+}
+
+module.exports = { retry, computeDelay };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@verifyhash/retry",
+  "version": "0.1.0",
+  "description": "Zero-dependency async retry for Node.js with exponential backoff and full jitter (AWS-style), AbortSignal support that cancels even mid-sleep, shouldRetry/onRetry hooks, and injectable sleep + rand so tests are exact and instant without fake-timer libraries.",
+  "keywords": [
+    "retry",
+    "backoff",
+    "exponential-backoff",
+    "jitter",
+    "abortsignal",
+    "abort",
+    "async",
+    "promise",
+    "zero-dependency",
+    "typescript"
+  ],
+  "main": "index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "test": "node test/index.test.js"
+  },
+  "license": "MIT",
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE",
+    "index.d.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/verifyhash/libs.git",
+    "directory": "retry"
+  },
+  "homepage": "https://github.com/verifyhash/libs/tree/main/retry#readme",
+  "bugs": {
+    "url": "https://github.com/verifyhash/libs/issues"
+  }
+}