> ## 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()

> The function that declares a reaction to an event, its options and the types behind what your function receives

> [!NOTE]
>
> How to write an event is in [Events](https://www.chapterjs.org/events.md); every event, with what its function receives, is in [Events reference](https://www.chapterjs.org/reference/events.md).

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

```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(`Welcome to ${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>
```

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](#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

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

The name of an event: what `name` takes.

### EventContexts

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

### ContextOf

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

```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} 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`](https://www.chapterjs.org/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>> & { /* 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** `Name` *required*

The event to react to: `'messageCreate'`, `'memberJoin'`...

**run** `(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

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

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

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

### 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;
}
```

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

### MessageEventOptions

Options of the events about messages.

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

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

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

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

### WhereEventOptions

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

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

### EventWhere

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

> [accordion] No name
>
> ```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] A name that is not an event
>
> ```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.
> ```
>
> The `Did you mean` part is only there when a real event is close to the name.

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

> [accordion] No 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] An option that does not exist
>
> ```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.
> ```
>
> For an event without 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] A wrong value
>
> ```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] A named export
>
> When the declaration is not the default export of its file, the name of the export follows the file:
>
> ```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.