Listeners

How to use Listeners

Necord supports interacting with all discord events via the @On and @Once decorator. These decorators can be used within any injectable class, such as services or custom providers.

app.service.ts

import { Injectable, Logger } from '@nestjs/common';
import { Once, On, Context, ContextOf } from 'necord';

@Injectable()
export class AppService {
    private readonly logger = new Logger(AppService.name);

    @Once('clientReady')
    public onReady(@Context() [client]: ContextOf<'clientReady'>) {
        this.logger.log(`Bot logged in as ${client.user.username}`);
    }

    @On('warn')
    public onWarn(@Context() [message]: ContextOf<'warn'>) {
        this.logger.warn(message);
    }
}

Warning

If you use global filters, guards or interceptors, they will be triggered once per event! This means if you are replying to the message in guards, you can run into issues with duplicated responses or invalid interactions. Have a look at the NecordExecutionContext.getDiscovery() metadata to learn more about the current context.

Context

You might have noticed the @Context decorator in the last snippet: This is used to inject the event context within the method. As there are many type of events, its type must be inferred from the ContextOf<type: string> type.

You can access the context variables by using the @Context() decorator within your function, which will populate the variable with an array of arguments.

app.service.ts

@On('messageCreate')
public onMessageCreate(@Context() [message]: ContextOf<'messageCreate'>) {
    console.log(message.content);
}

Custom Events

Necord out of the box supports all the events provided by discord.js. You can also create custom events using the @CustomListenerHandler and @CustomListener decorators.

user-update.handler.ts

import { Injectable } from '@nestjs/common';
import { CustomListener, CustomListenerHandler, BaseHandler, ContextOf, createCustomOnDecorator } from 'necord';
import { User } from 'discord.js';

export type CustomUserUpdateEvents = {
	userAvatarUpdate: [user: User, oldAvatar: string, newAvatar: string];
};

export type ContextOfCustomUserUpdate<K extends keyof E, E = CustomUserUpdateEvents> = E[K];

export const OnCustomUserUpdate = createCustomOnDecorator<CustomUserUpdateEvents>();

@Injectable()
@CustomListener('userUpdate')
export class UserUpdateHandler extends BaseHandler<CustomUserUpdateEvents> {
	@CustomListenerHandler()
	public handleUserAvatarUpdate([oldUser, newUser]: ContextOf<'userUpdate'>) {
		if (oldUser.partial) return;

		if (oldUser.displayAvatarURL() !== newUser.displayAvatarURL()) {
			this.emit(
				'userAvatarUpdate',
				newUser,
				oldUser.displayAvatarURL(),
				newUser.displayAvatarURL()
			);
		}
	}
}

Tip

You can create not only custom @On decorators, but also your own @Once decorators. To do this, use the createCustomOnceDecorator function, which works similarly to createCustomOnDecorator but subscribes the handler only to the first occurrence of the event.

Also, you can create multiple custom event handlers in a single class by adding more methods with the @CustomListenerHandler() decorator.

And then you can listen to the custom event using the @OnCustomUserUpdate decorator.

app.service.ts

import { Injectable } from '@nestjs/common';
import { OnCustomUserUpdate, ContextOfCustomUserUpdate, Context } from './user-update.handler';

@Injectable()
export class AppService {
	@OnCustomUserUpdate('userAvatarUpdate')
	public onAvatarUpdate(@Context() context: ContextOfCustomUserUpdate<'userAvatarUpdate'>) {
		const [user, oldAvatar, newAvatar] = context;
		console.log(`User ${user.username} changed avatar from ${oldAvatar} to ${newAvatar}`);
	}
}

Also you can use @On<CustomUserUpdateEvents>('userAvatarUpdate') instead of creating a new decorator. But creating a new decorator is more convenient and cleaner.

List of Custom Events

The following is a list of all the custom events provided by Necord. It can be accessed via the @On decorator.

Channel Events

Event Name	Description
guildChannelPermissionsUpdate	Emitted whenever a channel's permission overwrite for a guild is updated.

Guild Events

Event Name	Description
guildBoostLevelUp	Emitted whenever a guild's boost level increases.
guildBoostLevelDown	Emitted whenever a guild's boost level decreases.
guildBannerAdd	Emitted whenever a guild's banner is added.
guildAfkChannelAdd	Emitted whenever a guild's AFK channel is added.
guildVanityURLAdd	Emitted whenever a guild's vanity URL is added.
guildVanityURLUpdate	Emitted whenever a guild's vanity URL is updated.
guildVanityURLRemove	Emitted whenever a guild's vanity URL is removed.
guildFeaturesUpdate	Emitted whenever a guild's features are updated.
guildAcronymUpdate	Emitted whenever a guild's acronym is updated.
guildOwnerUpdate	Emitted whenever a guild's owner is updated.
guildPartnerAdd	Emitted whenever a guild's is partner of discord now
guildPartnerRemove	Emitted whenever a guild's is no longer partner of discord
guildVerificationAdd	Emitted whenever a guild's verification level is added.
guildVerificationRemove	Emitted whenever a guild's verification level is removed.

Guild Audit Log Events

Event Name	Description
guildAuditLogEntryAdd	Emitted whenever an entry is added to the audit log.
guildAuditLogEntryUpdate	Emitted whenever an entry is updated in the audit log.
guildAuditLogEntryDelete	Emitted whenever an entry is removed from the audit log.
guildAuditLogEntryWebhookCreate	Emitted whenever a webhook is created in the audit log.
guildAuditLogEntryWebhookUpdate	Emitted whenever a webhook is updated in the audit log.
guildAuditLogEntryWebhookDelete	Emitted whenever a webhook is deleted in the audit log.

Guild Member Events

Event Name	Description
guildMemberBoost	Emitted whenever a member's boost is activated.
guildMemberUnboost	Emitted whenever a member's boost is deactivated.
guildMemberRoleAdd	Emitted whenever a role is added to a member.
guildMemberRoleRemove	Emitted whenever a role is removed from a member.
guildMemberNicknameUpdate	Emitted whenever a member's nickname is updated.
guildMemberEntered	Emitted whenever a member enters a guild.
guildMemberAvatarAdd	Emitted whenever a member's avatar is added.
guildMemberAvatarRemove	Emitted whenever a member's avatar is removed.
guildMemberAvatarUpdate	Emitted whenever a member's avatar is updated.

Role Update Events

Event Name	Description
rolePositionUpdate	Emitted whenever a role's position is updated.
rolePermissionsUpdate	Emitted whenever a role's permissions are updated.
roleIconAdd	Emitted whenever a role's icon is added.
roleIconRemove	Emitted whenever a role's icon is removed.
roleIconUpdate	Emitted whenever a role's icon is updated.

Thread Update Events

Event Name	Description
threadStateUpdate	Emitted whenever a thread's state is updated.
threadNameUpdate	Emitted whenever a thread's name is updated.
threadLockStateUpdate	Emitted whenever a thread's lock state is updated.
threadRateLimitPerUserUpdate	Emitted whenever a thread's rate limit per user is updated.
threadAutoArchiveDurationUpdate	Emitted whenever a thread's auto archive duration is updated.

Message Events

Event Name	Description
messagePinned	Emitted whenever a message is pinned.
messageContentEdited	Emitted whenever a message is updated.

Presence Events

Event Name	Description
guildMemberOffline	Emitted whenever a member goes offline.
guildMemberOnline	Emitted whenever a member goes online.

User Events

Event Name	Description
userAvatarUpdate	Emitted whenever a user's avatar is updated.
userUsernameUpdate	Emitted whenever a user's username is updated.
userDiscriminatorUpdate	Emitted whenever a user's discriminator is updated.
userFlagsUpdate	Emitted whenever a user's flags are updated.

Voice Events

Event Name	Description
voiceChannelJoin	Emitted whenever a member joins a voice channel.
voiceChannelLeave	Emitted whenever a member leaves a voice channel.
voiceChannelSwitch	Emitted whenever a member switches voice channel.
voiceChannelMutestate	Emitted whenever a member is muted or deafened in a voice channel.
voiceChannelUnmute	Emitted whenever a member is unmuted in a voice channel.
voiceChannelDeaf	Emitted whenever a member is deafened in a voice channel.
voiceChannelUndeaf	Emitted whenever a member is undeafened in a voice channel.
voiceStreamingStart	Emitted whenever a member starts streaming.
voiceStreamingStop	Emitted whenever a member stops streaming.