🔁 retry-flow

Smart Retry + Production-Grade Reliability System for Node.js

retry-flow is a TypeScript-first library designed to make your distributed systems more resilient. It provides a simple but powerful retry API, a policy-driven configuration system, and a core job queue with built-in Dead Letter Queue (DLQ) support.

🚀 Features

• Smart Retries: Beyond simple loops. Supports Fixed, Exponential, and Linear backoff.
• Jitter Support: Randomized delays to prevent thundering herd issues.
• Policy-Driven: Reusable retry configurations for Different scenarios (e.g., http-safe).
• Observability: Comprehensive lifecycle hooks for tracking attempts and failures.
• Job Queue: Built-in memory queue with concurrency control and automated retries.
• Dead Letter Queue (DLQ): Automatic capture and replay of permanently failed jobs.
• TypeScript First: Rich types for a premium developer experience.

📦 Installation

npm install retry-flow

🛠️ Quick Start

Basic Retry

import { retry } from "retry-flow";

const result = await retry(
  async ({ attempt }) => {
    return await fetch("https://api.example.com/data");
  },
  {
    retries: 3,
    strategy: "exponential",
    baseDelay: 1000,
    jitter: true,
  }
);

Using Policies

import { retry } from "retry-flow";

// Uses the built-in 'http-safe' policy
const result = await retry(
  async () => fetch("..."),
  "http-safe"
);

🏗️ Core API

retry<T>(fn, options)

Executes an async function with the specified retry logic.

RetryOptions

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | retries | number | 3 | Maximum number of retry attempts. | | strategy | "fixed" \| "exponential" \| "linear" | "fixed" | The wait strategy between attempts. | | baseDelay | number | 1000 | The initial delay in milliseconds. | | maxDelay | number | 30000 | The maximum delay allowed. | | jitter | boolean | false | Whether to add randomization to the delay. | | timeout | number | - | Timeout per attempt in milliseconds. | | retryIf | (error) => boolean | - | Predicate to decide if a retry should happen. | | abortIf | (error) => boolean | - | Predicate to immediately stop all retries. |

Hooks

{
  onRetry: ({ attempt, delay, error }) => console.log(`Retrying...`),
  onSuccess: ({ attempt, result }) => console.log(`Succeeded!`),
  onFailure: ({ error, attempts }) => console.log(`Failed after ${attempts} attempts.`),
}

📥 Job Queue & DLQ

retry-flow includes a lightweight job queue for background processing with built-in reliability.

import { createQueue } from "retry-flow";

const queue = createQueue({ driver: "memory", concurrency: 5 });

// Register a processor
queue.process("send-email", async (job) => {
  await mailer.send(job.data.to, job.data.subject);
});

// Add a job with custom retry policy
await queue.add("send-email", 
  { to: "[email protected]", subject: "Hello!" }, 
  { retryOptions: { retries: 5, strategy: "exponential" } }
);

Dead Letter Queue (DLQ)

When a job fails all retry attempts, it is moved to the DLQ.

const deadJobs = await queue.deadLetters.list();

// Replay a specific job
await queue.replay(deadJobs[0].id);

🔧 Advanced: Custom Policies

Register global policies to stay DRY across your codebase.

import { registerPolicy } from "retry-flow";

registerPolicy("my-custom-policy", {
  retries: 10,
  strategy: "linear",
  baseDelay: 500,
});

// Usage
await retry(fn, "my-custom-policy");

🧪 Development

# Run tests
npm test

# Run demo
npx tsx examples/demo.ts

📄 License

MIT © retry-flow