Event patterns (event-based) in NestJS - Step-by-Step Execution

Concept Flow - Event patterns (event-based)

Event Emitted

↓

Event Bus Receives

↓

Event Pattern Matches?

No→Ignore Event

Yes↓

Invoke Event Handler

↓

Handler Processes Event

↓

Optional: Emit New Event

↩Back to Event Bus

This flow shows how an event is emitted, matched by pattern, handled, and optionally triggers new events.

Execution Sample

NestJS

import { EventsHandler, IEventHandler } from '@nestjs/cqrs';

export class UserCreatedEvent {
  constructor(public readonly userId: string) {}
}

@EventsHandler(UserCreatedEvent)
export class UserCreatedHandler implements IEventHandler<UserCreatedEvent> {
  handle(event: UserCreatedEvent) {
    console.log(`User created: ${event.userId}`);
  }
}

This code defines an event and a handler that listens for that event and logs the user ID.

Execution Table

Step	Action	Event Bus State	Event Pattern Match	Handler Called	Output
1	UserCreatedEvent emitted with userId='abc123'	Event queue: [UserCreatedEvent]	Matches UserCreatedEvent pattern	UserCreatedHandler.handle called	Logs: 'User created: abc123'
2	Handler finishes processing	Event queue: []	N/A	N/A	No further output
3	No more events	Event queue: []	N/A	N/A	Execution stops

💡 No more events in the queue, event processing ends

Variable Tracker

Variable	Start	After Step 1	After Step 2	Final
eventQueue	[]	[UserCreatedEvent]	[]	[]
currentEvent	null	UserCreatedEvent(userId='abc123')	null	null

Key Moments - 2 Insights

Why does the handler only run when the event pattern matches?

Because the event bus checks each event against registered patterns and only calls handlers for matching events, as shown in execution_table step 1.

What happens if no handler matches an event?

The event is ignored and removed from the queue without calling any handler, as implied by the 'No more events' step in execution_table.

Visual Quiz - 3 Questions

Look at the execution table, what is the eventQueue after step 1?

A [UserCreatedEvent]

B []

C [UserCreatedEvent, AnotherEvent]

D null

💡 Hint

Check the 'Event Bus State' column at step 1 in the execution_table

At which step does the handler log the user ID?

A Step 3

B Step 1

C Step 2

D No logging occurs

💡 Hint

Look at the 'Output' column for when 'Logs: User created: abc123' appears

If a new event with no matching handler is emitted, what happens to the eventQueue?

A It stays the same

B It grows indefinitely

C The event is removed without handler call

D The system crashes

💡 Hint

Refer to key_moments about unmatched events and execution_table step 3

Concept Snapshot

Event patterns in NestJS use an event bus to listen for specific event classes.
Handlers are registered with @EventsHandler for those event classes.
When an event is emitted, the bus matches it to handlers by pattern.
Matching handlers run their handle() method with the event data.
Unmatched events are ignored.
Handlers can emit new events, continuing the cycle.

Full Transcript

In NestJS event patterns, an event is created as a class and emitted to the event bus. The bus holds events in a queue. It checks each event against registered patterns, which are event classes linked to handlers. If the event matches a pattern, the corresponding handler's handle() method runs, processing the event data. For example, a UserCreatedEvent with a userId is emitted, matched, and handled by UserCreatedHandler, which logs the userId. After handling, the event is removed from the queue. If no handler matches, the event is simply discarded. This cycle allows decoupled communication where events trigger actions without direct calls. Handlers can also emit new events, continuing the event flow.

Practice

1. What is the main purpose of using @EventPattern in a NestJS application?

easy

A. To create database entities

B. To define HTTP routes for REST APIs

C. To listen for specific events and handle their data

D. To style components with CSS

Solution

1. Step 1: Understand the role of @EventPattern

   This decorator is used to mark a method that listens for a specific event in an event-based system.

2. Step 2: Compare with other options

   Options B, C, and D relate to other parts of NestJS or frontend development, not event listening.

3. Final Answer:

   To listen for specific events and handle their data -> Option C

4. Quick Check:

   @EventPattern listens to events [OK]

Hint: Remember: @EventPattern listens to events, not routes or styles [OK]

Common Mistakes:

• Confusing @EventPattern with @Controller for routes
• Thinking @EventPattern creates database models
• Mixing event listening with styling tasks

2. Which of the following is the correct way to receive event data inside an event handler method in NestJS?

easy

A. Use @Payload() decorator on a method parameter

B. Use @Body() decorator on a method parameter

C. Use @Query() decorator on a method parameter

D. Use @Param() decorator on a method parameter

Solution

1. Step 1: Identify the decorator for event data

   In NestJS event handlers, @Payload() extracts the data sent with the event.

2. Step 2: Differentiate from HTTP decorators

   @Body(), @Query(), and @Param() are used in HTTP controllers, not event handlers.

3. Final Answer:

   Use @Payload() decorator on a method parameter -> Option A

4. Quick Check:

   @Payload() gets event data [OK]

Hint: Event data comes from @Payload(), not HTTP decorators [OK]

Common Mistakes:

• Using @Body() in event handlers instead of @Payload()
• Confusing HTTP request decorators with event decorators
• Omitting the decorator and expecting automatic data injection

3. Given the following NestJS event handler code, what will be logged when an event named 'order_created' with payload { id: 42 } is emitted?

@EventPattern('order_created')
handleOrder(@Payload() data: any) {
  console.log(`Order ID: ${data.id}`);
}

medium

A. No output because event name is wrong

B. Order ID: undefined

C. SyntaxError due to missing return

D. Order ID: 42

Solution

1. Step 1: Understand event matching

   The handler listens for 'order_created' events, so it will trigger when such an event is emitted.

2. Step 2: Check payload usage

   The payload has an object with id: 42, so data.id is 42 and will be logged.

3. Final Answer:

   Order ID: 42 -> Option D

4. Quick Check:

   Payload id 42 logs correctly [OK]

Hint: Match event name exactly and use @Payload() to access data [OK]

Common Mistakes:

• Assuming event name is case-insensitive
• Forgetting to use @Payload() and getting undefined
• Expecting a return value to log output

4. Identify the error in this NestJS event handler code:

@EventPattern('user_registered')
handleUser(@Payload data: any) {
  console.log(data.username);
}

medium

A. Missing parentheses in @Payload decorator

B. Incorrect event name format

C. Method name must be 'onUserRegistered'

D. Payload parameter must be last in method

Solution

1. Step 1: Check decorator syntax

   The @Payload decorator requires parentheses even if no arguments are passed, so it should be @Payload().

2. Step 2: Verify other parts

   Event name format is correct, method name can be anything, and parameter order is flexible.

3. Final Answer:

   Missing parentheses in @Payload decorator -> Option A

4. Quick Check:

   @Payload() needs parentheses [OK]

Hint: Always write @Payload() with parentheses, even if empty [OK]

Common Mistakes:

• Omitting parentheses in decorators
• Thinking method names must follow event names
• Assuming parameter order matters for decorators

5. You want to create a NestJS service that listens to two different events: 'payment_success' and 'payment_failed'. Which of the following is the best way to implement this using event patterns?

hard

A. Use @Controller with two routes named after events

B. Create two methods, each decorated with @EventPattern for each event name

C. Create one method with @EventPattern('payment') and check event type inside

D. Use @Payload() decorator twice in one method for both events

Solution

1. Step 1: Understand event pattern usage

   Each event should have its own handler method decorated with @EventPattern specifying the event name.

2. Step 2: Evaluate other options

   Create one method with @EventPattern('payment') and check event type inside is less clear and not idiomatic; Use @Controller with two routes named after events is for HTTP routes, not events; Use @Payload() decorator twice in one method for both events is invalid syntax.

3. Final Answer:

   Create two methods, each decorated with @EventPattern for each event name -> Option B

4. Quick Check:

   Separate methods for separate events [OK]

Hint: Use one @EventPattern per event with separate methods [OK]

Common Mistakes:

• Trying to handle multiple events in one method without checking
• Confusing event handlers with HTTP controllers
• Using multiple @Payload decorators in one method