feat: add a way to stop event propagation

Author: notunderctrl

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

@@ -2,6 +2,7 @@ import { CommandKit } from '../../CommandKit';
 import { ListenerFunction } from '../../events/CommandKitEventsChannel';
 import { Logger } from '../../logger/Logger';
 import { toFileURL } from '../../utils/resolve-file-url';
+import { StopEventPropagationError } from '../../utils/utilities';
 import { ParsedEvent } from '../router';
 
 export type EventListener = {
@@ -107,6 +108,17 @@ export class AppEventsHandler {
           try {
             await listener.handler(...args);
           } catch (e) {
+            // Check if this is a stop propagation signal
+            if (e instanceof StopEventPropagationError) {
+              Logger.debug(
+                `Event propagation stopped for ${name}${
+                  namespace ? ` of namespace ${namespace}` : ''
+                }`,
+              );
+              break; // Stop executing remaining listeners
+            }
+
+            // Otherwise log the error as usual
             Logger.error(
               `Error handling event ${name}${
                 namespace ? ` of namespace ${namespace}` : ''
@@ -127,6 +139,17 @@ export class AppEventsHandler {
             await listener.handler(...args);
             executedOnceListeners.add(listener.handler);
           } catch (e) {
+            // Check if this is a stop propagation signal
+            if (e instanceof StopEventPropagationError) {
+              Logger.debug(
+                `Event propagation stopped for ${name}${
+                  namespace ? ` of namespace ${namespace}` : ''
+                }`,
+              );
+              break; // Stop executing remaining listeners
+            }
+
+            // Otherwise log the error as usual
             Logger.error(
               `Error handling event ${name}${
                 namespace ? ` of namespace ${namespace}` : ''

packages/commandkit/src/index.ts

@@ -21,6 +21,8 @@ export {
   getSourceDirectories,
   devOnly,
   debounce,
+  stopEvents,
+  StopEventPropagationError,
 } from './utils/utilities';
 export type { CommandKitHMREvent } from './utils/dev-hooks';
 export * from './utils/constants';

packages/commandkit/src/utils/utilities.ts

@@ -110,3 +110,21 @@ export function devOnly<T extends (...args: any[]) => any>(fn: T): T {
 
   return f as T;
 }
+
+/**
+ * Custom error for stopping event propagation.
+ */
+export class StopEventPropagationError extends Error {
+  constructor() {
+    super('Event propagation stopped');
+    this.name = 'StopEventPropagationError';
+  }
+}
+
+/**
+ * Stops event propagation.
+ * @throws {StopEventPropagationError}
+ */
+export function stopEvents(): never {
+  throw new StopEventPropagationError();
+}