Message Handlers

📦 Message Handlers

Message handlers define how your application reacts to specific messages dispatched on a bus. They encapsulate business logic triggered by inter-service or internal communication.

This page explains how to define, register, and work with message handlers using @nestjstools/messaging.

---

🛠️ Defining a Message Handler

A message handler is a class that implements the IMessageHandler<T> interface for a specific message type.

Example:

import { Injectable } from '@nestjs/common';
import { MessageHandler, IMessageHandler, MessageResponse } from '@nestjstools/messaging';
import { SendMessage } from './send-message';

@Injectable()
@MessageHandler('your.message')
export class SendMessageHandler implements IMessageHandler<SendMessage> {
  async handle(message: SendMessage): Promise<MessageResponse | void> {
    console.log(message.content);
    // Your business logic here
  }
}

---

🔁 MessageHandler routing keys and priority

@MessageHandler supports two ways of defining routing keys.

🔹 Direct routing keys

Use the decorator arguments when you only need to define routing keys.

Single routing key

@MessageHandler('your.message')

Multiple routing keys

@MessageHandler('your.message', 'alternate.route')

⚙️ Configuration form

Use the configuration object when you also want to define handler priority.

Single routing key

@MessageHandler({
  routingKey: 'your.message',
  priority: 10,
})

Multiple routing keys

@MessageHandler({
  routingKey: ['your.message', 'alternate.route'],
  priority: 10,
})

🚦 Handler priority

routingKey accepts either:

string | string[]

priority is optional and defaults to:

priority: 0

When multiple handlers listen to the same routing key:

• ⬆️ Higher-priority handlers run first

• ⬇️ Lower-priority handlers run after higher-priority handlers complete

• ⚡ Handlers with the same priority run in parallel

For example:

@MessageHandler({
  routingKey: 'order.created',
  priority: 20,
})
handleCriticalOrderLogic() {}

@MessageHandler({
  routingKey: 'order.created',
  priority: 10,
})
handleSecondaryLogic() {}

@MessageHandler({
  routingKey: 'order.created',
  priority: 10,
})
handleAnalytics() {}

Execution order:

priority 20
    ↓
priority 10 ──┬── handleSecondaryLogic()
              └── handleAnalytics()
                  (executed in parallel)

---

🧠 Typed Message Input with @DenormalizeMessage()

By default, the handler receives the raw message data (usually as a plain JavaScript object). If you want to receive it as a properly instantiated class, use the @DenormalizeMessage() decorator:

async handle(@DenormalizeMessage() message: SendMessage): Promise<void> {
  // Now message is an instance of SendMessage with all class logic available
}

This is especially helpful when your message class contains methods, getters, or requires validation logic.

---

🧩 Registering Handlers

Handlers are automatically discovered by NestJS as long as they are included in the providers of a module:

@Module({
  providers: [SendMessageHandler],
})
export class MessagingFeatureModule {}

If you use a feature module, ensure that the module is imported by the root module and that MessagingModule is globally available or also imported.

---

📤 Triggering Handlers

Handlers respond to messages dispatched through a message bus with a matching route:

await messageBus.dispatch(
  new RoutingMessage(new SendMessage('Hello!'), 'your.message'),
);

If a handler is decorated with @MessageHandler('your.message'), it will receive this message.

---

Returning a Response

Handlers can return a MessageResponse if needed:

import { MessageResponse } from '@nestjstools/messaging';

return new MessageResponse({ result: 'OK' });

You can optionally implement response-handling logic in the calling component.

---

Summary

Concept	Description
@MessageHandler()	Binds a handler to one or more routes
IMessageHandler<T>	Interface for handling a specific message type
@DenormalizeMessage()	Automatically deserializes message into class instance
MessageResponse	Optional way to return structured results from handlers, you can also return object

---

Note that handlers are visible across channels