Retry

Automatically retry failed function calls with configurable backoff strategies

Function Signature

function withRetry<T extends AnyFn>(
  fn: T,
  options: RetryOptions
): T

Wraps a function with retry logic. Automatically retries failed calls with configurable backoff strategies.

Options

attempts · number · required

Number of retry attempts. Must be at least 1.

delay · number | [number, number]

Delay between retries in milliseconds. Can be a single number or a range [min, max]. Defaults to 1000ms.

backoff · 'fixed' | 'linear' | 'exponential'

Backoff strategy for retries:

• fixed: Use the same delay for all retries
• linear: Multiply delay by attempt number
• exponential: Multiply delay by 2^(attempt-1)

maxDelay · number

Maximum delay in milliseconds. Caps the backoff delay.

onRetry · (attempt: number, error: Error) => void

Callback invoked before each retry attempt.

retryIf · (error: Error) => boolean

Predicate function to determine if an error should be retried. If it returns false, the error is thrown immediately.

Return Type

Returns the wrapped function with retry logic.

Types

interface RetryOptions {
  attempts: number
  delay?: number | [number, number]
  backoff?: "fixed" | "linear" | "exponential"
  maxDelay?: number
  onRetry?: (attempt: number, error: Error) => void
  retryIf?: (error: Error) => boolean
}

Example

import { withRetry } from 'cruel'

const resilientFetch = withRetry(
  async (url: string) => {
    const response = await fetch(url)
    if (!response.ok) throw new Error('Request failed')
    return response.json()
  },
  {
    attempts: 3,
    delay: 1000,
    backoff: 'exponential',
    maxDelay: 10000,
    onRetry: (attempt, error) => {
      console.log(`Retry attempt ${attempt}: ${error.message}`)
    },
    retryIf: (error) => {
      // Only retry on network errors, not client errors
      return !error.message.includes('400')
    }
  }
)

const data = await resilientFetch('https://api.example.com/data')