@ekaone/retry

Composable retry primitive with exponential backoff, jitter, and AbortSignal support.

Zero dependencies. Works in Node 18+, Bun, Deno, browsers, and edge runtimes.

Comparison — @ekaone/retry vs native fetch

See detailed comparison table here.

Retry

| Feature | @ekaone/retry | fetch | |---|---|---| | Automatic retry — Retries failed calls without manual loops | ✓ built-in | ✗ manual | | Max attempts — Hard cap on total number of tries | ✓ maxAttempts | ✗ none | | Exponential backoff — Delay grows as 2^attempt between retries | ✓ built-in | ✗ none | | Linear backoff — Delay grows linearly per attempt | ✓ built-in | ✗ none | | Fixed backoff — Constant delay between every attempt | ✓ built-in | ✗ none | | Jitter — Randomised delay to prevent thundering herd | ✓ full jitter | ✗ none | | Max delay cap — Upper bound on computed delay | ✓ 30s default | ✗ none |

Control

| Feature | @ekaone/retry | fetch | |---|---|---| | shouldRetry predicate — Selective retry on recoverable errors | ✓ per-error | ✗ none | | AbortSignal support — External cancellation mid-retry loop | ✓ built-in | ~ per-request only | | Total timeout — Cap on entire operation including delays | ✓ totalTimeoutMs | ✗ none | | onError hook — Callback fired after each failed attempt | ✓ per-attempt | ✗ none |

Error Handling

| Feature | @ekaone/retry | fetch | |---|---|---| | RetryError with diagnostics — Attempts count, lastError, failure reason | ✓ RetryError | ✗ raw error | | Failure reason — exhausted / aborted / timeout / rejected | ✓ reason field | ✗ none |

Scope

| Feature | @ekaone/retry | fetch | |---|---|---| | Works with any async fn — DB calls, SDK calls, agent turns | ✓ any Promise | ✗ HTTP only | | Works with Anthropic SDK — anthropic.messages.create() | ✓ yes | ✗ no | | Works with native fetch — Can wrap fetch() calls too | ✓ yes | ✓ yes |

Runtime & Package

| Feature | @ekaone/retry | fetch | |---|---|---| | Zero dependencies | ✓ zero | ✓ native | | Node / Browser / Edge / Bun | ✓ universal | ✓ universal | | ESM + CJS dual output | ✓ tsup | N/A — native |

Install

npm install @ekaone/retry
# or
pnpm add @ekaone/retry

Usage

import { retry } from '@ekaone/retry'

// Basic
const data = await retry(() => fetch('https://api.example.com').then(r => r.json()))

// With options
const data = await retry(
  () => anthropic.messages.create({ model: 'claude-opus-4-5', ... }),
  {
    maxAttempts: 4,
    backoff: 'exponential',
    baseDelayMs: 200,
    jitter: true,
    shouldRetry: (error) => error?.status === 429,
    onError: (error, attempt) => console.warn(`Attempt ${attempt} failed`, error),
  }
)

API

retry(fn, options?)

| Option | Type | Default | Description | |---|---|---|---| | maxAttempts | number | 3 | Max attempts including the first call | | backoff | 'fixed' \| 'linear' \| 'exponential' | 'exponential' | Delay growth strategy | | baseDelayMs | number | 100 | Base delay in ms | | maxDelayMs | number | 30_000 | Upper cap on computed delay | | totalTimeoutMs | number | undefined | Cap on total elapsed time across all attempts | | jitter | boolean | false | Randomise delay to prevent thundering herd | | signal | AbortSignal | undefined | External cancellation | | shouldRetry | (error, attempt) => boolean \| undefined | undefined | Selective retry predicate | | onError | (error, attempt) => void | undefined | Per-attempt error hook |

RetryError

Thrown when all attempts are exhausted or retry is stopped.

import { retry, RetryError } from '@ekaone/retry'

try {
  await retry(() => unstable(), { maxAttempts: 3 })
} catch (err) {
  if (err instanceof RetryError) {
    console.log(err.attempts)   // number of attempts made
    console.log(err.lastError)  // original error from last attempt
    console.log(err.reason)     // 'exhausted' | 'aborted' | 'timeout' | 'rejected'
  }
}

Backoff Strategies

| Strategy | Delay formula | |---|---| | fixed | baseDelayMs every time | | linear | baseDelayMs × attempt | | exponential | baseDelayMs × 2^(attempt-1) |

All strategies are capped at maxDelayMs. Enable jitter: true to randomise between 0 and the computed value.

Integration with @ekaone/n-agent

n-agent is multi-agent conversation loop with human-in-the-loop support

import { createAgent } from '@ekaone/n-agent'
import { retry } from '@ekaone/retry'

const agent = createAgent({
  onError: async (error, ctx) => {
    await retry(() => ctx.replayTurn(), {
      maxAttempts: 3,
      backoff: 'exponential',
      jitter: true,
      signal: ctx.signal,
    })
    return 'skip'
  }
})

License

MIT © Eka Prasetia

Links

• npm Package
• GitHub Repository
• Issue Tracker

⭐ If this library helps you, please consider giving it a star on GitHub!