TypeScript · Zero runtime dependencies · npm · Source

API Reference

Complete API documentation for Polite Retry.

Functions

retry<T>(fn, options?): Promise<T>

Retry an async function with exponential backoff and jitter.

Parameters

Name Type Description
fn () => Promise<T> The async function to retry
options RetryOptions Optional configuration

Returns

Promise<T> - The result of the function, or throws the last error.

Example

const data = await retry(
  async () => fetch('/api/data').then(r => r.json()),
  { maxRetries: 3, jitter: 'full' }
);

retryWithResult<T>(fn, options?): Promise<RetryResult<T>>

Retry with detailed result information including attempt count and timing.

Returns

Promise<RetryResult<T>> - Object with result, success flag, attempts, and timing.

Example

const { success, result, attempts, totalTimeMs } = await retryWithResult(
  async () => fetch('/api/data'),
  { maxRetries: 3 }
);

if (success) {
  console.log(`Got result in ${attempts} attempts (${totalTimeMs}ms)`);
} else {
  console.log(`Failed after ${attempts} attempts`);
}

retryWithCircuitBreaker<T>(fn, circuitBreaker, options?): Promise<T>

Retry with circuit breaker protection. Fails fast when circuit is open.

Parameters

Name Type Description
fn () => Promise<T> The async function to retry
circuitBreaker CircuitBreaker Circuit breaker instance
options RetryOptions Optional configuration

Throws

CircuitOpenError when circuit is open.

retryWithBudget<T>(fn, budget, options?): Promise<T>

Retry with Adaptive Retry Budgeting. Limits retry volume to prevent amplification.

Parameters

Name Type Description
fn () => Promise<T> The async function to retry
budget AdaptiveRetryBudget Budget manager instance
options RetryOptions Optional configuration

retryWithProtection<T>(fn, protection, options?): Promise<T>

Retry with both circuit breaker AND adaptive budget protection.

Parameters

Name Type Description
fn () => Promise<T> The async function to retry
protection { circuitBreaker, budget } Protection instances
options RetryOptions Optional configuration

Example

const breaker = new CircuitBreaker({ failureThreshold: 0.5 });
const budget = new AdaptiveRetryBudget({ initialBudget: 0.2 });

const result = await retryWithProtection(
  async () => criticalOperation(),
  { circuitBreaker: breaker, budget },
  { maxRetries: 3 }
);

createRetryable<TArgs, TResult>(fn, options?)

Wrap a function to make it automatically retryable.

Example

const fetchUser = createRetryable(
  async (id: string) => {
    const res = await fetch(`/api/users/${id}`);
    return res.json();
  },
  { maxRetries: 3, jitter: 'full' }
);

// Use like a normal function
const user = await fetchUser('123');

Classes

class CircuitBreaker

Implements the circuit breaker pattern to prevent requests to failing services.

Constructor Options

Option Type Default Description
failureThreshold number 0.5 Failure rate to open circuit (0-1)
windowSize number 10 Requests to consider for rate
resetTimeoutMs number 30000 Time before testing recovery
onStateChange function - Callback on state change

Methods

Method Returns Description
getState() CircuitState Get current state
isAllowed() boolean Check if requests allowed
recordSuccess() void Record successful request
recordFailure() void Record failed request
getFailureRate() number Current failure rate
reset() void Reset to closed state

class AdaptiveRetryBudget

Manages retry budget with adaptive adjustment based on failure rates.

Constructor Options

Option Type Default Description
initialBudget number 0.2 Initial budget (0-1)
budgetIncreaseRate number 0.1 Rate to increase budget
budgetDecreaseRate number 0.5 Rate to decrease budget
highFailureThreshold number 0.3 Threshold to decrease
lowFailureThreshold number 0.05 Threshold to increase
adjustmentIntervalMs number 1000 Budget adjustment interval
onBudgetChange function - Callback on budget change
checkBackpressure function - Backpressure check function

Methods

Method Returns Description
shouldRetry() Promise<boolean> Check if retry allowed
shouldRetrySync() boolean Sync version (no backpressure)
recordOutcome(success) void Record request outcome
getBudget() number Current budget value
getFailureRate() number Current failure rate
getMetrics() RetryMetrics Get all metrics
reset() void Reset to initial state
dispose() void Clean up timers

class BackpressureManager

Tracks backpressure signals from downstream services.

Methods

Method Description
recordSignal(serviceId, signal) Record a backpressure signal
recordFromHeaders(serviceId, headers) Extract signal from HTTP headers
isOverloaded(serviceId) Check if service is overloaded
getLoadLevel(serviceId) Get current load level
getRetryAfterMs(serviceId) Get suggested retry delay

class RequestCounter

Tracks active concurrent requests for load calculation.

Methods

Method Description
middleware() Express middleware that auto-tracks
getCount() Current active request count
increment() Manual increment
decrement() Manual decrement

Types

interface RetryOptions

interface RetryOptions {
  maxRetries?: number;        // Default: 3
  initialDelayMs?: number;    // Default: 100
  maxDelayMs?: number;        // Default: 30000
  backoffMultiplier?: number; // Default: 2
  jitter?: 'none' | 'full' | 'equal' | 'decorrelated'; // Default: 'full'
  retryIf?: (error: Error) => boolean;
  onRetry?: (error: Error, attempt: number, delayMs: number) => void;
  timeoutMs?: number;
}

interface RetryResult<T>

interface RetryResult<T> {
  result?: T;           // Successful result
  error?: Error;        // Final error if failed
  success: boolean;     // Whether succeeded
  attempts: number;     // Total attempts made
  totalTimeMs: number;  // Total time including delays
}

interface RetryMetrics

interface RetryMetrics {
  totalRequests: number;
  successfulRequests: number;
  failedRequests: number;
  totalRetries: number;
  failureRate: number;
  retryAmplificationFactor: number;
}