fetch-resilience

Composable resilience policies for native fetch and any async function. Inspired by Polly and Cockatiel, but built from scratch with modern constraints in mind.

• Zero dependencies — pure TypeScript, nothing to audit
• Edge-safe — runs in Node.js, Bun, Deno, and Cloudflare Workers. No Node.js-specific APIs (setTimeout through standard timers, AbortController for cancellation)
• Composable — stack policies like middleware: wrap(fetch, [timeout, retry, circuitBreaker])
• Type-safe — full TypeScript with generics, works with any () => Promise<T>

Why not opossum or cockatiel?

| | fetch-resilience | opossum | cockatiel | |---|---|---|---| | Zero deps | Yes | No (6+) | No (2+) | | Edge runtime safe | Yes | No (uses Node EventEmitter) | Partial | | Composable wrap() | Yes | No (single policy per breaker) | Yes | | Bundle size | ~2KB | ~15KB | ~8KB | | Native fetch focus | Yes | Generic | Generic |

Install

npm install fetch-resilience

Quick Start

import { wrap, retry, timeout, circuitBreaker, bulkhead } from 'fetch-resilience';

const resilientFetch = wrap(fetch, [
  timeout({ ms: 5000 }),
  circuitBreaker({ threshold: 5, halfOpenAfter: 30000 }),
  bulkhead({ maxConcurrent: 10 }),
  retry({ attempts: 3, backoff: 'exponential', delayMs: 200 }),
]);

// Use exactly like fetch
const response = await resilientFetch('https://api.example.com/data');

Policies are applied outer-to-inner. In the example above, the call flows: timeout → circuitBreaker → bulkhead → retry → fetch

If the retry loop takes longer than 5 seconds total, timeout kills the entire operation.

API

retry(options)

Retries failed requests with configurable backoff.

import { retry } from 'fetch-resilience';

const policy = retry({
  attempts: 3,                          // max retries (not counting initial attempt)
  backoff: 'exponential',               // 'fixed' | 'linear' | 'exponential'
  delayMs: 200,                         // base delay in ms (default: 100)
  jitter: true,                         // add random jitter (default: false)
  retryOn: [429, 500, 502, 503, 504],   // HTTP status codes to retry (defaults shown)
  retryOnError: true,                   // retry on network errors (default: true)
});

const result = await policy.execute(() => fetch('https://api.example.com'));

Backoff strategies:

• fixed — always waits delayMs
• linear — waits delayMs * attempt (100, 200, 300...)
• exponential — waits delayMs * 2^attempt (200, 400, 800...)
• With jitter: true, adds Math.random() * delayMs to each delay

timeout(options)

Aborts the operation after a deadline using AbortController.

import { timeout, TimeoutError } from 'fetch-resilience';

const policy = timeout({ ms: 3000 });

try {
  const result = await policy.execute(() => fetch('https://slow-api.example.com'));
} catch (err) {
  if (err instanceof TimeoutError) {
    console.log('Request timed out');
  }
}

circuitBreaker(options)

Implements the circuit breaker pattern with three states:

• Closed (normal) — requests flow through. Consecutive failures are counted.
• Open — all requests are immediately rejected with CircuitOpenError. Entered after threshold consecutive failures.
• Half-open — after halfOpenAfter ms, one probe request is allowed through. Success closes the circuit; failure reopens it.

import { circuitBreaker, CircuitOpenError } from 'fetch-resilience';

const policy = circuitBreaker({
  threshold: 5,          // open after 5 consecutive failures
  halfOpenAfter: 30000,  // try again after 30 seconds
  onStateChange: (state) => {
    console.log(`Circuit is now: ${state}`);  // 'closed' | 'open' | 'half-open'
  },
});

try {
  const result = await policy.execute(() => fetch('https://api.example.com'));
} catch (err) {
  if (err instanceof CircuitOpenError) {
    console.log('Circuit is open — not even trying');
  }
}

bulkhead(options)

Limits concurrent executions. Excess calls are queued (or rejected if the queue is full).

import { bulkhead, BulkheadRejectedError } from 'fetch-resilience';

const policy = bulkhead({
  maxConcurrent: 10,   // max 10 simultaneous executions
  maxQueue: 100,       // max 100 waiting in queue (default: unlimited)
});

try {
  const result = await policy.execute(() => fetch('https://api.example.com'));
} catch (err) {
  if (err instanceof BulkheadRejectedError) {
    console.log('Too many requests queued');
  }
}

wrap(fn, policies)

Composes multiple policies around a function. Policies are applied outer-to-inner — the first policy in the array is the outermost wrapper.

import { wrap, retry, timeout } from 'fetch-resilience';

// timeout wraps retry wraps fetch
const resilientFetch = wrap(fetch, [
  timeout({ ms: 5000 }),
  retry({ attempts: 3, delayMs: 100 }),
]);

const response = await resilientFetch('https://api.example.com/users', {
  method: 'POST',
  body: JSON.stringify({ name: 'Alice' }),
});

Works with any async function, not just fetch:

async function queryDatabase(sql: string): Promise<Row[]> { /* ... */ }

const resilientQuery = wrap(queryDatabase, [
  timeout({ ms: 2000 }),
  retry({ attempts: 2, delayMs: 500, retryOnError: true }),
]);

const rows = await resilientQuery('SELECT * FROM users');

Using policies directly

Every policy implements the Policy<T> interface with a single execute method:

import { retry } from 'fetch-resilience';
import type { Policy } from 'fetch-resilience';

const policy: Policy<Response> = retry({ attempts: 3 });
const response = await policy.execute(() => fetch('https://example.com'));

Edge Runtime Compatibility

fetch-resilience uses only standard web APIs available across all modern runtimes:

| API Used | Node.js | Bun | Deno | Cloudflare Workers | |----------|---------|-----|------|--------------------| | Promise | Yes | Yes | Yes | Yes | | setTimeout | Yes | Yes | Yes | Yes | | AbortController | Yes | Yes | Yes | Yes | | Math.random | Yes | Yes | Yes | Yes | | Date.now | Yes | Yes | Yes | Yes |

No EventEmitter, no process, no Buffer, no fs — nothing that would break in an edge environment.

License

MIT