@adcops/autocore-react 3.1.1 → 3.3.2

package/src/hub/HubBase.ts

@@ -3,99 +3,56 @@
  * Created Date: 2023-12-15 14:21:33
  * Author: Thomas C. Bitsky Jr.
  * -----
- * Last Modified: 2025-09-05 14:50:03
+ * Last Modified: 2026-01-29 09:34:10
  * Modified By: ADC
  * -----
- * 
+ *
  */
 
-import type { EventEmitterContextType} from '../core/EventEmitterContext';
-import type {CommandMessageResult} from "./CommandMessage";
+import type { EventEmitterContextType } from '../core/EventEmitterContext';
+import type { CommandMessage } from "./CommandMessage";
+import { MessageType } from "./CommandMessage";
 
 
 /**
- * Base class for the interface for the IPC to the backend, 
- * which may be websockets, MQTT, the Tauri API, 
- * or something else.
- * 
- * The EventEmitterContext should generate the hub automatically. 
- * 
- * # Usage
- * The hub can be used to publish and subscribe to
- * topics in the front-end, regardless of being connected to any backend.
- * 
- * ```
- * const {dispatch, subscribe, unsubscribe} = useContext(EventEmitterContext);
- * const [controlPower, setControlPower] = useState(false);
- * useEffect(() => {
- *      const unsubscribeControlPower = subscribe('value-simulator-bBit1', (value) => {
- *          setControlPower(value);
- *      });  
- *
- *
- *      return () => {
- *           unsubscribe(unsubscribeControlPower);
- *      }
- * }, [] );
+ * @class HubBase
+ * @abstract
  * 
- * const onPbPressed = () => {
- *      let count = 1;
- *      dispatch({
- *          topic: "my-awesome-topic",
- *          payload: count
- *      });
- * }
+ * Abstract base class that defines the interface for communicating with the AutoCore backend.
+ * Implementations (like `HubWebSocket` or `HubTauri`) handle the specific transport mechanics.
  * 
- * ``` 
- * 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});        
- * };
+ * ## Core Responsibilities
  * 
- * Subscribing to a topic is simple. The type of value received is specific
- * to the topic.
+ * 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`.
  * 
- * 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);
- *        });
+ * ## Usage
  * 
- *    return () => {
- *        unsubscribe(unsubscripeMp);
- *    }
+ * The `Hub` is typically accessed via the `EventEmitterContext`:
  * 
- * }, [] );
- *
+ * ```typescript
+ * const { hub } = useContext(EventEmitterContext);
+ * await hub.write("ADS.Main.nSpeed", 500);
  * ```
- * 
  */
 export abstract class HubBase {
 
-    protected localTopicToBackendTopicMap : Map<string,string> = new Map<string,string>();
-    protected backendTopicToLocalMap : Map<string,string> = new Map<string,string>();
-    protected localFNameToBackendFNameMap : Map<string,string> = new Map<string,string>();
-    protected backendFNameToLocalFNameMap : Map<string,string> = new Map<string,string>();
+    /** 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>();
 
-    protected context : EventEmitterContextType | null = null;
+    /** Reference to the global event emitter for dispatching incoming messages. */
+    protected context: EventEmitterContextType | null = null;
 
-    protected isConnected_ : boolean = false;
+    /** Connection state tracker. */
+    protected isConnected_: boolean = false;
 
 
     /**
@@ -106,66 +63,125 @@ export abstract class HubBase {
 
 
     /**
-     * Set the EventEmitterContext for this instance of the Hub. The EventEmitterContext
-     * should handle this as part of the initialization sequence. Because React can
-     * sometimes make (and destroy) multiple copies of the EventEmitterContext, it's important
-     * that the context be stored in the instance this way so that the HubBase can properly target
-     * right context.
+     * Links this Hub instance with the React application's Event Context.
      * 
-     * If this context is not sent, no events will be emitted from the backend to the front end,
-     * and global events in the interface may not work.
+     * 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 ) {
+    setContext(context: EventEmitterContextType | null) {
         this.context = context;
-    }    
+    }
 
-    /** 
-     * Invoke/send a message to the back end. 
-     * This does NOT get published to the front end.
+    // =========================================================================
+    // 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(domain: string, fname: string, payload? : object) : Promise<CommandMessageResult>;
+    abstract invoke(topic: string, messageType: MessageType, payload?: object): Promise<CommandMessage>;
 
+    // =========================================================================
+    // Convenience Helper Methods
+    // =========================================================================
 
     /**
-     * Allos the derived class to set whether the hub is connected to its source.
-     * @param s boolean
+     * Request the current value of a resource.
+     * 
+     * @param topic FQDN of the resource.
      */
-    protected setIsConnected = (s : boolean) => {
-        this.isConnected_ = s;
+    read(topic: string, payload?: object): Promise<CommandMessage> {
+        return this.invoke(topic, MessageType.Read, payload);
     }
 
     /**
-     * Returns true if the Hub is connected to its source.
+     * Write a new value to a resource.
+     * 
+     * @param topic FQDN of the resource.
+     * @param value The value to write.
      */
-    isConnected = () : boolean => {
-        return this.isConnected_;
+    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;
     }
 
     /**
-     * Convenience function to invoke a command with an optional topic and optional value.
-     * This will invoke the specified command in the backend. It does not broadcast the
-     * value within the local frontend.
-     * @param domain string The domain of the command that will be invoked.
-     * @param fname string Function name
-     * @param topic string Topic 
-     * @param value any data payload
+     * Check if currently connected to backend.
      */
-    invokeTopic( domain: string, fname : string, topic : string | null, value? : any ) : Promise<CommandMessageResult> {
-        const msg = {
-            topic : topic,
-            data : value
-        };
-        return this.invoke(domain, fname, msg);
+    isConnected = (): boolean => {
+        return this.isConnected_;
     }
 
-    /** 
-     * Pubish a topic throughout the web app using the 
-     * Global EventEmitterContext. This will broadcast within the local frontend. 
-     * This does NOT get relayed to the backend.
+    // =========================================================================
+    // 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);        
+    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({
@@ -174,139 +190,47 @@ export abstract class HubBase {
         });
     }
 
+    // =========================================================================
+    // Topic Mapping (for aliasing backend topics to local names)
+    // =========================================================================
 
     /**
-     * Map a local topic to a topic in the backend.
-     * @param localTopic string
-     * @param backendTopic string
+     * Registers a mapping between a local name and a backend FQDN.
      */
-    mapTopic(localTopic : string, backendTopic: string ) : void {
+    mapTopic(localTopic: string, backendTopic: string): void {
         this.localTopicToBackendTopicMap.set(localTopic, backendTopic);
         this.backendTopicToLocalMap.set(backendTopic, localTopic);
     }
 
     /**
-     * Unmap a local topic.
-     * @param localTopic string
+     * Removes a mapping.
      */
-    unmapTopic(localTopic: string) : void {
-        if (this.localTopicToBackendTopicMap.has(localTopic) ) {
+    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);
             }
-        }        
+        }
     }
 
-
     /**
-     * Map a local function name, as would be sent to the invoke method, to a 
-     * function name in the backend.
-     * @param localFName string
-     * @param backendFName string
+     * Translates Local Name -> Backend FQDN.
      */
-    mapFName(localFName : string, backendFName: string ) : void {
-        this.localFNameToBackendFNameMap.set(localFName, backendFName);
-        this.backendFNameToLocalFNameMap.set(backendFName, localFName);
+    toBackendTopic(localTopic: string): string {
+        const mapped = this.localTopicToBackendTopicMap.get(localTopic);
+        return mapped ?? localTopic;
     }
 
     /**
-     * Unmap a local function name.
-     * @param localFName string
+     * Translates Backend FQDN -> Local Name.
      */
-    unmapFName(localFName: string) : void {
-        if (this.localFNameToBackendFNameMap.has(localFName) ) {
-            const be = this.localFNameToBackendFNameMap.get(localFName);
-            this.localFNameToBackendFNameMap.delete(localFName);
-            
-            if (be !== null && be !== undefined && this.backendFNameToLocalFNameMap.has(be)) {
-                this.backendFNameToLocalFNameMap.delete(be);
-            }
-        }        
+    toLocalTopic(backendTopic: string): string {
+        const mapped = this.backendTopicToLocalMap.get(backendTopic);
+        return mapped ?? backendTopic;
     }
-
-
-    /**
-     * Convert a local topic to a backend topic. If a mapping isn't
-     * registered, the local topic is returned.
-     * @param localTopic local topic name
-     * @returns string
-     */
-    toBackendTopic(localTopic : string) : string {
-        if (this.localTopicToBackendTopicMap.has(localTopic) ) {
-            const ret = this.localTopicToBackendTopicMap.get(localTopic);
-            if (ret !== null && ret !== undefined)
-                return ret;
-            else
-                return localTopic;
-        }
-        else {
-            return localTopic;
-        }
-    }
-
-    /**
-     * Convert a local function name to a backend function name. If a mapping isn't
-     * registered, the local FName is returned.
-     * @param localTopic local function name
-     * @returns string
-     */    
-    toBackendFName(localFName : string) : string {
-        if (this.localFNameToBackendFNameMap.has(localFName) ) {
-            const ret = this.localFNameToBackendFNameMap.get(localFName);
-            if (ret !== null && ret !== undefined)
-                return ret;
-            else
-                return localFName;
-        }
-        else {
-            return localFName;
-        }
-    }    
-
-
-    /**
-     * Convert a backend topic to a local topic. If a mapping isn't
-     * registered, the backend topic is returned.
-     * @param backendTopic backend topic name
-     * @returns string
-     */
-    toLocalTopic(backendTopic : string) : string {
-        if (this.backendTopicToLocalMap.has(backendTopic) ) {
-            const ret = this.backendTopicToLocalMap.get(backendTopic);
-            if (ret !== null && ret !== undefined)
-                return ret;
-            else
-                return backendTopic;
-        }
-        else {
-            return backendTopic;
-        }
-    }    
-    
-
-    /**
-     * Convert a backend function name to a local function name. If a mapping isn't
-     * registered, the backend function name is returned.
-     * @param backendTopic backend function name
-     * @returns string
-     */    
-    toLocalFName(backendTopic : string) : string {
-        if (this.backendFNameToLocalFNameMap.has(backendTopic) ) {
-            const ret = this.backendFNameToLocalFNameMap.get(backendTopic);
-            if (ret !== null && ret !== undefined)
-                return ret;
-            else
-                return backendTopic;
-        }
-        else {
-            return backendTopic;
-        }
-    }       
-
-
 }
 
 

package/src/hub/HubSimulate.ts

@@ -2,54 +2,123 @@
  * Copyright (C) 2023 Automated Design Corp. All Rights Reserved.
  * Created Date: 2023-12-17 10:38:21
  * -----
- * Last Modified: 2025-09-05 14:49:57
+ * Last Modified: 2026-01-29 09:34:15
  * Modified By: ADC
  * -----
- * 
+ *
  */
 
-
 import { HubBase } from './HubBase';
-import type { CommandMessageResult } from "./CommandMessage";
+import type { CommandMessage } from "./CommandMessage";
+import { MessageType } from "./CommandMessage";
+
 /**
- * Hub for simulating functionality when no backend is present.
+ * Hub for simulating backend functionality when no actual backend is present.
+ *
+ * Useful for development, testing, and demos without a running autocore-server.
+ * The simulator echoes back requests as successful responses after a configurable delay.
+ *
+ * ## Usage Examples
+ *
+ * ```typescript
+ * const { hub } = useContext(EventEmitterContext);
+ *
+ * // Read returns the topic as the "value"
+ * const result = await hub.read("ads.plc1.gio.bControlPowerOk");
+ * console.log(result.data); // { value: "ads.plc1.gio.bControlPowerOk" }
+ *
+ * // Write echoes back the written value
+ * await hub.write("ads.plc1.gio.nSetpoint", 100);
+ * ```
  */
 export class HubSimulate extends HubBase {
 
+    private responseDelay: number;
+
     /**
      * Constructor
+     * @param responseDelay Simulated response delay in milliseconds (default: 20ms)
      */
-    constructor() {
+    constructor(responseDelay: number = 20) {
         super();
+        this.responseDelay = responseDelay;
+        this.setIsConnected(true); // Simulator is always "connected"
     }
 
     /**
-     * Invoke a method in the Socket.IO backend and wait for acknowledgment.
-     * 
-     * @param fname method name
+     * Simulate sending a message to a backend.
+     *
+     * For Read operations, returns the topic as the value.
+     * For Write operations, echoes back the payload.
+     * For all operations, returns a successful response after the configured delay.
+     *
+     * @param topic The FQDN of the resource
+     * @param messageType The action to perform
      * @param payload Optional data payload
-     * @param timeout Timeout in milliseconds after which the promise is rejected if no response is received.
-     * @returns A Promise that resolves to the response from the backend or rejects if a timeout occurs.
+     * @returns Promise<CommandMessage> A simulated successful response
      */
-    invoke(domain: string, fname: string, payload?: object, timeout: number = 20): Promise<CommandMessageResult> {
-        domain; // Not using for simulator
-        fname; // Not using for simulator
-        return new Promise((resolve, reject) => {
-            reject; // not using for simulator
-            // Set a timeout to echo a response
+    invoke(topic: string, messageType: MessageType, payload?: object): Promise<CommandMessage> {
+        return new Promise((resolve) => {
             setTimeout(() => {
+                let responseData: any;
+
+                // Simulate appropriate responses based on message type
+                switch (messageType) {
+                    case MessageType.Read:
+                        // Simulate reading - return the topic as a "value"
+                        responseData = { value: topic, simulated: true };
+                        break;
+
+                    case MessageType.Write:
+                        // Simulate writing - echo back the payload
+                        responseData = { written: true, ...payload };
+                        break;
+
+                    case MessageType.Subscribe:
+                        // Simulate subscribing - acknowledge
+                        responseData = { subscribed: true, topic: topic };
+                        break;
 
-                let ret: CommandMessageResult = {
-                    data: payload,
-                    error_message: "",
-                    success: true
+                    case MessageType.Unsubscribe:
+                        // Simulate unsubscribing - acknowledge
+                        responseData = { unsubscribed: true, topic: topic };
+                        break;
+
+                    default:
+                        // Echo back the payload for other message types
+                        responseData = payload ?? {};
+                        break;
+                }
+
+                const response: CommandMessage = {
+                    transaction_id: 0,
+                    timecode: Date.now(),
+                    topic: topic,
+                    message_type: MessageType.Response,
+                    data: responseData,
+                    success: true,
+                    error_message: ''
                 };
 
-                resolve(ret);
-            }, timeout);
+                resolve(response);
+            }, this.responseDelay);
         });
     }
 
+    /**
+     * Simulate a broadcast from the "backend".
+     *
+     * This is useful for testing subscription handlers.
+     *
+     * @param topic The topic to broadcast on
+     * @param data The data to broadcast
+     * @param delay Optional delay before broadcasting (default: 0ms)
+     */
+    simulateBroadcast(topic: string, data: any, delay: number = 0): void {
+        setTimeout(() => {
+            this.publish(topic, data);
+        }, delay);
+    }
 }
 
-export default HubSimulate;
+export default HubSimulate;