retry-kit

Zero-dependency async retry, exponential backoff, and timeout utilities. Works in Node and the browser, CommonJS and ESM, with full TypeScript types included.

No dependencies. No bloat. ~150 lines of actual logic.

Install

npm install retry-kit

Quick start

import { retry, withTimeout, sleep } from 'retry-kit';
// or: const { retry, withTimeout, sleep } = require('retry-kit');

// Retry a flaky call with exponential backoff + jitter
const data = await retry(() => fetch('/api/data').then(r => r.json()), {
  retries: 4,
  minDelay: 200,
  maxDelay: 5000
});

// Wrap any promise with a timeout
const result = await withTimeout(fetch('/api/slow'), 3000, 'API took too long');

// Plain sleep, abortable
await sleep(1000);

Combine retry + per-attempt timeout

import { retryWithTimeout } from 'retry-kit';

const data = await retryWithTimeout(
  () => fetch('/api/data').then(r => r.json()),
  { timeoutMs: 2000, retries: 3 }
);

API

retry(fn, options?)

Retries fn (sync or async) with exponential backoff.

| Option | Default | Description | |---|---|---| | retries | 3 | Retries after the first attempt | | minDelay | 200 | Base delay in ms | | maxDelay | 5000 | Cap on delay in ms | | factor | 2 | Exponential growth factor | | jitter | true | Randomize delay (full jitter) | | onRetry | – | (error, attempt) => void, called before each retry | | retryIf | – | (error) => boolean — return false to stop retrying immediately | | signal | – | AbortSignal to cancel retries/delays early |

withTimeout(promiseOrFn, ms, message?)

Races a promise (or promise-returning function) against a timeout. Rejects with TimeoutError if ms elapses first.

sleep(ms, options?)

Resolves after ms. Pass { signal } to make it abortable (rejects with AbortError).

retryWithTimeout(fn, options)

Same as retry, but wraps every individual attempt in withTimeout. Requires options.timeoutMs.

Errors

TimeoutError and AbortError are exported so you can instanceof check them.

Why not p-retry / async-retry?

Those are solid — this exists for people who want retry and timeout handling in one place, zero dependencies, and don't want to pull in a dependency tree for something this small.

License

MIT