bullmq

Name: bullmq
Author: jgamaraalv

67installs0forks

How to install bullmq?

jgamaraalv/ts-dev-kit/bullmq

$npx -y skills add jgamaraalv/ts-dev-kit --skill bullmq

Installs into the current project.

Summary

BullMQ queue system reference for Redis-backed job queues, workers, flows, and schedulers. Use when: (1) creating queues and workers with BullMQ, (2) adding jobs (delayed, prioritized, repeatable, deduplicated), (3) setting up FlowProducer parent-child job hierarchies, (4) config

Files · 1

View on GitHub

SKILL.md

1	# BullMQ
2
3	Redis-backed queue system for Node.js. Four core classes: `Queue`, `Worker`, `QueueEvents`, `FlowProducer`.
4
5	## Table of Contents
6
7	- [Install](#install)
8	- [Quick Start](#quick-start)
9	- [Connections](#connections)
10	- [Queue](#queue)
11	- [Worker](#worker)
12	- [TypeScript Generics](#typescript-generics)
13	- [Events](#events)
14	- [Job Lifecycle States](#job-lifecycle-states)
15	- [Advanced Topics](#advanced-topics)
16
17	## Install
18
19	`yarn add bullmq` — requires Redis 5.0+ with `maxmemory-policy=noeviction`.
20
21	<quick_reference>
22
23	## Quick Start
24
25	```ts
26	import { Queue, Worker, QueueEvents } from "bullmq";
27
28	// --- Producer ---
29	const queue = new Queue("my-queue", {
30	connection: { host: "localhost", port: 6379 },
31	});
32
33	await queue.add("job-name", { foo: "bar" });
34
35	// --- Consumer ---
36	const worker = new Worker(
37	"my-queue",
38	async (job) => {
39	// process job
40	await job.updateProgress(50);
41	return { result: "done" };
42	},
43	{ connection: { host: "localhost", port: 6379 } },
44	);
45
46	worker.on("completed", (job, returnvalue) => {
47	console.log(`${job.id} completed with`, returnvalue);
48	});
49
50	worker.on("failed", (job, err) => {
51	console.error(`${job.id} failed with`, err.message);
52	});
53
54	// IMPORTANT: always attach an error handler
55	worker.on("error", (err) => {
56	console.error(err);
57	});
58
59	// --- Global event listener (all workers) ---
60	const queueEvents = new QueueEvents("my-queue", {
61	connection: { host: "localhost", port: 6379 },
62	});
63
64	queueEvents.on("completed", ({ jobId, returnvalue }) => {
65	console.log(`Job ${jobId} completed`);
66	});
67
68	queueEvents.on("failed", ({ jobId, failedReason }) => {
69	console.error(`Job ${jobId} failed: ${failedReason}`);
70	});
71	```
72
73	## Job Lifecycle States
74
75	```
76	add() → wait / prioritized / delayed
77	↓
78	active → completed
79	↓
80	failed → (retry) → wait/delayed
81	```
82
83	With FlowProducer: jobs can also be in `waiting-children` state until all children complete.
84
85	</quick_reference>
86
87	<rules>
88
89	## Connections
90
91	BullMQ uses ioredis internally. Pass `connection` options or an existing ioredis instance.
92
93	```ts
94	import { Queue, Worker } from "bullmq";
95	import { Redis } from "ioredis";
96
97	// Option 1: connection config (new connection per instance)
98	const queue = new Queue("q", {
99	connection: { host: "redis.example.com", port: 6379 },
100	});
101
102	// Option 2: reuse ioredis instance (Queue and multiple Queues can share)
103	const connection = new Redis();
104	const q1 = new Queue("q1", { connection });
105	const q2 = new Queue("q2", { connection });
106
107	// Option 3: reuse for Workers (BullMQ internally duplicates for blocking)
108	const workerConn = new Redis({ maxRetriesPerRequest: null });
109	const w1 = new Worker("q1", async (job) => {}, { connection: workerConn });
110	```
111
112	Critical rules:
113
114	- Workers REQUIRE `maxRetriesPerRequest: null` on the ioredis instance. BullMQ enforces this and will warn/throw if not set.
115	- Do NOT use ioredis `keyPrefix` option — use BullMQ's `prefix` option instead.
116	- `QueueEvents` cannot share connections (uses blocking Redis commands).
117	- Redis MUST have `maxmemory-policy=noeviction`.
118
119	</rules>
120
121	<examples>
122
123	## Queue
124
125	```ts
126	const queue = new Queue("paint", { connection });
127
128	// Add a job
129	await queue.add("job-name", { color: "red" });
130
131	// Add with options
132	await queue.add(
133	"job-name",
134	{ color: "blue" },
135	{
136	delay: 5000, // wait 5s before processing
137	priority: 1, // lower = higher priority (0 is highest, max 2^21)
138	attempts: 3, // retry up to 3 times
139	backoff: { type: "exponential", delay: 1000 },
140	removeOnComplete: true, // or { count: 100 } to keep last 100
141	removeOnFail: 1000, // keep last 1000 failed jobs
142	},
143	);
144
145	// Add bulk
146	await queue.addBulk([
147	{ name: "job1", data: { x: 1 } },
148	{ name: "job2", data: { x: 2 }, opts: { priority: 1 } },
149	]);
150
151	// Queue operations
152	await queue.pause();
153	await queue.resume();
154	await queue.obliterate({ force: true }); // remove all data
155	await queue.close();
156	```
157
158	## Worker
159
160	```ts
161	const worker = new Worker<MyData, MyReturn>(
162	"paint",
163	async (job) => {
164	await job.updateProgress(42);
165	return { cost: 100 };
166	},
167	{
168	connection,
169	concurrency: 5, // process 5 jobs concurrently
170	autorun: false, // don't start immediately
171	},
172	);
173
174	worker.run(); // start when ready
175
176	// Update concurrency at runtime
177	worker.concurrency = 10;
178	```
179
180	Processor receives 3 args: `(job, token?, signal?)` — signal is an `AbortSignal` for cancellation support.
181
182	## TypeScript Generics
183
184	```ts
185	interface JobDa

People who liked this also viewed

6 picks

Type

bullmq

67installs0forks

View on GitHub

How to install bullmq?

jgamaraalv/ts-dev-kit/bullmq

$npx -y skills add jgamaraalv/ts-dev-kit --skill bullmq

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# BullMQ
2
3	Redis-backed queue system for Node.js. Four core classes: `Queue`, `Worker`, `QueueEvents`, `FlowProducer`.
4
5	## Table of Contents
6
7	- [Install](#install)
8	- [Quick Start](#quick-start)
9	- [Connections](#connections)
10	- [Queue](#queue)
11	- [Worker](#worker)
12	- [TypeScript Generics](#typescript-generics)
13	- [Events](#events)
14	- [Job Lifecycle States](#job-lifecycle-states)
15	- [Advanced Topics](#advanced-topics)
16
17	## Install
18
19	`yarn add bullmq` — requires Redis 5.0+ with `maxmemory-policy=noeviction`.
20
21	<quick_reference>
22
23	## Quick Start
24
25	```ts
26	import { Queue, Worker, QueueEvents } from "bullmq";
27
28	// --- Producer ---
29	const queue = new Queue("my-queue", {
30	connection: { host: "localhost", port: 6379 },
31	});
32
33	await queue.add("job-name", { foo: "bar" });
34
35	// --- Consumer ---
36	const worker = new Worker(
37	"my-queue",
38	async (job) => {
39	// process job
40	await job.updateProgress(50);
41	return { result: "done" };
42	},
43	{ connection: { host: "localhost", port: 6379 } },
44	);
45
46	worker.on("completed", (job, returnvalue) => {
47	console.log(`${job.id} completed with`, returnvalue);
48	});
49
50	worker.on("failed", (job, err) => {
51	console.error(`${job.id} failed with`, err.message);
52	});
53
54	// IMPORTANT: always attach an error handler
55	worker.on("error", (err) => {
56	console.error(err);
57	});
58
59	// --- Global event listener (all workers) ---
60	const queueEvents = new QueueEvents("my-queue", {
61	connection: { host: "localhost", port: 6379 },
62	});
63
64	queueEvents.on("completed", ({ jobId, returnvalue }) => {
65	console.log(`Job ${jobId} completed`);
66	});
67
68	queueEvents.on("failed", ({ jobId, failedReason }) => {
69	console.error(`Job ${jobId} failed: ${failedReason}`);
70	});
71	```
72
73	## Job Lifecycle States
74
75	```
76	add() → wait / prioritized / delayed
77	↓
78	active → completed
79	↓
80	failed → (retry) → wait/delayed
81	```
82
83	With FlowProducer: jobs can also be in `waiting-children` state until all children complete.
84
85	</quick_reference>
86
87	<rules>
88
89	## Connections
90
91	BullMQ uses ioredis internally. Pass `connection` options or an existing ioredis instance.
92
93	```ts
94	import { Queue, Worker } from "bullmq";
95	import { Redis } from "ioredis";
96
97	// Option 1: connection config (new connection per instance)
98	const queue = new Queue("q", {
99	connection: { host: "redis.example.com", port: 6379 },
100	});
101
102	// Option 2: reuse ioredis instance (Queue and multiple Queues can share)
103	const connection = new Redis();
104	const q1 = new Queue("q1", { connection });
105	const q2 = new Queue("q2", { connection });
106
107	// Option 3: reuse for Workers (BullMQ internally duplicates for blocking)
108	const workerConn = new Redis({ maxRetriesPerRequest: null });
109	const w1 = new Worker("q1", async (job) => {}, { connection: workerConn });
110	```
111
112	Critical rules:
113
114	- Workers REQUIRE `maxRetriesPerRequest: null` on the ioredis instance. BullMQ enforces this and will warn/throw if not set.
115	- Do NOT use ioredis `keyPrefix` option — use BullMQ's `prefix` option instead.
116	- `QueueEvents` cannot share connections (uses blocking Redis commands).
117	- Redis MUST have `maxmemory-policy=noeviction`.
118
119	</rules>
120
121	<examples>
122
123	## Queue
124
125	```ts
126	const queue = new Queue("paint", { connection });
127
128	// Add a job
129	await queue.add("job-name", { color: "red" });
130
131	// Add with options
132	await queue.add(
133	"job-name",
134	{ color: "blue" },
135	{
136	delay: 5000, // wait 5s before processing
137	priority: 1, // lower = higher priority (0 is highest, max 2^21)
138	attempts: 3, // retry up to 3 times
139	backoff: { type: "exponential", delay: 1000 },
140	removeOnComplete: true, // or { count: 100 } to keep last 100
141	removeOnFail: 1000, // keep last 1000 failed jobs
142	},
143	);
144
145	// Add bulk
146	await queue.addBulk([
147	{ name: "job1", data: { x: 1 } },
148	{ name: "job2", data: { x: 2 }, opts: { priority: 1 } },
149	]);
150
151	// Queue operations
152	await queue.pause();
153	await queue.resume();
154	await queue.obliterate({ force: true }); // remove all data
155	await queue.close();
156	```
157
158	## Worker
159
160	```ts
161	const worker = new Worker<MyData, MyReturn>(
162	"paint",
163	async (job) => {
164	await job.updateProgress(42);
165	return { cost: 100 };
166	},
167	{
168	connection,
169	concurrency: 5, // process 5 jobs concurrently
170	autorun: false, // don't start immediately
171	},
172	);
173
174	worker.run(); // start when ready
175
176	// Update concurrency at runtime
177	worker.concurrency = 10;
178	```
179
180	Processor receives 3 args: `(job, token?, signal?)` — signal is an `AbortSignal` for cancellation support.
181
182	## TypeScript Generics
183
184	```ts
185	interface JobDa

People who liked this also viewed

6 picks

Type