@adcops/autocore-react 3.3.9 → 3.3.10

package/src/hub/HubBase.ts

@@ -1,237 +1,250 @@
-/*
- * Copyright (C) 2023 Automated Design Corp. All Rights Reserved.
- * Created Date: 2023-12-15 14:21:33
- * Author: Thomas C. Bitsky Jr.
- * -----
- * Last Modified: 2026-01-29 09:34:10
- * Modified By: ADC
- * -----
- *
- */
-
-import type { EventEmitterContextType } from '../core/EventEmitterContext';
-import type { CommandMessage } from "./CommandMessage";
-import { MessageType } from "./CommandMessage";
-
-
-/**
- * @class HubBase
- * @abstract
- * 
- * Abstract base class that defines the interface for communicating with the AutoCore backend.
- * Implementations (like `HubWebSocket` or `HubTauri`) handle the specific transport mechanics.
- * 
- * ## Core Responsibilities
- * 
- * 1. **Transport Abstraction**: Provides a unified API (`read`, `write`, `subscribe`) regardless of 
- *    underlying transport (WS, IPC, etc.).
- * 2. **Topic Mapping**: Maintains a bidirectional mapping between local `tagName` (UI friendly) 
- *    and backend `FQDN` (Fully Qualified Domain Name).
- *    - `tagName`: "motorsEnable"
- *    - `FQDN`: "ADS.Main.bMotorsEnable"
- * 3. **Event Dispatching**: Routes incoming messages from the backend to the `EventEmitterContext`.
- * 
- * ## Usage
- * 
- * The `Hub` is typically accessed via the `EventEmitterContext`:
- * 
- * ```typescript
- * const { hub } = useContext(EventEmitterContext);
- * await hub.write("ADS.Main.nSpeed", 500);
- * ```
- */
-export abstract class HubBase {
-
-    /** Maps local tag names to backend FQDNs. */
-    protected localTopicToBackendTopicMap: Map<string, string> = new Map<string, string>();
-    
-    /** Maps backend FQDNs to local tag names. */
-    protected backendTopicToLocalMap: Map<string, string> = new Map<string, string>();
-
-    /** Reference to the global event emitter for dispatching incoming messages. */
-    protected context: EventEmitterContextType | null = null;
-
-    /** Connection state tracker. */
-    protected isConnected_: boolean = false;
-
-
-    /**
-     * Constructor
-     */
-    constructor() {
-    }
-
-
-    /**
-     * Links this Hub instance with the React application's Event Context.
-     * 
-     * This connection allows the Hub to "push" messages into the React app by calling `context.dispatch()`.
-     * This is called automatically by `EventEmitterProvider` on initialization.
-     * 
-     * @param context The React context instance.
-     */
-    setContext(context: EventEmitterContextType | null) {
-        this.context = context;
-    }
-
-    // =========================================================================
-    // Abstract Methods - Must be implemented by subclasses
-    // =========================================================================
-
-    /**
-     * Sends a raw command message to the backend.
-     * 
-     * @param topic The resource identifier (FQDN).
-     * @param messageType The operation to perform (Read, Write, etc.).
-     * @param payload The data payload.
-     * @returns A Promise that resolves with the server's response.
-     */
-    abstract invoke(topic: string, messageType: MessageType, payload?: object): Promise<CommandMessage>;
-
-    // =========================================================================
-    // Convenience Helper Methods
-    // =========================================================================
-
-    /**
-     * Request the current value of a resource.
-     * 
-     * @param topic FQDN of the resource.
-     */
-    read(topic: string, payload?: object): Promise<CommandMessage> {
-        return this.invoke(topic, MessageType.Read, payload);
-    }
-
-    /**
-     * Write a new value to a resource.
-     * 
-     * @param topic FQDN of the resource.
-     * @param value The value to write.
-     */
-    write(topic: string, value: any): Promise<CommandMessage> {
-        return this.invoke(topic, MessageType.Write, { value });
-    }
-
-    /**
-     * Subscribe to updates for a specific resource.
-     * 
-     * Registers a mapping so that when the server sends updates for `topic` (FQDN),
-     * the Hub will translate it to `tagName` before dispatching to the UI.
-     * 
-     * @param tagName The local alias for this resource (e.g., "position").
-     * @param topic The backend FQDN (e.g., "ADS.Main.fPos").
-     * @param payload Optional subscription parameters (rate, deadband).
-     */
-    subscribe(tagName : string, topic: string, payload?: object): Promise<CommandMessage> {
-        this.mapTopic(tagName, topic);
-        return this.invoke(topic, MessageType.Subscribe, payload);
-    }
-
-    /**
-     * Unsubscribe from updates.
-     * 
-     * Uses the `tagName` to look up the FQDN and send the unsubscribe command.
-     * Also removes the local mapping.
-     * 
-     * @param tagName The local alias to unsubscribe.
-     */
-    unsubscribe( /* topic: string,*/ tagName : string, payload?: object): Promise<CommandMessage> {
-        const fqdn = this.toBackendTopic(tagName);        
-        this.unmapTopic(tagName);
-        return this.invoke(fqdn, MessageType.Unsubscribe, payload);
-    }
-
-    /**
-     * Send a generic request (custom command).
-     */
-    request(topic: string, payload?: object): Promise<CommandMessage> {
-        return this.invoke(topic, MessageType.Request, payload);
-    }
-
-    // =========================================================================
-    // Connection State
-    // =========================================================================
-
-    /**
-     * Update internal connection state.
-     */
-    protected setIsConnected = (s: boolean) => {
-        this.isConnected_ = s;
-    }
-
-    /**
-     * Check if currently connected to backend.
-     */
-    isConnected = (): boolean => {
-        return this.isConnected_;
-    }
-
-    // =========================================================================
-    // Frontend Event Bus (Local Publish/Subscribe)
-    // =========================================================================
-
-    /**
-     * Dispatches an event to the React application.
-     * 
-     * 1. Translates the `topic` (potentially an FQDN) to a local `tagName` if a mapping exists.
-     * 2. Calls `context.dispatch()` to notify local subscribers.
-     * 
-     * This is the bridge between the backend transport and the frontend UI components.
-     * 
-     * @param topic The topic from the message (usually FQDN).
-     * @param data The data payload.
-     */
-    publish(topic: string, data: any | undefined): void {
-        const convertedTopic = this.toLocalTopic(topic);
-
-        console.log(`HUB Dispatch topic ${convertedTopic} payload ${JSON.stringify(data)}`);
-        this.context?.dispatch({
-            topic: convertedTopic,
-            payload: data
-        });
-    }
-
-    // =========================================================================
-    // Topic Mapping (for aliasing backend topics to local names)
-    // =========================================================================
-
-    /**
-     * Registers a mapping between a local name and a backend FQDN.
-     */
-    mapTopic(localTopic: string, backendTopic: string): void {
-        this.localTopicToBackendTopicMap.set(localTopic, backendTopic);
-        this.backendTopicToLocalMap.set(backendTopic, localTopic);
-    }
-
-    /**
-     * Removes a mapping.
-     */
-    unmapTopic(localTopic: string): void {
-        if (this.localTopicToBackendTopicMap.has(localTopic)) {
-            const be = this.localTopicToBackendTopicMap.get(localTopic);
-            this.localTopicToBackendTopicMap.delete(localTopic);
-
-            if (be !== null && be !== undefined && this.backendTopicToLocalMap.has(be)) {
-                this.backendTopicToLocalMap.delete(be);
-            }
-        }
-    }
-
-    /**
-     * Translates Local Name -> Backend FQDN.
-     */
-    toBackendTopic(localTopic: string): string {
-        const mapped = this.localTopicToBackendTopicMap.get(localTopic);
-        return mapped ?? localTopic;
-    }
-
-    /**
-     * Translates Backend FQDN -> Local Name.
-     */
-    toLocalTopic(backendTopic: string): string {
-        const mapped = this.backendTopicToLocalMap.get(backendTopic);
-        return mapped ?? backendTopic;
-    }
-}
-
-
+/*
+ * Copyright (C) 2023 Automated Design Corp. All Rights Reserved.
+ * Created Date: 2023-12-15 14:21:33
+ * Author: Thomas C. Bitsky Jr.
+ * -----
+ * Last Modified: 2026-01-29 09:34:10
+ * Modified By: ADC
+ * -----
+ *
+ */
+
+import type { EventEmitterContextType } from '../core/EventEmitterContext';
+import type { CommandMessage } from "./CommandMessage";
+import { MessageType } from "./CommandMessage";
+
+
+/**
+ * @class HubBase
+ * @abstract
+ * 
+ * Abstract base class that defines the interface for communicating with the AutoCore backend.
+ * Implementations (like `HubWebSocket` or `HubTauri`) handle the specific transport mechanics.
+ * 
+ * ## Core Responsibilities
+ * 
+ * 1. **Transport Abstraction**: Provides a unified API (`read`, `write`, `subscribe`) regardless of 
+ *    underlying transport (WS, IPC, etc.).
+ * 2. **Topic Mapping**: Maintains a bidirectional mapping between local `tagName` (UI friendly) 
+ *    and backend `FQDN` (Fully Qualified Domain Name).
+ *    - `tagName`: "motorsEnable"
+ *    - `FQDN`: "ADS.Main.bMotorsEnable"
+ * 3. **Event Dispatching**: Routes incoming messages from the backend to the `EventEmitterContext`.
+ * 
+ * ## Usage
+ * 
+ * The `Hub` is typically accessed via the `EventEmitterContext`:
+ * 
+ * ```typescript
+ * const { hub } = useContext(EventEmitterContext);
+ * await hub.write("ADS.Main.nSpeed", 500);
+ * ```
+ */
+export abstract class HubBase {
+
+    /** Maps local tag names to backend FQDNs. */
+    protected localTopicToBackendTopicMap: Map<string, string> = new Map<string, string>();
+    
+    /** Maps backend FQDNs to local tag names. */
+    protected backendTopicToLocalMap: Map<string, string[]> = new Map<string, string[]>();
+
+    /** Reference to the global event emitter for dispatching incoming messages. */
+    protected context: EventEmitterContextType | null = null;
+
+    /** Connection state tracker. */
+    protected isConnected_: boolean = false;
+
+
+    /**
+     * Constructor
+     */
+    constructor() {
+    }
+
+
+    /**
+     * Links this Hub instance with the React application's Event Context.
+     * 
+     * This connection allows the Hub to "push" messages into the React app by calling `context.dispatch()`.
+     * This is called automatically by `EventEmitterProvider` on initialization.
+     * 
+     * @param context The React context instance.
+     */
+    setContext(context: EventEmitterContextType | null) {
+        this.context = context;
+    }
+
+    // =========================================================================
+    // Abstract Methods - Must be implemented by subclasses
+    // =========================================================================
+
+    /**
+     * Sends a raw command message to the backend.
+     * 
+     * @param topic The resource identifier (FQDN).
+     * @param messageType The operation to perform (Read, Write, etc.).
+     * @param payload The data payload.
+     * @returns A Promise that resolves with the server's response.
+     */
+    abstract invoke(topic: string, messageType: MessageType, payload?: object): Promise<CommandMessage>;
+
+    // =========================================================================
+    // Convenience Helper Methods
+    // =========================================================================
+
+    /**
+     * Request the current value of a resource.
+     * 
+     * @param topic FQDN of the resource.
+     */
+    read(topic: string, payload?: object): Promise<CommandMessage> {
+        return this.invoke(topic, MessageType.Read, payload);
+    }
+
+    /**
+     * Write a new value to a resource.
+     * 
+     * @param topic FQDN of the resource.
+     * @param value The value to write.
+     */
+    write(topic: string, value: any): Promise<CommandMessage> {
+        return this.invoke(topic, MessageType.Write, { value });
+    }
+
+    /**
+     * Subscribe to updates for a specific resource.
+     * 
+     * Registers a mapping so that when the server sends updates for `topic` (FQDN),
+     * the Hub will translate it to `tagName` before dispatching to the UI.
+     * 
+     * @param tagName The local alias for this resource (e.g., "position").
+     * @param topic The backend FQDN (e.g., "ADS.Main.fPos").
+     * @param payload Optional subscription parameters (rate, deadband).
+     */
+    subscribe(tagName : string, topic: string, payload?: object): Promise<CommandMessage> {
+        this.mapTopic(tagName, topic);
+        return this.invoke(topic, MessageType.Subscribe, payload);
+    }
+
+    /**
+     * Unsubscribe from updates.
+     * 
+     * Uses the `tagName` to look up the FQDN and send the unsubscribe command.
+     * Also removes the local mapping.
+     * 
+     * @param tagName The local alias to unsubscribe.
+     */
+    unsubscribe( /* topic: string,*/ tagName : string, payload?: object): Promise<CommandMessage> {
+        const fqdn = this.toBackendTopic(tagName);        
+        this.unmapTopic(tagName);
+        return this.invoke(fqdn, MessageType.Unsubscribe, payload);
+    }
+
+    /**
+     * Send a generic request (custom command).
+     */
+    request(topic: string, payload?: object): Promise<CommandMessage> {
+        return this.invoke(topic, MessageType.Request, payload);
+    }
+
+    // =========================================================================
+    // Connection State
+    // =========================================================================
+
+    /**
+     * Update internal connection state.
+     */
+    protected setIsConnected = (s: boolean) => {
+        this.isConnected_ = s;
+    }
+
+    /**
+     * Check if currently connected to backend.
+     */
+    isConnected = (): boolean => {
+        return this.isConnected_;
+    }
+
+    // =========================================================================
+    // Frontend Event Bus (Local Publish/Subscribe)
+    // =========================================================================
+
+    /**
+     * Dispatches an event to the React application.
+     * 
+     * 1. Translates the `topic` (potentially an FQDN) to a local `tagName` if a mapping exists.
+     * 2. Calls `context.dispatch()` to notify local subscribers.
+     * 
+     * This is the bridge between the backend transport and the frontend UI components.
+     * 
+     * @param topic The topic from the message (usually FQDN).
+     * @param data The data payload.
+     */
+    publish(topic: string, data: any | undefined): void {
+        const convertedTopics = this.toLocalTopics(topic);
+
+        for (const convertedTopic of convertedTopics) {
+            console.log(`HUB Dispatch topic ${convertedTopic} payload ${JSON.stringify(data)}`);
+            this.context?.dispatch({
+                topic: convertedTopic,
+                payload: data
+            });
+        }
+    }
+
+    // =========================================================================
+    // Topic Mapping (for aliasing backend topics to local names)
+    // =========================================================================
+
+    /**
+     * Registers a mapping between a local name and a backend FQDN.
+     */
+    mapTopic(localTopic: string, backendTopic: string): void {
+        this.localTopicToBackendTopicMap.set(localTopic, backendTopic);
+        
+        let localTopics = this.backendTopicToLocalMap.get(backendTopic) || [];
+        if (!localTopics.includes(localTopic)) {
+            localTopics.push(localTopic);
+            this.backendTopicToLocalMap.set(backendTopic, localTopics);
+        }
+    }
+
+    /**
+     * Removes a mapping.
+     */
+    unmapTopic(localTopic: string): void {
+        if (this.localTopicToBackendTopicMap.has(localTopic)) {
+            const be = this.localTopicToBackendTopicMap.get(localTopic);
+            this.localTopicToBackendTopicMap.delete(localTopic);
+
+            if (be !== null && be !== undefined && this.backendTopicToLocalMap.has(be)) {
+                let localTopics = this.backendTopicToLocalMap.get(be) || [];
+                localTopics = localTopics.filter(t => t !== localTopic);
+                if (localTopics.length > 0) {
+                    this.backendTopicToLocalMap.set(be, localTopics);
+                } else {
+                    this.backendTopicToLocalMap.delete(be);
+                }
+            }
+        }
+    }
+
+    /**
+     * Translates Local Name -> Backend FQDN.
+     */
+    toBackendTopic(localTopic: string): string {
+        const mapped = this.localTopicToBackendTopicMap.get(localTopic);
+        return mapped ?? localTopic;
+    }
+
+    /**
+     * Translates Backend FQDN -> Array of Local Names.
+     */
+    toLocalTopics(backendTopic: string): string[] {
+        const mapped = this.backendTopicToLocalMap.get(backendTopic);
+        return mapped && mapped.length > 0 ? mapped : [backendTopic];
+    }
+}
+
+
 export default HubBase;