> ## Documentation Index
> Fetch the complete documentation index at: https://www.chapterjs.org/llms.txt
> Use this file to discover all available pages before exploring further.

# event()

> La fonction qui déclare une réaction à un événement, ses options et les types derrière ce que reçoit votre fonction

> [!NOTE]
>
> Comment écrire un événement est dans [Événements](https://www.chapterjs.org/fr/events.md) ; chaque événement, avec ce que reçoit sa fonction, est dans la [référence des événements](https://www.chapterjs.org/fr/reference/events.md).

`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'`.

```ts src/events/welcome.ts theme={"theme":{"light":"github-light","dark":"vesper"}}
import { event } from 'chapterjs';

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

## event()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
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](#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

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type EventName = keyof EventContexts
```

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

### EventContexts

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
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](https://www.chapterjs.org/fr/reference/events.md).

### ContextOf

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
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 :

```ts src/lib/log.ts theme={"theme":{"light":"github-light","dark":"vesper"}}
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`](https://www.chapterjs.org/fr/reference/message#membermessage).

### EventConfig

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
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** `Name` *required*

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

**run** `(context: ContextOf\<Name, Options\>) =\> unknown` *required*

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

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
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.

**config** `EventConfig\<Name, never\>` *required*

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

### EventOptions

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
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.

**bots** `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.

**where** `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.

**bots** `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.

**where** `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.

### WhereEventOptions

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

**where** `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.

### EventWhere

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
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.

> [accordion] Pas de nom
>
> ```text theme={"theme":{"light":"github-light","dark":"vesper"}}
> ✗ 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.
> ```

> [accordion] Un nom qui n’est pas un événement
>
> ```text theme={"theme":{"light":"github-light","dark":"vesper"}}
> ✗ 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.

> [accordion] event() sans objet
>
> ```text theme={"theme":{"light":"github-light","dark":"vesper"}}
> ✗ src/events/online.ts event() needs an object: event({ name: 'messageCreate', run({ message }) { ... } })
> ```

> [accordion] Pas de run
>
> ```text theme={"theme":{"light":"github-light","dark":"vesper"}}
> ✗ src/events/online.ts This ready event has no "run": the function to run when it happens, like event({ name: 'messageCreate', run({ message }) { ... } })
> ```

> [accordion] Une option qui n’existe pas
>
> ```text theme={"theme":{"light":"github-light","dark":"vesper"}}
> ✗ src/events/ping.ts "bot" is not an option of messageCreate. Options of messageCreate are: bots, where.
> ```
>
> Pour un événement sans options :
>
> ```text theme={"theme":{"light":"github-light","dark":"vesper"}}
> ✗ 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.
> ```

> [accordion] Une mauvaise valeur
>
> ```text theme={"theme":{"light":"github-light","dark":"vesper"}}
> ✗ src/events/ping.ts The option bots of messageCreate is true or false, got "yes".
> ```
>
> ```text theme={"theme":{"light":"github-light","dark":"vesper"}}
> ✗ src/events/ping.ts The option where of messageCreate is 'guild', 'dm' or 'both', got "everywhere".
> ```

> [accordion] 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 :
>
> ```text theme={"theme":{"light":"github-light","dark":"vesper"}}
> ✗ src/moderation.ts (logged) "banAdded" is not an event. Did you mean "banAdd"? Events are: ...
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.