Communitygithub.com

agents-inc/skills

Colas de trabajos, procesamiento en segundo plano y planificación de tareas con BullMQ v5

¿Qué es skills?

Este skill proporciona una guía completa para usar BullMQ (v5.x) para el procesamiento de trabajos en segundo plano, planificación de tareas y orquestación de flujos de trabajo sobre Redis. Cubre las clases principales (Queue, Worker, QueueEvents, FlowProducer) y sus configuraciones críticas, como la obligatoriedad de pasar un objeto `connection` a cada constructor y establecer `maxRetriesPerRequest: null` en las conexiones ioredis para Workers. Incluye patrones esenciales como la creación de una fábrica de conexiones, configuración de colas y workers con tipos TypeScript, opciones de trabajos (retraso, prioridad, reintentos, backoff), cierre graceful, FlowProducer para dependencias padre-hijo, y programación de trabajos repetitivos/cron con `upsertJobScheduler`. También aborda la limitación de tasa, el monitoreo global con QueueEvents y la optimización del rendimiento mediante concurrencia y procesadores sandbox. El skill está diseñado para desarrolladores que necesitan integrar BullMQ en sus aplicaciones Node.js, asegurando prácticas recomendadas y evitando errores comunes como olvidar configuraciones obligatorias o no cerrar workers correctamente.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/agents-inc/skills/tree/HEAD/src/skills/api-queue-bullmq

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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 objeto connection a cada constructor (requerido en v5). Establece maxRetriesPerRequest: null en las conexiones ioredis para Workers. Usa upsertJobScheduler para 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: null para 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.RateLimitError manual)
  • 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:

  1. 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.
  2. 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).
  3. 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.
  4. Falla gracefully con reintentos -- Configura estrategias de attempts y backoff para que los fallos transitorios se resuelvan automáticamente. Los trabajos fallados permanentemente se mueven al conjunto de fallos para inspección.
  5. 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 concurrency en 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 a queue.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

MalPor quéBien
Compartir la misma instancia de Redis entre Queue y WorkerLos Workers usan comandos bloqueantes que interferiríanUsa conexiones separadas (fábrica de conexiones)
Usar queue.add() con repeat después de v5.16.0API obsoleta desde v5.16.0Usa upsertJobScheduler con every/pattern
Depender de process.on('exit') para cerrar WorkersNo captura SIGTERM/SIGINTCaptura SIGTERM y SIGINT para llamar a worker.close()
Usar BullMQ para mensajería pub/sub sin persistenciaBullMQ está diseñado para colas persistentesUsa Redis Pub/Sub, RabbitMQ u otra solución de mensajería
Ignorar maxRetriesPerRequest: null en WorkersBullMQ lanza error al inicioSiempre establece maxRetriesPerRequest: null en conexiones de Workers
Procesar trabajo intensivo en CPU en el bucle de eventos principalBloquea la renovación del bloqueo -> trabajos estancadosUsa procesadores sandbox o trabaja en Worker/Thread separados
No establecer removeOnComplete/FailLa memoria de Redis crece sin límiteConfigura 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 connection a 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 upsertJobScheduler en lugar de la opción repeat obsoleta?
  • ¿Están configurados removeOnComplete y removeOnFail con 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 addBulk para adiciones masivas de trabajos?
  • ¿Están separadas las conexiones de productores, Workers y QueueEvents?

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

Skills relacionados