Nest Events @Emitter

Welcome to the Nest Events library! This library provides event handling and emitting capabilities for your NestJS applications. With Nest Events, you can easily manage and trigger events within your application, making it simpler to implement various communication patterns and workflows.

It's the same as @nestjs/event-emitter but allowing you to implement your own emitter, like AWS SNS, RabbitMQ, etc. A default emitter is already provided by default using EventEmitter2.

Installation

To get started with Nest Events, you need to install the library using npm or yarn. Open your terminal and run the following command:

npm install nest-events

or

yarn add nest-events

Usage

Importing the Module

To start using the Nest Events library, you need to import the EventBusModule into your NestJS application. In your module file (e.g., app.module.ts), import the module like this:

import { Module } from '@nestjs/common';
import { EventBusModule } from 'nest-events';

@Module({
  imports: [EventBusModule.forRoot()],
})
export class AppModule {}

Emitting Events

You can emit events using the EventBus service provided by the library. Here's how you can emit an event:

import { Injectable } from '@nestjs/common';
import { EventBus } from 'nest-events';

@Injectable()
export class MyService {
  constructor(private readonly eventBus: EventBus) {
  }

  async doSomething() {
    // ... your logic

    // Emit an event
    await this.eventBus.emitAsync('myEvent', eventData);
  }
}

Handling Events

To handle events, you can use decorators provided by the library. Here's an example of how to use the @On decorator to handle an event:

import { Injectable } from '@nestjs/common';
import { On } from 'nest-events';

@Injectable()
export class MyEventHandler {
  @On('myEvent')
  handleMyEvent(eventData: any) {
    // Handle the event
    console.log('Event received:', eventData);
  }
}

Custom Emitters

Nest Events allows you to work with multiple emitters for different scenarios. You can define custom emitters and use them accordingly.

import { DefaultEventEmitter, Emitter, EventBus, On } from 'nest-events';

@Emitter('cloud')
export class CloudEmitter extends DefaultEventEmitter {
  private sns: SNS;

  constructor() {
    super();
    this.sns = new SNS();
  }

  async emitAsync(event: string, message: any): Promise<boolean> {
    try {
      const params = {
        Message: JSON.stringify(message),
        TopicArn: 'arn:aws:sns:us-east-1:123456789012:MyTopic'
      };
      await this.sns.publish(params).promise();
      return true;
    } catch (error) {
      console.error('Error emitting event:', error);
      return false;
    }
  }
}

@Injectable()
export class MyService {
  constructor(private readonly eventBus: EventBus) {
  }

  async doSomething() {
    // ... your logic

    // Emit an event using the custom emitter
    await this.eventBus.emitter('cloud').emitAsync('myEvent', eventData);
  }
}

@Injectable()
export class MyListener {
  @On('myEvent')
  handleCustomEvent(eventData: any) {
    // Handle the event from the custom emitter
    console.log('Custom event received:', eventData);
  }
}

Configuration

The EventBusModule.forRoot() method accepts an optional configuration object. See EventEmitter2 for more configuration options details. Here's an example of how to use it:

import { Module } from '@nestjs/common';
import { EventBusModule } from 'nest-events';

@Module({
  imports: [
    EventBusModule.forRoot({
      global: true // Set to "true" (default) to register as a global module
      /* Additional configuration options from eventemitter2 can be added here */
    })
  ]
})
export class AppModule {}

Contributing

We welcome contributions to the Nest Events library! If you find a bug, have a feature request, or want to improve the documentation, please open an issue or submit a pull request.

License

This library is released under the MIT License.

Happy event handling with Nest Events! 🎉