#1565·es-toolkit

Proposal: Add exponential backoff and jitter utilities for retry

Author: KimKyuHoiCreated Dec 21, 2025Updated Mar 2, 2026
Labelsp2: new feature

Summary

Add exponentialBackoff, withJitter, withEqualJitter, and withDecorrelatedJitter utility functions that can be composed with the existing retry function.

Motivation

The current retry function already supports dynamic delay via delay: (attempts) => number, which is great! However, implementing exponential backoff with jitter correctly requires users to:

  1. Know the proper formulas for each jitter strategy
  2. Understand the trade-offs between different approaches (full, equal, decorrelated)
  3. Handle edge cases like max delay capping

These are well-established patterns from AWS Architecture Blog that would benefit from first-class support.

Proposed API

exponentialBackoff

Creates an exponential backoff delay function.

typescript
import { retry, exponentialBackoff } from 'es-toolkit/function';

// Basic usage
retry(() => fetchData(), {
  delay: exponentialBackoff(),
  retries: 5
});

// Custom options
retry(() => fetchData(), {
  delay: exponentialBackoff({ baseDelay: 200, maxDelay: 10000, multiplier: 2 }),
  retries: 5
});

withJitter (Full Jitter)

Applies full jitter (0 ~ baseDelay)

typescript
import { retry, exponentialBackoff, withJitter } from 'es-toolkit/function';

retry(() => fetchData(), {
  delay: withJitter(exponentialBackoff()),
  retries: 5
});

### `withEqualJitter`
Applies equal jitter (baseDelay/2 ~ baseDelay) - guarantees minimum delay.

```typescript
retry(() => fetchData(), {
  delay: withEqualJitter(exponentialBackoff()),
  retries: 5
});

withDecorrelatedJitter

typescript
retry(() => fetchData(), {
  delay: withDecorrelatedJitter(100, 30000),
  retries: 5
});

References