Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 42 ยท Beyond HTTP

Queues and Events

Decouple work in NestJS with the EventEmitter module and BullMQ queues: producers, workers, retries with backoff, idempotency, plus a runnable event bus and job queue.

Some work does not belong inside a request. Sending a welcome email, resizing an image, generating a report or calling a slow partner API can take seconds, fail halfway, or need to be retried. If you do it inline, the user waits, a failure becomes a failed request, and a traffic spike becomes a pile of slow requests. The usual answer is to separate announcing the work from doing the work.

Nest gives you two tools for this, at two scales. The EventEmitter module lets parts of one application react to things that happened, without calling each other directly. A queue (most often BullMQ on top of Redis) stores jobs durably so that worker processes can handle them later, with retries, delays and concurrency limits, even across restarts and many machines.

The real packages need Node, npm and Redis, so the Nest snippets are read-only. The runnable stand-ins are an in-process event bus and a job queue with retries, so you can watch the mechanics.

Events vs queues

Events In-process, instant, not stored.
Queues Stored in Redis, processed by workers.

Use events to decouple code, queues to survive failure.

1 / 2

In-process events

Install @nestjs/event-emitter, import EventEmitterModule.forRoot() once, and you can emit and listen anywhere:

TypeScript
@Injectable()
export class UsersService {
  constructor(private readonly events: EventEmitter2) {}

  async register(dto: RegisterDto) {
    const user = await this.repo.save(dto);
    this.events.emit('user.registered', new UserRegisteredEvent(user.id, user.email));
    return user;
  }
}

@Injectable()
export class WelcomeEmailListener {
  @OnEvent('user.registered')
  async handle(event: UserRegisteredEvent) {
    await this.mailer.sendWelcome(event.email);
  }
}

UsersService no longer knows that a welcome email exists. Adding an analytics listener or an audit-log listener later means adding a class, not editing register. That is the whole benefit: the code that does the thing is separate from the code that reacts to it.

Know the limits:

  • Events are synchronous dispatch within one process. emit calls the listeners right away, and an async listener's returned promise is not awaited by emit (use emitAsync if you need to wait).
  • Nothing is stored. If the process crashes after emit, the reaction is lost.
  • An exception in a listener must be handled inside it. An unhandled rejection in an async listener can bring down a process or vanish silently depending on settings.
  • Events do not cross processes. For that you need a broker (see Microservices and Transports) or a queue.

Keep event names consistent (user.registered, order.paid), pass a small typed event class rather than loose arguments, and keep payloads to facts (ids, a few fields), not whole entities that will be stale by the time a listener reads them.

Stand-in: an event bus

This is a tiny bus with on, emit and emitAsync. Listeners run in the order they were registered, and a failing listener does not stop the others.

Node.js An in-process event bus

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The broken analytics listener did not stop the audit log. An event with no listeners is simply ignored. And the asynchronous failure arrives after emit has already returned: the sender never learns of it, which is exactly why important work belongs in a queue.

Queues with BullMQ

A queue turns "do this later" into data. The producer adds a job (a name and a JSON payload) to a Redis-backed queue and returns immediately. A worker, possibly in another process, takes jobs out and runs them. Because the job lives in Redis, it survives a crash of the producer, and if a worker dies mid-job the job can be retried.

Install @nestjs/bullmq and bullmq, point the root module at Redis and register a queue:

TypeScript
@Module({
  imports: [
    BullModule.forRoot({ connection: { host: 'localhost', port: 6379 } }),
    BullModule.registerQueue({ name: 'emails' }),
  ],
  providers: [EmailsProducer, EmailsProcessor],
})
export class EmailsModule {}

The producer injects the queue:

TypeScript
@Injectable()
export class EmailsProducer {
  constructor(@InjectQueue('emails') private readonly queue: Queue) {}

  async sendWelcome(userId: number, email: string) {
    await this.queue.add(
      'welcome',
      { userId, email },
      {
        attempts: 5,
        backoff: { type: 'exponential', delay: 1000 },
        removeOnComplete: true,
        jobId: `welcome-${userId}`,
      },
    );
  }
}

The processor is a worker class bound to the queue name:

TypeScript
@Processor('emails')
export class EmailsProcessor extends WorkerHost {
  async process(job: Job<{ userId: number; email: string }>) {
    await this.mailer.sendWelcome(job.data.email);
    return { sent: true };
  }
}

Throwing from process marks the attempt as failed. BullMQ then retries according to attempts and backoff, and after the last attempt the job moves to the failed set, where you can inspect it and re-run it. Options worth knowing: delay (run later), priority, repeat (recurring jobs, an alternative to cron in Caching, Throttling and Scheduling), and worker concurrency (how many jobs run at once in one worker). You can also run workers as a separate Nest application so that heavy jobs never compete with HTTP traffic for CPU.

Producer-side details of the real library, such as exact option names and defaults, can change between versions, so check the version you install.

Retries, backoff and why idempotency matters

An exponential backoff waits longer after each failure (1 s, 2 s, 4 s, ...) so a struggling dependency is not hammered. Retries sound harmless until you ask what a retry repeats. Suppose a job charges a card, then crashes while writing the receipt. The retry will charge again unless the work is idempotent: running it twice has the same effect as running it once.

Most queues give you at-least-once delivery: a job will run at least once, possibly more. Plan for duplicates:

  • Give each logical job a stable identifier (jobId, an order id) so a duplicate add is ignored.
  • Record completed work with a unique key (for example a database constraint on (order_id, payment_attempt)) and skip it if it already exists.
  • Pass your payment or email provider an idempotency key if it supports one.
  • Make each step small, and persist progress, so a retry resumes rather than restarts.

Stand-in: a job queue with workers, retries and dedup

This queue keeps jobs in memory, processes them with a concurrency limit, retries with exponential backoff and moves exhausted jobs to a failed list. To keep the output deterministic, there are no real delays: the queue computes the backoff it would wait and records it in the log. The jobId option rejects duplicates, as BullMQ does for a job id that already exists.

Node.js A job queue with retries and backoff

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Read the log from top to bottom. The duplicate welcome-1 is dropped at add. The flaky job fails twice, with waits of 500 ms and 1000 ms, and succeeds on the third attempt. The broken job uses all three attempts (waits of 100 ms and 200 ms) and lands in the failed state, where a human or an alert would pick it up. In the real library a retry waits for its backoff before running again; this stand-in re-queues immediately and only reports the wait, so the output is stable.

Events or queues?

Question Events (EventEmitter) Queue (BullMQ)
Must survive a crash? No Yes
Can run on another machine? No Yes
Needs retries or delays? No Yes
Latency Immediate, in-process Small, via Redis
Operational cost None Redis and workers to run

A good pattern combines them: a listener reacts to user.registered by adding a job to the email queue. The event decouples the code, and the queue makes the work reliable.

Practical advice

  • Keep job payloads small: ids and parameters, not whole objects. The worker should load fresh data.
  • Always set attempts and backoff deliberately, and decide what happens to jobs that fail for good (alert, dashboard, manual replay).
  • Listen for failed jobs and log them; a silent failed set is a hidden outage.
  • Keep processors thin: call a normal service, so the logic is testable without Redis (see Testing Nest Applications).
  • Shut workers down gracefully so they finish their current job (see Deployment and Performance).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main advantage of in-process events with @nestjs/event-emitter?

    Events decouple producers from listeners inside one process. They are not stored, not distributed and not retried.
  2. 2. A job charges a customer and may be retried after a crash. What protects the customer from being charged twice?

    Queues deliver at least once, so duplicates are possible. Idempotent processing makes a repeat harmless.
  3. 3. What happens to a BullMQ job whose processor keeps throwing after the last allowed attempt?

    After the final attempt the job is marked failed and kept (unless configured otherwise), so you can inspect and retry it.
  4. 4. Why use exponential backoff for retries?

    Growing delays spread retries out and give the failing service time to recover. They do not guarantee success.

Summary

  • Separate announcing work from doing it: events for decoupling inside one process, queues for reliable background work.
  • @nestjs/event-emitter offers emit and @OnEvent; events are immediate, in-process and not stored, so handle errors inside listeners.
  • BullMQ queues keep jobs in Redis: a producer calls queue.add, a @Processor worker runs process, and failures are retried with attempts and backoff.
  • Delivery is at least once, so design jobs to be idempotent and use stable job ids.
  • Watch the failed set and keep processors thin and testable.

Continue with WebSockets and Gateways for real-time, two-way communication.