jmri-client 3.7.1 → 4.1.0

package/README.md

@@ -19,6 +19,7 @@ WebSocket client for [JMRI](http://jmri.sourceforge.net/) with real-time updates
 - ✅ **Heartbeat monitoring** - Automatic ping/pong keepalive
 - ✅ **TypeScript** - Full type definitions included
 - ✅ **Dual module support** - ESM and CommonJS
+- ✅ **Extensible** - Subclass `JmriClient` to add support for additional JMRI object types
 
 ## Installation
 
@@ -105,6 +106,37 @@ client.on('reconnecting', (attempt, delay) => {
 });
 ```
 
+### Extending JmriClient
+
+`JmriClient` exposes its `wsClient` as `protected`, so you can subclass it to add support for JMRI object types not yet built in (e.g., sensors, lights, routes, blocks):
+
+```typescript
+import { JmriClient } from 'jmri-client';
+import type { PartialClientOptions } from 'jmri-client';
+
+class MyExtendedClient extends JmriClient {
+  constructor(options?: PartialClientOptions) {
+    super(options);
+
+    // this.wsClient is available — use it to send/receive JMRI JSON messages
+    this.wsClient.on('update', (message: any) => {
+      if (message.type === 'sensor') {
+        this.emit('sensor:changed', message.data.name, message.data.state);
+      }
+    });
+  }
+
+  async listSensors() {
+    const response = await this.wsClient.request({ type: 'sensor', method: 'list' });
+    return Array.isArray(response?.data)
+      ? response.data.map((r: any) => r.data ?? r)
+      : [];
+  }
+}
+```
+
+`WebSocketClient` is also exported for direct use if you need it. See its `send()`, `request()`, and `on('update', ...)` API for low-level messaging.
+
 ## Testing
 
 **Unit Tests** (no hardware required):

package/dist/browser/jmri-client.js

@@ -638,6 +638,23 @@ function turnoutStateToString(state) {
       return "UNKNOWN";
   }
 }
+var LightState = /* @__PURE__ */ ((LightState2) => {
+  LightState2[LightState2["UNKNOWN"] = 0] = "UNKNOWN";
+  LightState2[LightState2["ON"] = 2] = "ON";
+  LightState2[LightState2["OFF"] = 4] = "OFF";
+  return LightState2;
+})(LightState || {});
+function lightStateToString(state) {
+  switch (state) {
+    case 2 /* ON */:
+      return "ON";
+    case 4 /* OFF */:
+      return "OFF";
+    case 0 /* UNKNOWN */:
+    default:
+      return "UNKNOWN";
+  }
+}
 
 // src/mocks/mock-data.ts
 var mockData = {
@@ -823,6 +840,13 @@ var mockData = {
       }
     }
   },
+  "light": {
+    "list": [
+      { "type": "light", "data": { "name": "IL1", "userName": "Yard Light", "comment": null, "properties": [], "state": 4 } },
+      { "type": "light", "data": { "name": "IL2", "userName": "Platform Light", "comment": null, "properties": [], "state": 4 } },
+      { "type": "light", "data": { "name": "IL3", "userName": "Signal Lamp", "comment": null, "properties": [], "state": 2 } }
+    ]
+  },
   "turnout": {
     "list": [
       { "type": "turnout", "data": { "name": "LT1", "userName": "Main Diverge", "state": 2 } },
@@ -868,6 +892,11 @@ var mockData = {
 var MockResponseManager = class {
   constructor(options = {}) {
     this.throttles = /* @__PURE__ */ new Map();
+    this.lights = /* @__PURE__ */ new Map([
+      ["IL1", 4 /* OFF */],
+      ["IL2", 4 /* OFF */],
+      ["IL3", 2 /* ON */]
+    ]);
     this.turnouts = /* @__PURE__ */ new Map([
       ["LT1", 2 /* CLOSED */],
       ["LT2", 2 /* CLOSED */],
@@ -892,6 +921,8 @@ var MockResponseManager = class {
         return this.getRosterResponse(message);
       case "throttle":
         return this.getThrottleResponse(message);
+      case "light":
+        return this.getLightResponse(message);
       case "turnout":
         return this.getTurnoutResponse(message);
       case "ping":
@@ -1007,6 +1038,26 @@ var MockResponseManager = class {
       data: {}
     };
   }
+  /**
+   * Get light response
+   */
+  getLightResponse(message) {
+    if (message.method === "list") {
+      return {
+        type: "light",
+        data: JSON.parse(JSON.stringify(mockData.light.list))
+      };
+    }
+    const name = message.data?.name;
+    if (!name) {
+      return { type: "light", data: { name: "", state: 0 /* UNKNOWN */ } };
+    }
+    if (message.method === "post" && message.data?.state !== void 0) {
+      this.lights.set(name, message.data.state);
+    }
+    const state = this.lights.get(name) ?? 0 /* UNKNOWN */;
+    return { type: "light", data: { name, state } };
+  }
   /**
    * Get turnout response
    */
@@ -1057,6 +1108,12 @@ var MockResponseManager = class {
   getThrottles() {
     return this.throttles;
   }
+  /**
+   * Get all light states (for testing)
+   */
+  getLights() {
+    return this.lights;
+  }
   /**
    * Get all turnout states (for testing)
    */
@@ -1069,6 +1126,11 @@ var MockResponseManager = class {
   reset() {
     this.powerState = 4 /* OFF */;
     this.throttles.clear();
+    this.lights = /* @__PURE__ */ new Map([
+      ["IL1", 4 /* OFF */],
+      ["IL2", 4 /* OFF */],
+      ["IL3", 2 /* ON */]
+    ]);
     this.turnouts = /* @__PURE__ */ new Map([
       ["LT1", 2 /* CLOSED */],
       ["LT2", 2 /* CLOSED */],
@@ -1891,6 +1953,104 @@ var TurnoutManager = class extends import_index.default {
   }
 };
 
+// src/managers/light-manager.ts
+var LightManager = class extends import_index.default {
+  constructor(client) {
+    super();
+    this.lights = /* @__PURE__ */ new Map();
+    this.client = client;
+    this.client.on("update", (message) => {
+      if (message.type === "light") {
+        this.handleLightUpdate(message);
+      }
+    });
+  }
+  /**
+   * Get the current state of a light.
+   * Also registers a server-side listener so subsequent changes are pushed.
+   */
+  async getLight(name) {
+    const message = {
+      type: "light",
+      data: { name }
+    };
+    const response = await this.client.request(message);
+    const state = response.data?.state ?? 0 /* UNKNOWN */;
+    this.lights.set(name, state);
+    return state;
+  }
+  /**
+   * Set a light to the given state
+   */
+  async setLight(name, state) {
+    const message = {
+      type: "light",
+      method: "post",
+      data: { name, state }
+    };
+    await this.client.request(message);
+    const oldState = this.lights.get(name);
+    this.lights.set(name, state);
+    if (oldState !== state) {
+      this.emit("light:changed", name, state);
+    }
+  }
+  /**
+   * Turn a light on
+   */
+  async turnOnLight(name) {
+    return this.setLight(name, 2 /* ON */);
+  }
+  /**
+   * Turn a light off
+   */
+  async turnOffLight(name) {
+    return this.setLight(name, 4 /* OFF */);
+  }
+  /**
+   * List all lights known to JMRI
+   */
+  async listLights() {
+    const message = {
+      type: "light",
+      method: "list"
+    };
+    const response = await this.client.request(message);
+    const entries = Array.isArray(response?.data) ? response.data.map((r) => r.data ?? r) : [];
+    for (const entry of entries) {
+      if (entry.name && entry.state !== void 0) {
+        this.lights.set(entry.name, entry.state);
+      }
+    }
+    return entries;
+  }
+  /**
+   * Get cached light state without a network request
+   */
+  getLightState(name) {
+    return this.lights.get(name);
+  }
+  /**
+   * Get all cached light states
+   */
+  getCachedLights() {
+    return new Map(this.lights);
+  }
+  /**
+   * Handle unsolicited light state updates from JMRI
+   */
+  handleLightUpdate(message) {
+    const name = message.data?.name;
+    const state = message.data?.state;
+    if (!name || state === void 0) return;
+    const oldState = this.lights.get(name);
+    this.lights.set(name, state);
+    if (oldState !== state) {
+      this.emit("light:changed", name, state);
+    }
+  }
+};
+
 // src/types/client-options.ts
 var DEFAULT_CLIENT_OPTIONS = {
   host: "localhost",
@@ -1967,6 +2127,7 @@ var JmriClient = class extends import_index.default {
     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.wsClient.on("connected", () => this.emit("connected"));
     this.wsClient.on("disconnected", (reason) => this.emit("disconnected", reason));
     this.wsClient.on(
@@ -1994,6 +2155,10 @@ var JmriClient = class extends import_index.default {
       "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)
@@ -2142,6 +2307,51 @@ var JmriClient = class extends import_index.default {
     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
   // ============================================================================
   /**
@@ -2239,11 +2449,14 @@ var JmriClient = class extends import_index.default {
 export {
   ConnectionState,
   JmriClient,
+  LightState,
   MockResponseManager,
   PowerState,
   TurnoutState,
+  WebSocketClient,
   isThrottleFunctionKey,
   isValidSpeed,
+  lightStateToString,
   mockData,
   mockResponseManager,
   powerStateToString,

package/dist/cjs/client.js

@@ -10,6 +10,7 @@ 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 client_options_js_1 = require("./types/client-options.js");
 /**
  * JMRI WebSocket Client
@@ -43,6 +44,7 @@ class JmriClient extends eventemitter3_1.EventEmitter {
         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);
         // Forward events from WebSocket client
         this.wsClient.on('connected', () => this.emit('connected'));
         this.wsClient.on('disconnected', (reason) => this.emit('disconnected', reason));
@@ -57,6 +59,7 @@ class JmriClient extends eventemitter3_1.EventEmitter {
         // 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));
@@ -196,6 +199,51 @@ class JmriClient extends eventemitter3_1.EventEmitter {
         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
     // ============================================================================
     /**

package/dist/cjs/index.js

@@ -4,14 +4,17 @@
  * WebSocket client for JMRI with real-time updates and throttle control
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.mockData = exports.mockResponseManager = exports.MockResponseManager = exports.turnoutStateToString = exports.powerStateToString = exports.isValidSpeed = exports.isThrottleFunctionKey = exports.ConnectionState = exports.TurnoutState = exports.PowerState = exports.JmriClient = void 0;
+exports.mockData = exports.mockResponseManager = exports.MockResponseManager = exports.lightStateToString = exports.turnoutStateToString = exports.powerStateToString = exports.isValidSpeed = exports.isThrottleFunctionKey = exports.ConnectionState = exports.LightState = exports.TurnoutState = exports.PowerState = exports.WebSocketClient = exports.JmriClient = void 0;
 var client_js_1 = require("./client.js");
 Object.defineProperty(exports, "JmriClient", { enumerable: true, get: function () { return client_js_1.JmriClient; } });
+var websocket_client_js_1 = require("./core/websocket-client.js");
+Object.defineProperty(exports, "WebSocketClient", { enumerable: true, get: function () { return websocket_client_js_1.WebSocketClient; } });
 // Export types
 var index_js_1 = require("./types/index.js");
 // JMRI message types
 Object.defineProperty(exports, "PowerState", { enumerable: true, get: function () { return index_js_1.PowerState; } });
 Object.defineProperty(exports, "TurnoutState", { enumerable: true, get: function () { return index_js_1.TurnoutState; } });
+Object.defineProperty(exports, "LightState", { enumerable: true, get: function () { return index_js_1.LightState; } });
 // Event types
 Object.defineProperty(exports, "ConnectionState", { enumerable: true, get: function () { return index_js_1.ConnectionState; } });
 // Export utility functions
@@ -21,6 +24,7 @@ Object.defineProperty(exports, "isValidSpeed", { enumerable: true, get: function
 var jmri_messages_js_1 = require("./types/jmri-messages.js");
 Object.defineProperty(exports, "powerStateToString", { enumerable: true, get: function () { return jmri_messages_js_1.powerStateToString; } });
 Object.defineProperty(exports, "turnoutStateToString", { enumerable: true, get: function () { return jmri_messages_js_1.turnoutStateToString; } });
+Object.defineProperty(exports, "lightStateToString", { enumerable: true, get: function () { return jmri_messages_js_1.lightStateToString; } });
 // Export mock system for testing and demo purposes
 var index_js_2 = require("./mocks/index.js");
 Object.defineProperty(exports, "MockResponseManager", { enumerable: true, get: function () { return index_js_2.MockResponseManager; } });

package/dist/cjs/managers/index.js

@@ -21,3 +21,4 @@ __exportStar(require("./power-manager.js"), exports);
 __exportStar(require("./roster-manager.js"), exports);
 __exportStar(require("./throttle-manager.js"), exports);
 __exportStar(require("./turnout-manager.js"), exports);
+__exportStar(require("./light-manager.js"), exports);

package/dist/cjs/managers/light-manager.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * Light manager
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LightManager = void 0;
+const eventemitter3_1 = require("eventemitter3");
+const jmri_messages_js_1 = require("../types/jmri-messages.js");
+/**
+ * Manages JMRI light state
+ */
+class LightManager extends eventemitter3_1.EventEmitter {
+    constructor(client) {
+        super();
+        this.lights = new Map();
+        this.client = client;
+        this.client.on('update', (message) => {
+            if (message.type === 'light') {
+                this.handleLightUpdate(message);
+            }
+        });
+    }
+    /**
+     * Get the current state of a light.
+     * Also registers a server-side listener so subsequent changes are pushed.
+     */
+    async getLight(name) {
+        const message = {
+            type: 'light',
+            data: { name }
+        };
+        const response = await this.client.request(message);
+        const state = response.data?.state ?? jmri_messages_js_1.LightState.UNKNOWN;
+        this.lights.set(name, state);
+        return state;
+    }
+    /**
+     * Set a light to the given state
+     */
+    async setLight(name, state) {
+        const message = {
+            type: 'light',
+            method: 'post',
+            data: { name, state }
+        };
+        await this.client.request(message);
+        const oldState = this.lights.get(name);
+        this.lights.set(name, state);
+        if (oldState !== state) {
+            this.emit('light:changed', name, state);
+        }
+    }
+    /**
+     * Turn a light on
+     */
+    async turnOnLight(name) {
+        return this.setLight(name, jmri_messages_js_1.LightState.ON);
+    }
+    /**
+     * Turn a light off
+     */
+    async turnOffLight(name) {
+        return this.setLight(name, jmri_messages_js_1.LightState.OFF);
+    }
+    /**
+     * List all lights known to JMRI
+     */
+    async listLights() {
+        const message = {
+            type: 'light',
+            method: 'list'
+        };
+        const response = await this.client.request(message);
+        const entries = Array.isArray(response?.data)
+            ? response.data.map((r) => r.data ?? r)
+            : [];
+        for (const entry of entries) {
+            if (entry.name && entry.state !== undefined) {
+                this.lights.set(entry.name, entry.state);
+            }
+        }
+        return entries;
+    }
+    /**
+     * Get cached light state without a network request
+     */
+    getLightState(name) {
+        return this.lights.get(name);
+    }
+    /**
+     * Get all cached light states
+     */
+    getCachedLights() {
+        return new Map(this.lights);
+    }
+    /**
+     * Handle unsolicited light state updates from JMRI
+     */
+    handleLightUpdate(message) {
+        const name = message.data?.name;
+        const state = message.data?.state;
+        if (!name || state === undefined)
+            return;
+        const oldState = this.lights.get(name);
+        this.lights.set(name, state);
+        if (oldState !== state) {
+            this.emit('light:changed', name, state);
+        }
+    }
+}
+exports.LightManager = LightManager;

package/dist/cjs/mocks/mock-data.js

@@ -188,6 +188,13 @@ exports.mockData = {
             }
         }
     },
+    "light": {
+        "list": [
+            { "type": "light", "data": { "name": "IL1", "userName": "Yard Light", "comment": null, "properties": [], "state": 4 } },
+            { "type": "light", "data": { "name": "IL2", "userName": "Platform Light", "comment": null, "properties": [], "state": 4 } },
+            { "type": "light", "data": { "name": "IL3", "userName": "Signal Lamp", "comment": null, "properties": [], "state": 2 } }
+        ]
+    },
     "turnout": {
         "list": [
             { "type": "turnout", "data": { "name": "LT1", "userName": "Main Diverge", "state": 2 } },

package/dist/cjs/mocks/mock-response-manager.js

@@ -13,6 +13,11 @@ const mock_data_js_1 = require("./mock-data.js");
 class MockResponseManager {
     constructor(options = {}) {
         this.throttles = new Map();
+        this.lights = new Map([
+            ['IL1', jmri_messages_js_1.LightState.OFF],
+            ['IL2', jmri_messages_js_1.LightState.OFF],
+            ['IL3', jmri_messages_js_1.LightState.ON]
+        ]);
         this.turnouts = new Map([
             ['LT1', jmri_messages_js_1.TurnoutState.CLOSED],
             ['LT2', jmri_messages_js_1.TurnoutState.CLOSED],
@@ -39,6 +44,8 @@ class MockResponseManager {
                 return this.getRosterResponse(message);
             case 'throttle':
                 return this.getThrottleResponse(message);
+            case 'light':
+                return this.getLightResponse(message);
             case 'turnout':
                 return this.getTurnoutResponse(message);
             case 'ping':
@@ -164,6 +171,29 @@ class MockResponseManager {
             data: {}
         };
     }
+    /**
+     * Get light response
+     */
+    getLightResponse(message) {
+        // List all lights
+        if (message.method === 'list') {
+            return {
+                type: 'light',
+                data: JSON.parse(JSON.stringify(mock_data_js_1.mockData.light.list))
+            };
+        }
+        const name = message.data?.name;
+        if (!name) {
+            return { type: 'light', data: { name: '', state: jmri_messages_js_1.LightState.UNKNOWN } };
+        }
+        // Set light state
+        if (message.method === 'post' && message.data?.state !== undefined) {
+            this.lights.set(name, message.data.state);
+        }
+        // Get or confirm current state
+        const state = this.lights.get(name) ?? jmri_messages_js_1.LightState.UNKNOWN;
+        return { type: 'light', data: { name, state } };
+    }
     /**
      * Get turnout response
      */
@@ -217,6 +247,12 @@ class MockResponseManager {
     getThrottles() {
         return this.throttles;
     }
+    /**
+     * Get all light states (for testing)
+     */
+    getLights() {
+        return this.lights;
+    }
     /**
      * Get all turnout states (for testing)
      */
@@ -229,6 +265,11 @@ class MockResponseManager {
     reset() {
         this.powerState = jmri_messages_js_1.PowerState.OFF;
         this.throttles.clear();
+        this.lights = new Map([
+            ['IL1', jmri_messages_js_1.LightState.OFF],
+            ['IL2', jmri_messages_js_1.LightState.OFF],
+            ['IL3', jmri_messages_js_1.LightState.ON]
+        ]);
         this.turnouts = new Map([
             ['LT1', jmri_messages_js_1.TurnoutState.CLOSED],
             ['LT2', jmri_messages_js_1.TurnoutState.CLOSED],

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

@@ -4,9 +4,10 @@
  * Based on JMRI JSON protocol specification
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TurnoutState = exports.PowerState = void 0;
+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)
@@ -66,3 +67,29 @@ function turnoutStateToString(state) {
             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/esm/client.js

@@ -7,6 +7,7 @@ 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 { mergeOptions } from './types/client-options.js';
 /**
  * JMRI WebSocket Client
@@ -40,6 +41,7 @@ export class JmriClient extends EventEmitter {
         this.rosterManager = new RosterManager(this.wsClient);
         this.throttleManager = new ThrottleManager(this.wsClient);
         this.turnoutManager = new TurnoutManager(this.wsClient);
+        this.lightManager = new LightManager(this.wsClient);
         // Forward events from WebSocket client
         this.wsClient.on('connected', () => this.emit('connected'));
         this.wsClient.on('disconnected', (reason) => this.emit('disconnected', reason));
@@ -54,6 +56,7 @@ export class JmriClient extends EventEmitter {
         // 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));
@@ -193,6 +196,51 @@ export class JmriClient extends EventEmitter {
         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
     // ============================================================================
     /**

package/dist/esm/index.js

@@ -3,14 +3,15 @@
  * WebSocket client for JMRI with real-time updates and throttle control
  */
 export { JmriClient } from './client.js';
+export { WebSocketClient } from './core/websocket-client.js';
 // Export types
 export { 
 // JMRI message types
-PowerState, TurnoutState, 
+PowerState, TurnoutState, LightState, 
 // Event types
 ConnectionState } from './types/index.js';
 // Export utility functions
 export { isThrottleFunctionKey, isValidSpeed } from './types/throttle.js';
-export { powerStateToString, turnoutStateToString } from './types/jmri-messages.js';
+export { powerStateToString, turnoutStateToString, lightStateToString } from './types/jmri-messages.js';
 // Export mock system for testing and demo purposes
 export { MockResponseManager, mockResponseManager, mockData } from './mocks/index.js';

package/dist/esm/managers/index.js

@@ -5,3 +5,4 @@ export * from './power-manager.js';
 export * from './roster-manager.js';
 export * from './throttle-manager.js';
 export * from './turnout-manager.js';
+export * from './light-manager.js';

package/dist/esm/managers/light-manager.js

@@ -0,0 +1,107 @@
+/**
+ * Light manager
+ */
+import { EventEmitter } from 'eventemitter3';
+import { LightState } from '../types/jmri-messages.js';
+/**
+ * Manages JMRI light state
+ */
+export class LightManager extends EventEmitter {
+    constructor(client) {
+        super();
+        this.lights = new Map();
+        this.client = client;
+        this.client.on('update', (message) => {
+            if (message.type === 'light') {
+                this.handleLightUpdate(message);
+            }
+        });
+    }
+    /**
+     * Get the current state of a light.
+     * Also registers a server-side listener so subsequent changes are pushed.
+     */
+    async getLight(name) {
+        const message = {
+            type: 'light',
+            data: { name }
+        };
+        const response = await this.client.request(message);
+        const state = response.data?.state ?? LightState.UNKNOWN;
+        this.lights.set(name, state);
+        return state;
+    }
+    /**
+     * Set a light to the given state
+     */
+    async setLight(name, state) {
+        const message = {
+            type: 'light',
+            method: 'post',
+            data: { name, state }
+        };
+        await this.client.request(message);
+        const oldState = this.lights.get(name);
+        this.lights.set(name, state);
+        if (oldState !== state) {
+            this.emit('light:changed', name, state);
+        }
+    }
+    /**
+     * Turn a light on
+     */
+    async turnOnLight(name) {
+        return this.setLight(name, LightState.ON);
+    }
+    /**
+     * Turn a light off
+     */
+    async turnOffLight(name) {
+        return this.setLight(name, LightState.OFF);
+    }
+    /**
+     * List all lights known to JMRI
+     */
+    async listLights() {
+        const message = {
+            type: 'light',
+            method: 'list'
+        };
+        const response = await this.client.request(message);
+        const entries = Array.isArray(response?.data)
+            ? response.data.map((r) => r.data ?? r)
+            : [];
+        for (const entry of entries) {
+            if (entry.name && entry.state !== undefined) {
+                this.lights.set(entry.name, entry.state);
+            }
+        }
+        return entries;
+    }
+    /**
+     * Get cached light state without a network request
+     */
+    getLightState(name) {
+        return this.lights.get(name);
+    }
+    /**
+     * Get all cached light states
+     */
+    getCachedLights() {
+        return new Map(this.lights);
+    }
+    /**
+     * Handle unsolicited light state updates from JMRI
+     */
+    handleLightUpdate(message) {
+        const name = message.data?.name;
+        const state = message.data?.state;
+        if (!name || state === undefined)
+            return;
+        const oldState = this.lights.get(name);
+        this.lights.set(name, state);
+        if (oldState !== state) {
+            this.emit('light:changed', name, state);
+        }
+    }
+}

package/dist/esm/mocks/mock-data.js

@@ -185,6 +185,13 @@ export const mockData = {
             }
         }
     },
+    "light": {
+        "list": [
+            { "type": "light", "data": { "name": "IL1", "userName": "Yard Light", "comment": null, "properties": [], "state": 4 } },
+            { "type": "light", "data": { "name": "IL2", "userName": "Platform Light", "comment": null, "properties": [], "state": 4 } },
+            { "type": "light", "data": { "name": "IL3", "userName": "Signal Lamp", "comment": null, "properties": [], "state": 2 } }
+        ]
+    },
     "turnout": {
         "list": [
             { "type": "turnout", "data": { "name": "LT1", "userName": "Main Diverge", "state": 2 } },

package/dist/esm/mocks/mock-response-manager.js

@@ -2,7 +2,7 @@
  * Mock Response Manager
  * Generates mock JMRI responses for testing and demo purposes
  */
-import { PowerState, TurnoutState } from '../types/jmri-messages.js';
+import { PowerState, TurnoutState, LightState } from '../types/jmri-messages.js';
 import { mockData } from './mock-data.js';
 /**
  * Manages mock responses for JMRI protocol
@@ -10,6 +10,11 @@ import { mockData } from './mock-data.js';
 export class MockResponseManager {
     constructor(options = {}) {
         this.throttles = new Map();
+        this.lights = new Map([
+            ['IL1', LightState.OFF],
+            ['IL2', LightState.OFF],
+            ['IL3', LightState.ON]
+        ]);
         this.turnouts = new Map([
             ['LT1', TurnoutState.CLOSED],
             ['LT2', TurnoutState.CLOSED],
@@ -36,6 +41,8 @@ export class MockResponseManager {
                 return this.getRosterResponse(message);
             case 'throttle':
                 return this.getThrottleResponse(message);
+            case 'light':
+                return this.getLightResponse(message);
             case 'turnout':
                 return this.getTurnoutResponse(message);
             case 'ping':
@@ -161,6 +168,29 @@ export class MockResponseManager {
             data: {}
         };
     }
+    /**
+     * Get light response
+     */
+    getLightResponse(message) {
+        // List all lights
+        if (message.method === 'list') {
+            return {
+                type: 'light',
+                data: JSON.parse(JSON.stringify(mockData.light.list))
+            };
+        }
+        const name = message.data?.name;
+        if (!name) {
+            return { type: 'light', data: { name: '', state: LightState.UNKNOWN } };
+        }
+        // Set light state
+        if (message.method === 'post' && message.data?.state !== undefined) {
+            this.lights.set(name, message.data.state);
+        }
+        // Get or confirm current state
+        const state = this.lights.get(name) ?? LightState.UNKNOWN;
+        return { type: 'light', data: { name, state } };
+    }
     /**
      * Get turnout response
      */
@@ -214,6 +244,12 @@ export class MockResponseManager {
     getThrottles() {
         return this.throttles;
     }
+    /**
+     * Get all light states (for testing)
+     */
+    getLights() {
+        return this.lights;
+    }
     /**
      * Get all turnout states (for testing)
      */
@@ -226,6 +262,11 @@ export class MockResponseManager {
     reset() {
         this.powerState = PowerState.OFF;
         this.throttles.clear();
+        this.lights = new Map([
+            ['IL1', LightState.OFF],
+            ['IL2', LightState.OFF],
+            ['IL3', LightState.ON]
+        ]);
         this.turnouts = new Map([
             ['LT1', TurnoutState.CLOSED],
             ['LT2', TurnoutState.CLOSED],

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

@@ -61,3 +61,29 @@ export function turnoutStateToString(state) {
             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)
+ */
+export var LightState;
+(function (LightState) {
+    LightState[LightState["UNKNOWN"] = 0] = "UNKNOWN";
+    LightState[LightState["ON"] = 2] = "ON";
+    LightState[LightState["OFF"] = 4] = "OFF";
+})(LightState || (LightState = {}));
+/**
+ * Convert LightState enum to human-readable string
+ */
+export function lightStateToString(state) {
+    switch (state) {
+        case LightState.ON:
+            return 'ON';
+        case LightState.OFF:
+            return 'OFF';
+        case LightState.UNKNOWN:
+        default:
+            return 'UNKNOWN';
+    }
+}

package/dist/types/client.d.ts

@@ -2,8 +2,9 @@
  * Main JMRI client class
  */
 import { EventEmitter } from 'eventemitter3';
+import { WebSocketClient } from './core/websocket-client.js';
 import { PartialClientOptions } from './types/client-options.js';
-import { PowerState, RosterEntryWrapper, TurnoutState, TurnoutData } from './types/jmri-messages.js';
+import { PowerState, RosterEntryWrapper, TurnoutState, TurnoutData, LightState, LightData } from './types/jmri-messages.js';
 import { ConnectionState } from './types/events.js';
 import { ThrottleAcquireOptions, ThrottleFunctionKey, ThrottleState } from './types/throttle.js';
 /**
@@ -12,11 +13,12 @@ import { ThrottleAcquireOptions, ThrottleFunctionKey, ThrottleState } from './ty
  */
 export declare class JmriClient extends EventEmitter {
     private options;
-    private wsClient;
+    protected wsClient: WebSocketClient;
     private powerManager;
     private rosterManager;
     private throttleManager;
     private turnoutManager;
+    private lightManager;
     /**
      * Create a new JMRI client
      *
@@ -111,6 +113,34 @@ export declare class JmriClient extends EventEmitter {
      * Get all cached turnout states
      */
     getCachedTurnouts(): Map<string, TurnoutState>;
+    /**
+     * Get the current state of a light
+     */
+    getLight(name: string): Promise<LightState>;
+    /**
+     * Set a light to the given state
+     */
+    setLight(name: string, state: LightState): Promise<void>;
+    /**
+     * Turn a light on
+     */
+    turnOnLight(name: string): Promise<void>;
+    /**
+     * Turn a light off
+     */
+    turnOffLight(name: string): Promise<void>;
+    /**
+     * List all lights known to JMRI
+     */
+    listLights(): Promise<LightData[]>;
+    /**
+     * Get cached light state without a network request
+     */
+    getLightState(name: string): LightState | undefined;
+    /**
+     * Get all cached light states
+     */
+    getCachedLights(): Map<string, LightState>;
     /**
      * Acquire a throttle for a locomotive
      *

package/dist/types/index.d.ts

@@ -3,8 +3,9 @@
  * WebSocket client for JMRI with real-time updates and throttle control
  */
 export { JmriClient } from './client.js';
-export { JmriClientOptions, PartialClientOptions, ReconnectionOptions, HeartbeatOptions, MockOptions, PowerState, TurnoutState, RosterEntry, TurnoutData, JmriMessage, PowerMessage, TurnoutMessage, ThrottleMessage, RosterMessage, ConnectionState, EventPayloads, ThrottleAcquireOptions, ThrottleFunctionKey, ThrottleState } from './types/index.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 { isThrottleFunctionKey, isValidSpeed } from './types/throttle.js';
-export { powerStateToString, turnoutStateToString } from './types/jmri-messages.js';
+export { powerStateToString, turnoutStateToString, lightStateToString } from './types/jmri-messages.js';
 export { MockResponseManager, mockResponseManager, mockData } from './mocks/index.js';
 export type { MockResponseManagerOptions } from './mocks/index.js';

package/dist/types/managers/index.d.ts

@@ -5,3 +5,4 @@ export * from './power-manager.js';
 export * from './roster-manager.js';
 export * from './throttle-manager.js';
 export * from './turnout-manager.js';
+export * from './light-manager.js';

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

@@ -0,0 +1,47 @@
+/**
+ * Light manager
+ */
+import { EventEmitter } from 'eventemitter3';
+import { WebSocketClient } from '../core/websocket-client.js';
+import { LightState, LightData } from '../types/jmri-messages.js';
+/**
+ * Manages JMRI light state
+ */
+export declare class LightManager extends EventEmitter {
+    private client;
+    private lights;
+    constructor(client: WebSocketClient);
+    /**
+     * Get the current state of a light.
+     * Also registers a server-side listener so subsequent changes are pushed.
+     */
+    getLight(name: string): Promise<LightState>;
+    /**
+     * Set a light to the given state
+     */
+    setLight(name: string, state: LightState): Promise<void>;
+    /**
+     * Turn a light on
+     */
+    turnOnLight(name: string): Promise<void>;
+    /**
+     * Turn a light off
+     */
+    turnOffLight(name: string): Promise<void>;
+    /**
+     * List all lights known to JMRI
+     */
+    listLights(): Promise<LightData[]>;
+    /**
+     * Get cached light state without a network request
+     */
+    getLightState(name: string): LightState | undefined;
+    /**
+     * Get all cached light states
+     */
+    getCachedLights(): Map<string, LightState>;
+    /**
+     * Handle unsolicited light state updates from JMRI
+     */
+    private handleLightUpdate;
+}

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

@@ -263,6 +263,36 @@ export declare const mockData: {
             };
         };
     };
+    readonly light: {
+        readonly list: readonly [{
+            readonly type: "light";
+            readonly data: {
+                readonly name: "IL1";
+                readonly userName: "Yard Light";
+                readonly comment: null;
+                readonly properties: readonly [];
+                readonly state: 4;
+            };
+        }, {
+            readonly type: "light";
+            readonly data: {
+                readonly name: "IL2";
+                readonly userName: "Platform Light";
+                readonly comment: null;
+                readonly properties: readonly [];
+                readonly state: 4;
+            };
+        }, {
+            readonly type: "light";
+            readonly data: {
+                readonly name: "IL3";
+                readonly userName: "Signal Lamp";
+                readonly comment: null;
+                readonly properties: readonly [];
+                readonly state: 2;
+            };
+        }];
+    };
     readonly turnout: {
         readonly list: readonly [{
             readonly type: "turnout";

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

@@ -2,7 +2,7 @@
  * Mock Response Manager
  * Generates mock JMRI responses for testing and demo purposes
  */
-import { JmriMessage, PowerState, TurnoutState } from '../types/jmri-messages.js';
+import { JmriMessage, PowerState, TurnoutState, LightState } from '../types/jmri-messages.js';
 export interface MockResponseManagerOptions {
     /**
      * Delay in milliseconds before returning responses (simulates network latency)
@@ -21,6 +21,7 @@ export declare class MockResponseManager {
     private responseDelay;
     private powerState;
     private throttles;
+    private lights;
     private turnouts;
     constructor(options?: MockResponseManagerOptions);
     /**
@@ -43,6 +44,10 @@ export declare class MockResponseManager {
      * Get throttle response
      */
     private getThrottleResponse;
+    /**
+     * Get light response
+     */
+    private getLightResponse;
     /**
      * Get turnout response
      */
@@ -67,6 +72,10 @@ export declare class MockResponseManager {
      * Get all throttles (for testing)
      */
     getThrottles(): Map<string, any>;
+    /**
+     * Get all light states (for testing)
+     */
+    getLights(): Map<string, LightState>;
     /**
      * Get all turnout states (for testing)
      */

package/dist/types/types/events.d.ts

@@ -1,7 +1,7 @@
 /**
  * Event types for JmriClient EventEmitter
  */
-import { PowerState, TurnoutState } from './jmri-messages.js';
+import { PowerState, TurnoutState, LightState } from './jmri-messages.js';
 import { ThrottleData } from './jmri-messages.js';
 /**
  * Connection states
@@ -24,6 +24,7 @@ export interface EventPayloads {
     'error': Error;
     'power:changed': PowerState;
     'turnout:changed': [name: string, state: TurnoutState];
+    'light:changed': [name: string, state: LightState];
     'throttle:acquired': string;
     'throttle:updated': [throttleId: string, data: ThrottleData];
     'throttle:released': string;

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

@@ -183,6 +183,38 @@ export interface TurnoutMessage extends JmriMessage {
     type: 'turnout';
     data?: TurnoutData;
 }
+/**
+ * Light state values (from JMRI JSON protocol constants)
+ * UNKNOWN = 0 (state cannot be determined)
+ * ON = 2 (light is on)
+ * OFF = 4 (light is off)
+ */
+export declare enum LightState {
+    UNKNOWN = 0,
+    ON = 2,
+    OFF = 4
+}
+/**
+ * Convert LightState enum to human-readable string
+ */
+export declare function lightStateToString(state: LightState): string;
+/**
+ * Light data structure
+ */
+export interface LightData {
+    name: string;
+    userName?: string;
+    comment?: string | null;
+    properties?: any[];
+    state?: LightState;
+}
+/**
+ * Light message
+ */
+export interface LightMessage extends JmriMessage {
+    type: 'light';
+    data?: LightData;
+}
 /**
  * Ping message (heartbeat)
  */
@@ -231,4 +263,4 @@ export interface ErrorMessage extends JmriMessage {
 /**
  * Union type of all possible JMRI messages
  */
-export type AnyJmriMessage = PowerMessage | ThrottleMessage | RosterMessage | TurnoutMessage | PingMessage | PongMessage | HelloMessage | GoodbyeMessage | ErrorMessage;
+export type AnyJmriMessage = PowerMessage | ThrottleMessage | RosterMessage | TurnoutMessage | LightMessage | PingMessage | PongMessage | HelloMessage | GoodbyeMessage | ErrorMessage;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jmri-client",
-  "version": "3.7.1",
+  "version": "4.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",