jmri-client 4.2.0-beta.2 → 5.0.0

package/docs/BROWSER.md

@@ -1,6 +1,6 @@
 # Browser Usage Guide
 
-jmri-client v3.2.0+ supports both Node.js and browser environments. This guide shows how to use jmri-client in web applications.
+jmri-client supports both Node.js and browser environments. This guide shows how to use jmri-client in web applications.
 
 ## Installation
 
@@ -112,7 +112,7 @@ For quick prototypes without a build step, use the browser bundle:
 
   <script type="module">
     // Use the browser bundle from CDN
-    import { JmriClient } from 'https://unpkg.com/jmri-client@3.3.0/dist/browser/jmri-client.js';
+    import { JmriClient } from 'https://unpkg.com/jmri-client@5.0.0/dist/browser/jmri-client.js';
 
     const client = new JmriClient({
       host: 'localhost',
@@ -144,8 +144,8 @@ For quick prototypes without a build step, use the browser bundle:
 ```
 
 Alternative CDNs:
-- **unpkg**: `https://unpkg.com/jmri-client@3.3.0/dist/browser/jmri-client.js`
-- **jsDelivr**: `https://cdn.jsdelivr.net/npm/jmri-client@3.3.0/dist/browser/jmri-client.js`
+- **unpkg**: `https://unpkg.com/jmri-client@5.0.0/dist/browser/jmri-client.js`
+- **jsDelivr**: `https://cdn.jsdelivr.net/npm/jmri-client@5.0.0/dist/browser/jmri-client.js`
 
 ## React Example
 

package/docs/MIGRATION.md

@@ -1,4 +1,33 @@
-# Migration Guide: v2.x to v3.x
+# Migration Guide
+
+## v4.x to v5.0
+
+### Breaking Changes
+
+#### Node.js version requirement
+
+**v4.x:** Node.js 18+
+**v5.0:** Node.js 22+
+
+Node 18 reached end-of-life in April 2025 and Node 20 in April 2026. v5.0 requires Node 22 (Active LTS, EOL April 2027) or later.
+
+```bash
+node --version  # Should be >= 22.0.0
+```
+
+#### No API changes
+
+There are no API-level breaking changes between v4.x and v5.0. All existing code targeting v4.x will work without modification.
+
+### What's new in v5.0
+
+- Node.js 22+ required (drops EOL Node 18 and 20)
+- Built with TypeScript 6
+- esbuild-based build pipeline — faster, smaller outputs, no more dual `tsc` compilation
+
+---
+
+## v2.x to v3.x
 
 ## Overview
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jmri-client",
-  "version": "4.2.0-beta.2",
+  "version": "5.0.0",
   "description": "WebSocket client for JMRI with real-time updates and throttle control - works in both Node.js and browsers",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -8,19 +8,18 @@
   "types": "./dist/types/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/types/index.d.ts",
       "browser": "./dist/browser/jmri-client.js",
       "import": "./dist/esm/index.js",
-      "require": "./dist/cjs/index.js",
-      "types": "./dist/types/index.d.ts"
+      "require": "./dist/cjs/index.js"
     }
   },
   "scripts": {
     "prepublishOnly": "npm run build",
-    "build": "npm run build:cjs && npm run build:esm && npm run build:types && npm run build:browser",
-    "build:cjs": "tsc -p tsconfig.json",
-    "build:esm": "tsc -p tsconfig.esm.json",
-    "build:types": "tsc -p tsconfig.json --declaration --emitDeclarationOnly --outDir dist/types",
-    "build:browser": "node build-browser.mjs",
+    "clean": "rm -rf dist",
+    "build": "npm run clean && node build.mjs && npm run build:types",
+    "build:types": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "jest --no-cache --coverage",
     "test:browser": "node ./tests/integration/serve-test.mjs",
     "test:reconnect": "node ./tests/integration/forced-reconnect.mjs",
@@ -59,21 +58,21 @@
     "url": "https://github.com/yamanote1138/jmri-client/issues"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "devDependencies": {
-    "@types/jest": "^29.0.3",
-    "@types/node": "^18.19.0",
-    "@types/ws": "^8.5.10",
-    "esbuild": "^0.27.3",
-    "jest": "^29.0.3",
-    "playwright": "^1.58.2",
-    "ts-jest": "^29.4.6",
-    "typescript": "^5.3.3"
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.18.0",
+    "esbuild": "^0.28.0",
+    "jest": "^30.0.0",
+    "playwright": "^1.60.0",
+    "ts-jest": "^29.4.11",
+    "typescript": "^6.0.0"
   },
   "dependencies": {
     "eventemitter3": "^5.0.4",
-    "ws": "^8.16.0"
+    "ws": "^8.21.0"
   },
   "files": [
     "dist",

package/dist/cjs/client.js

@@ -1,366 +0,0 @@
-"use strict";
-/**
- * Main JMRI client class
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.JmriClient = void 0;
-const eventemitter3_1 = require("eventemitter3");
-const websocket_client_js_1 = require("./core/websocket-client.js");
-const power_manager_js_1 = require("./managers/power-manager.js");
-const roster_manager_js_1 = require("./managers/roster-manager.js");
-const throttle_manager_js_1 = require("./managers/throttle-manager.js");
-const turnout_manager_js_1 = require("./managers/turnout-manager.js");
-const light_manager_js_1 = require("./managers/light-manager.js");
-const system_connections_manager_js_1 = require("./managers/system-connections-manager.js");
-const client_options_js_1 = require("./types/client-options.js");
-/**
- * JMRI WebSocket Client
- * Provides event-driven interface to JMRI with throttle control
- */
-class JmriClient extends eventemitter3_1.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 = (0, client_options_js_1.mergeOptions)(options);
-        // Create WebSocket client
-        this.wsClient = new websocket_client_js_1.WebSocketClient(this.options);
-        // Create managers
-        this.powerManager = new power_manager_js_1.PowerManager(this.wsClient);
-        this.rosterManager = new roster_manager_js_1.RosterManager(this.wsClient);
-        this.throttleManager = new throttle_manager_js_1.ThrottleManager(this.wsClient);
-        this.turnoutManager = new turnout_manager_js_1.TurnoutManager(this.wsClient);
-        this.lightManager = new light_manager_js_1.LightManager(this.wsClient);
-        this.systemConnectionsManager = new system_connections_manager_js_1.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();
-    }
-}
-exports.JmriClient = JmriClient;

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

@@ -1,84 +0,0 @@
-"use strict";
-/**
- * Connection state management with state machine
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ConnectionStateManager = void 0;
-const eventemitter3_1 = require("eventemitter3");
-const events_js_1 = require("../types/events.js");
-/**
- * Valid state transitions
- */
-const VALID_TRANSITIONS = {
-    [events_js_1.ConnectionState.DISCONNECTED]: [events_js_1.ConnectionState.CONNECTING],
-    [events_js_1.ConnectionState.CONNECTING]: [events_js_1.ConnectionState.CONNECTED, events_js_1.ConnectionState.DISCONNECTED],
-    [events_js_1.ConnectionState.CONNECTED]: [events_js_1.ConnectionState.DISCONNECTED, events_js_1.ConnectionState.RECONNECTING],
-    [events_js_1.ConnectionState.RECONNECTING]: [events_js_1.ConnectionState.CONNECTING, events_js_1.ConnectionState.CONNECTED, events_js_1.ConnectionState.DISCONNECTED]
-};
-/**
- * Manages connection state with validation
- */
-class ConnectionStateManager extends eventemitter3_1.EventEmitter {
-    constructor() {
-        super(...arguments);
-        this.currentState = events_js_1.ConnectionState.DISCONNECTED;
-    }
-    /**
-     * Get current connection state
-     */
-    getState() {
-        return this.currentState;
-    }
-    /**
-     * Check if currently connected
-     */
-    isConnected() {
-        return this.currentState === events_js_1.ConnectionState.CONNECTED;
-    }
-    /**
-     * Check if currently connecting
-     */
-    isConnecting() {
-        return this.currentState === events_js_1.ConnectionState.CONNECTING;
-    }
-    /**
-     * Check if currently disconnected
-     */
-    isDisconnected() {
-        return this.currentState === events_js_1.ConnectionState.DISCONNECTED;
-    }
-    /**
-     * Check if currently reconnecting
-     */
-    isReconnecting() {
-        return this.currentState === events_js_1.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(events_js_1.ConnectionState.DISCONNECTED);
-    }
-}
-exports.ConnectionStateManager = ConnectionStateManager;

package/dist/cjs/core/heartbeat-manager.js

@@ -1,79 +0,0 @@
-"use strict";
-/**
- * Heartbeat (ping/pong) management
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.HeartbeatManager = void 0;
-const eventemitter3_1 = require("eventemitter3");
-/**
- * Manages WebSocket heartbeat via ping/pong
- */
-class HeartbeatManager extends eventemitter3_1.EventEmitter {
-    constructor(options) {
-        super();
-        this.isRunning = false;
-        this.options = options;
-    }
-    /**
-     * Start heartbeat monitoring
-     * @param sendPing - Callback to send ping message
-     */
-    start(sendPing) {
-        if (!this.options.enabled || this.isRunning) {
-            return;
-        }
-        this.isRunning = true;
-        // Send ping at regular intervals
-        this.pingInterval = setInterval(() => {
-            sendPing();
-            this.emit('pingSent');
-            // Start pong timeout
-            this.pongTimeout = setTimeout(() => {
-                this.emit('timeout');
-            }, this.options.timeout);
-        }, this.options.interval);
-    }
-    /**
-     * Stop heartbeat monitoring
-     */
-    stop() {
-        this.isRunning = false;
-        if (this.pingInterval) {
-            clearInterval(this.pingInterval);
-            this.pingInterval = undefined;
-        }
-        if (this.pongTimeout) {
-            clearTimeout(this.pongTimeout);
-            this.pongTimeout = undefined;
-        }
-    }
-    /**
-     * Handle pong received from server
-     */
-    receivedPong() {
-        // Clear pong timeout
-        if (this.pongTimeout) {
-            clearTimeout(this.pongTimeout);
-            this.pongTimeout = undefined;
-        }
-        this.emit('pongReceived');
-    }
-    /**
-     * Check if heartbeat is running
-     */
-    running() {
-        return this.isRunning;
-    }
-    /**
-     * Update heartbeat options
-     */
-    updateOptions(options) {
-        const wasRunning = this.isRunning;
-        if (wasRunning) {
-            this.stop();
-        }
-        this.options = { ...this.options, ...options };
-        // Note: Caller must call start() again if needed
-    }
-}
-exports.HeartbeatManager = HeartbeatManager;

package/dist/cjs/core/index.js

@@ -1,25 +0,0 @@
-"use strict";
-/**
- * Core infrastructure exports
- */
-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("./websocket-client.js"), exports);
-__exportStar(require("./websocket-adapter.js"), exports);
-__exportStar(require("./connection-state-manager.js"), exports);
-__exportStar(require("./reconnection-manager.js"), exports);
-__exportStar(require("./heartbeat-manager.js"), exports);
-__exportStar(require("./message-queue.js"), exports);