noctcore-nestjs/worker-must-listen-failed
noctcore-nestjs/worker-must-listen-failed
- Package
- nestjs v0.2.0
- Preset
- recommended
- Severity
- error
- Autofix
- No
- Suggestions
- No
- Options
- Optional
- Type info
- Not needed
Every BullMQ new Worker(...) has a .on('failed', ...) listener in the same file.
When a BullMQ job throws, the worker moves it to the failed set, retries it if it has attempts left,
and emits a failed event. That event is the only signal. With no listener, nothing reaches the
logs or the error tracker: the email is never sent, the invoice is never generated, and the first
person to notice is the customer who asks where it went.
import { Worker } from 'bullmq';
const mailWorker = new Worker('mail', sendMail, { connection });import { Worker } from 'bullmq';
const mailWorker = new Worker('mail', sendMail, { connection });mailWorker.on('failed', (job, err) => logger.error({ jobId: job?.id, err }, 'mail job failed'));What it flags
Section titled “What it flags”- A
new Worker(...)bound to a name (const worker,this.worker =,this.worker ??=, or a class fieldprivate worker = new Worker(...)) when no<name>.on('failed', ...)appears anywhere in the file. Names are resolved through scope: a listener on another function’sw, or on thethis.workerof an unrelated class (a sibling subclass included), does not count. - A
new Worker(...)written as a bare statement with no.on('failed', ...)chained on it: nothing can ever subscribe to it. - With
requiredEvents, each listed event that has no listener. - A worker whose only listener is
.once('failed', ...)or.prependOnceListener('failed', ...): it hears the first failure and misses every later one.
import { Worker } from 'bullmq';
export class MailService { private worker = new Worker('mail', sendMail, { connection });
onModuleInit() { this.worker.on('completed', (job) => logger.info({ jobId: job.id }, 'mail sent')); }}import { Worker } from 'bullmq';
export class MailService { private worker = new Worker('mail', sendMail, { connection });
onModuleInit() { this.worker.on('completed', (job) => logger.info({ jobId: job.id }, 'mail sent')); this.worker.on('failed', (job, err) => logger.error({ jobId: job?.id, err }, 'mail failed')); }}What it does not flag
Section titled “What it does not flag”- A listener chained on the constructor:
new Worker(...).on('failed', ...), alone or after other.on(...)calls. - A listener attached through the same binding anywhere in the file, before or after the worker,
in any method of the class, with or without a non-null assertion (
this.worker!.on(...))..addListener('failed', ...)and.prependListener('failed', ...)count like.on. - A listener on
this.workerin a base class or a subclass declared in the same file: the field is shared along the hierarchy, so an abstract base service that wires the listeners covers the worker its subclass builds. Aconst self = thisalias reads the same field. - A worker held in a field of a class whose base class comes from another module, or is a
declare class: that base may attach the listener where the rule cannot see. A worker in a local variable of such a class is still checked. - A listener whose event name is not a static string, such as
worker.on(Events.Failed, ...)or an event from a loop: it may be thefailedlistener, so it counts for every event. Aconstholding a string (const FAILED = 'failed') is read, and'failed' as constis too. - A worker that is returned, passed to a function, stored in another variable, object or array, or
destructured (
const { worker } = this): the listener can be attached where it ends up. A chained assignment (const worker = this.worker = new Worker(...)) binds both names, so a listener on either counts. - A NestJS
@Processorclass extendingWorkerHost: Nest builds that worker, so there is nonew Worker(...)to check, and an@OnWorkerEvent('failed')method is how it listens. - A
Workerthat is not imported frombullmq, such as the one fromnode:worker_threads, a local class of the same name, or a parameter that shadows the import. A renamed import (import { Worker as BullWorker } from 'bullmq') is followed. - A namespace import (
import * as bullmq from 'bullmq') orrequire('bullmq').
import { Worker } from 'bullmq';
export function createMailWorker() { return new Worker('mail', sendMail, { connection });}
new Worker('reports', buildReport, { connection }).on('failed', (job, err) => { logger.error({ jobId: job?.id, err }, 'report failed');});
const exportWorker = new Worker('exports', runExport, { connection });for (const event of ['failed', 'error'] as const) { exportWorker.on(event, (...args) => logger.error({ event, args }, 'export worker event'));}import { Worker } from 'bullmq';
abstract class QueueWorker { protected abstract worker: Worker;
onModuleInit() { this.worker.on('failed', (job, err) => logger.error({ jobId: job?.id, err }, 'job failed')); }}
export class MailWorker extends QueueWorker { protected worker = new Worker('mail', sendMail, { connection });}Options
Section titled “Options”| Option | Type | Default | Meaning |
|---|---|---|---|
requiredEvents |
string[] |
['failed'] |
Events each worker needs a .on(event, ...) listener for. Replaces the default, so list failed too. |
'noctcore-nestjs/worker-must-listen-failed': ['error', { requiredEvents: ['failed', 'error'] }]// rule options: {"requiredEvents":["failed","error"]}import { Worker } from 'bullmq';
const mailWorker = new Worker('mail', sendMail, { connection });mailWorker.on('failed', (job, err) => logger.error({ jobId: job?.id, err }, 'mail job failed'));// rule options: {"requiredEvents":["failed","error"]}import { Worker } from 'bullmq';
const mailWorker = new Worker('mail', sendMail, { connection });mailWorker.on('failed', (job, err) => logger.error({ jobId: job?.id, err }, 'mail job failed'));mailWorker.on('error', (err) => logger.error({ err }, 'mail worker error'));When not to use it
Section titled “When not to use it”If your workers are built in one module and every listener is attached in another (a shared
instrumentWorker(worker) helper is fine, since passing the worker counts), the rule cannot see
across files and reports the worker. Export it through a function that attaches the listener, or
turn the rule off for that module. If failures are observed some other way, such as a
QueueEvents listener in a separate process, the rule reports workers you consider covered; turn
it off in that case.