NestJS Event Bus Transport Module

Description

This module provides an infrastructure to implement an event bus system in applications built with NestJS, using RabbitMQ or Kafka as messaging systems. The library allows managing domain events and provides the ability to publish and consume messages easily.

Features

• Support for multiple transports: RabbitMQ and Kafka.
• Domain events: Ability to define custom domain events.
• Event handling and publishing: Predefined services to manage the flow of events.

Installation

To install the library, you can use npm or yarn:

npm install @adual/nestjs-event-bus-transport

yarn add @adual/nestjs-event-bus-transport

Usage

Importing the Module into Your Project

The EventBusTransportModule can be configured using two main methods: forRoot for global configuration, and forFeature to register specific events.

Basic Configuration

import { EventBusTransportModule, Transport } from '@adual/nestjs-event-bus-transport';

@Module({
  imports: [
    EventBusTransportModule.forRoot({
      transport: Transport.RABBITMQ,
      options: {
        uri: 'amqp://guest:guest@localhost:5672',
        exchangeName: 'domain-events',
      },
    }),
  ],
})
export class AppModule {}

Registering Events

You can register specific events using the forFeature method:

import { EventBusTransportModule } from '@adual/nestjs-event-bus-transport';
import { UserCreatedEvent } from './events/user-created.event';

@Module({
  imports: [
    EventBusTransportModule.forFeature({
      events: [UserCreatedEvent],
    }),
  ],
})
export class UserModule {}

Creating a Domain Event

To create an event, you need to extend the IDomainEvent class provided by the library:

import { IDomainEvent } from '@adual/nestjs-event-bus-transport/core/models/domain-event';

export class UserCreatedEvent extends IDomainEvent {
  static EVENT_NAME: string = 'user.created';
  readonly id: string;
  readonly email: string;
  readonly password: string;

  constructor(
    email: string,
    password: string,
    aggregateId: string,
    eventId?: string,
    occurredOn?: Date,
  ) {
    super({
      aggregateId,
      eventName: UserCreatedEvent.EVENT_NAME,
      eventId,
      occurredOn,
    });
    this.id = aggregateId;
    this.email = email;
    this.password = password;
  }

  toPrimitives() {
    return {
      attributes: {
        email: this.email,
        password: this.password,
      },
      aggregateId: this.id,
      eventName: UserCreatedEvent.EVENT_NAME,
      eventId: this.eventId,
      occurredOn: this.occurredOn,
    };
  }
}

Event Handling

To handle an event, you can create a handler using the @EventHandler decorator provided by the library:

import { EventHandler } from '@adual/nestjs-event-bus-transport/decorator/event-handler.decorator';
import { Logger, OnModuleInit } from '@nestjs/common';
import { UserCreatedEvent } from './events/user-created.event';
import { IEventHandler } from '@adual/nestjs-event-bus-transport/core/models/event-handler';

@EventHandler(UserCreatedEvent)
export class ShowMessageOnSubscribe
  implements OnModuleInit, IEventHandler<UserCreatedEvent>
{
  onModuleInit() {
    Logger.log('Handler initialized', 'Handler');
  }

  handle(event: UserCreatedEvent): void {
    Logger.log(
      `type of event: ${JSON.stringify(event.toPrimitives())}`,
      'Handler',
    );
  }
}

Supported Transports

The module currently supports the following transports:

• RabbitMQ: Use the enum Transport.RABBITMQ to specify RabbitMQ as the transport.
• Kafka: Use the enum Transport.KAFKA to specify Kafka as the transport.

Configuration Options

RabbitMQ

export interface RabbitMQOptions {
  uri: string; // RabbitMQ connection URL
  exchangeName: string; // Name of the exchange
  durable?: boolean; // Whether the exchange is durable (optional)
  exchangeType?: 'direct' | 'fanout' | 'topic' | 'headers'; // Type of exchange (optional)
}

Kafka

export interface KafkaOptions {
  brokers: string[]; // List of Kafka brokers
  clientId: string; // Client ID
}

Complete Example

import { Module } from '@nestjs/common';
import { EventBusTransportModule, Transport } from '@adual/nestjs-event-bus-transport';
import { UserCreatedEvent } from './events/user-created.event';
import { ShowMessageOnSubscribe } from './handlers/show-message.handler';

@Module({
  imports: [
    EventBusTransportModule.forRoot({
      transport: Transport.RABBITMQ,
      options: {
        uri: 'amqp://guest:guest@localhost:5672',
        exchangeName: 'domain-events',
      },
    }),
    EventBusTransportModule.forFeature({
      events: [UserCreatedEvent],
    }),
  ],
  providers: [ShowMessageOnSubscribe],
})
export class AppModule {}

License

This project is licensed under the ISC License. See the LICENSE file for more details.