event()

Comment écrire un événement est dans Événements ; chaque événement, avec ce que reçoit sa fonction, est dans la référence des événements.

event() s’importe de 'chapterjs', dans n’importe quel fichier de src/. Elle prend un objet, EventConfig : le name de l’événement, ses options quand il en a, et run. name type le reste : la même ligne d’import donne un membre à votre fonction pour 'memberJoin' et un rôle pour 'roleDelete'.

src/events/welcome.ts

import { event } from 'chapterjs';

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

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

Déclare quoi faire quand un événement se produit. Exportez le résultat depuis n’importe quel fichier de src/ ; name dit quel événement, et type ce que reçoit run. Certains événements ont des options, écrites à côté de name (bots: true, where: 'dm') : ce que reçoit run les suit. Options est ce que la déclaration a écrit en plus de name et run, tel quel : une option que l’événement n’a pas est une erreur dans l’éditeur, et la déclaration est aussi vérifiée au chargement (voir Erreurs).

Types

Dix types accompagnent event() : EventName, EventContexts et ContextOf pour ce que reçoit votre fonction, EventConfig pour ce qu’elle prend, EventDeclaration pour ce qu’elle renvoie, EventOptions, MessageEventOptions, ReactionEventOptions, WhereEventOptions et EventWhere pour ses options. Tous s’importent avec import type { ... } from 'chapterjs'.

EventName

type EventName = keyof EventContexts

Le nom d’un événement : ce que prend name.

EventContexts

interface EventContexts {
  ready: { user: User; guilds: ReadonlyMap<Snowflake, Guild> };
  messageCreate: { message: Message };
  // ... une entrée par événement
}

Ce que reçoit votre fonction, pour chaque événement. C’est la forme la plus large, comme si chaque option était activée : les événements sur les messages donnent un Message tel quel. Pour typer ce que reçoit une déclaration avec des options données, utilisez ContextOf. Chaque entrée est listée dans la référence des événements.

ContextOf

type ContextOf<Name extends EventName, Options = object>

Ce que reçoit votre fonction pour un événement, d’après les options que son fichier a passées à event(). EventContexts est la forme la plus large : chaque option activée. C’est le type à utiliser pour une fonction partagée par plusieurs déclarations :

src/lib/log.ts

import type { ContextOf } from 'chapterjs';

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

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

Sans options, ContextOf<'messageCreate'> est ce que reçoit une déclaration sans options : un MemberMessage.

EventConfig

type EventConfig<Name extends EventName = EventName, Options extends object = {}> = {
  name: Name;
  run: (context: ContextOf<Name, Options>) => unknown;
} & Partial<OptionsOf<Name>> & { /* les options écrites, telles quelles */ }

Ce qu’un fichier donne à event() : l’événement, ses options quand il en a, et quoi faire. Ce que reçoit run suit les options : ce qu’une option laisse passer n’est là à traiter que quand l’option est activée.

Name

requis

L’événement auquel réagir : 'messageCreate', 'memberJoin'…

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

requis

Quoi faire quand l’événement se produit.

Les options de l’événement, quand il en a, s’écrivent à côté : voir EventOptions.

EventDeclaration

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

Ce que renvoie event() : une déclaration que le framework trouve dans les exports d’un fichier.

EventConfig<Name, never>

requis

Ce que le fichier a donné à event(), pas encore vérifié.

EventOptions

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

Les options qu’une déclaration peut écrire à côté de name, pour les événements qui en ont.

MessageEventOptions

Options des événements sur les messages.

boolean

Tourner aussi pour les messages écrits par des bots (celui-ci compris) et par des webhooks. Par défaut ils sont ignorés : un bot qui répond aux bots peut finir par se répondre à lui-même, ou à un autre bot, sans fin.

EventWhere

Où le fichier écoute : 'guild' (dans les serveurs, par défaut), 'dm' (dans les messages privés avec le bot) ou 'both'. Ce que reçoit la fonction le suit : un serveur toujours là, jamais là, ou à vérifier.

ReactionEventOptions

Options des événements sur les réactions ajoutées ou retirées.

boolean

Tourner aussi pour les réactions des bots, celui-ci compris. Par défaut elles sont ignorées : un bot qui réagit aux réactions peut finir par répondre aux siennes, sans fin.

EventWhere

WhereEventOptions

L’option des événements qui se produisent aussi en messages privés.

EventWhere

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

Où quelque chose se passe : dans les serveurs ('guild'), dans les messages privés avec le bot ('dm'), ou dans les deux.

Erreurs

Une déclaration qui n’est pas ce qu’attend event() est signalée avec son fichier (et le nom de son export, quand ce n’est pas celui par défaut) au chargement, et ne fait jamais planter le bot. Dans chapterjs dev, la déclaration garde sa dernière version qui fonctionnait, si elle en avait une ; dans chapterjs build, la compilation échoue.

Pas de nom

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

Un nom qui n’est pas un événement

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

La partie Did you mean n’est là que quand un vrai événement est proche du nom.

event() sans objet

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

Pas de run

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

Une option qui n’existe pas

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

Pour un événement sans 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.

Une mauvaise valeur

✗ 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".

Un export nommé

Quand la déclaration n’est pas l’export par défaut de son fichier, le nom de l’export suit le fichier :

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

Référence

Vos fichiers

Structures

Types

CLI

event()

event()

Types

EventName

EventContexts

ContextOf

EventConfig

EventDeclaration

EventOptions

MessageEventOptions

ReactionEventOptions

WhereEventOptions

EventWhere

Erreurs