npm package: @nhtio/adonis-mqtt-event-bus
Description: A cross-process event bus for AdonisJS based on MQTT
Author: Jak Giveon
Latest version: 1.20250319.0

# Adonis MQTT Event Bus

A cross-process event bus for AdonisJS based on MQTT

## Features

* Provides centralized, event-driven architecture across containerized applications.
* Clean integration with AdonisJS IoC, leveraging dependency injection.
* Efficient, lightweight inter-container/event-driven communication.

## Getting Started

### Installation

Install the package using your preferred package manager:

```bash
npm install @nhtio/adonis-mqtt-event-bus
```

Run the Adonis configuration command to set up the package:

```bash
node ace configure @nhtio/adonis-mqtt-event-bus
```

### Configuration

The configuration file for the MQTT Event Bus will be located at `config/meb.ts`. You can customize the following options:

```typescript
export default {
  host: 'mqtt://127.0.0.1:1883', // The MQTT broker URL
  baseTopic: 'adonis',           // The base topic for all events
  // you can add more options here
};
```

Make sure your MQTT broker is running and accessible at the specified `host`.

## Accessing the Event Bus

You can access the event bus through one of the following methods:

### 1. As an Importable Service

```typescript
import meb from '@nhtio/adonis-mqtt-event-bus/services/main';

// Example usage
meb.emit('my:event', { key: 'value' });
meb.on('my:event', (payload) => {
  console.log(payload);
});
```

### 2. As an Attribute of the Application

```typescript
import { default as app } from "@adonisjs/core/services/app";

// Access the event bus
app.meb.emit('my:event', { key: 'value' });
```

### 3. Using Container Services

```typescript
import { default as app } from "@adonisjs/core/services/app";

// Resolve the event bus from the IoC container
const meb = await app.container.make('meb');
meb.emit('my:event', { key: 'value' });
```

## Adding Typescript Definitions for Events

You can add support for more events by augmenting the `EventCallbackSignatures` interface:

```typescript
declare module "@nhtio/adonis-mqtt-event-bus" {
  interface EventCallbackSignatures {
    // your additional definitions here
  }
}
```

## Instance Methods

| Method                                             | Description                                                                            | Documentation                                                                                    |
| -------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `addListener(eventName, listener)`                 | Adds the listener function to the end of the listeners array for the event.            | [Documentation](https://nodejs.org/api/events.html#emitteraddlistenereventname-listener)         |
| `emit(eventName[, ...args])`                       | Syncronously emits the event to the MQTT broker                                        | [Documentation](https://nodejs.org/api/events.html#emitteremiteventname-args)                    |
| `eventNames()`                                     | Returns an array listing the events for which the emitter has registered listeners.    | [Documentation](https://nodejs.org/api/events.html#emittereventnames)                            |
| `getMaxListeners()`                                | Returns the current max listener value for the EventEmitter                            | [Documentation](https://nodejs.org/api/events.html#emittergetmaxlisteners)                       |
| `listenerCount(eventName[, listener])`             | Returns the number of listeners listening for the event.                               | [Documentation](https://nodejs.org/api/events.html#emitterlistenercounteventname-listener)       |
| `listeners(eventName)`                             | Returns a copy of the array of listeners for the event.                                | [Documentation](https://nodejs.org/api/events.html#emitterlistenerseventname)                    |
| `off(eventName, listener)`                         | Removes the specified listener from the listener array for the event                   | [Documentation](https://nodejs.org/api/events.html#emitteroffeventname-listener)                 |
| `on(eventName, listener)`                          | Adds the listener function to the end of the listeners array for the event.            | [Documentation](https://nodejs.org/api/events.html#emitteroneventname-listener)                  |
| `once(eventName, listener)`                        | Adds a one-time listener function for the event.                                       | [Documentation](https://nodejs.org/api/events.html#emitteronceeventname-listener)                |
| `prependListener(eventName, listener)`             | Adds the listener function to the beginning of the listeners array for the event.      | [Documentation](https://nodejs.org/api/events.html#emitterprependlistenereventname-listener)     |
| `prependOnceListener(eventName, listener)`         | Adds a one-time listener function for the event                                        | [Documentation](https://nodejs.org/api/events.html#emitterprependoncelistenereventname-listener) |
| `removeAllListeners([eventName])`                  | Removes all listeners, or those of the specified eventName.                            | [Documentation](https://nodejs.org/api/events.html#emitterremovealllistenerseventname)           |
| `removeListener(eventName, listener)`              | Removes the specified listener from the listener array for the event                   | [Documentation](https://nodejs.org/api/events.html#emitterremovelistenereventname-listener)      |
| `setMaxListeners(n)`                               | Set the maximum number of listeners for a specific event before a warning is triggered | [Documentation](https://nodejs.org/api/events.html#emittersetmaxlistenersn)                      |
| `rawListeners(eventName)`                          | Returns a copy of the array of listeners for the event, including any wrappers         | [Documentation](https://nodejs.org/api/events.html#emitterrawlistenerseventname)                 |
| `boot`                                             | Runs tasks for when the Adonis bindings have booted                                    |                                                                                                  |
| `start`                                            | Run tasks for when the Adonis application has started                                  |                                                                                                  |
| `ready`                                            | Run tasks for when the Adonis application is in a ready state                          |                                                                                                  |
| `shutdown`                                         | Run tasks for when the Adonis application is shutting down                             |                                                                                                  |
| `clearDeadLetterQueue`                             | Clears the dead-letter queue                                                           |                                                                                                  |
| `publish(eventName, options, [, ...args])`         | Asyncronously emits the event to the MQTT Broker. Uses options from `mqttjs#publish`   | [mqttjs#publish](https://github.com/mqttjs/MQTT.js/tree/main#publish)                            |
| `addWildcardListener(eventName, listener)`         | Adds the listener function to the end of the listeners array for the event.            | [Documentation](https://nodejs.org/api/events.html#emitteraddlistenereventname-listener)         |
| `offWildcard(eventName, listener)`                 | Removes the specified listener from the listener array for the event                   | [Documentation](https://nodejs.org/api/events.html#emitteroffeventname-listener)                 |
| `onWildcard(eventName, listener)`                  | Adds the listener function to the end of the listeners array for the event.            | [Documentation](https://nodejs.org/api/events.html#emitteroneventname-listener)                  |
| `onceWildcard(eventName, listener)`                | Adds a one-time listener function for the event.                                       | [Documentation](https://nodejs.org/api/events.html#emitteronceeventname-listener)                |
| `prependWildcardListener(eventName, listener)`     | Adds the listener function to the beginning of the listeners array for the event.      | [Documentation](https://nodejs.org/api/events.html#emitterprependlistenereventname-listener)     |
| `prependOnceWildcardListener(eventName, listener)` | Adds a one-time listener function for the event                                        | [Documentation](https://nodejs.org/api/events.html#emitterprependoncelistenereventname-listener) |
| `removeAllWildcardListeners([eventName])`          | Removes all listeners, or those of the specified eventName.                            | [Documentation](https://nodejs.org/api/events.html#emitterremovealllistenerseventname)           |
| `removeWildcardListener(eventName, listener)`      | Removes the specified listener from the listener array for the event                   | [Documentation](https://nodejs.org/api/events.html#emitterremovelistenereventname-listener)      |

## Instance Properties

| Property          | Description                                                                          |
| ----------------- | ------------------------------------------------------------------------------------ |
| `connected`       | Boolean for if connected to the MQTT Broker                                          |
| `state`           | An object which indicates the Adonis Application Lifecycle progress                  |
| `deadLetterQueue` | A list of events for which there has not been a listener active since the last check |

---

Adonis MQTT Event Bus is a commercial work product released under the MIT License and is provided as-is with no warranty or guarantee of support.

Copyright © 2025-present New Horizon Technology LTD