Skip to Content
nyx logonyx guide

Subscribers

Reading time:4 min read

Subscribers are objects that are notified by an EventBus when an event they are subscribed to is emitted.

Creation

Creation

You'll first need a type for your events arguments, here we'll use MyEventsArgs.

Either:

  • Extend AbstractEventSubscriber class and implement handleEvent() and event:
import { , type  } from '@nyx-discord/djs';

type  = {
  : [string, number];
};

class  extends <, 'someEvent'> {
  protected readonly  = 'someEvent';

  public async (: , ...: ['someEvent']) {
    // Handle event
  }
}
  • Use SubscriberCallbackWrapper to create a subscriber from a generic callback:
import { , type  } from '@nyx-discord/djs';

type  = {
  : [string, number];
};

export const  = new <, 'someEvent'>(
  'someEvent',
  (: , ...: ['someEvent']) => {
    // Handle event
  }
);

Subscription

Register the subscriber to an EventBus:

await .();

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.
    • HighMonitor is the first priority to be executed.
    • LowMonitor is 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.Id field.
  • The execution start date, via the TypedFields.CreationDate field.
  • The bot that called the event, via the TypedFields.Bot field.
  • The bus where the event was emitted, via the TypedFields.EventBus field.
  • Whether the event has been marked as handled by another subscriber, via the TypedFields.EventHandled field, 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 = false

Notice 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:

  • On to "permanently" subscribe to the bus until manually unsubscribed (default).
  • Once to subscribe for a single call (The EventSubscriberMiddleware must 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
On

Notice 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.

Edit on GitHub

Last updated on

On this page