AsyncRetryer

Defined in: async-retryer.ts:298

Provides robust retry functionality for asynchronous functions, supporting configurable backoff strategies, attempt limits, timeout controls, and detailed state management. The AsyncRetryer class is designed to help you reliably execute async operations that may fail intermittently, such as network requests or database operations, by automatically retrying them according to your chosen policy.

Retrying Concepts

• Retrying: Automatically re-executes a failed async function up to a specified number of attempts. Useful for handling transient errors (e.g., network flakiness, rate limits, temporary server issues).
• Backoff Strategies: Controls the delay between retry attempts (default: 'exponential'):
  • 'exponential': Wait time doubles with each attempt (1s, 2s, 4s, ...) - DEFAULT
  • 'linear': Wait time increases linearly (1s, 2s, 3s, ...)
  • 'fixed': Waits a constant amount of time (baseWait) between each attempt
• Jitter: Adds randomness to retry delays to prevent thundering herd problems (default: 0). Set to a value between 0-1 to apply that percentage of random variation to each delay.
• Max Wait: Caps the maximum wait time between retries (default: Infinity). Useful for preventing exponential backoff from growing too large (e.g., cap at 30s even if exponential would be 64s).
• Timeout Controls: Set limits on execution time to prevent hanging operations:
  • maxExecutionTime: Maximum time for a single function call (default: Infinity)
  • maxTotalExecutionTime: Maximum time for the entire retry operation (default: Infinity)
• Abort & Cancellation: Supports cancellation via an internal AbortController. Call abort() to stop retries. Use getAbortSignal() to make your async function actually cancellable (e.g., with fetch requests).

State Management

Uses TanStack Store for fine-grained reactivity. State can be accessed via the store.state property.

Available state properties:

• currentAttempt: The current retry attempt number (0 when not executing)
• executionCount: Total number of completed executions (successful or failed)
• isExecuting: Whether the retryer is currently executing the function
• lastError: The most recent error encountered during execution
• lastExecutionTime: Timestamp of the last execution completion in milliseconds
• lastResult: The result from the most recent successful execution
• status: Current execution status ('disabled' | 'idle' | 'executing' | 'retrying')
• totalExecutionTime: Total time spent executing (including retries) in milliseconds

Error Handling

The throwOnError option controls when errors are thrown (default: 'last'):

• 'last': Only throws the final error after all retries are exhausted - DEFAULT
• true: Throws every error immediately (disables retrying)
• false: Never throws errors, returns undefined instead

Callbacks for lifecycle management:

• onAbort: Called when execution is aborted (manually or due to timeouts)
• onError: Called for every error (including during retries)
• onLastError: Called only for the final error after all retries fail
• onRetry: Called before each retry attempt
• onSettled: Called after execution completes (success or failure) of each attempt
• onSuccess: Called when execution succeeds
• onExecutionTimeout: Called when a single execution attempt times out
• onTotalExecutionTimeout: Called when the total execution time times out

Usage

• Use for async operations that may fail transiently and benefit from retrying.
• Configure maxAttempts, backoff, baseWait, maxWait, and jitter to control retry behavior.
• Set maxExecutionTime and maxTotalExecutionTime to prevent hanging operations.
• Use onAbort, onError, onLastError, onRetry, onSettled, onSuccess, onExecutionTimeout, and onTotalExecutionTimeout for custom side effects.
• Call abort() to cancel ongoing execution and pending retries.
• Call reset() to reset state and cancel execution.
• Use getAbortSignal() to make your async function cancellable.
• Use dynamic options (functions) for maxAttempts, baseWait, and enabled based on retryer state.

Important: This class is designed for single-use execution. Calling execute() multiple times on the same instance will abort previous executions. For multiple calls, create a new instance each time.

Example

// Retry a fetch operation up to 5 times with exponential backoff, jitter, and timeouts
const retryer = new AsyncRetryer(async (url: string) => {
  const signal = retryer.getAbortSignal()
  return await fetch(url, { signal })
}, {
  maxAttempts: 5,
  backoff: 'exponential',
  baseWait: 1000,
  jitter: 0.1, // Add 10% random variation to prevent thundering herd
  maxExecutionTime: 5000, // Abort individual calls after 5 seconds
  maxTotalExecutionTime: 30000, // Abort entire operation after 30 seconds
  onRetry: (attempt, error) => console.log(`Retry attempt ${attempt} after error:`, error),
  onSuccess: (result) => console.log('Success:', result),
  onError: (error) => console.error('Error:', error),
  onLastError: (error) => console.error('All retries failed:', error),
})

const result = await retryer.execute('/api/data')

Type Parameters

TFn

TFn extends AnyAsyncFunction

The async function type to be retried.

Constructors

Constructor

new AsyncRetryer<TFn>(fn, initialOptions?): AsyncRetryer<TFn>;

Defined in: async-retryer.ts:311

Creates a new AsyncRetryer instance

Parameters

fn

TFn

The async function to retry

initialOptions?

AsyncRetryerOptions<TFn> = {}

Configuration options for the retryer

Returns

AsyncRetryer<TFn>

Properties

fn

fn: TFn;

Defined in: async-retryer.ts:312

The async function to retry

key

key: string | undefined;

Defined in: async-retryer.ts:302

options

options: AsyncRetryerOptions<TFn> & Omit<Required<AsyncRetryerOptions<any>>,
  | "initialState"
  | "key"
  | "onAbort"
  | "onError"
  | "onLastError"
  | "onRetry"
  | "onSettled"
  | "onSuccess"
  | "onExecutionTimeout"
| "onTotalExecutionTimeout">;

Defined in: async-retryer.ts:303

store

readonly store: Store<Readonly<AsyncRetryerState<TFn>>>;

Defined in: async-retryer.ts:299

Methods

abort()

abort(reason?): void;

Defined in: async-retryer.ts:612

Cancels the current execution and any pending retries

Parameters

reason?

"manual" | "execution-timeout" | "total-timeout" | "new-execution"

The reason for the abort (defaults to 'manual')

Returns

void

execute()

execute(...args): Promise<Awaited<ReturnType<TFn>> | undefined>;

Defined in: async-retryer.ts:419

Executes the function with retry logic

Parameters

args

...Parameters<TFn>

Arguments to pass to the function

Returns

Promise<Awaited<ReturnType<TFn>> | undefined>

The function result, or undefined if disabled or all retries failed (when throwOnError is false)

Throws

The last error if throwOnError is true and all retries fail

getAbortSignal()

getAbortSignal(): AbortSignal | null;

Defined in: async-retryer.ts:604

Returns the current AbortSignal for the executing operation. Use this signal in your async function to make it cancellable. Returns null when not currently executing.

Returns

AbortSignal | null

Example

const retryer = new AsyncRetryer(async (userId: string) => {
  const signal = retryer.getAbortSignal()
  if (signal) {
    return fetch(`/api/users/${userId}`, { signal })
  }
  return fetch(`/api/users/${userId}`)
})

// Abort will now actually cancel the fetch
retryer.abort()

reset()

reset(): void;

Defined in: async-retryer.ts:632

Resets the retryer to its initial state

Returns

void

setOptions()

setOptions(newOptions): void;

Defined in: async-retryer.ts:330

Updates the retryer options

Parameters

newOptions

Partial<AsyncRetryerOptions<TFn>>

Partial options to merge with existing options

Returns

void