@enyo-energy/energy-app-sdk 0.0.37 → 0.0.39

package/dist/cjs/implementations/appliances/in-memory-appliance-manager.d.cts

@@ -0,0 +1,119 @@
+import type { EnergyApp } from "../../index.cjs";
+import type { EnyoNetworkDevice } from "../../types/enyo-network-device.cjs";
+import { EnyoAppliance, EnyoApplianceConnectionType, EnyoApplianceMetadata, EnyoApplianceStateEnum, EnyoApplianceTypeEnum } from "../../types/enyo-appliance.cjs";
+import { ApplianceConfig, ApplianceManager, ApplianceManagerConfig, FindResult } from "./appliance-manager.cjs";
+import { IdentifierStrategy } from "./identifier-strategies.cjs";
+/**
+ * Demo implementation of ApplianceManager that stores all data in memory.
+ * This class provides the same interface as ApplianceManager but doesn't
+ * use energyApp.useAppliances() for persistence.
+ */
+export declare class InMemoryApplianceManager extends ApplianceManager {
+    private memoryStore;
+    private nextId;
+    private networkDevicesStore;
+    /**
+     * Creates a new DemoApplianceManager instance.
+     * @param energyApp The EnergyApp instance (not used for persistence in demo)
+     * @param config Configuration options for the manager
+     */
+    constructor(energyApp: EnergyApp, config?: ApplianceManagerConfig);
+    /**
+     * Creates or updates an appliance in memory.
+     * @param config The appliance configuration
+     * @param existingApplianceId Optional ID of an existing appliance to update
+     * @returns The ID of the created or updated appliance
+     */
+    createOrUpdateAppliance(config: ApplianceConfig, existingApplianceId?: string): Promise<string>;
+    /**
+     * Gets an appliance by ID from memory.
+     * @param applianceId The ID of the appliance
+     * @returns The appliance or null if not found
+     */
+    getApplianceById(applianceId: string): Promise<EnyoAppliance | null>;
+    /**
+     * Gets all appliances from memory.
+     * @returns Array of all appliances
+     */
+    getAllAppliances(): Promise<EnyoAppliance[]>;
+    /**
+     * Gets network devices associated with an appliance.
+     * @param appliance The appliance
+     * @returns Array of network devices
+     */
+    protected getNetworkDevicesForApplianceDemo(appliance: EnyoAppliance): Promise<EnyoNetworkDevice[]>;
+    /**
+     * Finds appliances by their identifier using the configured strategy.
+     * @param identifier The identifier to search for
+     * @returns Array of matching appliances
+     */
+    findByIdentifier(identifier: string): Promise<EnyoAppliance[]>;
+    /**
+     * Finds an appliance using multiple strategies.
+     * @param searchValue The value to search for
+     * @param strategies Array of strategies to try
+     * @returns The first matching result or undefined
+     */
+    findWithStrategies(searchValue: string, strategies: IdentifierStrategy[]): Promise<FindResult | undefined>;
+    /**
+     * Gets all appliances of a specific type.
+     * @param type The appliance type to filter by
+     * @returns Array of appliances of the specified type
+     */
+    getAppliancesByType(type: EnyoApplianceTypeEnum): Promise<EnyoAppliance[]>;
+    /**
+     * Updates the state of an appliance in memory.
+     * @param applianceId The ID of the appliance to update
+     * @param connectionType The new connection type
+     * @param state The new state
+     */
+    updateApplianceState(applianceId: string, connectionType: EnyoApplianceConnectionType, state: EnyoApplianceStateEnum): Promise<void>;
+    /**
+     * Updates metadata for an appliance in memory.
+     * @param applianceId The ID of the appliance
+     * @param metadata The metadata to update
+     */
+    updateApplianceMetadata(applianceId: string, metadata: Partial<EnyoApplianceMetadata> & {
+        connectionType: EnyoApplianceConnectionType;
+    }): Promise<void>;
+    /**
+     * Removes an appliance from memory.
+     * @param applianceId The ID of the appliance to remove
+     */
+    removeAppliance(applianceId: string): Promise<void>;
+    /**
+     * Performs a bulk update on multiple appliances in memory.
+     * @param updates Array of updates to perform
+     * @returns Results of the bulk update operation
+     */
+    bulkUpdate(updates: Array<{
+        applianceId: string;
+        data: Partial<Omit<EnyoAppliance, 'id'>>;
+    }>): Promise<{
+        succeeded: string[];
+        failed: string[];
+    }>;
+    /**
+     * Gets statistics about the managed appliances in memory.
+     * @returns Statistics object
+     */
+    getStatistics(): Promise<{
+        total: number;
+        byType: Record<string, number>;
+        byState: Record<string, number>;
+        cached: number;
+    }>;
+    /**
+     * Refreshes the cache with all appliances from memory.
+     */
+    refreshCache(): Promise<void>;
+    /**
+     * Clears all data from memory (for testing purposes).
+     */
+    clearAllData(): void;
+    /**
+     * Gets the current size of the memory store.
+     * @returns The number of appliances in memory
+     */
+    getMemoryStoreSize(): number;
+}

package/dist/cjs/implementations/data-bus/demo-data-bus.cjs

@@ -0,0 +1,246 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DemoDataBus = void 0;
+/**
+ * Demo implementation of EnergyAppDataBus that logs messages to console
+ * and maintains an in-memory message history and listener registry.
+ */
+class DemoDataBus {
+    enableConsoleLogging;
+    messageHistory = [];
+    listeners = new Map();
+    nextListenerId = 1;
+    maxHistorySize = 1000;
+    /**
+     * Creates a new DemoDataBus instance.
+     * @param enableConsoleLogging Whether to log messages to console (default: true)
+     * @param maxHistorySize Maximum number of messages to keep in history (default: 1000)
+     */
+    constructor(enableConsoleLogging = true, maxHistorySize) {
+        this.enableConsoleLogging = enableConsoleLogging;
+        if (maxHistorySize !== undefined) {
+            this.maxHistorySize = maxHistorySize;
+        }
+    }
+    /**
+     * Sends messages to the data bus (logs to console and notifies listeners).
+     * @param messages Array of messages to send
+     * @param options Optional send options (not used in demo)
+     */
+    sendMessage(messages, options) {
+        for (const message of messages) {
+            // Log to console if enabled
+            if (this.enableConsoleLogging) {
+                console.log('[DEMO DataBus] Message sent:', {
+                    id: message.id,
+                    type: message.message,
+                    applianceId: message.applianceId,
+                    timestamp: message.timestampIso,
+                    data: message.data
+                });
+            }
+            // Add to history
+            this.addToHistory(message);
+            // Notify listeners
+            this.notifyListeners(message);
+        }
+    }
+    /**
+     * Sends an answer message to the data bus.
+     * @param answer The answer message to send
+     * @param options Optional send options (not used in demo)
+     */
+    sendAnswer(answer, options) {
+        // Log to console if enabled
+        if (this.enableConsoleLogging) {
+            console.log('[DEMO DataBus] Answer sent:', {
+                id: answer.id,
+                type: answer.message,
+                status: answer.data.status,
+                applianceId: answer.applianceId,
+                timestamp: answer.timestampIso
+            });
+        }
+        // Add to history
+        this.addToHistory(answer);
+        // Notify listeners
+        this.notifyListeners(answer);
+    }
+    /**
+     * Registers a listener for specific message types.
+     * @param types Array of message types to listen for
+     * @param listener Callback function to invoke when matching messages are received
+     * @returns Listener ID that can be used to unsubscribe
+     */
+    listenForMessages(types, listener) {
+        const listenerId = `listener_${this.nextListenerId++}`;
+        this.listeners.set(listenerId, {
+            types,
+            callback: listener
+        });
+        if (this.enableConsoleLogging) {
+            console.log(`[DEMO DataBus] Listener ${listenerId} registered for types:`, types);
+        }
+        return listenerId;
+    }
+    /**
+     * Unsubscribes a listener from the data bus.
+     * @param listenerId The ID of the listener to unsubscribe
+     */
+    unsubscribe(listenerId) {
+        if (this.listeners.has(listenerId)) {
+            const listener = this.listeners.get(listenerId);
+            this.listeners.delete(listenerId);
+            if (this.enableConsoleLogging) {
+                console.log(`[DEMO DataBus] Listener ${listenerId} unsubscribed`);
+            }
+        }
+        else {
+            console.warn(`[DEMO DataBus] Attempted to unsubscribe non-existent listener: ${listenerId}`);
+        }
+    }
+    /**
+     * Adds a message to the history, maintaining the maximum size limit.
+     * @param message The message to add to history
+     */
+    addToHistory(message) {
+        this.messageHistory.push(message);
+        // Trim history if it exceeds the maximum size
+        if (this.messageHistory.length > this.maxHistorySize) {
+            this.messageHistory = this.messageHistory.slice(-this.maxHistorySize);
+        }
+    }
+    /**
+     * Notifies all registered listeners that match the message type.
+     * @param message The message to notify listeners about
+     */
+    notifyListeners(message) {
+        for (const [listenerId, listener] of this.listeners.entries()) {
+            if (listener.types.includes(message.message)) {
+                try {
+                    listener.callback(message);
+                    if (this.enableConsoleLogging) {
+                        console.log(`[DEMO DataBus] Notified listener ${listenerId} of ${message.message}`);
+                    }
+                }
+                catch (error) {
+                    console.error(`[DEMO DataBus] Error in listener ${listenerId}:`, error);
+                }
+            }
+        }
+    }
+    /**
+     * Gets the message history.
+     * @param limit Optional limit on the number of messages to return
+     * @returns Array of messages from history
+     */
+    getMessageHistory(limit) {
+        if (limit && limit > 0) {
+            return this.messageHistory.slice(-limit);
+        }
+        return [...this.messageHistory];
+    }
+    /**
+     * Gets messages of specific types from history.
+     * @param types Array of message types to filter by
+     * @param limit Optional limit on the number of messages to return
+     * @returns Filtered array of messages
+     */
+    getMessagesByType(types, limit) {
+        const filtered = this.messageHistory.filter(msg => types.includes(msg.message));
+        if (limit && limit > 0) {
+            return filtered.slice(-limit);
+        }
+        return filtered;
+    }
+    /**
+     * Gets messages for a specific appliance from history.
+     * @param applianceId The appliance ID to filter by
+     * @param limit Optional limit on the number of messages to return
+     * @returns Filtered array of messages
+     */
+    getMessagesByAppliance(applianceId, limit) {
+        const filtered = this.messageHistory.filter(msg => msg.applianceId === applianceId);
+        if (limit && limit > 0) {
+            return filtered.slice(-limit);
+        }
+        return filtered;
+    }
+    /**
+     * Clears the message history.
+     */
+    clearHistory() {
+        this.messageHistory = [];
+        if (this.enableConsoleLogging) {
+            console.log('[DEMO DataBus] Message history cleared');
+        }
+    }
+    /**
+     * Gets the current number of registered listeners.
+     * @returns The number of active listeners
+     */
+    getListenerCount() {
+        return this.listeners.size;
+    }
+    /**
+     * Gets information about all registered listeners.
+     * @returns Array of listener information
+     */
+    getListenerInfo() {
+        return Array.from(this.listeners.entries()).map(([id, listener]) => ({
+            id,
+            types: listener.types
+        }));
+    }
+    /**
+     * Enables or disables console logging.
+     * @param enabled Whether to enable console logging
+     */
+    setConsoleLogging(enabled) {
+        this.enableConsoleLogging = enabled;
+        console.log(`[DEMO DataBus] Console logging ${enabled ? 'enabled' : 'disabled'}`);
+    }
+    /**
+     * Simulates receiving a message from an external source.
+     * This is useful for testing listeners without actually sending messages.
+     * @param message The message to simulate receiving
+     */
+    simulateIncomingMessage(message) {
+        if (this.enableConsoleLogging) {
+            console.log('[DEMO DataBus] Simulating incoming message:', {
+                id: message.id,
+                type: message.message,
+                applianceId: message.applianceId
+            });
+        }
+        // Add to history
+        this.addToHistory(message);
+        // Notify listeners
+        this.notifyListeners(message);
+    }
+    /**
+     * Gets statistics about the data bus usage.
+     * @returns Statistics object
+     */
+    getStatistics() {
+        const now = new Date();
+        const oneHourAgo = new Date(now.getTime() - 60 * 60 * 1000);
+        const messagesByType = {};
+        let messagesInLastHour = 0;
+        for (const message of this.messageHistory) {
+            // Count by type
+            messagesByType[message.message] = (messagesByType[message.message] ?? 0) + 1;
+            // Count messages in last hour
+            if (new Date(message.timestampIso) > oneHourAgo) {
+                messagesInLastHour++;
+            }
+        }
+        return {
+            totalMessages: this.messageHistory.length,
+            messagesByType,
+            activeListeners: this.listeners.size,
+            messagesInLastHour
+        };
+    }
+}
+exports.DemoDataBus = DemoDataBus;

package/dist/cjs/implementations/data-bus/demo-data-bus.d.cts

@@ -0,0 +1,111 @@
+import { EnergyAppDataBus, EnergyAppDataBusSendDataOptions } from "../../packages/energy-app-data-bus.cjs";
+import { EnyoDataBusMessage, EnyoDataBusMessageAnswer, EnyoDataBusMessageEnum } from "../../types/enyo-data-bus-value.cjs";
+/**
+ * Demo implementation of EnergyAppDataBus that logs messages to console
+ * and maintains an in-memory message history and listener registry.
+ */
+export declare class DemoDataBus implements EnergyAppDataBus {
+    private enableConsoleLogging;
+    private messageHistory;
+    private listeners;
+    private nextListenerId;
+    private maxHistorySize;
+    /**
+     * Creates a new DemoDataBus instance.
+     * @param enableConsoleLogging Whether to log messages to console (default: true)
+     * @param maxHistorySize Maximum number of messages to keep in history (default: 1000)
+     */
+    constructor(enableConsoleLogging?: boolean, maxHistorySize?: number);
+    /**
+     * Sends messages to the data bus (logs to console and notifies listeners).
+     * @param messages Array of messages to send
+     * @param options Optional send options (not used in demo)
+     */
+    sendMessage(messages: EnyoDataBusMessage[], options?: EnergyAppDataBusSendDataOptions): void;
+    /**
+     * Sends an answer message to the data bus.
+     * @param answer The answer message to send
+     * @param options Optional send options (not used in demo)
+     */
+    sendAnswer(answer: EnyoDataBusMessageAnswer, options?: EnergyAppDataBusSendDataOptions): void;
+    /**
+     * Registers a listener for specific message types.
+     * @param types Array of message types to listen for
+     * @param listener Callback function to invoke when matching messages are received
+     * @returns Listener ID that can be used to unsubscribe
+     */
+    listenForMessages(types: EnyoDataBusMessageEnum[], listener: (entry: EnyoDataBusMessage) => void): string;
+    /**
+     * Unsubscribes a listener from the data bus.
+     * @param listenerId The ID of the listener to unsubscribe
+     */
+    unsubscribe(listenerId: string): void;
+    /**
+     * Adds a message to the history, maintaining the maximum size limit.
+     * @param message The message to add to history
+     */
+    private addToHistory;
+    /**
+     * Notifies all registered listeners that match the message type.
+     * @param message The message to notify listeners about
+     */
+    private notifyListeners;
+    /**
+     * Gets the message history.
+     * @param limit Optional limit on the number of messages to return
+     * @returns Array of messages from history
+     */
+    getMessageHistory(limit?: number): EnyoDataBusMessage[];
+    /**
+     * Gets messages of specific types from history.
+     * @param types Array of message types to filter by
+     * @param limit Optional limit on the number of messages to return
+     * @returns Filtered array of messages
+     */
+    getMessagesByType(types: EnyoDataBusMessageEnum[], limit?: number): EnyoDataBusMessage[];
+    /**
+     * Gets messages for a specific appliance from history.
+     * @param applianceId The appliance ID to filter by
+     * @param limit Optional limit on the number of messages to return
+     * @returns Filtered array of messages
+     */
+    getMessagesByAppliance(applianceId: string, limit?: number): EnyoDataBusMessage[];
+    /**
+     * Clears the message history.
+     */
+    clearHistory(): void;
+    /**
+     * Gets the current number of registered listeners.
+     * @returns The number of active listeners
+     */
+    getListenerCount(): number;
+    /**
+     * Gets information about all registered listeners.
+     * @returns Array of listener information
+     */
+    getListenerInfo(): Array<{
+        id: string;
+        types: EnyoDataBusMessageEnum[];
+    }>;
+    /**
+     * Enables or disables console logging.
+     * @param enabled Whether to enable console logging
+     */
+    setConsoleLogging(enabled: boolean): void;
+    /**
+     * Simulates receiving a message from an external source.
+     * This is useful for testing listeners without actually sending messages.
+     * @param message The message to simulate receiving
+     */
+    simulateIncomingMessage(message: EnyoDataBusMessage): void;
+    /**
+     * Gets statistics about the data bus usage.
+     * @returns Statistics object
+     */
+    getStatistics(): {
+        totalMessages: number;
+        messagesByType: Record<string, number>;
+        activeListeners: number;
+        messagesInLastHour: number;
+    };
+}

package/dist/cjs/implementations/modbus/EnergyAppModbusDataTypeConverter.d.cts

@@ -1,10 +1,10 @@
-import type { IDataTypeConverter, EnergyAppModbusDataType } from './interfaces.cjs';
+import { EnergyAppModbusDataType } from "./interfaces.cjs";
 /**
  * Data Type Converter for Modbus Register Values
  *
  * @description Converts raw buffer data from Modbus registers into appropriate JavaScript types
  */
-export declare class EnergyAppModbusDataTypeConverter implements IDataTypeConverter {
+export declare class EnergyAppModbusDataTypeConverter {
     /**
      * Converts raw buffer data from Modbus registers into appropriate JavaScript types
      *

package/dist/cjs/implementations/modbus/EnergyAppModbusFaultTolerantReader.cjs

@@ -1,12 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EnergyAppModbusFaultTolerantReader = void 0;
+const EnergyAppModbusDataTypeConverter_js_1 = require("./EnergyAppModbusDataTypeConverter.cjs");
 class EnergyAppModbusFaultTolerantReader {
     _modbusInstance;
     _connectionHealth;
+    _converter;
     constructor(modbusInstance, connectionHealth) {
         this._modbusInstance = modbusInstance;
         this._connectionHealth = connectionHealth;
+        this._converter = new EnergyAppModbusDataTypeConverter_js_1.EnergyAppModbusDataTypeConverter();
     }
     async readHoldingRegisters(startAddress, quantity) {
         try {
@@ -45,5 +48,78 @@ class EnergyAppModbusFaultTolerantReader {
     isHealthy() {
         return this._connectionHealth.isHealthy();
     }
+    /**
+     * Reads holding registers with automatic type conversion
+     *
+     * @param address - Starting register address
+     * @param dataType - The data type to convert to
+     * @param options - Optional parameters for scaling and string length
+     * @returns Register value converted to the specified type, or error
+     */
+    async readHoldingRegisterWithType(address, dataType, options) {
+        try {
+            // Calculate register quantity based on data type
+            let registerQuantity;
+            if (dataType === 'string') {
+                // For strings, quantity represents character count
+                // Each register holds 2 ASCII characters
+                if (!options?.quantity || options.quantity <= 0) {
+                    throw new Error('String data type requires a valid quantity parameter (character count)');
+                }
+                registerQuantity = Math.ceil(options.quantity / 2);
+            }
+            else {
+                // For numeric types, get register count from converter
+                registerQuantity = this._converter.getRegisterQuantity(dataType);
+            }
+            // Read registers with fault tolerance
+            const result = await this.readHoldingRegisters(address, registerQuantity);
+            if (!result.success || !result.value) {
+                return {
+                    success: false,
+                    error: result.error || new Error('Failed to read registers')
+                };
+            }
+            // Convert buffer to appropriate type
+            const convertedValue = this._converter.convertFromBuffer(result.value, dataType, options?.scale, options?.quantity);
+            // Validate the converted value
+            if (!this._converter.isValidValue(convertedValue, dataType)) {
+                console.warn(`Invalid value for ${dataType} at register ${address}: ${convertedValue}`);
+            }
+            return {
+                success: true,
+                value: convertedValue
+            };
+        }
+        catch (error) {
+            const err = error;
+            console.error(`Failed to read ${dataType} from register ${address}: ${err.message}`);
+            return {
+                success: false,
+                error: err
+            };
+        }
+    }
+    /**
+     * Convenience method for reading string values from holding registers
+     *
+     * @param address - Starting register address
+     * @param length - String length in characters
+     * @returns String value or error
+     */
+    async readString(address, length) {
+        return this.readHoldingRegisterWithType(address, 'string', { quantity: length });
+    }
+    /**
+     * Convenience method for reading numeric values from holding registers
+     *
+     * @param address - Starting register address
+     * @param dataType - Numeric data type (uint16, int16, uint32, int32, float32)
+     * @param scale - Optional scaling factor (divide by 10^scale)
+     * @returns Numeric value or error
+     */
+    async readNumeric(address, dataType, scale) {
+        return this.readHoldingRegisterWithType(address, dataType, { scale });
+    }
 }
 exports.EnergyAppModbusFaultTolerantReader = EnergyAppModbusFaultTolerantReader;

package/dist/cjs/implementations/modbus/EnergyAppModbusFaultTolerantReader.d.cts

@@ -1,10 +1,40 @@
 import type { EnergyAppModbusInstance } from "../../packages/energy-app-modbus.cjs";
-import type { IRegisterReader, IConnectionHealth, RegisterReadResult } from './interfaces.cjs';
+import type { IRegisterReader, IConnectionHealth, RegisterReadResult, EnergyAppModbusDataType } from './interfaces.cjs';
 export declare class EnergyAppModbusFaultTolerantReader implements IRegisterReader {
     private readonly _modbusInstance;
     private readonly _connectionHealth;
+    private readonly _converter;
     constructor(modbusInstance: EnergyAppModbusInstance, connectionHealth: IConnectionHealth);
     readHoldingRegisters(startAddress: number, quantity: number): Promise<RegisterReadResult<Buffer>>;
     readInputRegisters(startAddress: number, quantity: number): Promise<RegisterReadResult<Buffer>>;
     isHealthy(): boolean;
+    /**
+     * Reads holding registers with automatic type conversion
+     *
+     * @param address - Starting register address
+     * @param dataType - The data type to convert to
+     * @param options - Optional parameters for scaling and string length
+     * @returns Register value converted to the specified type, or error
+     */
+    readHoldingRegisterWithType<T = any>(address: number, dataType: EnergyAppModbusDataType, options?: {
+        scale?: number;
+        quantity?: number;
+    }): Promise<RegisterReadResult<T>>;
+    /**
+     * Convenience method for reading string values from holding registers
+     *
+     * @param address - Starting register address
+     * @param length - String length in characters
+     * @returns String value or error
+     */
+    readString(address: number, length: number): Promise<RegisterReadResult<string>>;
+    /**
+     * Convenience method for reading numeric values from holding registers
+     *
+     * @param address - Starting register address
+     * @param dataType - Numeric data type (uint16, int16, uint32, int32, float32)
+     * @param scale - Optional scaling factor (divide by 10^scale)
+     * @returns Numeric value or error
+     */
+    readNumeric(address: number, dataType: Exclude<EnergyAppModbusDataType, 'string'>, scale?: number): Promise<RegisterReadResult<number>>;
 }

package/dist/cjs/implementations/modbus/EnergyAppModbusRegisterMapper.d.cts

@@ -1,8 +1,8 @@
-import { type IRegisterMapper, type IRegisterReader, type IDataTypeConverter, type EnergyAppModbusRegisterConfig, type EnergyAppRegisterMap, type RegisterReadResult } from './interfaces.cjs';
+import { type EnergyAppModbusRegisterConfig, type EnergyAppRegisterMap, type IDataTypeConverter, type IRegisterMapper, type IRegisterReader, type RegisterReadResult } from './interfaces.cjs';
 export declare class EnergyAppModbusRegisterMapper implements IRegisterMapper {
     private readonly dataTypeConverter;
     constructor(dataTypeConverter?: IDataTypeConverter);
-    readRegister<T>(reader: IRegisterReader, config: EnergyAppModbusRegisterConfig): Promise<RegisterReadResult<T>>;
+    readRegister<T, E>(reader: IRegisterReader, config: EnergyAppModbusRegisterConfig<E>): Promise<RegisterReadResult<T>>;
     readMultipleRegisters(reader: IRegisterReader, registerMap: EnergyAppRegisterMap): Promise<{
         [key: string]: any;
     }>;