@selentia/async-retry

A zero-dependency retry policy library for Node.js and browsers.
It supports exponential backoff, Retry-After handling, AbortSignal integration, full jitter,
and an overall max elapsed time limit via maxElapsedMs. Runs on Node.js ≥18 and modern browsers.

Used in production by Pastellink, a Discord bot trusted by 2,500+ servers.

📄 Other languages:

• 🇰🇷 한국어 문서

---

Table of Contents

• Install
• Quick Start
  • retry
  • createRetry
• API
  • retry(task, options?) → Promise<T>
  • createRetry(defaultOptions) → (task, overrides?) => Promise<T>
  • Options
  • Retry-After semantics
  • Abort & Timeout semantics
  • Errors
  • Guarantees
• License

---

Install

npm i @selentia/async-retry

---

Quick Start

retry

import { retry } from '@selentia/async-retry';

const data = await retry(async ({ attempt }) => {
  const res = await fetch('/api/data');
  if (!res.ok) throw new Error(`HTTP ${res.status} (attempt=${attempt})`);
  return res.json();
});

createRetry

createRetry() applies default options and supports per-call overrides.

import { createRetry } from '@selentia/async-retry';

const retryFetch = createRetry({
  maxAttempts: 5,
  baseMs: 200,
  capMs: 4000,
  jitter: 'full',
});

const json = await retryFetch(
  async () => {
    const r = await fetch('/api/data');
    if (!r.ok) throw new Error(`HTTP ${r.status}`);
    return r.json();
  },
  {
    // per-call overrides (shallow merge)
    maxElapsedMs: 10_000,
  },
);

---

API

retry(task, options?) → Promise<T>

task receives a RetryContext:

await retry(async (ctx) => {
  ctx.attempt;      // 1..maxAttempts
  ctx.maxAttempts;  // max attempts
  ctx.startedAt;    // epoch ms when retry() started
  ctx.elapsedMs;    // elapsed ms since startedAt (int)
  ctx.signal;       // AbortSignal (if provided)
  return 'ok';
});

---

createRetry(defaultOptions) → (task, overrides?) => Promise<T>

Returns a retry-compatible function that applies defaultOptions first. Overrides are merged shallowly ({ ...defaultOptions, ...overrides }), so nested objects are not deep-merged.

---

Options

The following defaults are applied:

Option	Type	Default	Description
maxAttempts	number	3	Total attempts including the first call. Must be an integer ≥ 1.
baseMs	number	200	Base backoff (ms). Must be finite ≥ 0.
capMs	number	2000	Backoff cap (ms). Must be finite ≥ 0.
factor	number	2	Exponential factor. Must be finite > 0.
jitter	'full' | 'none'	'full'	Full jitter randomizes delay in [0, backoff).
rng	() => number	Math.random	Random source for jitter. Non-finite results are treated as 0.
signal	AbortSignal	undefined	Aborts the entire retry loop (including sleep).
maxElapsedMs	number	undefined	Overall time budget (ms), checked before each attempt and before sleeping.
shouldRetry	(err, ctx) => boolean | Promise<boolean>	defaultShouldRetry	Determines whether the error is retriable.
onRetry	(event) => void	undefined	Hook called immediately before sleeping.
wrapError	boolean	false	If true, wraps exhausted/non-retriable failures into RetryExhaustedError.
respectRetryAfter	boolean	true	If true, respects Retry-After for 429.
retryAfterHeaderName	string	'retry-after'	Header name (case-insensitive). Whitespace is trimmed; empty falls back to default.
retryAfterBodyUnit	false | 'seconds' | 'milliseconds'	false	If enabled, reads retry_after from the response body when the header is missing.

---

Retry-After semantics

When status === 429 and respectRetryAfter === true:

1. The Retry-After header is checked first (case-insensitive key match).

• Numeric values are treated as seconds.
• HTTP-date values are parsed and converted to max(0, date - now) in ms.

2. If there is no usable header and retryAfterBodyUnit !== false, a body value is used:

• Reads retry_after in the following order: err.response.data.retry_after, err.rawError.retry_after, err.data.retry_after
• String/number values are parsed; the unit is controlled by retryAfterBodyUnit.

If neither yields a usable delay, it falls back to regular exponential backoff.

Within onRetry(event), event.reason will be:

• 'retry-after' when Retry-After is used
• 'backoff' when exponential backoff is used

---

Abort & Timeout semantics

• If signal is already aborted before an attempt, retry() throws AbortError and does not call the task.
• If aborted during sleep, sleep is interrupted and AbortError is thrown.
• If the task throws an “abort-like” error (name === 'AbortError' or code === 'ABORT_ERR' / code === 'ERR_CANCELED'), it is propagated immediately (no retries).
• maxElapsedMs is enforced:
  • before each attempt
  • and before sleeping (so a long delay cannot exceed the budget)

---

Errors

These errors can be handled via instanceof.

Error	When it occurs
AbortError	The retry loop is aborted (before an attempt or during sleep).
RetryTimeoutError	The maxElapsedMs budget is exceeded (before an attempt or before sleeping).
RetryExhaustedError	wrapError=true and the loop ends due to exhaustion or a non-retriable decision (the original error is available as cause).

Example:

import { retry } from '@selentia/async-retry';
import { AbortError, RetryTimeoutError, RetryExhaustedError } from '@selentia/async-retry/errors';

try {
  await retry(async () => {
    // ...
  }, { maxElapsedMs: 2000, wrapError: true });
} catch (err) {
  if (err instanceof AbortError) {
    // aborted by signal
  } else if (err instanceof RetryTimeoutError) {
    // budget exceeded
  } else if (err instanceof RetryExhaustedError) {
    // exhausted or non-retriable (the original error is available as `err.cause`)
  }
}

---

Guarantees

• Attempts are 1-indexed: the first call is attempt = 1.
• maxAttempts is never exceeded.
• onRetry() is called only when a retry will actually happen, and it is called before sleeping.
• When Retry-After is used, jitter is not applied; the delay is taken as-is (normalized to a non-negative integer ms).
• All delays are normalized to integer milliseconds (>= 0).

---

License

MIT