Subscribers
Subscribers are objects that are notified by an EventBus when an event they are subscribed to is emitted.
Creation
Creation
MyEventsArgs.Either:
- Extend
AbstractEventSubscriberclass and implementhandleEvent()andevent:
import { , type } from '@nyx-discord/djs';
type = {
: [string, number];
};
class extends <, 'someEvent'> {
protected readonly = 'someEvent';
public async (: , ...: ['someEvent']) {
// Handle event
}
}- Use
SubscriberCallbackWrapperto create a subscriber from a generic callback:
import { , type } from '@nyx-discord/djs';
type = {
: [string, number];
};
export const = new <, 'someEvent'>(
'someEvent',
(: , ...: ['someEvent']) => {
// Handle event
}
);If you want to create a listener for the Client bus, you can extend the AbstractDJSClientSubscriber (or AbstractCoreClientSubscriber for @discordjs/core) utility class instead, and you won't have to type out the client's event map generic. Check the Events Overview page for an example.
Priorities
The priority determines the order in which they are executed:
- Higher priorities are executed first.
- Monitors are specifically meant for monitoring (e.g. metrics), though that's not enforced.
HighMonitoris the first priority to be executed.LowMonitoris the last priority to be executed.
import { } from '@nyx-discord/djs';
.- LowMonitor
- Lowest
- Low
- Normal
- High
- Highest
- HighMonitor
The default priority is Normal, it's changed by overriding the priority property in classes. It can't be changed for callback-based subscribers.
Subscription notification
The subscriber will be notified when its un/subscribed to an EventBus, and when said bus is unregistered:
class extends <, 'someEvent'> {
public override (: <>) {
.('I was subscribed!');
}
public override (: <>) {
.('I was unsubscribed!');
}
public override (: <>) {
.('My bus was unregistered!');
}
}
await .();
// console: I was subscribed!
await .();
// console: I was unsubscribed!Event Meta
The first argument of the handleEvent() is an Metadata object, which is a Record that stores metadata about the event call.
Apart from the keys saved by the caller or the middleware, the dispatch meta contains:
- The execution ID, via the
TypedFields.Idfield. - The execution start date, via the
TypedFields.CreationDatefield. - The bot that called the event, via the
TypedFields.Botfield. - The bus where the event was emitted, via the
TypedFields.EventBusfield. - Whether the event has been marked as handled by another subscriber, via the
TypedFields.EventHandledfield, which will be explained later.
To learn more about TypedFields, check the Metadata page.
Event handling
By default, when a subscriber marks an event as "handled" with this.setHandled(meta), it won't be received by the rest of the subscribers.
This is useful for events that only need to be "executed once", for example, replying to an Interaction.
However, you can make your subscriber to be always called, even when the event is handled, overriding the ignoreHandled property:
// A subscriber with priority Highest marks the event as handled
class extends <, 'someEvent'> {
protected readonly = .;
public (: ) {
.('Highest');
this.();
}
}
// A subscriber with priority Lowest doesn't receive the event
class extends <, 'someEvent'> {
protected readonly = .;
public () {
.('Lowest');
}
}
// A subscriber with priority Lowest but `ignoreHandled = false` receives the event
class extends <, 'someEvent'> {
protected readonly = .;
protected readonly = false;
public () {
.('Lowest with ignoreHandled = false');
}
}
await .(new (), new (), new ());
await .('someEvent', []);Would log:
Highest
Lowest with ignoreHandled = falseNotice how the Lowest subscriber is not called, because it has a lower priority than the Highest one, which marked the event as handled, and it has ignoreHandled = true by default.
Lifetime
Subscribers can specify its "lifetime", which determines how much it lasts registered on the bus. This is similar to using Node's EventEmitter#on() vs EventEmitter#once().
This can be done overriding the lifetime property. Currently available lifetimes are:
Onto "permanently" subscribe to the bus until manually unsubscribed (default).Onceto subscribe for a single call (TheEventSubscriberMiddlewaremust allow the execution).
class extends <, 'someEvent'> {
protected readonly = .;
public () {
.('Once');
}
}
class extends <, 'someEvent'> {
protected readonly = .;
public () {
.('On');
}
}
await .(new (), new ());
await .('someEvent', []);
await .('someEvent', []);Would log:
Once
On
OnNotice how the Once subscriber is called only once, while the On subscriber is called twice (as many times as the event is emitted).
Metadata
When extending nyx with plugins, you may want to specify extra data for them. You can do so with the Metadata object, saved on the subscriber.
While subscribers internally save a Metadata, the return type of #getMeta() is a ReadonlyMetadata,
meaning that external objects can read the object, but not modify it.
import { } from '@nyx-discord/djs';
class extends <, 'someEvent'> {
protected override readonly = {
: 'someValue',
};
}
const = new ();
const = .();
const = ['someKey']; // 'someValue'For a more type-safe approach, you can use TypedFields. Check the Metadata page for more information.
Last updated on
