@mayurbhusare/resilient-queue

Minimal resilient Redis-backed job queue for Node.js.

Provides exponential retry, dead-letter queue (DLQ) handling, idempotency guarantees, and graceful shutdown — without heavy frameworks.

✨ Features

• Redis-backed job queue
• Exponential backoff retry
• Dead Letter Queue (DLQ) support
• Idempotency protection
• Graceful shutdown support
• Lightweight and minimal design
• Fully tested with Jest

📦 Installation

npm install @mayurbhusare/resilient-queue

🚀 Quick Example

const {
  ResilientQueue,
  RetryableError,
  FatalError
} = require("@mayurbhusare/resilient-queue");

const queue = new ResilientQueue({
  redisUrl: "redis://127.0.0.1:6379",
  maxRetries: 2,
  baseDelay: 500
});

queue.process(async (job) => {
  console.log("Processing:", job.data);

  if (job.data.retry) {
    throw new RetryableError("Temporary failure");
  }

  if (job.data.fatal) {
    throw new FatalError("Permanent failure");
  }

  console.log("Completed");
});

queue.enqueue({ message: "Hello World" });

🧠 How It Works

Main Queue

Jobs are pushed into:

rq:main

Workers consume jobs using blocking Redis BLPOP.

Retry Strategy

Retryable errors trigger exponential backoff:

delay = baseDelay * 2^attempt

After exceeding maxRetries, the job is moved to the DLQ.

Dead Letter Queue (DLQ)

Failed jobs are stored in:

rq:dlq

DLQ entries contain:

• failure reason
• attempt count
• timestamps

Idempotency

If an idempotencyKey is provided:

• First execution succeeds
• Duplicate submissions are ignored
• Retries are not blocked

Graceful Shutdown

await queue.close();

Safely stops worker and closes Redis connections.

🎯 Use Cases

• Email processing
• Webhook consumers
• Payment confirmation retries
• Background jobs
• Distributed microservices tasks