chore(message-bus): improve docs and fix lint issues

Signed-off-by: Saulo Vallory <me@saulo.engineer>

Author: svallory

packages/message-bus/README.md

@@ -1,3 +1,7 @@
-# browser-package
+# Figma Message Bus
 
-A browser package with ECMAScript support, written in TypeScript `.ts` files.
+A TypeScript package providing a robust, type-safe message bus for communication between the Figma plugin main thread and its UI context. It simplifies event handling and command execution across contexts, including support for standard Figma API events and custom events/commands.
+
+Includes utilities for serializing/deserializing complex data types (like `Map`) across the communication channel.
+
+Built with TypeScript for strong typing and ECMAScript support.

packages/message-bus/src/MessageBus.ts

@@ -1,6 +1,8 @@
 import type { CommandRegistry } from './commands';
 import {
+  type ArgFreeEventType,
   type EventRegistry,
+  FigmaEvent,
   type FigmaEventDefinition,
   type FigmaEventRegistry,
   isFigmaEvent,
@@ -10,7 +12,8 @@ import type { CommandHandlers, DeregisterFn, EventListeners } from './types';
 import { JsonReviver, serializeForMessageBus } from './utils';
 
 /**
- * A simple message bus implementation which magically works in both the main thread and the plugin UI.
+ * A simple message bus implementation facilitating communication between
+ * the main thread and the plugin UI.
  * No need to worry about sending messages in the right direction.
  *
  * @remarks
@@ -24,13 +27,22 @@ import { JsonReviver, serializeForMessageBus } from './utils';
 export class MessageBusSingleton<TCommands = unknown, TEvents = unknown> {
   private static instance?: MessageBusSingleton<unknown, unknown>;
 
+  /** Internal storage for registered command handlers. */
   protected $handlers: Partial<CommandHandlers<TCommands>> = {};
 
+  /** Internal storage for registered event listeners. */
   protected $listeners: Partial<EventListeners<TEvents>> = {};
 
+  // Prevent external instantiation
   // eslint-disable-next-line @typescript-eslint/no-empty-function
   private constructor() {}
 
+  /**
+   * Retrieves the singleton instance of the MessageBus.
+   * @template T - The type definition for commands the bus will handle.
+   * @template E - The type definition for events the bus will handle.
+   * @returns The singleton instance of MessageBusSingleton.
+   */
   public static getInstance<T = unknown, E = unknown>(): MessageBusSingleton<
     T,
     E
@@ -41,6 +53,13 @@ export class MessageBusSingleton<TCommands = unknown, TEvents = unknown> {
     return MessageBusSingleton.instance as MessageBusSingleton<T, E>;
   }
 
+  /**
+   * Registers a handler function for a specific command.
+   * @template Id - The ID of the command to handle.
+   * @param command The command ID.
+   * @param handler The function to execute when the command is received.
+   * @returns A function to deregister the handler.
+   */
   public handleCommand<Id extends keyof CommandHandlers<TCommands>>(
     command: Id,
     handler: CommandHandlers<TCommands>[Id],
@@ -57,6 +76,13 @@ export class MessageBusSingleton<TCommands = unknown, TEvents = unknown> {
     });
   }
 
+  /**
+   * Sends a command to the appropriate context (main thread or UI).
+   * @template Id - The ID of the command to send.
+   * @param command The command ID.
+   * @param data The payload for the command.
+   * @returns The result of the command execution (currently always returns `undefined` as execution is asynchronous).
+   */
   public sendCommand<Id extends keyof CommandRegistry<TCommands>>(
     command: Id,
     data: CommandRegistry<TCommands>[Id]['message'],
@@ -68,77 +94,143 @@ export class MessageBusSingleton<TCommands = unknown, TEvents = unknown> {
     return undefined;
   }
 
+  /**
+   * Registers a listener function for a specific event.
+   * This handles both custom events and standard Figma events.
+   * @template Id - The ID of the event to listen to.
+   * @param event The event ID.
+   * @param listener The function to execute when the event is published.
+   * @returns A function to deregister the listener.
+   */
   public listenToEvent<Id extends keyof EventListeners<TEvents>>(
     event: Id,
     listener: EventListeners<TEvents>[Id],
   ): DeregisterFn {
     this.$listeners[event] = listener as Partial<EventListeners<TEvents>>[Id];
 
-    if (isFigmaEvent(event as string)) {
-      // Only attempt to use Figma API if the global `figma` object exists
+    const eventString = String(event);
+
+    if (isFigmaEvent(eventString)) {
       if (typeof figma !== 'undefined') {
-        figma.on(
-          event as ArgFreeEventType,
-          listener as (...args: unknown[]) => void,
-        );
+        const typedListener = listener as (...args: any[]) => any;
+
+        // Use the string value for the switch and figma.on/off calls
+        switch (eventString) {
+          case FigmaEvent.SelectionChanged:
+          case FigmaEvent.CurrentPageChanged:
+          case FigmaEvent.OnClose:
+          case FigmaEvent.TimerStarted:
+          case FigmaEvent.TimerPaused:
+          case FigmaEvent.TimerStopped:
+          case FigmaEvent.TimerDone:
+          case FigmaEvent.TimerResume:
+          case FigmaEvent.TimerAdjust:
+            figma.on(
+              eventString as ArgFreeEventType,
+              typedListener as () => void,
+            );
+            break;
+          case FigmaEvent.DocumentChanged:
+            figma.on(
+              'documentchange',
+              typedListener as (evt: DocumentChangeEvent) => void,
+            );
+            break;
+          case FigmaEvent.OnDrop:
+            figma.on('drop', typedListener as (evt: DropEvent) => boolean);
+            break;
+          case FigmaEvent.OnRun:
+            figma.on('run', typedListener as (evt: RunEvent) => void);
+            break;
+        }
+
         return (): void => {
-          // Also check before using figma.off
           if (typeof figma !== 'undefined') {
-            figma.off(
-              event as ArgFreeEventType,
-              listener as (...args: unknown[]) => void,
-            );
+            switch (eventString) {
+              case FigmaEvent.SelectionChanged:
+              case FigmaEvent.CurrentPageChanged:
+              case FigmaEvent.OnClose:
+              case FigmaEvent.TimerStarted:
+              case FigmaEvent.TimerPaused:
+              case FigmaEvent.TimerStopped:
+              case FigmaEvent.TimerDone:
+              case FigmaEvent.TimerResume:
+              case FigmaEvent.TimerAdjust:
+                figma.off(
+                  eventString as ArgFreeEventType,
+                  typedListener as () => void,
+                );
+                break;
+              case FigmaEvent.DocumentChanged:
+                figma.off(
+                  'documentchange',
+                  typedListener as (evt: DocumentChangeEvent) => void,
+                );
+                break;
+              case FigmaEvent.OnDrop:
+                figma.off('drop', typedListener as (evt: DropEvent) => boolean);
+                break;
+              case FigmaEvent.OnRun:
+                figma.off('run', typedListener as (evt: RunEvent) => void);
+                break;
+            }
           }
         };
       }
 
-      // If figma is not defined, warn and return a no-op deregister function
-      // This code is only reached if `typeof figma === 'undefined'`
+      // Handle case where Figma API is not available but a Figma event is listened to
       console.warn(
-        `Attempted to listen to Figma event '${String(
-          event,
-        )}' in a non-Figma environment.`,
+        `Attempted to listen to Figma event '${eventString}' in a non-Figma environment.`,
       );
-      return () => {}; // Return a no-op function
+      // Return a no-op deregister function
+      return () => {};
     }
 
-    return evtHandler.on(String(event), (data: unknown) => {
-      // Parse received data through JSON to reconstruct Map objects
+    // Handle custom events using the internal event handler system
+    return evtHandler.on(eventString, (data: unknown) => {
       const parsedData =
         typeof data === 'string' ? JSON.parse(data, JsonReviver) : data;
-
       listener(parsedData as EventRegistry<TEvents>[Id]['message']);
     });
   }
 
+  /**
+   * Publishes an event to the appropriate context (main thread or UI).
+   * This handles both custom events and standard Figma events.
+   * @template Id - The ID of the event to publish.
+   * @param event The event ID.
+   * @param data The payload for the event.
+   */
   public publishEvent<
     Id extends keyof EventRegistry<TEvents> | keyof FigmaEventRegistry,
   >(
     event: Id,
     data: Id extends keyof EventRegistry<TEvents>
       ? EventRegistry<TEvents>[Id]['message']
       : Id extends keyof FigmaEventRegistry
-        ? FigmaEventRegistry[Id] extends FigmaEventDefinition<infer T, infer U>
+        ? FigmaEventRegistry[Id] extends FigmaEventDefinition<infer _T, infer U>
           ? U
           : never
         : never,
   ): void {
-    // Serialize data to handle Maps and complex objects
     const serializedData = serializeForMessageBus(data);
-
     evtHandler.emit(String(event), serializedData);
   }
 }
 
+/** The singleton instance of the MessageBus. */
 const singleton = MessageBusSingleton.getInstance();
 
 // ensure the API is never changed
-// -------------------------------
 Object.freeze(singleton);
 
-// export the singleton instance only
-// -----------------------------
-
+/**
+ * Retrieves the singleton instance of the MessageBus, typed for specific command and event registries.
+ * This is the preferred way to access the MessageBus.
+ * @template TCmdRegistry - The type definition for the command registry.
+ * @template TEvtRegistry - The type definition for the event registry.
+ * @returns The singleton `MessageBusSingleton` instance, properly typed.
+ */
 export function getMessageBus<
   TCmdRegistry = unknown,
   TEvtRegistry = unknown,

packages/message-bus/src/ambient.d.ts

@@ -1,7 +1,14 @@
 import '@figma/plugin-typings';
 
+/**
+ * Extends the global scope with custom properties.
+ */
 declare global {
+  /**
+   * Represents the global object, extended with a `TESTING` flag.
+   */
   var global: typeof globalThis & {
+    /** Optional flag to indicate if the environment is running in test mode. */
     TESTING: boolean | undefined;
   };
 }

packages/message-bus/src/commands.ts

@@ -1,15 +1,32 @@
+/**
+ * Defines the structure for a command within the message bus system.
+ * @template Id - A unique string identifier for the command.
+ * @template Message - The type of the message payload associated with the command (defaults to undefined).
+ * @template Result - The type of the result expected after executing the command (defaults to void).
+ */
 export interface CommandDefinition<
   Id extends string,
   Message = undefined,
   Result = void,
 > {
+  /** The unique identifier for the command. */
   $id: Id;
+  /** Indicates the type of this definition (always 'command'). */
   $type: 'command';
+  /** The type of the message payload for this command. */
   message: Message;
+  /** The type of the result returned by this command's handler. */
   result: Result;
 }
 
+/**
+ * Represents a registry mapping command IDs to their definitions.
+ * @template TCommandMessageMap - An object type where keys are command IDs (strings)
+ *                                and values are the corresponding message payloads.
+ */
 export type CommandRegistry<TCommandMessageMap> = {
+  // Maps each key K from TCommandMessageMap to a CommandDefinition.
+  // Ensures that the key K is a string.
   [K in keyof TCommandMessageMap]: K extends string
     ? CommandDefinition<K, TCommandMessageMap[K]>
     : never;