export error codes for better event error handling

Author: notunderctrl

apps/test-bot/src/events/messageCreate/01-log.ts

@@ -0,0 +1,27 @@
+import {
+  type EventHandler,
+  stopEvents,
+  isErrorType,
+  CommandKitErrorCodes,
+} from 'commandkit';
+
+const handler: EventHandler<'messageCreate'> = (message) => {
+  try {
+    // code that may throw an error
+
+    stopEvents(); // conditionally stop the event chain
+  } catch (error) {
+    if (isErrorType(error, CommandKitErrorCodes.StopEvents)) {
+      console.log('Stopping event chain');
+      // if stopEvents() is called in the try block, throw it so CommandKit can stop the event chain
+      throw error;
+    }
+
+    console.log('Not stopping event chain');
+    // this means that the code threw the error, and stopEvents() was not called
+    // the rest of the event handlers will be executed as normal
+    console.error(error);
+  }
+};
+
+export default handler;

apps/test-bot/src/events/messageCreate/02-log.ts

@@ -0,0 +1,29 @@
+import {
+  type EventHandler,
+  stopEvents,
+  isErrorType,
+  CommandKitErrorCodes,
+} from 'commandkit';
+
+const handler: EventHandler<'messageCreate'> = (message) => {
+  try {
+    // code that may throw an error
+
+    throw new Error('test');
+
+    // stopEvents(); // conditionally stop the event chain
+  } catch (error) {
+    if (isErrorType(error, CommandKitErrorCodes.StopEvents)) {
+      console.log('Stopping event chain');
+      // if stopEvents() is called in the try block, throw it so CommandKit can stop the event chain
+      throw error;
+    }
+
+    console.log('Not stopping event chain');
+    // this means that the code threw the error, and stopEvents() was not called
+    // the rest of the event handlers will be executed as normal
+    console.error(error);
+  }
+};
+
+export default handler;

apps/test-bot/src/events/ready/test.ts

@@ -1,5 +1,9 @@
-import { Logger } from 'commandkit';
+import { type EventHandler, Logger } from 'commandkit';
 
-export default function onReady() {
-  Logger.log('Ready from legacy event handler');
-}
+export const once = true;
+
+const handler: EventHandler<'ready'> = (client, c, commandkit) => {
+  Logger.log(`Ready from legacy event handler: ${client.user.username}`);
+};
+
+export default handler;

apps/website/docs/guide/03-events/03-stopevents-function.mdx

@@ -11,21 +11,54 @@ handlers to control the flow of execution.
 ## Usage
 
 ```ts title="src/app/events/messageCreate/event.ts"
-import type { Message } from 'discord.js';
-import { stopEvents } from 'commandkit';
+import { type EventHandler, stopEvents } from 'commandkit';
 
-export default async function (message: Message) {
+const handler: EventHandler<'messageCreate'> = (message) => {
   console.log('Message received:', message.content);
 
   // Stop further event handlers of messageCreate from being executed after this point
   stopEvents();
-  // code below will not be executed
-}
+  // code below, and the rest of the event handlers, will not be executed
+};
+
+export default handler;
 ```
 
 :::warning
 
 Calling `stopEvents()` in a try/catch block may lead to unexpected
 behavior.
 
+If you still want to use `stopEvents()` in a try/catch block, you can
+use the `isErrorType` function to check if the error is an instance of
+the `CommandKitErrorCodes.StopEvents` error.
+
+```ts title="src/app/events/messageCreate/event.ts"
+import {
+  type EventHandler,
+  stopEvents,
+  isErrorType,
+  CommandKitErrorCodes,
+} from 'commandkit';
+
+const handler: EventHandler<'messageCreate'> = (message) => {
+  try {
+    // code that may throw an error
+
+    stopEvents(); // conditionally stop the event chain
+  } catch (error) {
+    if (isErrorType(error, CommandKitErrorCodes.StopEvents)) {
+      // if stopEvents() is called in the try block, throw it so CommandKit can stop the event chain
+      throw error;
+    }
+
+    // this means that the code threw the error, and stopEvents() was not called
+    // the rest of the event handlers will be executed as normal
+    console.error(error);
+  }
+};
+
+export default handler;
+```
+
 :::

packages/commandkit/src/index.ts

@@ -28,6 +28,7 @@ export * from './app/interrupt/signals';
 export type { CommandKitHMREvent } from './utils/dev-hooks';
 export * from './utils/constants';
 export * from './app/events/EventWorkerContext';
+export { CommandKitErrorCodes, isErrorType } from './utils/error-codes';
 export { Collection, type Client } from 'discord.js';
 
 // cli