refactor: replace StopEventPropagationError with CommandKitErrorCodes for event handling and reorganize signal imports

Author: twlite

packages/commandkit/src/analytics/analytics-engine.ts

@@ -51,7 +51,6 @@ export class AnalyticsEngine {
    * @param provider The analytics provider to register.
    */
   public registerProvider(provider: AnalyticsProvider) {
-    warnUnstable('analytics');
     this.#provider = provider;
   }
 

packages/commandkit/src/app/commands/Context.ts

@@ -18,7 +18,7 @@ import {
 } from './MessageCommandParser';
 import { CommandKitEnvironment } from '../../context/environment';
 import { GenericFunction, getContext } from '../../context/async-context';
-import { exitMiddleware, redirect } from '../middleware/signals';
+import { exitMiddleware, redirect } from '../interrupt/signals';
 import {
   LoadedCommand,
   ResolvableCommand,

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

@@ -3,10 +3,10 @@ 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 { runInEventWorkerContext } from '../events/EventWorkerContext';
 import { ParsedEvent } from '../router';
 import { CommandKitEventDispatch } from '../../plugins';
+import { CommandKitErrorCodes, isErrorType } from '../../utils/error-codes';
 
 /**
  * Represents an event listener with its configuration.
@@ -207,7 +207,7 @@ export class AppEventsHandler {
                 await listener.handler(...args);
               } catch (e) {
                 // Check if this is a stop propagation signal
-                if (e instanceof StopEventPropagationError) {
+                if (isErrorType(e, CommandKitErrorCodes.StopEvents)) {
                   Logger.debug(
                     `Event propagation stopped for ${name}${
                       namespace ? ` of namespace ${namespace}` : ''
@@ -274,7 +274,7 @@ export class AppEventsHandler {
                 executedOnceListeners.add(listener.handler);
               } catch (e) {
                 // Check if this is a stop propagation signal
-                if (e instanceof StopEventPropagationError) {
+                if (isErrorType(e, CommandKitErrorCodes.StopEvents)) {
                   Logger.debug(
                     `Event propagation stopped for ${name}${
                       namespace ? ` of namespace ${namespace}` : ''

packages/commandkit/src/app/index.ts

@@ -1,7 +1,7 @@
 export * from './handlers/AppCommandHandler';
 export * from './commands/Context';
 export * from './commands/MessageCommandParser';
-export * from './middleware/signals';
+export * from './interrupt/signals';
 export * from './register/CommandRegistrar';
 
 export {

…commandkit/src/app/middleware/signals.ts …/commandkit/src/app/interrupt/signals.tspackages/commandkit/src/app/middleware/signals.ts renamed to packages/commandkit/src/app/interrupt/signals.ts packages/commandkit/src/app/middleware/signals.ts renamed to packages/commandkit/src/app/interrupt/signals.ts

@@ -3,6 +3,7 @@ import {
   createCommandKitError,
   isCommandKitError,
 } from '../../utils/error-codes';
+import { eventWorkerContext } from '../events/EventWorkerContext';
 
 /**
  * Cancel upcoming middleware execution.
@@ -17,6 +18,14 @@ export function exitMiddleware(): never {
 /**
  * Rethrow the error if it is a CommandKit error.
  * @param error The error to rethrow.
+ * @example try {
+ *    doSomething();
+ * } catch(e) {
+ *   // do something
+ *
+ *   // throw the error if it's a commandkit error
+ *   rethrow(e)
+ * }
  */
 export function rethrow(error: unknown): void {
   if (isCommandKitError(error)) throw error;
@@ -28,3 +37,23 @@ export function rethrow(error: unknown): void {
 export function redirect(): never {
   throw createCommandKitError(CommandKitErrorCodes.ForwardedCommand);
 }
+
+/**
+ * Stops event propagation. This function should be called inside an event handler
+ * to prevent further event handling.
+ * @example // src/app/events/messageCreate/handler.ts
+ * import { stopEvents } from 'commandkit';
+ *
+ * export default async function messageCreateHandler() {
+ *   console.log('Message created');
+ *   // Stop further event propagation
+ *   stopEvents();
+ * }
+ */
+export function stopEvents(): never {
+  if (!eventWorkerContext.getStore()) {
+    throw new Error('stopEvents() may only be called inside an event handler');
+  }
+
+  throw createCommandKitError(CommandKitErrorCodes.StopEvents);
+}

packages/commandkit/src/components/common/element.ts

@@ -82,8 +82,6 @@ export interface FragmentElementProps {
 export function Fragment(
   props: FragmentElementProps,
 ): CommandKitElementData[ElementType][] {
-  warnUnstable('CommandKit JSX');
-
   return Array.isArray(props.children)
     ? props.children.flat()
     : [props.children];
@@ -101,7 +99,6 @@ export function createElement(
   props: Record<string, unknown>,
   ...children: any[]
 ): CommandKitElement<ElementType> {
-  warnUnstable('CommandKit JSX');
   return type({ ...props, children: props.children ?? children });
 }
 

packages/commandkit/src/index.ts

@@ -21,10 +21,9 @@ export {
   getSourceDirectories,
   devOnly,
   debounce,
-  stopEvents,
-  StopEventPropagationError,
   defer,
 } from './utils/utilities';
+export * from './app/interrupt/signals';
 export type { CommandKitHMREvent } from './utils/dev-hooks';
 export * from './utils/constants';
 export * from './app/events/EventWorkerContext';

packages/commandkit/src/utils/error-codes.ts

@@ -18,6 +18,10 @@ export const CommandKitErrorCodes = {
    * Error code for plugin capture handle.
    */
   PluginCaptureHandle: Symbol('kPluginCaptureHandle'),
+  /**
+   * Error code for event interruption signal
+   */
+  StopEvents: Symbol('kStopEvents'),
 } as const;
 
 /**

packages/commandkit/src/utils/utilities.ts

@@ -166,37 +166,6 @@ 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. This function should be called inside an event handler
- * to prevent further event handling.
- * @throws {StopEventPropagationError}
- * @example // src/app/events/messageCreate/handler.ts
- * import { stopEvents } from 'commandkit';
- *
- * export default async function messageCreateHandler() {
- *   console.log('Message created');
- *   // Stop further event propagation
- *   stopEvents();
- * }
- */
-export function stopEvents(): never {
-  if (!eventWorkerContext.getStore()) {
-    throw new Error('stopEvents() may only be called inside an event handler');
-  }
-
-  throw new StopEventPropagationError();
-}
-
 /**
  * Represents a simple proxy object that mirrors a target object.
  */