Proposal: Add exponential backoff and jitter utilities for retry #1565
Description
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:
- Know the proper formulas for each jitter strategy
- Understand the trade-offs between different approaches (full, equal, decorrelated)
- 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.
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)
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
retry(() => fetchData(), {
delay: withDecorrelatedJitter(100, 30000),
retries: 5
});