Introduction

@warlock.js/queue gives Warlock apps durable background jobs backed by BullMQ and Redis. Jobs are stored, not held in memory, so they survive a process restart and can retry on failure.

Installation

npm install @warlock.js/queue

Redis (5.0+, or any Redis-compatible server BullMQ supports — Valkey, Dragonfly) must already be running; this package does not start or bundle it.

Configure and connect

src/config/queue.ts

import type { QueueConfig } from "@warlock.js/queue";

const queueConfig: QueueConfig = {
  connection: { host: "127.0.0.1", port: 6379 },
  defaultJobOptions: { attempts: 3, backoff: { type: "exponential", delay: 1000 } },
};

export default queueConfig;

warlock.config.ts

import { defineConfig } from "@warlock.js/core";
import { queueConnector } from "@warlock.js/queue";

export default defineConfig({
  connectors: [queueConnector()],
});

The connector reads the queue config key, starts one worker per queue name that has a registered job, and stops taking new work on shutdown while active jobs finish. See Configuration.

Define and dispatch a job

import { defineJob } from "@warlock.js/queue";

export const sendInvoice = defineJob({
  name: "invoices.send",
  attempts: 5,
  backoff: { type: "exponential", delay: 2000 },
  async handle(payload: { invoiceId: string }, ctx) {
    await ctx.progress(10);
    // ... work ...
    await ctx.progress(100);
    return { sent: true };
  },
});

await sendInvoice.dispatch({ invoiceId: "42" });
await sendInvoice.dispatch({ invoiceId: "43" }, { delay: "10m", priority: 1, jobId: "invoice:43" });

defineJob registers the handler by name in a process-wide registry; dispatch enqueues a payload for any worker sharing that registry to run. See Defining jobs.

What’s next

| Topic | Description | |---|---| | Defining jobs | defineJob, dispatch options, job context | | Configuration | QueueConfig, the connector, dispatch-only processes | | Retry & failed jobs | Backoff, failedJobs(), retryFailedJob() | | Notifications | Deliver @warlock.js/notifications .queue() through BullMQ | | Dashboard | The optional bull-board UI |