jmri-client 4.2.0-beta.1 → 5.0.0

package/docs/API.md

@@ -65,6 +65,9 @@ client.on('heartbeat:timeout', () => { });
 // Get current power state
 const state: PowerState = await client.getPower();
 
+// Get power state for a specific hardware connection (see System Connections)
+const state: PowerState = await client.getPower('L');  // LocoNet prefix
+
 // PowerState enum values (from JMRI JSON protocol):
 // PowerState.UNKNOWN = 0  (state cannot be determined)
 // PowerState.ON = 2       (power is on)
@@ -83,10 +86,15 @@ switch (state) {
     break;
 }
 
-// Set power
+// Set power (all connections, or a specific one)
 await client.setPower(PowerState.ON);
-await client.powerOn();   // Convenience method
-await client.powerOff();  // Convenience method
+await client.setPower(PowerState.ON, 'L');  // LocoNet only
+
+// Convenience methods — all accept an optional prefix
+await client.powerOn();         // All connections
+await client.powerOn('L');      // LocoNet only
+await client.powerOff();        // All connections
+await client.powerOff('D');     // DCC++ only
 
 // Listen for power changes (including UNKNOWN states)
 client.on('power:changed', (state: PowerState) => {
@@ -96,6 +104,29 @@ client.on('power:changed', (state: PowerState) => {
 });
 ```
 
+## System Connections
+
+Discover the hardware connections JMRI has configured and their short prefix strings. Use these prefixes to target power and throttle commands at a specific connection when multiple are active.
+
+```typescript
+// List all available system connections
+const connections: SystemConnectionData[] = await client.getSystemConnections();
+// [
+//   { name: 'LocoNet', prefix: 'L', userName: 'LocoNet' },
+//   { name: 'DCC++', prefix: 'D' }
+// ]
+
+// Use a prefix to target a specific connection
+const [loconet] = connections.filter(c => c.name === 'LocoNet');
+await client.powerOn(loconet.prefix);
+
+// Acquire a throttle on a specific connection
+const throttleId = await client.acquireThrottle({
+  address: 3,
+  prefix: loconet.prefix
+});
+```
+
 ## Roster Management
 
 ```typescript
@@ -150,6 +181,9 @@ client.on('light:changed', (name: string, state: LightState) => {
 // Acquire throttle
 const throttleId = await client.acquireThrottle({ address: 3 });
 
+// Acquire throttle on a specific hardware connection
+const throttleId = await client.acquireThrottle({ address: 3, prefix: 'L' });
+
 // Control speed (0.0 to 1.0)
 await client.setThrottleSpeed(throttleId, 0.0);   // Stopped
 await client.setThrottleSpeed(throttleId, 0.5);   // Half speed
@@ -237,6 +271,7 @@ import {
   TurnoutData,
   ThrottleState,
   ThrottleFunctionKey,
-  ConnectionState
+  ConnectionState,
+  SystemConnectionData
 } from 'jmri-client';
 ```

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/EXAMPLES.md

@@ -283,6 +283,48 @@ async function runLayout() {
 runLayout();
 ```
 
+## Multi-Connection / Hardware Prefix
+
+When JMRI is configured with more than one hardware connection (e.g. both LocoNet and DCC++), use `getSystemConnections()` to discover the available prefixes, then pass them to power and throttle commands to target a specific connection.
+
+```typescript
+import { JmriClient } from 'jmri-client';
+
+const client = new JmriClient({ host: 'jmri.local' });
+
+client.on('connected', async () => {
+  // Discover what hardware connections JMRI has configured
+  const connections = await client.getSystemConnections();
+  console.log('Available connections:');
+  for (const conn of connections) {
+    console.log(`  ${conn.name} (prefix: "${conn.prefix}")`);
+  }
+  // Available connections:
+  //   LocoNet (prefix: "L")
+  //   DCC++ (prefix: "D")
+
+  // Power on via LocoNet only
+  await client.powerOn('L');
+
+  // Acquire a throttle on LocoNet
+  const throttle = await client.acquireThrottle({ address: 3, prefix: 'L' });
+  await client.setThrottleDirection(throttle, true);
+  await client.setThrottleSpeed(throttle, 0.3);
+
+  await new Promise(resolve => setTimeout(resolve, 5000));
+
+  await client.setThrottleSpeed(throttle, 0);
+  await client.releaseThrottle(throttle);
+
+  // Power off via LocoNet only
+  await client.powerOff('L');
+
+  await client.disconnect();
+});
+```
+
+Single-connection layouts work exactly as before — just omit the prefix and JMRI routes to the default connection.
+
 ## CommonJS Usage
 
 ```javascript

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.1",
+  "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;