bullmq-jobs

When to trigger

• Authoring producer-side queue.add() calls inside a route handler or service.
• Authoring a queue worker (Worker) class to process a queue.
• Designing or modifying retry policy (backoff, max attempts).
• Idempotency-key design for a job type.
• Configuring a dead-letter queue (DLQ) for failed jobs.
• Queue health monitoring (active, waiting, failed counters).

Procedure

1. Queue definition in src/queues/<name>.ts: export a singleton Queue instance with the queue name as a typed constant. The cache/Redis connection is imported from the shared connection module — never inline a connection string.

2. Producer call in the route handler or service:

   await queue.add(JOB_NAME, data, {
     jobId: deriveIdempotencyKey(data),
     attempts: 3,
     backoff: { type: 'exponential', delay: 1000 },
   });
   

   Every queue.add() call has a jobId (idempotency key). Add a // dispatched-to: <queue-name> comment so the consumer is traceable from the producer.

3. Consumer in src/workers/<name>.worker.ts: export a Worker instance wrapping the queue name and a processor function. The processor receives a Job<DataType> and returns a result or throws on unrecoverable failure.

4. Retry policy — defaults: exponential backoff, 3 attempts. { attempts: 3, backoff: { type: 'exponential', delay: 1000 } } means: first retry after 1 s, second after 2 s, third after 4 s. Override per spec when the job has different SLA requirements.

5. Idempotency key: derive deterministically from the job payload so that retrying the same logical operation does not produce duplicate side effects. Example: jobId = \-${entityId}-${dateStr}`` for a recurring ingestion job. Document the derivation strategy in a comment.

6. DLQ pattern: configure removeOnFail: false and a failed event listener that logs the failure and — for critical queues — publishes to an alerting channel. For spec-defined critical queues, a separate DLQ queue (<name>-dlq) receives failed jobs after max attempts via a manual failed event handler.