web-beast-queue

A clean, opinionated Node.js queue package that adds only one folder to your project.

Features

• ✅ Only ONE folder added: queue/
• ✅ Works with any Node.js project (Express, Fastify, Nest, custom)
• ✅ Zero "folder pollution"
• ✅ No messy architecture
• ✅ Easy for all Node developers to accept
• ✅ Production-ready
• ✅ TypeScript and JavaScript support
• ✅ Multiple drivers: Sync, Redis, MongoDB, SQL

Quick Start

npm install web-beast-queue
npx web-beast-queue-init

This creates:

• queue/config.ts - Queue configuration
• queue/jobs/ExampleJob.ts - Sample job
• queue/worker.ts - Worker entry point

Usage

Define a Job

// queue/jobs/SendEmailJob.ts
import { Job } from "web-beast-queue";

export default class SendEmailJob extends Job<{ email: string }> {
  async handle(data) {
    console.log("Sending email to", data.email);
    // Your job logic here
  }
}

Dispatch a Job

import SendEmailJob from "./queue/jobs/SendEmailJob";

// Dispatch from anywhere in your app
SendEmailJob.dispatch({ email: "[email protected]" });

Run Worker

# Compile TypeScript first (if using TS)
npm run build

# Run the worker
node queue/worker.js

# Or use the CLI
npx web-beast-queue-work

Drivers

Switch drivers via environment variable or config:

Sync Driver (Development)

// queue/config.ts
export default {
  driver: "sync" // or process.env.QUEUE_DRIVER || "sync"
};

Perfect for local development - jobs run immediately in memory.

Redis Driver

# Install Redis dependencies
npm install redis ioredis

// queue/config.ts
export default {
  driver: process.env.QUEUE_DRIVER || "redis",
  redis: {
    url: process.env.REDIS_URL // or host, port, password, db
  }
};

Environment variable:

QUEUE_DRIVER=redis
REDIS_URL=redis://localhost:6379

MongoDB Driver

# Install MongoDB dependencies
npm install mongodb

// queue/config.ts
export default {
  driver: process.env.QUEUE_DRIVER || "mongodb",
  mongodb: {
    url: process.env.MONGO_URL,
    database: "queue", // optional
    collection: "jobs" // optional
  }
};

Environment variable:

QUEUE_DRIVER=mongodb
MONGO_URL=mongodb://localhost:27017

SQL Driver

The SQL driver requires a specific SQL client library. Implement using:

• pg for PostgreSQL
• mysql2 for MySQL
• better-sqlite3 for SQLite

// queue/config.ts
export default {
  driver: process.env.QUEUE_DRIVER || "sql",
  sql: {
    connectionString: process.env.DATABASE_URL,
    table: "queue_jobs", // optional
    driver: "postgres" // optional
  }
};

Configuration

All configuration happens in queue/config.ts:

export default {
  driver: process.env.QUEUE_DRIVER || "sync",
  redis: {
    url: process.env.REDIS_URL
  },
  mongodb: {
    url: process.env.MONGO_URL
  },
  sql: {
    connectionString: process.env.DATABASE_URL
  }
};

Switch drivers without code changes - just update the config or environment variable!

Job Options

SendEmailJob.dispatch(
  { email: "[email protected]" },
  {
    delay: 5000,      // Delay in milliseconds
    attempts: 3       // Number of retry attempts
  }
);

Project Structure

After setup, your project will have:

your-project/
├── src/
│   └── ... (your existing code)
├── queue/                    👈 Only folder added
│   ├── jobs/
│   │   ├── SendEmailJob.ts
│   │   └── ProcessOrderJob.ts
│   ├── worker.ts
│   └── config.ts
└── package.json

Everything else stays inside node_modules/web-beast-queue/ - you never see it!

Philosophy

"Bring your own structure. We add only what's necessary."

This package respects your project structure and adds minimal files. Perfect for teams that want queue functionality without architectural changes.

Development

For development with TypeScript:

# Watch mode
npm run dev

# Build
npm run build

The sync driver is perfect for development - no external dependencies needed!

Production

For production, use Redis or MongoDB:

1. Set environment variable: QUEUE_DRIVER=redis
2. Configure connection in queue/config.ts
3. Run worker: npx web-beast-queue-work

Examples

Simple Job

// queue/jobs/LogJob.ts
import { Job } from "web-beast-queue";

export default class LogJob extends Job<{ message: string }> {
  async handle(data) {
    console.log(data.message);
  }
}

Job with Error Handling

// queue/jobs/ProcessPaymentJob.ts
import { Job } from "web-beast-queue";

export default class ProcessPaymentJob extends Job<{ orderId: string; amount: number }> {
  async handle(data) {
    try {
      // Process payment
      await this.chargeCard(data.orderId, data.amount);
    } catch (error) {
      // Error is automatically handled by the worker
      throw error;
    }
  }

  private async chargeCard(orderId: string, amount: number) {
    // Payment logic
  }
}

License

MIT

Credits

Built and maintained by Web Beast

🌐 https://www.web-beast.com/

🔗 https://github.com/brijmansuriya/web-beast-queue