Patrones BullMQ
Guía rápida: Usa BullMQ (v5.x) para procesamiento de trabajos en segundo plano, planificación de tareas y orquestación de flujos de trabajo sobre Redis. Clases principales:
Queue(añade trabajos),Worker(procesa trabajos),QueueEvents(oyente de eventos global),FlowProducer(árboles de trabajos padre-hijo). Siempre pasa un objetoconnectiona cada constructor (requerido en v5). EstablecemaxRetriesPerRequest: nullen las conexiones ioredis para Workers. UsaupsertJobSchedulerpara trabajos repetitivos/cron (reemplaza la API repetitiva obsoleta). QueueScheduler se eliminó en v4 -- sus responsabilidades ahora son manejadas automáticamente por los Workers.
<critical_requirements>
CRÍTICO: Antes de Usar Este Skill
Todo el código debe seguir las convenciones del proyecto en CLAUDE.md (kebab-case, exportaciones nombradas, orden de importaciones,
import type, constantes nombradas)
(DEBES pasar un objeto connection a cada constructor de Queue, Worker, QueueEvents y FlowProducer -- BullMQ v5 lanza un error si falta la conexión)
(DEBES establecer maxRetriesPerRequest: null en las conexiones ioredis usadas por Workers -- BullMQ requiere reintentos infinitos y lanza un error sin esta configuración)
(DEBES llamar a await worker.close() en SIGTERM/SIGINT para un cierre graceful -- sin ello, los trabajos en curso se vuelven estancados)
(DEBES usar upsertJobScheduler para trabajos repetitivos/cron -- la antigua opción repeat en queue.add está obsoleta desde v5.16.0)
</critical_requirements>
Ejemplos
- Patrones Básicos -- Configuración de colas, procesamiento con Workers, opciones de trabajos, fábrica de conexiones, cierre graceful, trabajos tipados
- Patrones Avanzados -- FlowProducer, limitación de tasa, planificación de trabajos, QueueEvents, concurrencia, procesadores sandbox
Recursos adicionales:
- reference.md -- Marcos de decisión, referencia de opciones de trabajos, antipatrones, lista de verificación de producción
Auto-detección: BullMQ, bullmq, Queue, Worker, QueueEvents, FlowProducer, cola de trabajos, trabajo en segundo plano, proceso worker, planificador de trabajos, upsertJobScheduler, limitador de tasa, prioridad de trabajo, retraso de trabajo, procesador sandbox, trabajo repetitivo, trabajo cron, flow producer, trabajos padre hijo
Cuándo usar:
- Procesamiento en segundo plano (envío de correos, procesamiento de imágenes, generación de PDFs)
- Trabajos programados/cron (informes nocturnos, limpieza periódica)
- Orquestación de flujos de trabajo con dependencias padre-hijo (FlowProducer)
- Consumo de APIs con limitación de tasa (limitando solicitudes salientes)
- Procesamiento de trabajos basado en prioridad (trabajos urgentes antes que operaciones masivas)
- Distribución de trabajo intensivo en CPU entre múltiples workers o máquinas
Patrones clave cubiertos:
- Configuración de Queue y Worker con datos de trabajo y valores de retorno tipados
- Fábrica de conexiones con
maxRetriesPerRequest: nullpara Workers - Opciones de trabajo: retraso, prioridad, intentos, backoff, removeOnComplete/Fail
- Cierre graceful con
worker.close()en señales de proceso - FlowProducer para árboles de trabajos padre-hijo con seguimiento de dependencias
- Planificadores de trabajos para trabajos repetitivos/cron (
upsertJobScheduler) - Limitación de tasa (limitador global y
Worker.RateLimitErrormanual) - Control de concurrencia (local por worker y global)
- QueueEvents para monitoreo global de eventos en todos los workers
- Procesadores sandbox para trabajo intensivo en CPU
Cuándo NO usar:
- Temporizadores simples en proceso o
setTimeout(sin necesidad de persistencia) - Mensajería pub/sub en tiempo real sin persistencia (usa tu solución pub/sub)
- Datos que deben procesarse sincrónicamente dentro de un ciclo solicitud-respuesta
- Colas que no necesitan persistencia, reintentos o planificación
Filosofía
BullMQ es una cola de trabajos respaldada por Redis para Node.js que proporciona procesamiento en segundo plano confiable con garantías de entrega al menos una vez. El principio central: separar la producción de trabajos del consumo de trabajos para que tu aplicación se mantenga receptiva mientras el trabajo ocurre de forma asíncrona.
Principios básicos:
- Los productores y consumidores están desacoplados -- Cualquier proceso puede añadir trabajos a una cola; cualquier Worker puede procesarlos. Esto permite escalar horizontalmente añadiendo más Workers.
- Los trabajos son persistentes -- Los trabajos sobreviven a los reinicios del proceso porque viven en Redis. Los trabajos de un Worker que falla son retomados por otros Workers (o el mismo Worker después de reiniciar).
- Entrega al menos una vez -- BullMQ garantiza que cada trabajo se procesa al menos una vez. Usa procesadores idempotentes para manejar el (raro) caso de procesamiento duplicado después de un estancamiento.
- Falla gracefully con reintentos -- Configura estrategias de
attemptsybackoffpara que los fallos transitorios se resuelvan automáticamente. Los trabajos fallados permanentemente se mueven al conjunto de fallos para inspección. - Cada Queue/Worker/QueueEvents necesita su propia conexión -- BullMQ gestiona el estado de la conexión internamente. Nunca compartas una única instancia de ioredis entre múltiples clases de BullMQ (excepto Queues que actúan solo como productores).
Patrones Básicos
Patrón 1: Fábrica de Conexiones
BullMQ v5 requiere una conexión Redis explícita en cada constructor. Los Workers necesitan maxRetriesPerRequest: null para que ioredis reintente indefinidamente en lugar de rendirse.
import Redis from "ioredis";
function createBullMQConnection(): Redis {
const url = process.env.REDIS_URL;
if (!url) throw new Error("REDIS_URL es requerido");
return new Redis(url, { maxRetriesPerRequest: null });
}
export { createBullMQConnection };
Por qué es bueno: maxRetriesPerRequest: null satisface el requisito de BullMQ, la fábrica asegura una configuración consistente, la variable de entorno mantiene las credenciales fuera del código
// Mal -- falta maxRetriesPerRequest
const redis = new Redis("redis://localhost:6379");
const worker = new Worker("emails", processor, { connection: redis });
// BullMQ lanza: "maxRetriesPerRequest debe ser null"
Por qué es malo: BullMQ requiere reintentos infinitos en conexiones de Workers y lanzará un error al inicio sin null
Consulta examples/core.md para la fábrica de conexiones completa con separación de productor y consumidor.
Patrón 2: Configuración de Queue y Worker
Queue añade trabajos; Worker los procesa. Ambos aceptan genéricos TypeScript para datos de trabajo y valores de retorno tipados.
import { Queue, Worker, type Job } from "bullmq";
interface EmailJobData {
to: string;
subject: string;
body: string;
}
const QUEUE_NAME = "emails";
const emailQueue = new Queue<EmailJobData>(QUEUE_NAME, {
connection: createBullMQConnection(),
});
const emailWorker = new Worker<EmailJobData>(
QUEUE_NAME,
async (job: Job<EmailJobData>) => {
await sendEmail(job.data.to, job.data.subject, job.data.body);
},
{ connection: createBullMQConnection() },
);
Por qué es bueno: Los genéricos imponen seguridad de tipos en job.data, conexiones separadas para Queue y Worker, constante nombrada para el nombre de la cola
Consulta examples/core.md para la configuración completa con eventos, manejo de errores y valores de retorno tipados.
Patrón 3: Opciones de Trabajo
Controla el comportamiento del trabajo con opciones: retraso, prioridad, reintentos, backoff y eliminación automática.
const MAX_ATTEMPTS = 5;
const BACKOFF_DELAY_MS = 1000;
const DELAY_MS = 60_000;
const KEEP_COMPLETED_COUNT = 100;
await emailQueue.add(
"send-welcome",
{ to: "[email protected]", subject: "Bienvenido", body: "..." },
{
delay: DELAY_MS,
priority: 1, // 1 = más alta, números más altos = prioridad más baja
attempts: MAX_ATTEMPTS,
backoff: { type: "exponential", delay: BACKOFF_DELAY_MS },
removeOnComplete: { count: KEEP_COMPLETED_COUNT },
removeOnFail: false,
},
);
Por qué es bueno: Constantes nombradas para todos los valores numéricos, backoff exponencial para fallos transitorios, removeOnComplete con count previene el crecimiento ilimitado de la memoria de Redis, removeOnFail: false preserva trabajos fallados para depuración
Consulta examples/core.md para patrones de defaultJobOptions, addBulk y LIFO.
Patrón 4: Cierre Graceful
Llama a worker.close() en señales de proceso para finalizar trabajos en curso antes de salir. Sin esto, los trabajos se vuelven estancados y son reprocesados por otros Workers.
async function shutdown(workers: Worker[]): Promise<void> {
await Promise.all(workers.map((w) => w.close()));
process.exit(0);
}
process.on("SIGTERM", () => shutdown([emailWorker]));
process.on("SIGINT", () => shutdown([emailWorker]));
Por qué es bueno: close() deja de aceptar nuevos trabajos y espera a que los trabajos en curso finalicen, Promise.all maneja múltiples workers, los manejadores de señales cubren tanto SIGTERM como SIGINT
Trampa: worker.close() no tiene tiempo de espera integrado. Si un procesador se cuelga, el cierre se cuelga. Envuelve con tu propio tiempo de espera si es necesario.
Consulta examples/core.md para el cierre con patrón de tiempo de espera.
Patrón 5: FlowProducer (Trabajos Padre-Hijo)
FlowProducer crea árboles de trabajos donde los trabajos padre esperan a que todos los hijos se completen. Todo el árbol se añade atómicamente.
import { FlowProducer } from "bullmq";
const flowProducer = new FlowProducer({ connection: createBullMQConnection() });
await flowProducer.add({
name: "publish-video",
queueName: "videos",
children: [
{ name: "extract-audio", queueName: "media", data: { videoId: "abc" } },
{
name: "generate-thumbnail",
queueName: "media",
data: { videoId: "abc" },
},
{
name: "transcode",
queueName: "media",
data: { videoId: "abc", format: "mp4" },
},
],
});
Por qué es bueno: El padre espera hasta que todos los hijos se completen, adición atómica (todo o nada), los hijos pueden estar en diferentes colas, el procesador padre puede acceder a los resultados de los hijos mediante job.getChildrenValues()
Consulta examples/advanced.md para acceder a los valores de los hijos y flujos anidados.
Patrón 6: Planificadores de Trabajos (Trabajos Repetitivos/Cron)
Usa upsertJobScheduler (v5.16.0+) para trabajos repetitivos. Reemplaza la opción repeat obsoleta.
const REPORT_INTERVAL_MS = 3_600_000; // 1 hora
// Intervalo fijo
await emailQueue.upsertJobScheduler(
"hourly-digest",
{ every: REPORT_INTERVAL_MS },
{
name: "send-digest",
data: { type: "hourly" },
},
);
// Expresión Cron -- diariamente a las 3:15 AM
await emailQueue.upsertJobScheduler(
"nightly-cleanup",
{ pattern: "0 15 3 * * *" },
{
name: "cleanup",
data: { type: "nightly" },
opts: { removeOnComplete: true },
},
);
Por qué es bueno: upsertJobScheduler es idempotente (seguro de llamar en cada inicio), la plantilla define el nombre/datos/opts del trabajo heredados por cada trabajo producido, sintaxis cron mediante pattern
Trampa: Los intervalos every se alinean con el reloj, no con el momento en que llamaste a upsertJobScheduler. Un intervalo de 2000ms se dispara a los 0s, 2s, 4s, etc.
Consulta examples/advanced.md para eliminar planificadores y listar planificadores activos.
Patrón 7: Limitación de Tasa
Limita cuántos trabajos procesa un Worker por ventana de tiempo. El limitador es global entre todos los Workers en la misma cola.
const RATE_LIMIT_MAX = 10;
const RATE_LIMIT_DURATION_MS = 1000;
const worker = new Worker("api-calls", processor, {
connection: createBullMQConnection(),
limiter: { max: RATE_LIMIT_MAX, duration: RATE_LIMIT_DURATION_MS },
});
Por qué es bueno: Límite de tasa global (10 workers con esta configuración aún procesan un máximo de 10 trabajos/segundo en total), constantes nombradas para los límites
Para limitación de tasa dinámica basada en respuestas de API externas, usa worker.rateLimit(duration) + throw Worker.RateLimitError(). Consulta examples/advanced.md.
Patrón 8: QueueEvents para Monitoreo Global
QueueEvents usa Redis Streams (no Pub/Sub) para que los eventos sean confiables incluso a través de reconexiones. Requiere su propia conexión dedicada.
import { QueueEvents } from "bullmq";
const queueEvents = new QueueEvents(QUEUE_NAME, {
connection: createBullMQConnection(),
});
queueEvents.on("completed", ({ jobId, returnvalue }) => {
console.log(`Trabajo ${jobId} completado con: ${returnvalue}`);
});
queueEvents.on("failed", ({ jobId, failedReason }) => {
console.error(`Trabajo ${jobId} falló: ${failedReason}`);
});
Por qué es bueno: Monitorea todos los Workers en una cola desde un único oyente, entrega confiable mediante Redis Streams, conexión separada según requerimiento
Consulta examples/advanced.md para seguimiento de progreso y espera de finalización de un trabajo específico.
Optimización de Rendimiento
- Concurrencia -- Establece
concurrencyen las opciones del Worker para procesar múltiples trabajos en paralelo dentro de una sola instancia de Worker:{ concurrency: 10 }. Solo efectivo para trabajo ligado a E/S. El trabajo ligado a CPU bloquea el bucle de eventos y causa trabajos estancados -- usa procesadores sandbox en su lugar. - Procesadores sandbox -- Pasa una ruta de archivo en lugar de una función al constructor de Worker para ejecutar procesadores en un proceso separado (o hilo de trabajo con
useWorkerThreads: true). Previene que el trabajo intensivo en CPU bloquee la renovación del bloqueo. - addBulk -- Usa
queue.addBulk([...])para añadir muchos trabajos en un solo viaje de ida y vuelta a Redis en lugar de llamar aqueue.add()en un bucle. - removeOnComplete/Fail -- Configura la eliminación automática para evitar el crecimiento ilimitado de la memoria de Redis. Usa
{ count: N }para mantener los últimos N trabajos para depuración. - Conexiones separadas -- Los productores (Queue) pueden compartir una conexión. Los Workers y QueueEvents necesitan su propia conexión debido a comandos Redis bloqueantes.
<decision_framework>
Marco de Decisión
Cuándo Usar BullMQ
¿Necesitas procesamiento de trabajos en segundo plano?
|-- NO -> No uses BullMQ
+-- SÍ -> ¿Necesitas persistencia, reintentos o planificación?
|-- NO -> Una cola simple en proceso o setTimeout puede ser suficiente
+-- SÍ -> ¿Necesitas dependencias padre-hijo?
|-- SÍ -> BullMQ con FlowProducer
+-- NO -> ¿Necesitas limitación de tasa o prioridad?
|-- SÍ -> BullMQ con opciones de limitador/prioridad
+-- NO -> BullMQ con Queue + Worker básico
¿Qué Patrón de Trabajo?
¿Qué tipo de planificación de trabajos necesitas?
|-- Trabajo único con retraso -> queue.add() con opción delay
|-- Trabajo repetitivo/cron -> upsertJobScheduler con every/pattern
|-- Árbol de trabajos padre-hijo -> FlowProducer.add() con children
|-- Procesamiento con limitación de tasa -> Worker con opción limiter
|-- Procesamiento paralelo -> Worker con opción concurrency
|-- Trabajo intensivo en CPU -> Worker con procesador sandbox
</decision_framework>
<anti_patterns>
Antipatrones
| Mal | Por qué | Bien |
|---|---|---|
| Compartir la misma instancia de Redis entre Queue y Worker | Los Workers usan comandos bloqueantes que interferirían | Usa conexiones separadas (fábrica de conexiones) |
Usar queue.add() con repeat después de v5.16.0 | API obsoleta desde v5.16.0 | Usa upsertJobScheduler con every/pattern |
Depender de process.on('exit') para cerrar Workers | No captura SIGTERM/SIGINT | Captura SIGTERM y SIGINT para llamar a worker.close() |
| Usar BullMQ para mensajería pub/sub sin persistencia | BullMQ está diseñado para colas persistentes | Usa Redis Pub/Sub, RabbitMQ u otra solución de mensajería |
Ignorar maxRetriesPerRequest: null en Workers | BullMQ lanza error al inicio | Siempre establece maxRetriesPerRequest: null en conexiones de Workers |
| Procesar trabajo intensivo en CPU en el bucle de eventos principal | Bloquea la renovación del bloqueo -> trabajos estancados | Usa procesadores sandbox o trabaja en Worker/Thread separados |
| No establecer removeOnComplete/Fail | La memoria de Redis crece sin límite | Configura removeOnComplete/Fail con count o age |
</anti_patterns>
Lista de Verificación de Producción
- ¿Todas las conexiones de Workers tienen
maxRetriesPerRequest: null? - ¿Se pasa un objeto
connectiona todos los constructores (Queue, Worker, QueueEvents, FlowProducer)? - ¿Se llama a
worker.close()en SIGTERM/SIGINT? - ¿Hay un tiempo de espera en el cierre para evitar cuelgues?
- ¿Se usa
upsertJobScheduleren lugar de la opciónrepeatobsoleta? - ¿Están configurados
removeOnCompleteyremoveOnFailcon límites? - ¿Están las credenciales de Redis en variables de entorno?
- ¿Hay monitoreo configurado (QueueEvents, logs, métricas)?
- ¿Los procesadores son idempotentes para manejar procesamiento duplicado?
- ¿Se usa
addBulkpara adiciones masivas de trabajos? - ¿Están separadas las conexiones de productores, Workers y QueueEvents?