Getting Started

Install @zap-studio/retry and build your first retry policy step by step.

Installation

npm install @zap-studio/retry

yarn add @zap-studio/retry

pnpm add @zap-studio/retry

bun add @zap-studio/retry

deno add jsr:@zap-studio/retry

Create a Policy

Import a built-in policy factory and configure it. exponentialBackoff(...) doubles the delay after each failure, up to a cap.

import { exponentialBackoff } from "@zap-studio/retry";

const policy = exponentialBackoff({
  maxAttempts: 5, // total attempts, including the first
  baseDelayMs: 100, // first retry waits 100 ms
  maxDelayMs: 2_000, // later retries never wait longer than 2 s
});

Run Your Work

Pass the policy and an async function to runRetryPolicy(...). The runner calls the function once per attempt, catches failures, waits, and retries until it succeeds or the policy stops.

import { exponentialBackoff, runRetryPolicy } from "@zap-studio/retry";
import { $fetch } from "@zap-studio/fetch";

const policy = exponentialBackoff({
  maxAttempts: 5,
  baseDelayMs: 100,
  maxDelayMs: 2_000,
});

const users = await runRetryPolicy(policy, async () => {
  const response = await $fetch("https://api.example.com/users", {
    throwOnFetchError: true,
  });
  return await response.json();
});

Handle Exhaustion

By default, runRetryPolicy(...) throws a RetryError when every attempt fails.

import { RetryError, runRetryPolicy } from "@zap-studio/retry";

try {
  const users = await runRetryPolicy(policy, fetchUsers);
  console.log(users);
} catch (error) {
  if (error instanceof RetryError) {
    console.error("Retries exhausted after", error.attempts, "attempts");
    console.error("Last error:", error.lastError);
  } else {
    throw error;
  }
}

Prefer result objects over exceptions? Pass throwOnExhausted: false to receive a discriminated union instead:

import { RetryError, runRetryPolicy } from "@zap-studio/retry";

const result = await runRetryPolicy(policy, fetchUsers, {
  throwOnExhausted: false,
});

if (result.ok) {
  console.log(result.value);
} else {
  console.error("Failed after", result.attempts, "attempts");
  if (result.error instanceof RetryError) {
    console.error("Last error:", result.error.lastError);
  }
}