@adcops/autocore-react 3.0.40 → 3.3.2

package/src/core/EventEmitterContext.tsx

@@ -2,45 +2,84 @@
  * Copyright (C) 2024 Automated Design Corp. All Rights Reserved.
  * Created Date: 2024-01-17 11:45:10
  * -----
- * Last Modified: 2025-08-30 06:54:17
+ * Last Modified: 2026-01-29 09:32:29
  * Modified By: ADC
  * -----
  *
  */
 
+/**
+ * @fileoverview EventEmitterContext - Global Event Bus for AutoCore React Applications
+ * 
+ * The EventEmitterContext provides a comprehensive event-driven communication system for React applications,
+ * enabling seamless interaction between components and backend services. It serves as the foundational layer
+ * for AutoCore's real-time data flow and component communication architecture.
+ * 
+ * ## Core Features
+ * 
+ * - **Global Event Bus**: Publish and subscribe to events across all components.
+ * - **Backend Integration**: Direct communication with AutoCore server via Hub abstraction.
+ * - **Type-Safe Subscriptions**: Strongly-typed event handling with automatic cleanup.
+ * - **Performance Optimized**: Uses stable context values and direct callbacks to avoid global re-renders.
+ * - **Connection Management**: Automatic reconnection and state synchronization.
+ * 
+ * ## Architecture
+ * 
+ * The system consists of three main components:
+ * 1. **EventEmitterProvider**: React context provider that manages global state and event routing.
+ * 2. **Hub**: Abstraction layer for backend communication (WebSocket, HTTP, etc.).
+ * 3. **Subscription Manager**: Handles event routing and lifecycle management.
+ *
+ * ## Performance Notes
+ * 
+ * To ensure high performance with high-frequency data (e.g., 50Hz sensor updates):
+ * 1. **No State Updates on Dispatch**: The `dispatch` function does NOT update React state. It calls listeners directly.
+ *    This prevents the entire component tree from re-rendering on every message.
+ * 2. **Stable Context Value**: The `contextValue` object is memoized and rarely changes.
+ * 3. **Direct Subscriptions**: Components subscribe via `useEffect` and receive updates via callbacks, not props.
+ * 
+ * @module core/EventEmitterContext
+ * @version 3.0.42
+ * @author Automated Design Corp.
+ */
+
 import React, {
   createContext,
-  ReactNode,
   useState,
   useMemo,
   useCallback,
   useRef,
   useEffect,
 } from "react";
+
+import type {ReactNode} from "react";
 import { createHub, Hub } from "../hub";
-import { CommandMessageResult } from "../hub/CommandMessage";
+import type { CommandMessage } from "../hub";
+import { MessageType } from "../hub/CommandMessage";
 
 export { Hub };
 
 /**
- * Represents an event subsription.
+ * Represents an active event subscription.
  */
 export interface Subscription {
-  /** ID of the subscription used for unsubscription. */
+  /** Unique ID of the subscription used for unsubscription. */
   id: number;
-  /** Callback function. */
+  /** Callback function to execute when the event fires. */
   callback: React.Dispatch<any>;
 }
 
 /**
- * Represents the payload data associated with an event.
+ * Represents the internal state of the EventEmitter.
+ * Mostly used for debugging and dev tools inspection.
  */
 export interface State {
   /**
-   * The optional data payload of the event.
+   * The optional data payload of the last event (DEBUGGING ONLY).
+   * Note: This is no longer updated in production for performance reasons.
    */
   eventData?: any;
-  /** Callback subscription. A list of callback subscriptions matched to a topic. */
+  /** Active subscriptions grouped by topic. */
   subscriptions: Record<string, Subscription[]>;
 
   /** Tracks the next subscription ID that will be assigned. */
@@ -48,261 +87,152 @@ export interface State {
 }
 
 /**
- * An action event published by the EventEmitterContext. Contains
- * the topic identifying the event and the optional payload, which is
- * a value of any type.
+ * An action event published by the EventEmitterContext.
  */
 export interface Action {
-  /**
-   * The topic or identifier of the event.
-   */
+  /** The topic or identifier of the event. */
   topic: string;
-
-  /**
-   * The optional data payload associated with the event.
-   */
+  /** The optional data payload associated with the event. */
   payload?: any;
 }
 
-/**
- * Type declaration for the EventEmitter dispatch function, which
- * publishes an Action globally throughout the EventEmitterContext.
- */
 export type EmitterDispatchFunction = (action: Action) => void;
 
 /**
- * Type declaration for the EventEmitter dispatch function, which
- * receives an Action on a specific topic broadcast through the EventEmitterContext.
- */
-export type EmitterSubscribeFunction = (action: Action) => void;
-
-/**
- * Type declaration for the EventEmitter unsubscribe function, which
- * receives an Action on a specific topic broadcast through the EventEmitterContext.
- */
-export type EmitterUnsubscribeFunction = (action: Action) => void;
-
-/**
- * Defines the context for an event emitter used throughout a front-end application to manage and dispatch events.
- * This interface includes methods for managing the application's state, handling global actions, communicating with the back end,
- * subscribing to and unsubscribing from events, and accessing a global hub for event publishing and subscription management.
- * It serves as a central point for event-driven interactions within the application, facilitating communication between
- * components and the back end, as well as among components themselves.
+ * Defines the context for the global event emitter.
+ * Provides methods for dispatching events, subscribing to topics, and communicating with the backend.
  */
 export interface EventEmitterContextType {
   /**
-   * The current state of the event emitter, containing the latest event data.
+   * The current state of the event emitter (mostly for debugging).
    */
   state: State;
 
   /**
-   * A function to dispatch actions globally throughout the front-end,
-   * triggering state updates and events.
-   *
-   * @param action The action to dispatch, containing topic and optional payload.
+   * Dispatch an action globally throughout the front-end.
+   * Triggers callbacks for all subscribers of the topic.
+   * 
+   * @param action The action to dispatch.
    */
-  dispatch: (action: Action) => void;
+  dispatch: EmitterDispatchFunction;
 
   /**
-   * Invoke/send a message to the back end.
-   * This does NOT get published to the front end.
+   * Send a message to the backend (Low-level).
+   * 
+   * @param topic The FQDN of the resource (e.g., "ads.plc1.gio.bControlPowerOk")
+   * @param messageType The action to perform (Read, Write, Subscribe, etc.)
+   * @param payload Optional data payload
+   * @returns Promise resolving to the CommandMessage response
    */
   invoke(
-    domain: string,
-    fname: string,
+    topic: string,
+    messageType: MessageType,
     payload?: object
-  ): Promise<CommandMessageResult>;
+  ): Promise<CommandMessage>;
 
   /**
-   * Subscribe to events identified by the topic.
-   * @param topic The subscription topic.
+   * Read a value from the backend.
+   *
+   * @param topic The FQDN of the resource to read
+   * @param payload Optional additional parameters
+   * @returns Promise resolving to the CommandMessage response with the value in `data`
+   */
+  read(topic: string, payload?: object): Promise<CommandMessage>;
+
+  /**
+   * Write a value to the backend.
+   *
+   * @param topic The FQDN of the resource to write
+   * @param value The value to write
+   * @returns Promise resolving to the CommandMessage response
+   */
+  write(topic: string, value: any): Promise<CommandMessage>;
+
+  /**
+   * Subscribe to value changes on the backend.
+   *
+   * Tells the server to start broadcasting updates for a specific topic.
+   * Also registers a mapping between the local `tagName` and the remote `topic` (FQDN)
+   * in the Hub, so that incoming broadcasts are routed correctly.
+   *
+   * @param tagName The local tag name to map the topic to
+   * @param topic The FQDN of the resource to watch
+   * @param payload Optional subscription parameters (e.g., update rate)
+   * @returns Promise resolving to the CommandMessage response
+   */
+  serverSubscribe(tagName: string, topic: string, payload?: object): Promise<CommandMessage>;
+
+  /**
+   * Unsubscribe from value changes on the backend.
+   *
+   * @param tagName The local tag name to stop watching
+   * @param payload Optional parameters
+   * @returns Promise resolving to the CommandMessage response
+   */
+  serverUnsubscribe(tagName: string, payload?: object): Promise<CommandMessage>;
+
+  /**
+   * Subscribe to **local** frontend events.
+   * 
+   * This registers a callback to listen for events dispatched on the local event bus.
+   * This includes both locally dispatched events AND broadcast messages received
+   * from the server (which the Hub dispatches to the local bus).
+   *
+   * @param topic The subscription topic (or tagName).
    * @param callback The callback to signal.
    * @returns number Subscription ID used to unsubscribe later.
    */
   subscribe: (topic: string, callback: React.Dispatch<any>) => number;
 
   /**
-   * Unsubscribe to events.
-   * @param subscriptionId The id of the subscription returned by the subscribe method.
-   * @returns
+   * Unsubscribe from **local** frontend events.
+   *
+   * @param subscriptionId The id returned by the subscribe method.
    */
   unsubscribe: (subscriptionId: number) => void;
 
   /**
-   * Global hub for publishing and receiving events throughout the interface, and for exchanging
-   * data with the backend.
+   * Global hub instance for backend communication.
    */
   hub: Hub | null;
 
   /**
    * Retrieves the current subscriptions. Used for debugging purposes.
-   * @param topic Optional. The topic to retrieve subscriptions for. If omitted, returns all subscriptions.
-   * @returns An object containing the current subscriptions, optionally filtered by topic.
    */
   getSubscriptions: (
     topic?: string
   ) => Record<string, Subscription[]> | Subscription[];
 
   /**
-   * Returns true if the Hub in use is connected to its source.
-   * @returns boolean
+   * Returns true if the Hub is connected to the backend.
    */
   isConnected: () => boolean;
 }
 
-let globalSubscriptionId = 1;
+// Default placeholder CommandMessage for context initialization
+const placeholderResponse: CommandMessage = {
+  data: {},
+  success: false,
+  error_message: "Context not initialized",
+  transaction_id: 0,
+  timecode: 0,
+  topic: "",
+  message_type: MessageType.NoOp
+};
 
-/**
- * A global context for managing event emission and subscription.
- *
- * Creates a React context for the EventEmitter system, providing a structured way to manage events and data flow
- * in a React application. It serves as a global event bus that components can subscribe to or emit events, allowing for
- * a loosely coupled architecture. Additionally, it provides a mechanism for invoking backend functions and managing
- * subscriptions, making it easier to integrate React components with backend services.
- *
- * The context includes several key functionalities:
- * - `state`: Maintains the current state of subscriptions and their identifiers.
- * - `dispatch`: Allows components to emit events with specific topics and payloads, which can be listened to by other components.
- * - `subscribe`: Enables components to listen to specific topics and react to those events by providing a callback function.
- * - `unsubscribe`: Provides a way for components to stop listening to events, helping prevent memory leaks and unnecessary updates.
- * - `invoke`: Facilitates calling backend functions with specific arguments and handling their responses asynchronously.
- * - `getSubscriptions`: Offers insight into current active subscriptions, useful for debugging purposes.
- *
- * This context is essential for applications that require a high degree of inter-component communication or need to
- * interact with a backend efficiently.
- *
- * For more information, see [Additional Documentation](../additional-docs/GlobalEventEmitter.md).
- *
- * ## Usage
- *
- * The entire application should be wrapped in the EventEmitterProvider.
- *
- * App.tsx
- * ```
- * import { EventEmitterProvider } from "@adcops/autocore-react/core/EventEmitterContext.js";
- * function App() {
- *
- *      return(
- *          <EventEmitterProvider>
- *              <PrimeReactProvider>
- *                  <main>
- *                      <section>
- *                          <ContentView />
- *                      </section>
- *                  </main>
- *              </PrimeReactProvider>
- *          </EventEmitterProvider>
- *      );
- *
- * }
- *
- * ```
- *
- * ### Catching and receiving events
- * The EventEmitterContext creates an appropriate instance of the hub, which is derived from HubBase.
- * That hub can be used to publish and subscribe to
- * topics globally in the front-end, regardless of being connected to any backend.
- * Usage within a component is simple.
- *
- * ```
- * const {dispatch, subscribe, unsubscribe} = useContext(EventEmitterContext);
- * const [controlPower, setControlPower] = useState(false);
- * useEffect(() => {
- *      const unsubscribeControlPower = subscribe('value-simulator-bBit1', (value) => {
- *          setControlPower(value);
- *      });
- *
- *
- *      return () => {
- *           unsubscribe(unsubscribeControlPower);
- *      }
- * }, [] );
- *
- * const onPbPressed = () => {
- *      let count = 1;
- *      dispatch({
- *          topic: "my-awesome-topic",
- *          payload: count
- *      });
- * }
- *
- * ```
- * The hub should also be used for invoking events in the backend.
- * This example will call the function "update_count" in the backend, passing
- * the expected argument "count". Details of the interaction between the Hub and
- * the backend will be handled by the appropriate HubBase sub-class, and should
- * be transparent to the front end.
- *
- * ```
- * const {invoke} = useContext(EventEmitterContext);
- * const incrementCount = () => {
- *    count += 1;
- *    invoke('update_count', {"count": count});
- * };
- *
- * Subscribing to a topic is simple. The type of value received is specific
- * to the topic.
- *
- * Example: Listen to an event 'xarm-position':
- * ```
- * const {subscribe, unsubscribe} = useContext(EventEmitterContext);
- * useEffect(() => {
- *         const unsubscripeMp = subscribe('xarm-position', (value) => {
- *            // The publisher sent a JSON object of 3D position values.
- *            setX(value.x);
- *            setY(value.y);
- *            setZ(value.z);
- *            setA(value.roll);
- *            setB(value.yaw);
- *            setC(value.pitch);
- *        });
- *
- *    return () => {
- *        unsubscribe(unsubscripeMp);
- *    }
- *
- * }, [] );
- *
- * ```
- *
- * For applications that need to access the instance of the hub, get the current instance
- * from the EventEmitterContext:
- *
- * ```
- * const {hub} = useContext(EventEmitterContext);
- *  * ```
- *
- *
- */
 export const EventEmitterContext = createContext<EventEmitterContextType>({
   state: { subscriptions: {}, nextSubscriptionId: 1 },
   dispatch: () => {},
-  subscribe: () => {
-    return 0;
-  }, // Placeholder for subscription logic
-  invoke: async (domain: string, fname: string, payload?: object) => {
-    domain;
-    fname;
-    payload;
-    let ret: CommandMessageResult = {
-      data: {},
-      success: false,
-      error_message: "",
-    };
-    // Placeholder for invoke logic
-    // Implement the logic to send a message to the backend and return a promise
-    return Promise.resolve(ret); // Example placeholder, replace with actual implementation
-  },
-  unsubscribe: (subscriptionId: number) => {
-    subscriptionId;
-  }, // Placeholder for unsubscription logic
+  subscribe: () => 0,
+  unsubscribe: () => {},
+  invoke: async () => placeholderResponse,
+  read: async () => placeholderResponse,
+  write: async () => placeholderResponse,
+  serverSubscribe: async (_tagName: string, _topic: string, _payload?: object) => placeholderResponse,
+  serverUnsubscribe: async (_tagName: string, _payload?: object) => placeholderResponse,
   hub: null,
-  getSubscriptions: () => {
-    return [];
-  },
-  isConnected: () => {
-    return false;
-  },
+  getSubscriptions: () => [],
+  isConnected: () => false,
 });
 
 /**
@@ -312,56 +242,53 @@ export const EventEmitterContext = createContext<EventEmitterContextType>({
  * with the event emitter.
  *
  * @param children The child components to be wrapped in the context.
- *
- * ## Usage
- *
- * The entire application should be wrapped in the EventEmitterProvider.
- *
- * App.tsx
- * ```
- * import { EventEmitterProvider } from "@adcops/autocore-react/core/EventEmitterContext.js";
- * function App() {
- *
- *      return(
- *          <EventEmitterProvider>
- *              <PrimeReactProvider>
- *                  <main>
- *                      <section>
- *                          <ContentView />
- *                      </section>
- *                  </main>
- *              </PrimeReactProvider>
- *          </EventEmitterProvider>
- *      );
- *
- * }
- *
- * ```
  */
 export const EventEmitterProvider: React.FC<{ children: ReactNode }> = ({
   children,
 }) => {
+  console.log("[EventEmitterProvider] Rendering...");
+
   const [state, setState] = useState<State>({
     subscriptions: {},
     nextSubscriptionId: 1,
   });
 
-  // Memoize the hub instance so it's only created once
-  const hub = useMemo(() => createHub(), []);
+  // PERFORMANCE: Memoize the hub instance so it's only created once.
+  // This ensures the WebSocket connection persists across re-renders.
+  const hub = useMemo(() => {
+    console.log("[EventEmitterProvider] Creating Hub instance");
+    return createHub();
+  }, []);
+
+  // Use ref for subscription ID management (avoids global state issues)
+  const nextIdRef = useRef(1);
 
-  // <-- New: the source of truth for subscriptions lives in a ref
+  // Subscription storage - this is the single source of truth for local listeners
   const subsRef = useRef<Record<string, Subscription[]>>({});
 
-  // Keep the ref in sync for debugging / external reads
+  // Sync state with ref for debugging/inspection purposes only (on mount)
   useEffect(() => {
-    subsRef.current = state.subscriptions;
-  }, [state.subscriptions]);
+    setState(prev => ({
+      ...prev,
+      subscriptions: { ...subsRef.current },
+      nextSubscriptionId: nextIdRef.current
+    }));
+  }, []);
 
+  /**
+   * Dispatches an event to all listeners.
+   * 
+   * PERFORMANCE CRITICAL: This function iterates through listeners and calls them directly.
+   * It intentionally does NOT update React state (setState) to avoid triggering a 
+   * full app re-render on every high-frequency event.
+   */
   const dispatch = useCallback((action: Action) => {
     const { topic, payload } = action;
 
-    // Read once, outside setState, so it can't be double-invoked by StrictMode
+    // Read from ref (single source of truth) and create a defensive copy
     const listeners = subsRef.current[topic]?.slice() ?? [];
+    
+    // Execute callbacks synchronously to avoid timing issues
     for (const sub of listeners) {
       try {
         sub.callback(payload);
@@ -370,24 +297,32 @@ export const EventEmitterProvider: React.FC<{ children: ReactNode }> = ({
       }
     }
 
-    // Optional: keep last payload in state (pure)
-    setState((prev) => ({ ...prev, eventData: payload }));
+    // NOTE: State update removed for performance. 
+    // Uncommenting this will cause the entire Provider to re-render on every event!
+    // setState((prev) => ({ ...prev, eventData: payload }));
   }, []);
 
   const subscribe = useCallback(
     (topic: string, callback: React.Dispatch<any>): number => {
-      const id = ++globalSubscriptionId;
-
-      // Mutate ref
-      const prev = subsRef.current[topic] ?? [];
-      const next = [...prev, { id, callback }];
-      subsRef.current[topic] = next;
-
-      // Reflect in state (for debugging/inspection)
-      setState((prevState) => ({
+      const id = nextIdRef.current++;
+      
+      // Create new subscription entry
+      const newSub: Subscription = { id, callback };
+      
+      // Atomically update the ref with a complete new structure
+      const currentSubs = subsRef.current[topic] ?? [];
+      const newSubs = [...currentSubs, newSub];
+      
+      subsRef.current = {
+        ...subsRef.current,
+        [topic]: newSubs
+      };
+
+      // Update state for debugging/inspection (less frequent than dispatch, so acceptable)
+      setState(prevState => ({
         ...prevState,
-        subscriptions: { ...prevState.subscriptions, [topic]: next },
-        nextSubscriptionId: globalSubscriptionId + 1,
+        subscriptions: { ...subsRef.current },
+        nextSubscriptionId: nextIdRef.current,
       }));
 
       return id;
@@ -396,57 +331,98 @@ export const EventEmitterProvider: React.FC<{ children: ReactNode }> = ({
   );
 
   const unsubscribe = useCallback((subscriptionId: number) => {
-    const map = subsRef.current;
-    for (const t of Object.keys(map)) {
-      const next = map[t].filter((s) => s.id !== subscriptionId);
-      if (next.length) map[t] = next;
-      else delete map[t];
+    // Create a completely new structure to avoid mutation issues
+    const newSubscriptions: Record<string, Subscription[]> = {};
+    
+    for (const [topic, subs] of Object.entries(subsRef.current)) {
+      const filteredSubs = subs.filter(s => s.id !== subscriptionId);
+      if (filteredSubs.length > 0) {
+        newSubscriptions[topic] = filteredSubs;
+      }
     }
+    
+    // Atomically replace the entire structure
+    subsRef.current = newSubscriptions;
+
+    // Update state for debugging/inspection
+    setState(prev => ({ 
+      ...prev, 
+      subscriptions: { ...newSubscriptions }
+    }));
+  }, []);
 
-    setState((prev) => ({ ...prev, subscriptions: { ...map } }));
+  // Clean up on unmount
+  useEffect(() => {
+    return () => {
+      subsRef.current = {};
+      nextIdRef.current = 1;
+    };
   }, []);
 
-  // (Nice-to-have) Handle HMR so listeners don’t leak across hot updates
+  // Handle HMR so listeners don't leak across hot updates
   if (import.meta && (import.meta as any).hot) {
     (import.meta as any).hot.dispose(() => {
       subsRef.current = {};
+      nextIdRef.current = 1;
     });
   }
 
-//   const getSubscriptions = useCallback(
-//     (topic?: string): Record<string, Subscription[]> | Subscription[] => {
-//       if (topic) {
-//         // Return subscriptions for the provided topic, or an empty array if the topic doesn't exist
-//         return state.subscriptions[topic] || [];
-//       } else {
-//         // Return all subscriptions
-//         return state.subscriptions;
-//       }
-//     },
-//     []
-//   );
-
-  // Provide the memoized hub instance in the context value
+  // Memoize hub methods separately so they don't change when state changes.
+  // This prevents downstream useEffects from re-running due to function reference changes.
+  const invoke = useCallback(
+    (topic: string, messageType: MessageType, payload?: object) => hub.invoke(topic, messageType, payload),
+    [hub]
+  );
+  const read = useCallback(
+    (topic: string, payload?: object) => hub.read(topic, payload),
+    [hub]
+  );
+  const write = useCallback(
+    (topic: string, value: any) => hub.write(topic, value),
+    [hub]
+  );
+  const serverSubscribe = useCallback(
+    (tagName: string, topic: string, payload?: object) => hub.subscribe(tagName, topic, payload),
+    [hub]
+  );
+  const serverUnsubscribe = useCallback(
+    (tagName: string, payload?: object) => hub.unsubscribe(tagName, payload),
+    [hub]
+  );
+  const isConnected = useCallback(() => hub.isConnected(), [hub]);
+
+  // Provide the memoized context value
+  // PERFORMANCE: This object is memoized and its dependencies (dispatch, subscribe, etc.)
+  // are also memoized/stable. This means 'contextValue' reference rarely changes,
+  // preventing consumers (like App) from re-rendering unless necessary.
   const contextValue = useMemo(
     () => ({
       state,
       dispatch,
       subscribe,
       unsubscribe,
-      invoke: hub.invoke,
+      invoke,
+      read,
+      write,
+      serverSubscribe,
+      serverUnsubscribe,
       hub,
       getSubscriptions: (topic?: string) =>
         topic ? subsRef.current[topic] ?? [] : subsRef.current,
-      isConnected: hub.isConnected,
+      isConnected,
     }),
-    [state, hub, dispatch, subscribe, unsubscribe]
+    [state, hub, dispatch, subscribe, unsubscribe, invoke, read, write, serverSubscribe, serverUnsubscribe, isConnected]
   );
 
-  hub.setContext(contextValue);
+  // Set the context on the hub instance so it can dispatch back to us.
+  // Must be in useEffect to avoid side-effects during render phase.
+  useEffect(() => {
+    hub.setContext(contextValue);
+  }, [hub, contextValue]);
 
   return (
     <EventEmitterContext.Provider value={contextValue}>
       {children}
     </EventEmitterContext.Provider>
   );
-};
+};