Skip to Content
nyx logonyx guide

Buses

Reading time:5 min read

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]);
Type 'boolean' is not assignable to type 'string'.

It can be iterated and its subscribers can be obtained:

const subscribers = .();
const subscribers: ReadonlyCollection<Identifier, AnyEventSubscriberFrom<EventArgs>>
for (const [, subscriber] of ) {
const subscriber: AnyEventSubscriberFrom<EventArgs>
}

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.

AdvantagesDisadvantages
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 1 effectively 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.

AdvantagesDisadvantages
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);
The default is of 10000 ms (10 seconds).

Known buses

Client bus

The Client event bus is a built-in bus that wraps its events:

const bus = .();
const bus: EventBus<any>

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 commandBus: EventBus<CommandEventArgs<any>>
const scheduleBus = .().();
const scheduleBus: EventBus<ScheduleEventArgs>
const pluginBus = .().();
const pluginBus: EventBus<PluginEventArgs>

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.

On this page