jmri-client 4.2.0-beta.2 → 5.1.0

package/dist/cjs/types/jmri-messages.js

@@ -1,95 +0,0 @@
-"use strict";
-/**
- * JMRI WebSocket Protocol Message Types
- * Based on JMRI JSON protocol specification
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.LightState = exports.TurnoutState = exports.PowerState = void 0;
-exports.powerStateToString = powerStateToString;
-exports.turnoutStateToString = turnoutStateToString;
-exports.lightStateToString = lightStateToString;
-/**
- * Power state values (from JMRI JSON protocol constants)
- * UNKNOWN = 0 (state cannot be determined)
- * ON = 2 (power is on)
- * OFF = 4 (power is off)
- */
-var PowerState;
-(function (PowerState) {
-    PowerState[PowerState["UNKNOWN"] = 0] = "UNKNOWN";
-    PowerState[PowerState["ON"] = 2] = "ON";
-    PowerState[PowerState["OFF"] = 4] = "OFF";
-})(PowerState || (exports.PowerState = PowerState = {}));
-/**
- * Convert PowerState enum to human-readable string
- * @param state - The power state
- * @returns 'ON', 'OFF', or 'UNKNOWN'
- */
-function powerStateToString(state) {
-    switch (state) {
-        case PowerState.ON:
-            return 'ON';
-        case PowerState.OFF:
-            return 'OFF';
-        case PowerState.UNKNOWN:
-            return 'UNKNOWN';
-        default:
-            return 'UNKNOWN';
-    }
-}
-/**
- * Turnout state values (from JMRI JSON protocol constants)
- * UNKNOWN = 0 (state cannot be determined)
- * CLOSED = 2 (straight through / normal position)
- * THROWN = 4 (diverging route position)
- * INCONSISTENT = 8 (contradictory feedback state)
- */
-var TurnoutState;
-(function (TurnoutState) {
-    TurnoutState[TurnoutState["UNKNOWN"] = 0] = "UNKNOWN";
-    TurnoutState[TurnoutState["CLOSED"] = 2] = "CLOSED";
-    TurnoutState[TurnoutState["THROWN"] = 4] = "THROWN";
-    TurnoutState[TurnoutState["INCONSISTENT"] = 8] = "INCONSISTENT";
-})(TurnoutState || (exports.TurnoutState = TurnoutState = {}));
-/**
- * Convert TurnoutState enum to human-readable string
- */
-function turnoutStateToString(state) {
-    switch (state) {
-        case TurnoutState.CLOSED:
-            return 'CLOSED';
-        case TurnoutState.THROWN:
-            return 'THROWN';
-        case TurnoutState.INCONSISTENT:
-            return 'INCONSISTENT';
-        case TurnoutState.UNKNOWN:
-        default:
-            return 'UNKNOWN';
-    }
-}
-/**
- * Light state values (from JMRI JSON protocol constants)
- * UNKNOWN = 0 (state cannot be determined)
- * ON = 2 (light is on)
- * OFF = 4 (light is off)
- */
-var LightState;
-(function (LightState) {
-    LightState[LightState["UNKNOWN"] = 0] = "UNKNOWN";
-    LightState[LightState["ON"] = 2] = "ON";
-    LightState[LightState["OFF"] = 4] = "OFF";
-})(LightState || (exports.LightState = LightState = {}));
-/**
- * Convert LightState enum to human-readable string
- */
-function lightStateToString(state) {
-    switch (state) {
-        case LightState.ON:
-            return 'ON';
-        case LightState.OFF:
-            return 'OFF';
-        case LightState.UNKNOWN:
-        default:
-            return 'UNKNOWN';
-    }
-}

package/dist/cjs/types/throttle.js

@@ -1,19 +0,0 @@
-"use strict";
-/**
- * Throttle-specific types
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.isThrottleFunctionKey = isThrottleFunctionKey;
-exports.isValidSpeed = isValidSpeed;
-/**
- * Validates that a value is a valid throttle function key
- */
-function isThrottleFunctionKey(key) {
-    return /^F([0-9]|1[0-9]|2[0-8])$/.test(key);
-}
-/**
- * Validates that speed is in valid range (0.0 to 1.0)
- */
-function isValidSpeed(speed) {
-    return typeof speed === 'number' && speed >= 0 && speed <= 1;
-}

package/dist/cjs/utils/exponential-backoff.js

@@ -1,40 +0,0 @@
-"use strict";
-/**
- * Exponential backoff calculator with jitter
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.calculateBackoffDelay = calculateBackoffDelay;
-exports.shouldReconnect = shouldReconnect;
-/**
- * Calculate next reconnection delay using exponential backoff
- *
- * @param attempt - Current attempt number (1-indexed)
- * @param options - Reconnection options
- * @returns Delay in milliseconds
- */
-function calculateBackoffDelay(attempt, options) {
-    // Base delay calculation: initialDelay * (multiplier ^ (attempt - 1))
-    const exponentialDelay = options.initialDelay * Math.pow(options.multiplier, attempt - 1);
-    // Cap at maxDelay
-    const cappedDelay = Math.min(exponentialDelay, options.maxDelay);
-    // Add jitter if enabled (±25%)
-    if (options.jitter) {
-        const jitterAmount = cappedDelay * 0.25;
-        const jitter = (Math.random() * 2 - 1) * jitterAmount; // Random between -25% and +25%
-        return Math.max(0, Math.round(cappedDelay + jitter));
-    }
-    return Math.round(cappedDelay);
-}
-/**
- * Check if should attempt reconnection
- *
- * @param attempt - Current attempt number (1-indexed)
- * @param maxAttempts - Maximum attempts (0 = infinite)
- * @returns True if should attempt reconnection
- */
-function shouldReconnect(attempt, maxAttempts) {
-    if (maxAttempts === 0) {
-        return true; // Infinite attempts
-    }
-    return attempt <= maxAttempts;
-}

package/dist/cjs/utils/index.js

@@ -1,21 +0,0 @@
-"use strict";
-/**
- * Utility functions
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./message-id.js"), exports);
-__exportStar(require("./exponential-backoff.js"), exports);

package/dist/cjs/utils/message-id.js

@@ -1,40 +0,0 @@
-"use strict";
-/**
- * Message ID generator for request/response correlation
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MessageIdGenerator = void 0;
-/**
- * Sequential message ID generator
- * Provides unique IDs for correlating requests and responses
- */
-class MessageIdGenerator {
-    constructor() {
-        this.currentId = 0;
-        this.maxId = Number.MAX_SAFE_INTEGER;
-    }
-    /**
-     * Generate next sequential ID
-     * Wraps around at MAX_SAFE_INTEGER
-     */
-    next() {
-        this.currentId++;
-        if (this.currentId >= this.maxId) {
-            this.currentId = 1;
-        }
-        return this.currentId;
-    }
-    /**
-     * Reset ID counter to 0
-     */
-    reset() {
-        this.currentId = 0;
-    }
-    /**
-     * Get current ID without incrementing
-     */
-    current() {
-        return this.currentId;
-    }
-}
-exports.MessageIdGenerator = MessageIdGenerator;

package/dist/esm/client.js

@@ -1,362 +0,0 @@
-/**
- * Main JMRI client class
- */
-import { EventEmitter } from 'eventemitter3';
-import { WebSocketClient } from './core/websocket-client.js';
-import { PowerManager } from './managers/power-manager.js';
-import { RosterManager } from './managers/roster-manager.js';
-import { ThrottleManager } from './managers/throttle-manager.js';
-import { TurnoutManager } from './managers/turnout-manager.js';
-import { LightManager } from './managers/light-manager.js';
-import { SystemConnectionsManager } from './managers/system-connections-manager.js';
-import { mergeOptions } from './types/client-options.js';
-/**
- * JMRI WebSocket Client
- * Provides event-driven interface to JMRI with throttle control
- */
-export class JmriClient extends EventEmitter {
-    /**
-     * Create a new JMRI client
-     *
-     * @param options - Client configuration options
-     *
-     * @example
-     * ```typescript
-     * const client = new JmriClient({
-     *   host: 'jmri.local',
-     *   port: 12080
-     * });
-     *
-     * client.on('connected', () => console.log('Connected!'));
-     * client.on('power:changed', (state) => console.log('Power:', state));
-     * ```
-     */
-    constructor(options) {
-        super();
-        // Merge options with defaults
-        this.options = mergeOptions(options);
-        // Create WebSocket client
-        this.wsClient = new WebSocketClient(this.options);
-        // Create managers
-        this.powerManager = new PowerManager(this.wsClient);
-        this.rosterManager = new RosterManager(this.wsClient);
-        this.throttleManager = new ThrottleManager(this.wsClient);
-        this.turnoutManager = new TurnoutManager(this.wsClient);
-        this.lightManager = new LightManager(this.wsClient);
-        this.systemConnectionsManager = new SystemConnectionsManager(this.wsClient);
-        // Forward events from WebSocket client
-        this.wsClient.on('connected', () => this.emit('connected'));
-        this.wsClient.on('disconnected', (reason) => this.emit('disconnected', reason));
-        this.wsClient.on('reconnecting', (attempt, delay) => this.emit('reconnecting', attempt, delay));
-        this.wsClient.on('reconnected', () => this.emit('reconnected'));
-        this.wsClient.on('reconnectionFailed', (attempts) => this.emit('reconnectionFailed', attempts));
-        this.wsClient.on('connectionStateChanged', (state) => this.emit('connectionStateChanged', state));
-        this.wsClient.on('error', (error) => this.emit('error', error));
-        this.wsClient.on('heartbeat:sent', () => this.emit('heartbeat:sent'));
-        this.wsClient.on('heartbeat:timeout', () => this.emit('heartbeat:timeout'));
-        this.wsClient.on('hello', (data) => this.emit('hello', data));
-        // Forward events from managers
-        this.powerManager.on('power:changed', (state) => this.emit('power:changed', state));
-        this.turnoutManager.on('turnout:changed', (name, state) => this.emit('turnout:changed', name, state));
-        this.lightManager.on('light:changed', (name, state) => this.emit('light:changed', name, state));
-        this.throttleManager.on('throttle:acquired', (id) => this.emit('throttle:acquired', id));
-        this.throttleManager.on('throttle:updated', (id, data) => this.emit('throttle:updated', id, data));
-        this.throttleManager.on('throttle:released', (id) => this.emit('throttle:released', id));
-        this.throttleManager.on('throttle:lost', (id) => this.emit('throttle:lost', id));
-        // Auto-connect if enabled
-        if (this.options.autoConnect) {
-            this.connect().catch((error) => {
-                this.emit('error', error);
-            });
-        }
-    }
-    /**
-     * Connect to JMRI server
-     */
-    async connect() {
-        return this.wsClient.connect();
-    }
-    /**
-     * Disconnect from JMRI server
-     * Releases all throttles and closes connection
-     */
-    async disconnect() {
-        // Release all throttles first
-        await this.throttleManager.releaseAllThrottles();
-        // Disconnect WebSocket
-        return this.wsClient.disconnect();
-    }
-    /**
-     * Get current connection state
-     */
-    getConnectionState() {
-        return this.wsClient.getState();
-    }
-    /**
-     * Check if connected to JMRI
-     */
-    isConnected() {
-        return this.wsClient.isConnected();
-    }
-    // ============================================================================
-    // Power Control
-    // ============================================================================
-    /**
-     * Get current track power state
-     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
-     */
-    async getPower(prefix) {
-        return this.powerManager.getPower(prefix);
-    }
-    /**
-     * Set track power state
-     * @param state - The desired power state
-     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
-     */
-    async setPower(state, prefix) {
-        return this.powerManager.setPower(state, prefix);
-    }
-    /**
-     * Turn track power on
-     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
-     */
-    async powerOn(prefix) {
-        return this.powerManager.powerOn(prefix);
-    }
-    /**
-     * Turn track power off
-     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
-     */
-    async powerOff(prefix) {
-        return this.powerManager.powerOff(prefix);
-    }
-    // ============================================================================
-    // System Connections
-    // ============================================================================
-    /**
-     * List all available JMRI system connections and their prefixes.
-     * Use the returned prefix values with power and throttle commands to
-     * target a specific hardware connection when multiple are configured.
-     *
-     * @example
-     * ```typescript
-     * const connections = await client.getSystemConnections();
-     * // [{ name: 'LocoNet', prefix: 'L' }, { name: 'DCC++', prefix: 'D' }]
-     * await client.powerOn('L'); // power on via LocoNet only
-     * ```
-     */
-    async getSystemConnections() {
-        return this.systemConnectionsManager.getSystemConnections();
-    }
-    // ============================================================================
-    // Roster Management
-    // ============================================================================
-    /**
-     * Get all roster entries
-     */
-    async getRoster() {
-        return this.rosterManager.getRoster();
-    }
-    /**
-     * Get roster entry by name
-     */
-    async getRosterEntryByName(name) {
-        return this.rosterManager.getRosterEntryByName(name);
-    }
-    /**
-     * Get roster entry by address
-     */
-    async getRosterEntryByAddress(address) {
-        return this.rosterManager.getRosterEntryByAddress(address);
-    }
-    /**
-     * Search roster by partial name match
-     */
-    async searchRoster(query) {
-        return this.rosterManager.searchRoster(query);
-    }
-    // ============================================================================
-    // Turnout Control
-    // ============================================================================
-    /**
-     * Get the current state of a turnout
-     */
-    async getTurnout(name) {
-        return this.turnoutManager.getTurnout(name);
-    }
-    /**
-     * Set a turnout to the given state
-     */
-    async setTurnout(name, state) {
-        return this.turnoutManager.setTurnout(name, state);
-    }
-    /**
-     * Throw a turnout (diverging route)
-     */
-    async throwTurnout(name) {
-        return this.turnoutManager.throwTurnout(name);
-    }
-    /**
-     * Close a turnout (straight through / normal)
-     */
-    async closeTurnout(name) {
-        return this.turnoutManager.closeTurnout(name);
-    }
-    /**
-     * List all turnouts known to JMRI
-     */
-    async listTurnouts() {
-        return this.turnoutManager.listTurnouts();
-    }
-    /**
-     * Get cached turnout state without a network request
-     */
-    getTurnoutState(name) {
-        return this.turnoutManager.getTurnoutState(name);
-    }
-    /**
-     * Get all cached turnout states
-     */
-    getCachedTurnouts() {
-        return this.turnoutManager.getCachedTurnouts();
-    }
-    // ============================================================================
-    // Light Control
-    // ============================================================================
-    /**
-     * Get the current state of a light
-     */
-    async getLight(name) {
-        return this.lightManager.getLight(name);
-    }
-    /**
-     * Set a light to the given state
-     */
-    async setLight(name, state) {
-        return this.lightManager.setLight(name, state);
-    }
-    /**
-     * Turn a light on
-     */
-    async turnOnLight(name) {
-        return this.lightManager.turnOnLight(name);
-    }
-    /**
-     * Turn a light off
-     */
-    async turnOffLight(name) {
-        return this.lightManager.turnOffLight(name);
-    }
-    /**
-     * List all lights known to JMRI
-     */
-    async listLights() {
-        return this.lightManager.listLights();
-    }
-    /**
-     * Get cached light state without a network request
-     */
-    getLightState(name) {
-        return this.lightManager.getLightState(name);
-    }
-    /**
-     * Get all cached light states
-     */
-    getCachedLights() {
-        return this.lightManager.getCachedLights();
-    }
-    // ============================================================================
-    // Throttle Control
-    // ============================================================================
-    /**
-     * Acquire a throttle for a locomotive
-     *
-     * @param options - Throttle acquisition options
-     * @returns Throttle ID for use in other throttle methods
-     *
-     * @example
-     * ```typescript
-     * const throttleId = await client.acquireThrottle({ address: 3 });
-     * await client.setThrottleSpeed(throttleId, 0.5); // Half speed
-     * ```
-     */
-    async acquireThrottle(options) {
-        return this.throttleManager.acquireThrottle(options);
-    }
-    /**
-     * Release a throttle
-     */
-    async releaseThrottle(throttleId) {
-        return this.throttleManager.releaseThrottle(throttleId);
-    }
-    /**
-     * Set throttle speed (0.0 to 1.0)
-     *
-     * @param throttleId - Throttle ID from acquireThrottle
-     * @param speed - Speed value between 0.0 (stopped) and 1.0 (full speed)
-     */
-    async setThrottleSpeed(throttleId, speed) {
-        return this.throttleManager.setSpeed(throttleId, speed);
-    }
-    /**
-     * Set throttle direction
-     *
-     * @param throttleId - Throttle ID from acquireThrottle
-     * @param forward - True for forward, false for reverse
-     */
-    async setThrottleDirection(throttleId, forward) {
-        return this.throttleManager.setDirection(throttleId, forward);
-    }
-    /**
-     * Set throttle function (F0-F28)
-     *
-     * @param throttleId - Throttle ID from acquireThrottle
-     * @param functionKey - Function key (F0-F28)
-     * @param value - True to activate, false to deactivate
-     *
-     * @example
-     * ```typescript
-     * await client.setThrottleFunction(throttleId, 'F0', true);  // Headlight on
-     * await client.setThrottleFunction(throttleId, 'F2', true);  // Horn
-     * ```
-     */
-    async setThrottleFunction(throttleId, functionKey, value) {
-        return this.throttleManager.setFunction(throttleId, functionKey, value);
-    }
-    /**
-     * Emergency stop for a throttle (speed to 0)
-     */
-    async emergencyStop(throttleId) {
-        return this.throttleManager.emergencyStop(throttleId);
-    }
-    /**
-     * Set throttle to idle (speed to 0, maintain direction)
-     */
-    async idleThrottle(throttleId) {
-        return this.throttleManager.idle(throttleId);
-    }
-    /**
-     * Get throttle state
-     */
-    getThrottleState(throttleId) {
-        return this.throttleManager.getThrottleState(throttleId);
-    }
-    /**
-     * Get all throttle IDs
-     */
-    getThrottleIds() {
-        return this.throttleManager.getThrottleIds();
-    }
-    /**
-     * Get all throttle states
-     */
-    getAllThrottles() {
-        return this.throttleManager.getAllThrottles();
-    }
-    /**
-     * Release all throttles
-     */
-    async releaseAllThrottles() {
-        return this.throttleManager.releaseAllThrottles();
-    }
-}

package/dist/esm/core/connection-state-manager.js

@@ -1,80 +0,0 @@
-/**
- * Connection state management with state machine
- */
-import { EventEmitter } from 'eventemitter3';
-import { ConnectionState } from '../types/events.js';
-/**
- * Valid state transitions
- */
-const VALID_TRANSITIONS = {
-    [ConnectionState.DISCONNECTED]: [ConnectionState.CONNECTING],
-    [ConnectionState.CONNECTING]: [ConnectionState.CONNECTED, ConnectionState.DISCONNECTED],
-    [ConnectionState.CONNECTED]: [ConnectionState.DISCONNECTED, ConnectionState.RECONNECTING],
-    [ConnectionState.RECONNECTING]: [ConnectionState.CONNECTING, ConnectionState.CONNECTED, ConnectionState.DISCONNECTED]
-};
-/**
- * Manages connection state with validation
- */
-export class ConnectionStateManager extends EventEmitter {
-    constructor() {
-        super(...arguments);
-        this.currentState = ConnectionState.DISCONNECTED;
-    }
-    /**
-     * Get current connection state
-     */
-    getState() {
-        return this.currentState;
-    }
-    /**
-     * Check if currently connected
-     */
-    isConnected() {
-        return this.currentState === ConnectionState.CONNECTED;
-    }
-    /**
-     * Check if currently connecting
-     */
-    isConnecting() {
-        return this.currentState === ConnectionState.CONNECTING;
-    }
-    /**
-     * Check if currently disconnected
-     */
-    isDisconnected() {
-        return this.currentState === ConnectionState.DISCONNECTED;
-    }
-    /**
-     * Check if currently reconnecting
-     */
-    isReconnecting() {
-        return this.currentState === ConnectionState.RECONNECTING;
-    }
-    /**
-     * Transition to new state
-     * Validates transition and emits event
-     */
-    transition(newState) {
-        const validTransitions = VALID_TRANSITIONS[this.currentState];
-        if (!validTransitions.includes(newState)) {
-            throw new Error(`Invalid state transition: ${this.currentState} -> ${newState}`);
-        }
-        const previousState = this.currentState;
-        this.currentState = newState;
-        this.emit('stateChanged', newState, previousState);
-    }
-    /**
-     * Force state without validation (use with caution)
-     */
-    forceState(newState) {
-        const previousState = this.currentState;
-        this.currentState = newState;
-        this.emit('stateChanged', newState, previousState);
-    }
-    /**
-     * Reset to disconnected state
-     */
-    reset() {
-        this.forceState(ConnectionState.DISCONNECTED);
-    }
-}