event()

How to write an event is in Events; every event, with what its function receives, is in Events reference.

event() is imported from 'chapterjs', in any file of src/. It takes one object, EventConfig: the name of the event, its options when it has some, and run. name types the rest: the same import line gives your function a member for 'memberJoin' and a role for 'roleDelete'.

src/events/welcome.ts

import { event } from 'chapterjs';

export default event({
  name: 'memberJoin',
  async run({ member, guild }) {
    await member.send(`Welcome to ${guild.name}!`);
  },
});

event<Name extends EventName, const Options extends Partial<OptionsOf<Name>> & object = {}>(
  config: EventConfig<Name, Options>
): EventDeclaration<Name>

Declares what to do when an event happens. Export the result from any file of src/; name says which event, and types what run receives. Some events have options, written next to name (bots: true, where: 'dm'): what run receives follows them. Options is what the declaration wrote besides name and run, as written: an option that the event does not have is an error in the editor, and the declaration is also checked when it loads (see Errors).

Types

Ten types go with event(): EventName, EventContexts and ContextOf for what your function receives, EventConfig for what it takes, EventDeclaration for what it returns, EventOptions, MessageEventOptions, ReactionEventOptions, WhereEventOptions and EventWhere for its options. All are imported with import type { ... } from 'chapterjs'.

EventName

type EventName = keyof EventContexts

The name of an event: what name takes.

EventContexts

interface EventContexts {
  ready: { user: User; guilds: ReadonlyMap<Snowflake, Guild> };
  messageCreate: { message: Message };
  // ... one entry per event
}

What your function receives, for each event. It is the widest form, as if every option was on: the events about messages give a plain Message. To type what a declaration with given options receives, use ContextOf. Every entry is listed in the events reference.

ContextOf

type ContextOf<Name extends EventName, Options = object>

What your function receives for an event, given the options its file passed to event(). EventContexts is the widest form: every option on. This is the type to use for a function shared by several declarations:

src/lib/log.ts

import type { ContextOf } from 'chapterjs';

export function logJoin({ member, guild }: ContextOf<'memberJoin'>) {
  console.log(`${member.displayName} joined ${guild.name}`);
}

export function logPrivate({ message }: ContextOf<'messageCreate', { where: 'dm' }>) {
  console.log(`${message.author.username}: ${message.content}`);
}

Without options, ContextOf<'messageCreate'> is what a declaration without options receives: a MemberMessage.

EventConfig

type EventConfig<Name extends EventName = EventName, Options extends object = {}> = {
  name: Name;
  run: (context: ContextOf<Name, Options>) => unknown;
} & Partial<OptionsOf<Name>> & { /* the options written, as written */ }

What a file gives to event(): the event, its options when it has some, and what to do. What run receives follows the options: what an option lets through is only there to handle when the option is on.

Name

required

The event to react to: 'messageCreate', 'memberJoin'…

(context: ContextOf<Name, Options>) => unknown

required

What to do when the event happens.

The options of the event, when it has some, are written next to them: see EventOptions.

EventDeclaration

interface EventDeclaration<Name extends EventName = EventName> {
  readonly config: EventConfig<Name, never>;
}

What event() returns: a declaration the framework finds in the exports of a file.

EventConfig<Name, never>

required

What the file gave to event(), not checked yet.

EventOptions

interface EventOptions {
  messageCreate: MessageEventOptions;
  messageUpdate: MessageEventOptions;
  messageDelete: WhereEventOptions;
  reactionAdd: ReactionEventOptions;
  reactionRemove: ReactionEventOptions;
  reactionClear: WhereEventOptions;
  pollVoteAdd: WhereEventOptions;
  pollVoteRemove: WhereEventOptions;
  typingStart: WhereEventOptions;
}

The options a declaration can write next to name, for the events that have some.

MessageEventOptions

Options of the events about messages.

boolean

Also run for messages written by bots (this one included) and by webhooks. By default they are ignored: a bot that answers bots can end up answering itself, or another bot, forever.

EventWhere

Where the file listens: 'guild' (in servers, the default), 'dm' (in private messages with the bot) or 'both'. What the function receives follows it: a server that is always there, never there, or to check.

ReactionEventOptions

Options of the events about reactions added or removed.

boolean

Also run for the reactions of bots, this one included. By default they are ignored: a bot that reacts to reactions can end up answering its own, forever.

EventWhere

WhereEventOptions

The option of the events that also happen in private messages.

EventWhere

type EventWhere = 'guild' | 'dm' | 'both'

Where something happens: in servers ('guild'), in private messages with the bot ('dm'), or in both.

Errors

A declaration that is not what event() expects is reported with its file (and the name of its export, when it is not the default one) when it loads, and never crashes the bot. In chapterjs dev, the declaration keeps its last working version, if it had one; in chapterjs build, the build fails.

No name

✗ src/events/ping.ts This event has no "name": the event to react to, like event({ name: 'messageCreate', run({ message }) { ... } }). Events are: ready, messageCreate, messageUpdate, messageDelete, memberJoin, memberUpdate, memberLeave, guildJoin, guildLeave, channelCreate, channelUpdate, channelDelete, roleCreate, roleUpdate, roleDelete, guildUpdate, banAdd, banRemove, emojiCreate, emojiUpdate, emojiDelete, inviteCreate, inviteDelete, auditLogEntryCreate, reactionAdd, reactionRemove, reactionClear, pollVoteAdd, pollVoteRemove, typingStart, threadMemberJoin, threadMemberLeave, voiceJoin, voiceLeave, voiceMove, voiceUpdate, presenceUpdate, scheduledEventCreate, scheduledEventUpdate, scheduledEventDelete, scheduledEventUserAdd, scheduledEventUserRemove.

A name that is not an event

✗ src/events/welcome.ts "memberjoin" is not an event. Did you mean "memberJoin"? Events are: ready, messageCreate, messageUpdate, messageDelete, memberJoin, memberUpdate, memberLeave, guildJoin, guildLeave, channelCreate, channelUpdate, channelDelete, roleCreate, roleUpdate, roleDelete, guildUpdate, banAdd, banRemove, emojiCreate, emojiUpdate, emojiDelete, inviteCreate, inviteDelete, auditLogEntryCreate, reactionAdd, reactionRemove, reactionClear, pollVoteAdd, pollVoteRemove, typingStart, threadMemberJoin, threadMemberLeave, voiceJoin, voiceLeave, voiceMove, voiceUpdate, presenceUpdate, scheduledEventCreate, scheduledEventUpdate, scheduledEventDelete, scheduledEventUserAdd, scheduledEventUserRemove.

The Did you mean part is only there when a real event is close to the name.

event() without an object

✗ src/events/online.ts event() needs an object: event({ name: 'messageCreate', run({ message }) { ... } })

No run

✗ src/events/online.ts This ready event has no "run": the function to run when it happens, like event({ name: 'messageCreate', run({ message }) { ... } })

An option that does not exist

✗ src/events/ping.ts "bot" is not an option of messageCreate. Options of messageCreate are: bots, where.

For an event without options:

✗ src/events/online.ts "bots" is not an option of ready. ready has no options: an event has a name, a run function, and nothing else.

A wrong value

✗ src/events/ping.ts The option bots of messageCreate is true or false, got "yes".

✗ src/events/ping.ts The option where of messageCreate is 'guild', 'dm' or 'both', got "everywhere".

A named export

When the declaration is not the default export of its file, the name of the export follows the file:

✗ src/moderation.ts (logged) "banAdded" is not an event. Did you mean "banAdd"? Events are: ...

Reference

Your files

Structures

Types

CLI

event()

event()

Types

EventName

EventContexts

ContextOf

EventConfig

EventDeclaration

EventOptions

MessageEventOptions

ReactionEventOptions

WhereEventOptions

EventWhere

Errors