fix: legacy event handler behavior

Author: twlite

apps/website/docs/guide/06-plugins/03-creating-a-runtime-plugin.mdx

@@ -183,6 +183,35 @@ async onEventsRouterInit(ctx: CommandKitPluginRuntime): Promise<void> {
 }
 ```
 
+## Event handler hooks
+
+These hooks are called when processing events.
+
+#### `willEmitEvent(ctx, event)`
+
+Called before an event is emitted.
+
+**Parameters:**
+
+- `ctx`: The runtime context.
+- `event`: The event object being emitted.
+
+**Example use case:** Modify event data before it's emitted, or cancel the event.
+
+```typescript
+async willEmitEvent(
+  ctx: CommandKitPluginRuntime,
+  event: CommandKitEventDispatch
+): Promise<void> {
+  // prevent other plugins from handling this event
+  event.accept();
+  // Modify event data
+  event.args.push('This is a custom argument');
+}
+```
+
+Now the event listener will receive the modified event data.
+
 ## Command Registration Hooks
 
 These hooks are called during the command registration process, allowing you to modify commands before they're registered with Discord.

packages/commandkit/src/app/handlers/AppEventsHandler.ts

@@ -6,6 +6,7 @@ import { toFileURL } from '../../utils/resolve-file-url';
 import { StopEventPropagationError } from '../../utils/utilities';
 import { runInEventWorkerContext } from '../events/EventWorkerContext';
 import { ParsedEvent } from '../router';
+import { CommandKitEventDispatch } from '../../plugins';
 
 export type EventListener = {
   handler: ListenerFunction;
@@ -133,6 +134,27 @@ export class AppEventsHandler {
 
       // Create main handler for regular "on" listeners
       const mainHandler: ListenerFunction = async (...args) => {
+        let accepted = false;
+
+        const event: CommandKitEventDispatch = {
+          name,
+          args,
+          namespace: namespace ?? null,
+          once: false,
+          metadata: data.event,
+          accept() {
+            if (accepted) return;
+            accepted = true;
+          },
+        };
+
+        await this.commandkit.plugins
+          .execute(async (ctx, plugin) => {
+            if (accepted) return;
+            return plugin.willEmitEvent?.(ctx, event);
+          })
+          .catch(Object);
+
         await runInEventWorkerContext(
           {
             event: name,
@@ -172,6 +194,26 @@ export class AppEventsHandler {
       // Create handler for "once" listeners with cleanup logic
       const onceHandler: ListenerFunction = async (...args) => {
         let broken = false;
+        let accepted = false;
+
+        const event: CommandKitEventDispatch = {
+          name,
+          args,
+          namespace: namespace ?? null,
+          once: true,
+          metadata: data.event,
+          accept() {
+            if (accepted) return;
+            accepted = true;
+          },
+        };
+
+        await this.commandkit.plugins
+          .execute(async (ctx, plugin) => {
+            if (accepted) return;
+            return plugin.willEmitEvent?.(ctx, event);
+          })
+          .catch(Object);
 
         for (const listener of onceListeners) {
           if (broken) break; // Stop executing remaining listeners if propagation was stopped

packages/commandkit/src/plugins/RuntimePlugin.ts

@@ -1,4 +1,4 @@
-import { Interaction, Message, PartialMessage } from 'discord.js';
+import { Interaction, Message } from 'discord.js';
 import {
   isPlugin,
   PluginCommon,
@@ -10,6 +10,7 @@ import { CommandBuilderLike, PreparedAppCommandExecution } from '../app';
 import { CommandKitEnvironment } from '../context/environment';
 import { CommandKitHMREvent } from '../utils/dev-hooks';
 import { PreRegisterCommandsEvent } from '../app/register/CommandRegistrar';
+import { CommandKitEventDispatch } from './types';
 
 export abstract class RuntimePlugin<
   T extends PluginOptions = PluginOptions,
@@ -179,6 +180,16 @@ export abstract class RuntimePlugin<
     ctx: CommandKitPluginRuntime,
     env: CommandKitEnvironment,
   ) {}
+
+  /**
+   * Called before emitting an event
+   * @param ctx The context
+   * @param event The event that is being emitted
+   */
+  public async willEmitEvent(
+    ctx: CommandKitPluginRuntime,
+    event: CommandKitEventDispatch,
+  ) {}
 }
 
 export function isRuntimePlugin(plugin: unknown): plugin is RuntimePlugin {

packages/commandkit/src/plugins/types.ts

@@ -1,5 +1,15 @@
+import { ParsedEvent } from '../app/router';
 import type { CompilerPlugin } from './CompilerPlugin';
 import type { RuntimePlugin } from './RuntimePlugin';
 
 export type CommandKitPlugin = RuntimePlugin | CompilerPlugin;
 export type MaybeFalsey<T> = T | false | null | undefined;
+
+export interface CommandKitEventDispatch {
+  name: string;
+  args: unknown[];
+  namespace: string | null;
+  once: boolean;
+  metadata: ParsedEvent;
+  accept(): void;
+}

packages/legacy/src/index.ts

@@ -12,8 +12,9 @@ import {
   CommandKitHMREvent,
   HMREventType,
   getSourceDirectories,
+  CommandKitEventDispatch,
 } from 'commandkit';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { loadLegacyValidations } from './loadLegacyValidations.js';
 import { CommandData, loadLegacyCommands } from './loadLegacyCommands.js';
 import { existsSync } from 'node:fs';
@@ -107,6 +108,21 @@ export class LegacyHandlerPlugin extends RuntimePlugin<LegacyHandlerPluginOption
     await this.loadCommands(ctx, middlewareIds);
   }
 
+  public async willEmitEvent(
+    ctx: CommandKitPluginRuntime,
+    event: CommandKitEventDispatch,
+  ): Promise<void> {
+    const eventPath = resolve(event.metadata.path);
+    const ourPath = resolve(this.options.eventsPath);
+
+    if (!eventPath.startsWith(ourPath)) return;
+
+    event.accept();
+
+    // legacy handler injects the client to the last argument
+    event.args.push(ctx.commandkit.client);
+  }
+
   private async loadCommands(
     ctx: CommandKitPluginRuntime,
     middlewareIds: string[],