jmri-client 4.2.0-beta.2 → 5.1.0

package/dist/types/client.d.ts

@@ -4,7 +4,7 @@
 import { EventEmitter } from 'eventemitter3';
 import { WebSocketClient } from './core/websocket-client.js';
 import { PartialClientOptions } from './types/client-options.js';
-import { PowerState, RosterEntryWrapper, TurnoutState, TurnoutData, LightState, LightData, SystemConnectionData } from './types/jmri-messages.js';
+import { PowerState, RosterEntryWrapper, RosterGroup, TurnoutState, TurnoutData, LightState, LightData, SystemConnectionData } from './types/jmri-messages.js';
 import { ConnectionState } from './types/events.js';
 import { ThrottleAcquireOptions, ThrottleFunctionKey, ThrottleState } from './types/throttle.js';
 /**
@@ -104,6 +104,14 @@ export declare class JmriClient extends EventEmitter {
      * Search roster by partial name match
      */
     searchRoster(query: string): Promise<RosterEntryWrapper[]>;
+    /**
+     * Get all roster groups
+     */
+    getRosterGroups(): Promise<RosterGroup[]>;
+    /**
+     * Get roster entries belonging to a specific group
+     */
+    getRosterEntriesByGroup(group: string): Promise<RosterEntryWrapper[]>;
     /**
      * Get the current state of a turnout
      */

package/dist/types/index.d.ts

@@ -4,7 +4,7 @@
  */
 export { JmriClient } from './client.js';
 export { WebSocketClient } from './core/websocket-client.js';
-export { JmriClientOptions, PartialClientOptions, ReconnectionOptions, HeartbeatOptions, MockOptions, PowerState, TurnoutState, LightState, RosterEntry, TurnoutData, LightData, JmriMessage, PowerMessage, TurnoutMessage, LightMessage, ThrottleMessage, RosterMessage, ConnectionState, EventPayloads, ThrottleAcquireOptions, ThrottleFunctionKey, ThrottleState } from './types/index.js';
+export { JmriClientOptions, PartialClientOptions, ReconnectionOptions, HeartbeatOptions, MockOptions, PowerState, TurnoutState, LightState, RosterEntry, RosterGroup, TurnoutData, LightData, JmriMessage, PowerMessage, TurnoutMessage, LightMessage, ThrottleMessage, RosterMessage, ConnectionState, EventPayloads, ThrottleAcquireOptions, ThrottleFunctionKey, ThrottleState } from './types/index.js';
 export { isThrottleFunctionKey, isValidSpeed } from './types/throttle.js';
 export { powerStateToString, turnoutStateToString, lightStateToString } from './types/jmri-messages.js';
 export { MockResponseManager, mockResponseManager, mockData } from './mocks/index.js';

package/dist/types/managers/roster-manager.d.ts

@@ -2,7 +2,7 @@
  * Roster management
  */
 import { WebSocketClient } from '../core/websocket-client.js';
-import { RosterEntryWrapper } from '../types/jmri-messages.js';
+import { RosterEntryWrapper, RosterGroup } from '../types/jmri-messages.js';
 /**
  * Manages locomotive roster
  */
@@ -26,6 +26,14 @@ export declare class RosterManager {
      * Search roster by partial name match
      */
     searchRoster(query: string): Promise<RosterEntryWrapper[]>;
+    /**
+     * Get all roster groups
+     */
+    getRosterGroups(): Promise<RosterGroup[]>;
+    /**
+     * Get roster entries belonging to a specific group
+     */
+    getRosterEntriesByGroup(group: string): Promise<RosterEntryWrapper[]>;
     /**
      * Get cached roster (no network request)
      */

package/dist/types/mocks/mock-data.d.ts

@@ -96,8 +96,11 @@ export declare const mockData: {
                     readonly icon: null;
                     readonly selectedIcon: null;
                 }];
-                readonly attributes: readonly [];
-                readonly rosterGroups: readonly [];
+                readonly attributes: readonly [{
+                    readonly name: "RosterGroup:diesels";
+                    readonly value: "yes";
+                }];
+                readonly rosterGroups: readonly ["diesels"];
             };
             readonly id: 1;
         }, {
@@ -150,8 +153,11 @@ export declare const mockData: {
                     readonly icon: null;
                     readonly selectedIcon: null;
                 }];
-                readonly attributes: readonly [];
-                readonly rosterGroups: readonly [];
+                readonly attributes: readonly [{
+                    readonly name: "RosterGroup:steam";
+                    readonly value: "yes";
+                }];
+                readonly rosterGroups: readonly ["steam"];
             };
             readonly id: 2;
         }, {
@@ -210,12 +216,30 @@ export declare const mockData: {
                     readonly icon: null;
                     readonly selectedIcon: null;
                 }];
-                readonly attributes: readonly [];
-                readonly rosterGroups: readonly [];
+                readonly attributes: readonly [{
+                    readonly name: "RosterGroup:diesels";
+                    readonly value: "yes";
+                }];
+                readonly rosterGroups: readonly ["diesels"];
             };
             readonly id: 3;
         }];
     };
+    readonly rosterGroup: {
+        readonly list: readonly [{
+            readonly type: "rosterGroup";
+            readonly data: {
+                readonly name: "diesels";
+                readonly length: 2;
+            };
+        }, {
+            readonly type: "rosterGroup";
+            readonly data: {
+                readonly name: "steam";
+                readonly length: 1;
+            };
+        }];
+    };
     readonly throttle: {
         readonly acquire: {
             readonly success: {

package/dist/types/mocks/mock-response-manager.d.ts

@@ -20,6 +20,7 @@ export interface MockResponseManagerOptions {
 export declare class MockResponseManager {
     private responseDelay;
     private powerState;
+    private powerStateByPrefix;
     private throttles;
     private lights;
     private turnouts;
@@ -33,13 +34,17 @@ export declare class MockResponseManager {
      */
     private getHelloResponse;
     /**
-     * Get power response
+     * Get power response, with optional per-prefix state tracking
      */
     private getPowerResponse;
     /**
-     * Get roster response
+     * Get roster response, optionally filtered by group
      */
     private getRosterResponse;
+    /**
+     * Get roster group response
+     */
+    private getRosterGroupResponse;
     /**
      * Get throttle response
      */

package/dist/types/types/jmri-messages.d.ts

@@ -10,6 +10,7 @@ export interface JmriMessage {
     method?: 'get' | 'post' | 'put' | 'delete' | 'list';
     data?: any;
     id?: number;
+    params?: Record<string, string>;
 }
 /**
  * Power state values (from JMRI JSON protocol constants)
@@ -166,6 +167,27 @@ export interface RosterMessage extends JmriMessage {
 export interface RosterData {
     [key: string]: RosterEntry;
 }
+export interface RosterGroup {
+    name: string;
+    length: number;
+}
+export interface RosterGroupWrapper {
+    type: 'rosterGroup';
+    data: RosterGroup;
+}
+export interface RosterGroupMessage extends JmriMessage {
+    type: 'rosterGroup';
+    method: 'list';
+    data?: RosterGroupWrapper[];
+}
+export interface RosterMessageWithParams extends JmriMessage {
+    type: 'roster';
+    method: 'list';
+    params?: {
+        group: string;
+    };
+    data?: RosterResponse;
+}
 /**
  * Turnout state values (from JMRI JSON protocol constants)
  * UNKNOWN = 0 (state cannot be determined)

package/docs/API.md

@@ -141,6 +141,13 @@ const entry = await client.getRosterEntryByAddress(3);
 
 // Search roster
 const results = await client.searchRoster('steam');
+
+// Get all roster groups
+const groups: RosterGroup[] = await client.getRosterGroups();
+// [{ name: 'locos', length: 3 }, { name: 'trams', length: 2 }]
+
+// Get roster entries for a specific group
+const locos = await client.getRosterEntriesByGroup('locos');
 ```
 
 ## Light Control
@@ -267,6 +274,7 @@ import {
   LightState,
   LightData,
   RosterEntry,
+  RosterGroup,
   TurnoutState,
   TurnoutData,
   ThrottleState,

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/docs/MOCK_MODE.md

@@ -65,13 +65,18 @@ Connection establishment response with JMRI version info:
 Track power ON/OFF states
 
 ### Roster
-Three sample locomotives:
-- **CSX754** - GP38-2 diesel locomotive
-- **UP3985** - Challenger 4-6-6-4 steam locomotive
-- **BNSF5240** - SD40-2 diesel locomotive
+Three sample locomotives across two groups:
+- **CSX754** - GP38-2 diesel locomotive (`diesels` group)
+- **UP3985** - Challenger 4-6-6-4 steam locomotive (`steam` group)
+- **BNSF5240** - SD40-2 diesel locomotive (`diesels` group)
 
 Each includes realistic function key mappings (F0-F4).
 
+### Roster Groups
+Two sample groups:
+- **diesels** - CSX754, BNSF5240 (length: 2)
+- **steam** - UP3985 (length: 1)
+
 ### Lights
 Three sample lights:
 - **IL1** - Yard Light (OFF)
@@ -163,10 +168,10 @@ const response = await mockManager.getMockResponse({
 
 The mock system maintains state for realistic behavior:
 
-- **Power state** - Remembers if power is ON or OFF
+- **Power state** - Remembers if power is ON or OFF; tracked independently per connection prefix when one is supplied
 - **Light states** - Tracks ON/OFF state per light
 - **Turnout states** - Tracks CLOSED/THROWN state per turnout
-- **Throttles** - Tracks acquired throttles and their states
+- **Throttles** - Tracks acquired throttles and their states, including connection prefix
 - **Speed/Direction** - Maintains current speed and direction per throttle
 - **Functions** - Tracks function key states (F0-F28)
 
@@ -208,11 +213,12 @@ The mock data structure follows the JMRI JSON protocol specification.
 Mock mode implements the full JMRI client API. All methods work identically:
 
 - ✅ `connect()` / `disconnect()`
-- ✅ `getPower()` / `powerOn()` / `powerOff()`
-- ✅ `getRoster()`
+- ✅ `getPower()` / `powerOn()` / `powerOff()` (with optional prefix)
+- ✅ `getRoster()` / `getRosterEntryByName()` / `getRosterEntryByAddress()` / `searchRoster()`
+- ✅ `getRosterGroups()` / `getRosterEntriesByGroup()`
 - ✅ `getLight()` / `setLight()` / `turnOnLight()` / `turnOffLight()` / `listLights()`
 - ✅ `getTurnout()` / `setTurnout()` / `throwTurnout()` / `closeTurnout()` / `listTurnouts()`
-- ✅ `acquireThrottle()` / `releaseThrottle()`
+- ✅ `acquireThrottle()` / `releaseThrottle()` (with optional prefix)
 - ✅ `setThrottleSpeed()`
 - ✅ `setThrottleDirection()`
 - ✅ `setThrottleFunction()`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jmri-client",
-  "version": "4.2.0-beta.2",
+  "version": "5.1.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",