job-retry 0.1.0

package/README.md

@@ -0,0 +1,192 @@
+# job-retry
+
+Retry any async function with exponential backoff, per-attempt timeout control, and a dead letter queue so permanently failed jobs are never silently lost.
+
+```ts
+import { JobRetry } from 'job-retry';
+
+const runner = new JobRetry({ attempts: 5, backoff: 'exponential', baseDelay: 1000, jitter: true });
+
+const result = await runner.run('sendEmail', () => sendEmail(user));
+```
+
+---
+
+## Install
+
+```bash
+npm install job-retry
+```
+
+For the Redis DLQ backend, also install ioredis:
+
+```bash
+npm install ioredis
+```
+
+---
+
+## Quick start
+
+```ts
+import { JobRetry } from 'job-retry';
+
+const runner = new JobRetry({
+  attempts: 5,
+  backoff: 'exponential',
+  baseDelay: 1000,
+  timeout: 5000,
+  jitter: true,
+  dlq: 'memory',
+  onRetry: (error, attempt) => console.log(`Attempt ${attempt} failed`, error),
+  onFailure: (job) => console.error('Job permanently failed', job),
+  onSuccess: (result, attempts) => console.log(`Succeeded after ${attempts} tries`),
+});
+
+// Run a job — retries automatically on failure
+const result = await runner.run('sendEmail', () => sendEmail(user));
+
+// Inspect the dead letter queue
+const failed = await runner.dlq.getAll();
+
+// Retry a failed job after you've fixed the underlying issue
+await runner.dlq.retry(failed[0].id, runner);
+
+// Remove a single entry or wipe everything
+await runner.dlq.remove(failed[0].id);
+await runner.dlq.clear();
+```
+
+---
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `attempts` | `number` | `3` | Maximum attempts before the job is moved to the DLQ |
+| `backoff` | `'fixed' \| 'linear' \| 'exponential'` | `'exponential'` | Delay strategy between retries |
+| `baseDelay` | `number` | `1000` | Base delay in milliseconds |
+| `timeout` | `number` | none | Per-attempt timeout in ms — hanging attempts throw `TimeoutError` |
+| `jitter` | `boolean` | `false` | Adds random delay (up to 1× baseDelay) to prevent thundering herd |
+| `dlq` | `'memory' \| 'file' \| 'redis' \| DLQBackend` | `'memory'` | Dead letter queue backend |
+| `dlqFilePath` | `string` | `'./job-retry-dlq.json'` | File path for the file backend |
+| `dlqRedisClient` | `Redis` | — | ioredis client instance for the Redis backend |
+| `onRetry` | `(error, attempt) => void` | — | Called after each failed attempt except the last |
+| `onFailure` | `(job: DLQEntry) => void` | — | Called when the job is moved to the DLQ |
+| `onSuccess` | `(result, attempts) => void` | — | Called on success when retries were needed |
+
+---
+
+## Backoff strategies
+
+**Fixed** — waits `baseDelay` every attempt.
+
+**Linear** — waits `baseDelay × attempt` (1s, 2s, 3s, …).
+
+**Exponential** — waits `baseDelay × 2^(attempt−1)` (1s, 2s, 4s, 8s, …).
+
+**Jitter** — adds `random(0, delay)` to the computed delay. Prevents multiple jobs from retrying at the exact same instant after a shared outage (thundering herd).
+
+---
+
+## Dead letter queue backends
+
+### Memory (default)
+
+```ts
+new JobRetry({ dlq: 'memory' })
+```
+
+Stored in an in-process array. Lost on restart. Good for development and testing.
+
+### File
+
+```ts
+new JobRetry({
+  dlq: 'file',
+  dlqFilePath: './failed-jobs.json',
+})
+```
+
+Persisted to a JSON file on disk. Survives restarts. Good for single-server apps.
+
+### Redis
+
+```ts
+import Redis from 'ioredis';
+
+new JobRetry({
+  dlq: 'redis',
+  dlqRedisClient: new Redis(),
+})
+```
+
+Stored as Redis hashes with a list for ordering. Shared across multiple servers, survives restarts. Production-ready.
+
+### Custom backend
+
+Implement the `DLQBackend` interface and pass the instance directly:
+
+```ts
+import type { DLQBackend, DLQEntry } from 'job-retry';
+
+class MyDLQ implements DLQBackend {
+  async push(entry: DLQEntry): Promise<void> { /* ... */ }
+  async getAll(): Promise<DLQEntry[]> { /* ... */ }
+  async get(id: string): Promise<DLQEntry | null> { /* ... */ }
+  async retry(id: string, runner: JobRetry): Promise<unknown> { /* ... */ }
+  async remove(id: string): Promise<void> { /* ... */ }
+  async clear(): Promise<void> { /* ... */ }
+  async size(): Promise<number> { /* ... */ }
+}
+
+new JobRetry({ dlq: new MyDLQ() })
+```
+
+---
+
+## DLQ API
+
+| Method | Description |
+|---|---|
+| `dlq.getAll()` | Returns all entries in the queue |
+| `dlq.get(id)` | Returns a single entry by ID, or null |
+| `dlq.retry(id, runner)` | Re-runs the original function and removes the entry on success |
+| `dlq.remove(id)` | Deletes an entry from the queue |
+| `dlq.clear()` | Empties the entire queue |
+| `dlq.size()` | Returns the number of entries |
+
+---
+
+## Error types
+
+```ts
+import { MaxAttemptsExceededError, TimeoutError } from 'job-retry';
+
+try {
+  await runner.run('job', fn);
+} catch (err) {
+  if (err instanceof MaxAttemptsExceededError) {
+    console.log(`Failed after ${err.attempts} attempts`);
+    // err.cause holds the last underlying error
+  }
+}
+```
+
+`TimeoutError` is thrown internally when a per-attempt timeout fires. It becomes the `cause` on `MaxAttemptsExceededError`.
+
+---
+
+## TypeScript
+
+Full types ship with the package — no `@types/job-retry` needed.
+
+```ts
+import type { RetryOptions, DLQEntry, DLQBackend, BackoffStrategy } from 'job-retry';
+```
+
+---
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,94 @@
+import * as ioredis from 'ioredis';
+import { Redis } from 'ioredis';
+
+type BackoffStrategy = 'fixed' | 'linear' | 'exponential';
+interface DLQEntry {
+    id: string;
+    name: string;
+    error: string;
+    timestamp: number;
+    attempts: number;
+    payload?: unknown;
+}
+interface DLQBackend {
+    push(entry: DLQEntry): Promise<void>;
+    getAll(): Promise<DLQEntry[]>;
+    get(id: string): Promise<DLQEntry | null>;
+    retry(id: string, runner: JobRetry): Promise<unknown>;
+    remove(id: string): Promise<void>;
+    clear(): Promise<void>;
+    size(): Promise<number>;
+}
+type DLQType = 'memory' | 'file' | 'redis';
+interface RetryOptions {
+    attempts?: number;
+    backoff?: BackoffStrategy;
+    baseDelay?: number;
+    timeout?: number;
+    jitter?: boolean;
+    dlq?: DLQType | DLQBackend;
+    dlqFilePath?: string;
+    dlqRedisClient?: ioredis.Redis;
+    onRetry?: (error: unknown, attempt: number) => void;
+    onFailure?: (job: DLQEntry) => void;
+    onSuccess?: (result: unknown, attempts: number) => void;
+}
+
+declare class JobRetry {
+    private readonly opts;
+    readonly dlq: DLQBackend;
+    private replayFns;
+    constructor(opts?: RetryOptions);
+    run<T>(name: string, fn: () => Promise<T>): Promise<T>;
+    replayEntry(entry: DLQEntry): Promise<unknown>;
+    private resolveDLQ;
+}
+
+declare class MemoryDLQ implements DLQBackend {
+    private entries;
+    push(entry: DLQEntry): Promise<void>;
+    getAll(): Promise<DLQEntry[]>;
+    get(id: string): Promise<DLQEntry | null>;
+    retry(id: string, runner: JobRetry): Promise<unknown>;
+    remove(id: string): Promise<void>;
+    clear(): Promise<void>;
+    size(): Promise<number>;
+}
+
+declare class FileDLQ implements DLQBackend {
+    private filePath;
+    constructor(filePath?: string);
+    private read;
+    private write;
+    push(entry: DLQEntry): Promise<void>;
+    getAll(): Promise<DLQEntry[]>;
+    get(id: string): Promise<DLQEntry | null>;
+    retry(id: string, runner: JobRetry): Promise<unknown>;
+    remove(id: string): Promise<void>;
+    clear(): Promise<void>;
+    size(): Promise<number>;
+}
+
+declare class RedisDLQ implements DLQBackend {
+    private readonly redis;
+    constructor(redis: Redis);
+    push(entry: DLQEntry): Promise<void>;
+    getAll(): Promise<DLQEntry[]>;
+    get(id: string): Promise<DLQEntry | null>;
+    retry(id: string, runner: JobRetry): Promise<unknown>;
+    remove(id: string): Promise<void>;
+    clear(): Promise<void>;
+    size(): Promise<number>;
+    private getById;
+}
+
+declare class MaxAttemptsExceededError extends Error {
+    readonly attempts: number;
+    constructor(attempts: number, cause?: unknown);
+}
+declare class TimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+
+export { type BackoffStrategy, type DLQBackend, type DLQEntry, type DLQType, FileDLQ, JobRetry, MaxAttemptsExceededError, MemoryDLQ, RedisDLQ, type RetryOptions, TimeoutError };

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+import * as ioredis from 'ioredis';
+import { Redis } from 'ioredis';
+
+type BackoffStrategy = 'fixed' | 'linear' | 'exponential';
+interface DLQEntry {
+    id: string;
+    name: string;
+    error: string;
+    timestamp: number;
+    attempts: number;
+    payload?: unknown;
+}
+interface DLQBackend {
+    push(entry: DLQEntry): Promise<void>;
+    getAll(): Promise<DLQEntry[]>;
+    get(id: string): Promise<DLQEntry | null>;
+    retry(id: string, runner: JobRetry): Promise<unknown>;
+    remove(id: string): Promise<void>;
+    clear(): Promise<void>;
+    size(): Promise<number>;
+}
+type DLQType = 'memory' | 'file' | 'redis';
+interface RetryOptions {
+    attempts?: number;
+    backoff?: BackoffStrategy;
+    baseDelay?: number;
+    timeout?: number;
+    jitter?: boolean;
+    dlq?: DLQType | DLQBackend;
+    dlqFilePath?: string;
+    dlqRedisClient?: ioredis.Redis;
+    onRetry?: (error: unknown, attempt: number) => void;
+    onFailure?: (job: DLQEntry) => void;
+    onSuccess?: (result: unknown, attempts: number) => void;
+}
+
+declare class JobRetry {
+    private readonly opts;
+    readonly dlq: DLQBackend;
+    private replayFns;
+    constructor(opts?: RetryOptions);
+    run<T>(name: string, fn: () => Promise<T>): Promise<T>;
+    replayEntry(entry: DLQEntry): Promise<unknown>;
+    private resolveDLQ;
+}
+
+declare class MemoryDLQ implements DLQBackend {
+    private entries;
+    push(entry: DLQEntry): Promise<void>;
+    getAll(): Promise<DLQEntry[]>;
+    get(id: string): Promise<DLQEntry | null>;
+    retry(id: string, runner: JobRetry): Promise<unknown>;
+    remove(id: string): Promise<void>;
+    clear(): Promise<void>;
+    size(): Promise<number>;
+}
+
+declare class FileDLQ implements DLQBackend {
+    private filePath;
+    constructor(filePath?: string);
+    private read;
+    private write;
+    push(entry: DLQEntry): Promise<void>;
+    getAll(): Promise<DLQEntry[]>;
+    get(id: string): Promise<DLQEntry | null>;
+    retry(id: string, runner: JobRetry): Promise<unknown>;
+    remove(id: string): Promise<void>;
+    clear(): Promise<void>;
+    size(): Promise<number>;
+}
+
+declare class RedisDLQ implements DLQBackend {
+    private readonly redis;
+    constructor(redis: Redis);
+    push(entry: DLQEntry): Promise<void>;
+    getAll(): Promise<DLQEntry[]>;
+    get(id: string): Promise<DLQEntry | null>;
+    retry(id: string, runner: JobRetry): Promise<unknown>;
+    remove(id: string): Promise<void>;
+    clear(): Promise<void>;
+    size(): Promise<number>;
+    private getById;
+}
+
+declare class MaxAttemptsExceededError extends Error {
+    readonly attempts: number;
+    constructor(attempts: number, cause?: unknown);
+}
+declare class TimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+
+export { type BackoffStrategy, type DLQBackend, type DLQEntry, type DLQType, FileDLQ, JobRetry, MaxAttemptsExceededError, MemoryDLQ, RedisDLQ, type RetryOptions, TimeoutError };

package/dist/index.js

@@ -0,0 +1,322 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  FileDLQ: () => FileDLQ,
+  JobRetry: () => JobRetry,
+  MaxAttemptsExceededError: () => MaxAttemptsExceededError,
+  MemoryDLQ: () => MemoryDLQ,
+  RedisDLQ: () => RedisDLQ,
+  TimeoutError: () => TimeoutError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/JobRetry.ts
+var import_crypto = require("crypto");
+
+// src/backoff.ts
+function calculateDelay(attempt, strategy, baseDelay, jitter) {
+  let delay;
+  switch (strategy) {
+    case "fixed":
+      delay = baseDelay;
+      break;
+    case "linear":
+      delay = baseDelay * attempt;
+      break;
+    case "exponential":
+      delay = baseDelay * Math.pow(2, attempt - 1);
+      break;
+  }
+  if (jitter) {
+    delay = delay + Math.random() * delay;
+  }
+  return Math.round(delay);
+}
+
+// src/errors.ts
+var MaxAttemptsExceededError = class extends Error {
+  constructor(attempts, cause) {
+    super(`Job failed after ${attempts} attempt${attempts === 1 ? "" : "s"}`);
+    this.name = "MaxAttemptsExceededError";
+    this.attempts = attempts;
+    if (cause instanceof Error) {
+      this.cause = cause;
+    }
+  }
+};
+var TimeoutError = class extends Error {
+  constructor(timeoutMs) {
+    super(`Job timed out after ${timeoutMs}ms`);
+    this.name = "TimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+};
+
+// src/timeout.ts
+function withTimeout(promise, ms) {
+  let timer;
+  const timeoutPromise = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new TimeoutError(ms)), ms);
+  });
+  return Promise.race([promise, timeoutPromise]).finally(() => {
+    clearTimeout(timer);
+  });
+}
+
+// src/dlq/MemoryDLQ.ts
+var MemoryDLQ = class {
+  constructor() {
+    this.entries = /* @__PURE__ */ new Map();
+  }
+  async push(entry) {
+    this.entries.set(entry.id, entry);
+  }
+  async getAll() {
+    return Array.from(this.entries.values());
+  }
+  async get(id) {
+    return this.entries.get(id) ?? null;
+  }
+  async retry(id, runner) {
+    const entry = this.entries.get(id);
+    if (!entry) throw new Error(`DLQ entry not found: ${id}`);
+    this.entries.delete(id);
+    return runner.run(entry.name, () => runner.replayEntry(entry));
+  }
+  async remove(id) {
+    this.entries.delete(id);
+  }
+  async clear() {
+    this.entries.clear();
+  }
+  async size() {
+    return this.entries.size;
+  }
+};
+
+// src/dlq/FileDLQ.ts
+var import_fs = __toESM(require("fs"));
+var import_path = __toESM(require("path"));
+var FileDLQ = class {
+  constructor(filePath = "./job-retry-dlq.json") {
+    this.filePath = import_path.default.resolve(filePath);
+  }
+  read() {
+    if (!import_fs.default.existsSync(this.filePath)) return [];
+    try {
+      return JSON.parse(import_fs.default.readFileSync(this.filePath, "utf8"));
+    } catch {
+      return [];
+    }
+  }
+  write(entries) {
+    import_fs.default.writeFileSync(this.filePath, JSON.stringify(entries, null, 2), "utf8");
+  }
+  async push(entry) {
+    const entries = this.read();
+    entries.push(entry);
+    this.write(entries);
+  }
+  async getAll() {
+    return this.read();
+  }
+  async get(id) {
+    return this.read().find((e) => e.id === id) ?? null;
+  }
+  async retry(id, runner) {
+    const entries = this.read();
+    const idx = entries.findIndex((e) => e.id === id);
+    if (idx === -1) throw new Error(`DLQ entry not found: ${id}`);
+    const [entry] = entries.splice(idx, 1);
+    this.write(entries);
+    return runner.run(entry.name, () => runner.replayEntry(entry));
+  }
+  async remove(id) {
+    const entries = this.read().filter((e) => e.id !== id);
+    this.write(entries);
+  }
+  async clear() {
+    this.write([]);
+  }
+  async size() {
+    return this.read().length;
+  }
+};
+
+// src/dlq/RedisDLQ.ts
+var LIST_KEY = "job-retry:dlq:ids";
+var HASH_PREFIX = "job-retry:dlq:entry:";
+var RedisDLQ = class {
+  constructor(redis) {
+    this.redis = redis;
+  }
+  async push(entry) {
+    await Promise.all([
+      this.redis.hset(HASH_PREFIX + entry.id, entry),
+      this.redis.rpush(LIST_KEY, entry.id)
+    ]);
+  }
+  async getAll() {
+    const ids = await this.redis.lrange(LIST_KEY, 0, -1);
+    if (ids.length === 0) return [];
+    const entries = await Promise.all(ids.map((id) => this.getById(id)));
+    return entries.filter((e) => e !== null);
+  }
+  async get(id) {
+    return this.getById(id);
+  }
+  async retry(id, runner) {
+    const entry = await this.getById(id);
+    if (!entry) throw new Error(`DLQ entry not found: ${id}`);
+    await this.remove(id);
+    return runner.run(entry.name, () => runner.replayEntry(entry));
+  }
+  async remove(id) {
+    await Promise.all([
+      this.redis.del(HASH_PREFIX + id),
+      this.redis.lrem(LIST_KEY, 0, id)
+    ]);
+  }
+  async clear() {
+    const ids = await this.redis.lrange(LIST_KEY, 0, -1);
+    if (ids.length > 0) {
+      await Promise.all(ids.map((id) => this.redis.del(HASH_PREFIX + id)));
+    }
+    await this.redis.del(LIST_KEY);
+  }
+  async size() {
+    return this.redis.llen(LIST_KEY);
+  }
+  async getById(id) {
+    const raw = await this.redis.hgetall(HASH_PREFIX + id);
+    if (!raw || Object.keys(raw).length === 0) return null;
+    return {
+      id: raw["id"],
+      name: raw["name"],
+      error: raw["error"],
+      timestamp: Number(raw["timestamp"]),
+      attempts: Number(raw["attempts"]),
+      payload: raw["payload"] ? JSON.parse(raw["payload"]) : void 0
+    };
+  }
+};
+
+// src/JobRetry.ts
+var DEFAULTS = {
+  attempts: 3,
+  backoff: "exponential",
+  baseDelay: 1e3,
+  jitter: false
+};
+var JobRetry = class {
+  constructor(opts = {}) {
+    // Stores the fn for replay when a DLQ entry is retried
+    this.replayFns = /* @__PURE__ */ new Map();
+    this.opts = { ...DEFAULTS, ...opts };
+    this.dlq = this.resolveDLQ(opts);
+  }
+  async run(name, fn) {
+    const maxAttempts = this.opts.attempts ?? DEFAULTS.attempts;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        const promise = this.opts.timeout ? withTimeout(fn(), this.opts.timeout) : fn();
+        const result = await promise;
+        if (attempt > 1) {
+          this.opts.onSuccess?.(result, attempt);
+        }
+        return result;
+      } catch (err) {
+        lastError = err;
+        if (attempt < maxAttempts) {
+          this.opts.onRetry?.(err, attempt);
+          const delay = calculateDelay(
+            attempt,
+            this.opts.backoff ?? DEFAULTS.backoff,
+            this.opts.baseDelay ?? DEFAULTS.baseDelay,
+            this.opts.jitter ?? DEFAULTS.jitter
+          );
+          await sleep(delay);
+        }
+      }
+    }
+    const entry = {
+      id: (0, import_crypto.randomUUID)(),
+      name,
+      error: errorMessage(lastError),
+      timestamp: Date.now(),
+      attempts: maxAttempts
+    };
+    this.replayFns.set(entry.id, fn);
+    await this.dlq.push(entry);
+    this.opts.onFailure?.(entry);
+    throw new MaxAttemptsExceededError(maxAttempts, lastError instanceof Error ? lastError : void 0);
+  }
+  replayEntry(entry) {
+    const fn = this.replayFns.get(entry.id);
+    if (!fn) {
+      throw new Error(
+        `No replay function found for job "${entry.name}" (id: ${entry.id}). Replay is only available within the same process that originally ran the job.`
+      );
+    }
+    this.replayFns.delete(entry.id);
+    return fn();
+  }
+  resolveDLQ(opts) {
+    const backend = opts.dlq;
+    if (!backend || backend === "memory") return new MemoryDLQ();
+    if (backend === "file") return new FileDLQ(opts.dlqFilePath);
+    if (backend === "redis") {
+      if (!opts.dlqRedisClient) {
+        throw new Error('dlqRedisClient is required when dlq is "redis"');
+      }
+      return new RedisDLQ(opts.dlqRedisClient);
+    }
+    return backend;
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function errorMessage(err) {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FileDLQ,
+  JobRetry,
+  MaxAttemptsExceededError,
+  MemoryDLQ,
+  RedisDLQ,
+  TimeoutError
+});

package/dist/index.mjs

@@ -0,0 +1,280 @@
+// src/JobRetry.ts
+import { randomUUID } from "crypto";
+
+// src/backoff.ts
+function calculateDelay(attempt, strategy, baseDelay, jitter) {
+  let delay;
+  switch (strategy) {
+    case "fixed":
+      delay = baseDelay;
+      break;
+    case "linear":
+      delay = baseDelay * attempt;
+      break;
+    case "exponential":
+      delay = baseDelay * Math.pow(2, attempt - 1);
+      break;
+  }
+  if (jitter) {
+    delay = delay + Math.random() * delay;
+  }
+  return Math.round(delay);
+}
+
+// src/errors.ts
+var MaxAttemptsExceededError = class extends Error {
+  constructor(attempts, cause) {
+    super(`Job failed after ${attempts} attempt${attempts === 1 ? "" : "s"}`);
+    this.name = "MaxAttemptsExceededError";
+    this.attempts = attempts;
+    if (cause instanceof Error) {
+      this.cause = cause;
+    }
+  }
+};
+var TimeoutError = class extends Error {
+  constructor(timeoutMs) {
+    super(`Job timed out after ${timeoutMs}ms`);
+    this.name = "TimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+};
+
+// src/timeout.ts
+function withTimeout(promise, ms) {
+  let timer;
+  const timeoutPromise = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new TimeoutError(ms)), ms);
+  });
+  return Promise.race([promise, timeoutPromise]).finally(() => {
+    clearTimeout(timer);
+  });
+}
+
+// src/dlq/MemoryDLQ.ts
+var MemoryDLQ = class {
+  constructor() {
+    this.entries = /* @__PURE__ */ new Map();
+  }
+  async push(entry) {
+    this.entries.set(entry.id, entry);
+  }
+  async getAll() {
+    return Array.from(this.entries.values());
+  }
+  async get(id) {
+    return this.entries.get(id) ?? null;
+  }
+  async retry(id, runner) {
+    const entry = this.entries.get(id);
+    if (!entry) throw new Error(`DLQ entry not found: ${id}`);
+    this.entries.delete(id);
+    return runner.run(entry.name, () => runner.replayEntry(entry));
+  }
+  async remove(id) {
+    this.entries.delete(id);
+  }
+  async clear() {
+    this.entries.clear();
+  }
+  async size() {
+    return this.entries.size;
+  }
+};
+
+// src/dlq/FileDLQ.ts
+import fs from "fs";
+import path from "path";
+var FileDLQ = class {
+  constructor(filePath = "./job-retry-dlq.json") {
+    this.filePath = path.resolve(filePath);
+  }
+  read() {
+    if (!fs.existsSync(this.filePath)) return [];
+    try {
+      return JSON.parse(fs.readFileSync(this.filePath, "utf8"));
+    } catch {
+      return [];
+    }
+  }
+  write(entries) {
+    fs.writeFileSync(this.filePath, JSON.stringify(entries, null, 2), "utf8");
+  }
+  async push(entry) {
+    const entries = this.read();
+    entries.push(entry);
+    this.write(entries);
+  }
+  async getAll() {
+    return this.read();
+  }
+  async get(id) {
+    return this.read().find((e) => e.id === id) ?? null;
+  }
+  async retry(id, runner) {
+    const entries = this.read();
+    const idx = entries.findIndex((e) => e.id === id);
+    if (idx === -1) throw new Error(`DLQ entry not found: ${id}`);
+    const [entry] = entries.splice(idx, 1);
+    this.write(entries);
+    return runner.run(entry.name, () => runner.replayEntry(entry));
+  }
+  async remove(id) {
+    const entries = this.read().filter((e) => e.id !== id);
+    this.write(entries);
+  }
+  async clear() {
+    this.write([]);
+  }
+  async size() {
+    return this.read().length;
+  }
+};
+
+// src/dlq/RedisDLQ.ts
+var LIST_KEY = "job-retry:dlq:ids";
+var HASH_PREFIX = "job-retry:dlq:entry:";
+var RedisDLQ = class {
+  constructor(redis) {
+    this.redis = redis;
+  }
+  async push(entry) {
+    await Promise.all([
+      this.redis.hset(HASH_PREFIX + entry.id, entry),
+      this.redis.rpush(LIST_KEY, entry.id)
+    ]);
+  }
+  async getAll() {
+    const ids = await this.redis.lrange(LIST_KEY, 0, -1);
+    if (ids.length === 0) return [];
+    const entries = await Promise.all(ids.map((id) => this.getById(id)));
+    return entries.filter((e) => e !== null);
+  }
+  async get(id) {
+    return this.getById(id);
+  }
+  async retry(id, runner) {
+    const entry = await this.getById(id);
+    if (!entry) throw new Error(`DLQ entry not found: ${id}`);
+    await this.remove(id);
+    return runner.run(entry.name, () => runner.replayEntry(entry));
+  }
+  async remove(id) {
+    await Promise.all([
+      this.redis.del(HASH_PREFIX + id),
+      this.redis.lrem(LIST_KEY, 0, id)
+    ]);
+  }
+  async clear() {
+    const ids = await this.redis.lrange(LIST_KEY, 0, -1);
+    if (ids.length > 0) {
+      await Promise.all(ids.map((id) => this.redis.del(HASH_PREFIX + id)));
+    }
+    await this.redis.del(LIST_KEY);
+  }
+  async size() {
+    return this.redis.llen(LIST_KEY);
+  }
+  async getById(id) {
+    const raw = await this.redis.hgetall(HASH_PREFIX + id);
+    if (!raw || Object.keys(raw).length === 0) return null;
+    return {
+      id: raw["id"],
+      name: raw["name"],
+      error: raw["error"],
+      timestamp: Number(raw["timestamp"]),
+      attempts: Number(raw["attempts"]),
+      payload: raw["payload"] ? JSON.parse(raw["payload"]) : void 0
+    };
+  }
+};
+
+// src/JobRetry.ts
+var DEFAULTS = {
+  attempts: 3,
+  backoff: "exponential",
+  baseDelay: 1e3,
+  jitter: false
+};
+var JobRetry = class {
+  constructor(opts = {}) {
+    // Stores the fn for replay when a DLQ entry is retried
+    this.replayFns = /* @__PURE__ */ new Map();
+    this.opts = { ...DEFAULTS, ...opts };
+    this.dlq = this.resolveDLQ(opts);
+  }
+  async run(name, fn) {
+    const maxAttempts = this.opts.attempts ?? DEFAULTS.attempts;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        const promise = this.opts.timeout ? withTimeout(fn(), this.opts.timeout) : fn();
+        const result = await promise;
+        if (attempt > 1) {
+          this.opts.onSuccess?.(result, attempt);
+        }
+        return result;
+      } catch (err) {
+        lastError = err;
+        if (attempt < maxAttempts) {
+          this.opts.onRetry?.(err, attempt);
+          const delay = calculateDelay(
+            attempt,
+            this.opts.backoff ?? DEFAULTS.backoff,
+            this.opts.baseDelay ?? DEFAULTS.baseDelay,
+            this.opts.jitter ?? DEFAULTS.jitter
+          );
+          await sleep(delay);
+        }
+      }
+    }
+    const entry = {
+      id: randomUUID(),
+      name,
+      error: errorMessage(lastError),
+      timestamp: Date.now(),
+      attempts: maxAttempts
+    };
+    this.replayFns.set(entry.id, fn);
+    await this.dlq.push(entry);
+    this.opts.onFailure?.(entry);
+    throw new MaxAttemptsExceededError(maxAttempts, lastError instanceof Error ? lastError : void 0);
+  }
+  replayEntry(entry) {
+    const fn = this.replayFns.get(entry.id);
+    if (!fn) {
+      throw new Error(
+        `No replay function found for job "${entry.name}" (id: ${entry.id}). Replay is only available within the same process that originally ran the job.`
+      );
+    }
+    this.replayFns.delete(entry.id);
+    return fn();
+  }
+  resolveDLQ(opts) {
+    const backend = opts.dlq;
+    if (!backend || backend === "memory") return new MemoryDLQ();
+    if (backend === "file") return new FileDLQ(opts.dlqFilePath);
+    if (backend === "redis") {
+      if (!opts.dlqRedisClient) {
+        throw new Error('dlqRedisClient is required when dlq is "redis"');
+      }
+      return new RedisDLQ(opts.dlqRedisClient);
+    }
+    return backend;
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function errorMessage(err) {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+export {
+  FileDLQ,
+  JobRetry,
+  MaxAttemptsExceededError,
+  MemoryDLQ,
+  RedisDLQ,
+  TimeoutError
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "job-retry",
+  "version": "0.1.0",
+  "description": "Retry async functions with exponential backoff, per-attempt timeout, and a dead letter queue",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "test": "jest",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "retry",
+    "backoff",
+    "exponential-backoff",
+    "dead-letter-queue",
+    "dlq",
+    "job",
+    "queue",
+    "timeout",
+    "async"
+  ],
+  "author": "Rajat Thakur",
+  "license": "MIT",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "peerDependencies": {
+    "ioredis": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "ioredis": "^5.0.0",
+    "ioredis-mock": "^8.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}