Buses
Event buses are objects that store and notify their EventSubscribers when an event is called either internally, typically via an EventEmitter, or externally, via EventBus#emit().
Main features
An event bus can be un/subscribed to:
await .();
await .();Can be used to emit an event type-safely:
type = {
: [string, number];
};
declare const : <>;
await .('someEvent', ['hello', 123]);
// Error! Argument missmatch
await .('someEvent', [true, 123]);It can be iterated and its subscribers can be obtained:
const subscribers = .();
for (const [, subscriber] of ) {}And other features you might find useful. Check the EventBus docs for more details.
Subscriber concurrency
An event bus has complete freedom over how to execute its subscribers, however the framework has normalized two patterns for ease of use (though it's not hardcoded):
Async buses
It calls its subscribers asynchronously, meaning that it doesn't wait for the current subscriber to finish before executing the next.
| Advantages | Disadvantages |
|---|---|
| Can be faster, especially for events with many subscribers, since it executes them in bulk. | Multiple subscribers running may hog the event loop and decrease performance. |
| Less prone to blocking or delaying the system, since it can move on to the next subscriber while the previous one is still executing. | May lead to calling subscribers in an order different than their priority. For example, subscribers with PriorityEnum.Normal may execute before subscribers with PriorityEnum.High have finished. |
| Since subscribers are executed in bulk, it can be harder to trace when an error occurs. |
Concurrency Limit
To tackle the mentioned disadvantages, it has a concurrency limit functionality. This allows you to set how many subscribers are being checked or executed at the same time.
import { AsyncEventDispatcher } from '@nyx-discord/djs';
const = .() as AsyncEventDispatcher;
.(5);- Setting this limit to
1effectively turns the dispatcher into a sync one. - The default concurrency limit is
3.
Sync buses
It calls its subscribers synchronously, meaning that it waits for the current subscriber to finish before executing the next.
| Advantages | Disadvantages |
|---|---|
Ensures that subscribers are only executed in the order of their Priority. | May be slower for events with many subscribers, as it has to wait for each subscriber (and its middleware) to finish before moving on to the next one. |
| Easier to debug and to trace when and on which state an error occurs. | If one subscriber takes a long time to execute, it can cause a delay for others. |
Sync Timeout
To tackle the mentioned disadvantages, it has a sync timeout functionality. This allows you to set "timeframe" for any subscriber to finish, before the dispatcher stops waiting and calls the next subscriber.
import { SyncEventDispatcher } from '@nyx-discord/djs';
const = .() as SyncEventDispatcher;
.(50_000);Known buses
Client bus
The Client event bus is a built-in bus that wraps its events:
const bus = .();The bot also has a utility method to directly subscribe to it:
await .();Manager buses
Each manager holds a bus that wraps events related to the feature they manage:
const commandBus = .().();
const scheduleBus = .().();
const pluginBus = .().();See the respective guide of each feature for more information about the events they emit.
Custom buses
You can create your own event bus for your building an event-based bot.
Arguments type
You'll first need an arguments type for your events, for example:
type = {
: [string, number];
: [boolean];
};This type's keys are the event names, and their values are the arguments of that event.
Creation
Manual emits
If you want a bus whose emit() method is manually called, either:
- Use
BasicEventBus.createSync()to create a sync bus. - Use
BasicEventBus.createAsync()to create an async bus.
import { } from '@nyx-discord/djs';
const = .<>();
const = .<>();From an EventEmitter
You can also create a bus that will wrap an existent EventEmitter, or a class that extends it:
- Use
BasicEventBus.createSync()to create a sync bus. - Use
BasicEventBus.createAsync()to create an async bus.
import { EventEmitter } from 'node:events';
import { } from '@nyx-discord/djs';
const = new EventEmitter();
const = .<, EventEmitter>();
const = .<, EventEmitter>();Bus events
Apart from the events specified in the type, the bus also emits extra events related to the bus itself:
import { } from '@nyx-discord/djs';
.- EventSubscriberAdd
- EventSubscriberRemove
You can subscribe to these events in any bus, like any other event they'd manage.
