npm package: @kloudz-computing/retry-flow
Description: Smart retry engine with job queue and DLQ support for Node.js
Author: Krishnendu
Latest version: 1.0.0

# 🔁 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

```bash
npm install retry-flow
```

---

## 🛠️ Quick Start

### Basic Retry

```typescript
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

```typescript
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

```typescript
{
  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.

```typescript
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: "user@example.com", subject: "Hello!" }, 
  { retryOptions: { retries: 5, strategy: "exponential" } }
);
```

### Dead Letter Queue (DLQ)

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

```typescript
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.

```typescript
import { registerPolicy } from "retry-flow";

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

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

---

## 🧪 Development

```bash
# Run tests
npm test

# Run demo
npx tsx examples/demo.ts
```

---

## 📄 License

MIT © retry-flow