modbus-webserial 0.10.3 → 0.11.0

package/README.md

@@ -135,7 +135,53 @@ const client = await ModbusRTU.openWebSerial({
 });
 ```
 
+### Concurrency
+The WebSerial transport is **single-flight**: it can only have one in-progress Modbus RTU transaction at a time.
+
+This is intentional. Modbus RTU does not include a transaction identifier, so overlapping requests on the same serial link makes it ambiguous which response belongs to which request.
+
+There is **no internal request queue**. To avoid abstracting away the serial “one request at a time” nature of Modbus RTU, starting a new transaction while another is in progress will throw an error immediately.
+
+#### Wrong (concurrent calls on the same client/transport):
+```js
+// Two requests started without awaiting the first one.
+// This will throw (single-flight).
+const p1 = client.readHoldingRegisters(0x0000, 2);
+const p2 = client.readHoldingRegisters(0x0010, 2); 
+// -> Uncaught Error: Concurrent transact() calls are not supported
+
+await Promise.all([p1, p2]);
+```
+
+#### Right (serialize with `await`):
+```js
+await client.readHoldingRegisters(0x0000, 2);
+await client.readHoldingRegisters(0x0010, 2);
+```
+
+### Post-timeout recovery
+
+When a request times out, a Modbus RTU slave may still send a **late reply** afterwards. If you immediately send a new request (that is similar enough to the old one), that late reply can be mistaken as the response for the new request.
+
+To reduce that risk (along with strong request/response matching), the transport supports a post-timeout “quarantine” window.
+
+* If `postTimeoutWaitPeriod` is `0` (default), the next request is sent immediately after a timeout.
+* If `postTimeoutWaitPeriod` is `> 0`, the next `transact()` call will **delay sending** the request for the specified period, while **discarding** any bytes received during that window.
+
+```js
+const client = await ModbusRTU.openWebSerial({
+  // ...
+  postTimeoutWaitPeriod: 20, // ms
+});
+```
+
+Notes:
+* This affects **only the request after a timeout**.
+* When you use the client sequentially (with `await`), this shows up as a small delay before the next request. It does **not** change how timeouts are thrown or how you catch them.
+
+
 ## Current state
+* **v0.11**: Transport rework to handle edge cases explicitly
 * **v0.10**: Full modbus data-access coverage
 * **v0.9**: Full passing tests, smoke test passed, complete README, build scripts in place
 * **Beta**: Full Modbus RTU function‑code coverage

package/dist/index.d.ts

@@ -1,12 +1,16 @@
-interface WebSerialOptions {
+interface WebSerialOptions extends WebSerialConfig {
+    requestFilters?: SerialPortFilter[];
+    port?: SerialPort;
+}
+interface WebSerialConfig {
     baudRate?: number;
     dataBits?: 7 | 8;
     stopBits?: 1 | 2;
     parity?: "none" | "even" | "odd";
-    requestFilters?: SerialPortFilter[];
-    port?: SerialPort;
     timeout?: number;
-    crcPolicy?: CrcPolicy;
+    crcPolicy?: Required<CrcPolicy>;
+    postTimeoutWaitPeriod?: number;
+    interRequestDelay?: number;
 }
 type CrcPolicy = {
     mode: "strict";
@@ -210,9 +214,18 @@ declare class ResyncError extends Error {
 declare class TimeoutError extends Error {
     constructor();
 }
+declare class StreamClosedError extends Error {
+    constructor();
+}
 declare class ExceptionError extends Error {
     code: number;
     constructor(code: number);
 }
 
-export { CrcError, ExceptionError, type MaskWriteResult, ModbusRTU, type ReadFifoResult, type ReadRegisterResult, ResyncError, TimeoutError, type WebSerialOptions, type WriteFileResult, type WriteRegisterResult, buildMaskWriteRegister, buildReadCoils, buildReadDiscreteInputs, buildReadFifoQueue, buildReadFileRecord, buildReadHolding, buildReadInputRegisters, buildReadWriteMultiple, buildWriteFileRecord, buildWriteMultiple, buildWriteMultipleCoils, buildWriteSingle, buildWriteSingleCoil, crc16, parseMaskWriteRegister, parseReadCoils, parseReadDiscreteInputs, parseReadFifoQueue, parseReadFileRecord, parseReadHolding, parseReadInputRegisters, parseReadWriteMultiple, parseWriteSingle, parseWriteSingleCoil };
+declare const BUILD_INFO: {
+    readonly version: string;
+    readonly commit: string;
+    readonly buildTime: string;
+};
+
+export { BUILD_INFO, CrcError, ExceptionError, type MaskWriteResult, ModbusRTU, type ReadFifoResult, type ReadRegisterResult, ResyncError, StreamClosedError, TimeoutError, type WebSerialOptions, type WriteFileResult, type WriteRegisterResult, buildMaskWriteRegister, buildReadCoils, buildReadDiscreteInputs, buildReadFifoQueue, buildReadFileRecord, buildReadHolding, buildReadInputRegisters, buildReadWriteMultiple, buildWriteFileRecord, buildWriteMultiple, buildWriteMultipleCoils, buildWriteSingle, buildWriteSingleCoil, crc16, parseMaskWriteRegister, parseReadCoils, parseReadDiscreteInputs, parseReadFifoQueue, parseReadFileRecord, parseReadHolding, parseReadInputRegisters, parseReadWriteMultiple, parseWriteSingle, parseWriteSingleCoil };

package/dist/index.js

@@ -28,6 +28,11 @@ var TimeoutError = class extends Error {
     super("Modbus response timed out");
   }
 };
+var StreamClosedError = class extends Error {
+  constructor() {
+    super("Modbus stream closed");
+  }
+};
 var ExceptionError = class extends Error {
   constructor(code) {
     var _a;
@@ -48,23 +53,59 @@ function crc16(buf) {
   return crc;
 }
 
+// src/core/types.ts
+var FC_READ_HOLDING_REGISTERS = 3;
+var FC_WRITE_SINGLE_HOLDING_REGISTER = 6;
+var FC_WRITE_MULTIPLE_HOLDING_REGISTERS = 16;
+var FC_READ_COILS = 1;
+var FC_WRITE_SINGLE_COIL = 5;
+var FC_WRITE_MULTIPLE_COILS = 15;
+var FC_READ_INPUT_REGISTERS = 4;
+var FC_READ_DISCRETE_INPUTS = 2;
+var FC_READ_FILE_RECORD = 20;
+var FC_WRITE_FILE_RECORD = 21;
+var FC_MASK_WRITE_REGISTER = 22;
+var FC_READ_WRITE_MULTIPLE_REGISTERS = 23;
+var FC_READ_FIFO_QUEUE = 24;
+
 // src/transport/webserial.ts
 var DEFAULT_CRC_POLICY = { mode: "strict" };
 var DEFAULT_MAX_RESYNC_DROPS = 32;
-var WebSerialTransport = class _WebSerialTransport {
+var DEFAULTS = {
+  baudRate: 9600,
+  dataBits: 8,
+  stopBits: 1,
+  parity: "none",
+  timeout: 500,
+  crcPolicy: DEFAULT_CRC_POLICY,
+  postTimeoutWaitPeriod: 0,
+  interRequestDelay: 0
+};
+var _WebSerialTransport = class _WebSerialTransport {
   constructor() {
-    this.timeout = 500;
     this.rxBuf = new Uint8Array(0);
     // rolling buffer across calls
-    this.strictCrc = true;
-    this.maxResyncDrops = DEFAULT_MAX_RESYNC_DROPS;
+    this.dirtyUntil = 0;
+    this.inFlight = false;
+    this.lastTransactionEnd = null;
+    this.cfg = {
+      baudRate: DEFAULTS.baudRate,
+      dataBits: DEFAULTS.dataBits,
+      stopBits: DEFAULTS.stopBits,
+      parity: DEFAULTS.parity,
+      timeout: DEFAULTS.timeout,
+      postTimeoutWaitPeriod: DEFAULTS.postTimeoutWaitPeriod,
+      interRequestDelay: DEFAULTS.interRequestDelay
+    };
+    this.MAX_RESYNC_DROPS = DEFAULT_MAX_RESYNC_DROPS;
+    this.CRC_STRICT = DEFAULT_CRC_POLICY.mode === "strict";
   }
   // timeout gelpers
   setTimeout(ms) {
-    this.timeout = ms;
+    this.cfg.timeout = ms;
   }
   getTimeout() {
-    return this.timeout;
+    return this.cfg.timeout;
   }
   getPort() {
     return this.port;
@@ -78,92 +119,160 @@ var WebSerialTransport = class _WebSerialTransport {
     return t;
   }
   async init(opts) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _i;
-    this.timeout = (_a = opts.timeout) != null ? _a : 500;
+    var _a, _b, _c;
+    Object.entries(this.cfg).forEach(([key, defaultValue]) => {
+      if (typeof opts[key] !== "undefined") {
+        this.cfg[key] = opts[key];
+      }
+    });
+    if (opts.crcPolicy) {
+      this.CRC_STRICT = opts.crcPolicy.mode === "strict";
+      this.MAX_RESYNC_DROPS = opts.crcPolicy.mode === "resync" ? (_a = opts.crcPolicy.maxResyncDrops) != null ? _a : DEFAULT_MAX_RESYNC_DROPS : 0;
+    }
     this.port = (_c = opts.port) != null ? _c : await navigator.serial.requestPort({
       filters: (_b = opts.requestFilters) != null ? _b : []
     });
     await this.port.open({
-      baudRate: (_d = opts.baudRate) != null ? _d : 9600,
-      dataBits: (_e = opts.dataBits) != null ? _e : 8,
-      stopBits: (_f = opts.stopBits) != null ? _f : 1,
-      parity: (_g = opts.parity) != null ? _g : "none"
+      baudRate: this.cfg.baudRate,
+      dataBits: this.cfg.dataBits,
+      stopBits: this.cfg.stopBits,
+      parity: this.cfg.parity
     });
     this.reader = this.port.readable.getReader();
     this.writer = this.port.writable.getWriter();
-    const policy = (_h = opts.crcPolicy) != null ? _h : DEFAULT_CRC_POLICY;
-    if (policy.mode === "strict") {
-      this.strictCrc = true;
-      this.maxResyncDrops = 0;
-    } else {
-      this.strictCrc = false;
-      this.maxResyncDrops = (_i = policy.maxResyncDrops) != null ? _i : DEFAULT_MAX_RESYNC_DROPS;
+    if (typeof performance !== "undefined") {
+      this.now = () => performance.now();
     }
   }
   // ----------------------------------------------------------------
   //  transact(): Send `req` and await a response whose function-code matches the request
   // ---------------------------------------------------------------- */
   async transact(req) {
-    await this.writer.write(req);
-    const STRICT_CRC = this.strictCrc;
-    const MAX_RESYNC_DROPS = this.maxResyncDrops;
-    const expectedFC = req[1] & 127;
-    const deadline = Date.now() + this.timeout;
-    let State;
-    ((State2) => {
-      State2[State2["TRY_EXTRACT"] = 0] = "TRY_EXTRACT";
-      State2[State2["HAVE_FRAME"] = 1] = "HAVE_FRAME";
-      State2[State2["BAD_CRC"] = 2] = "BAD_CRC";
-      State2[State2["NEED_READ"] = 3] = "NEED_READ";
-    })(State || (State = {}));
-    let state = 0 /* TRY_EXTRACT */;
-    let frame = null;
-    let discardedBytes = 0;
-    while (true) {
-      switch (state) {
-        case 0 /* TRY_EXTRACT */: {
-          frame = this.extractFrame();
-          if (!frame) {
-            state = 3 /* NEED_READ */;
-            break;
+    if (this.inFlight) {
+      throw new Error("Concurrent transact() calls are not supported");
+    }
+    this.inFlight = true;
+    try {
+      if (this.cfg.interRequestDelay > 0 && this.lastTransactionEnd !== null) {
+        const wait = this.lastTransactionEnd + this.cfg.interRequestDelay - this.now();
+        if (wait > 0) await sleep(wait);
+      }
+      await this.waitOutDirtyPeriod();
+      await this.writer.write(req);
+      const deadline = this.now() + this.cfg.timeout;
+      let State;
+      ((State2) => {
+        State2[State2["TRY_EXTRACT"] = 0] = "TRY_EXTRACT";
+        State2[State2["HAVE_FRAME"] = 1] = "HAVE_FRAME";
+        State2[State2["BAD_CRC"] = 2] = "BAD_CRC";
+        State2[State2["NEED_READ"] = 3] = "NEED_READ";
+      })(State || (State = {}));
+      let state = 0 /* TRY_EXTRACT */;
+      let frame = null;
+      let discardedBytes = 0;
+      while (true) {
+        switch (state) {
+          case 0 /* TRY_EXTRACT */: {
+            frame = this.extractFrame();
+            if (!frame) {
+              state = 3 /* NEED_READ */;
+              break;
+            }
+            state = 1 /* HAVE_FRAME */;
           }
-          state = 1 /* HAVE_FRAME */;
-        }
-        case 1 /* HAVE_FRAME */: {
-          if (this.crcOk(frame)) {
-            const fc = frame[1] & 127;
-            if (fc === expectedFC) return frame;
-            frame = null;
-            state = 0 /* TRY_EXTRACT */;
-            continue;
+          case 1 /* HAVE_FRAME */: {
+            if (this.crcOk(frame)) {
+              if (!proveRequestResponseMismatch(req, frame)) return frame;
+              frame = null;
+              state = 0 /* TRY_EXTRACT */;
+              continue;
+            }
+            state = 2 /* BAD_CRC */;
           }
-          state = 2 /* BAD_CRC */;
-        }
-        case 2 /* BAD_CRC */: {
-          if (STRICT_CRC) throw new CrcError();
-          discardedBytes += frame ? frame.length : 0;
-          frame = null;
-          if (discardedBytes >= MAX_RESYNC_DROPS) {
-            throw new ResyncError(discardedBytes, MAX_RESYNC_DROPS);
+          case 2 /* BAD_CRC */: {
+            if (this.CRC_STRICT) throw new CrcError();
+            discardedBytes += frame ? frame.length : 0;
+            frame = null;
+            if (discardedBytes >= this.MAX_RESYNC_DROPS) {
+              throw new ResyncError(discardedBytes, this.MAX_RESYNC_DROPS);
+            }
+            if (this.rxBuf.length > 0) {
+              state = 0 /* TRY_EXTRACT */;
+              continue;
+            }
+            state = 3 /* NEED_READ */;
           }
-          if (this.rxBuf.length > 0) {
+          case 3 /* NEED_READ */: {
+            const now = this.now();
+            const remaining = deadline - now;
+            if (remaining <= 0) throw new TimeoutError();
+            const value = await this.readWithTimeout(remaining);
+            this.rxBuf = concat(this.rxBuf, value);
             state = 0 /* TRY_EXTRACT */;
             continue;
           }
-          state = 3 /* NEED_READ */;
+          default:
+            throw new Error("invalid state");
         }
-        case 3 /* NEED_READ */: {
-          if (Date.now() > deadline) throw new TimeoutError();
-          const { value } = await this.reader.read();
-          if (!value) throw new TimeoutError();
-          this.rxBuf = concat(this.rxBuf, value);
-          state = 0 /* TRY_EXTRACT */;
-          continue;
-        }
-        default:
-          throw new Error("invalid state");
       }
+    } finally {
+      this.inFlight = false;
+      this.lastTransactionEnd = this.now();
+    }
+  }
+  async readOnce(maxMs) {
+    if (maxMs <= 0) return { kind: "timeout" };
+    const ms = Math.max(1, maxMs);
+    let timer;
+    try {
+      const result = await Promise.race([
+        this.reader.read(),
+        new Promise((resolve) => {
+          timer = setTimeout(() => resolve(_WebSerialTransport.TIMEOUT), ms);
+        })
+      ]);
+      if (result === _WebSerialTransport.TIMEOUT)
+        return { kind: "timeout" };
+      if (result.done || !result.value) return { kind: "closed" };
+      return { kind: "chunk", value: result.value };
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+  async waitOutDirtyPeriod() {
+    for (; ; ) {
+      const now = this.now();
+      if (now >= this.dirtyUntil) return;
+      const remaining = this.dirtyUntil - now;
+      const r = await this.readOnce(remaining);
+      if (r.kind !== "chunk") break;
+    }
+    this.rxBuf = new Uint8Array(0);
+  }
+  async readWithTimeout(ms) {
+    const r = await this.readOnce(ms);
+    if (r.kind === "chunk") return r.value;
+    if (r.kind === "timeout") {
+      await this.resetReaderAfterTimeout();
+      this.rxBuf = new Uint8Array(0);
+      this.dirtyUntil = this.now() + this.cfg.postTimeoutWaitPeriod;
+      throw new TimeoutError();
+    }
+    if (r.kind === "closed") {
+      throw new StreamClosedError();
+    }
+    throw new Error("invalid read result");
+  }
+  async resetReaderAfterTimeout() {
+    try {
+      await this.reader.cancel();
+    } catch (e) {
     }
+    try {
+      this.reader.releaseLock();
+    } catch (e) {
+    }
+    this.reader = this.port.readable.getReader();
   }
   extractFrame() {
     if (this.rxBuf.length < 3) return null;
@@ -178,6 +287,9 @@ var WebSerialTransport = class _WebSerialTransport {
     const crcOk = (crc & 255) === frame[frame.length - 2] && crc >> 8 === frame[frame.length - 1];
     return crcOk;
   }
+  now() {
+    return Date.now();
+  }
   // ----------------------------------------------------------------
   //  Determine expected length; return 0 if we still need more bytes
   // ----------------------------------------------------------------
@@ -195,7 +307,11 @@ var WebSerialTransport = class _WebSerialTransport {
       const need = 3 + byteCount + 2;
       return buf.length >= need ? need : 0;
     }
-    if (fc === 5 || fc === 6 || fc === 15 || fc === 16)
+    if (fc === 5 || // write single coil
+    fc === 6 || // write single register
+    fc === 15 || // write multiple coils
+    fc === 16 || // write multiple registers
+    fc === 22)
       return buf.length >= 8 ? 8 : 0;
     return buf.length >= 8 ? 8 : 0;
   }
@@ -206,27 +322,100 @@ var WebSerialTransport = class _WebSerialTransport {
     await ((_c = this.port) == null ? void 0 : _c.close());
   }
 };
+_WebSerialTransport.TIMEOUT = Symbol("timeout");
+var WebSerialTransport = _WebSerialTransport;
+function proveRequestResponseMismatch(req, res) {
+  if (req.length < 2 || res.length < 2) return false;
+  const reqAddr = req[0];
+  const reqFc = req[1] & 127;
+  const resAddr = res[0];
+  const resFc = res[1];
+  const resBaseFc = resFc & 127;
+  if (resAddr !== reqAddr) return true;
+  if (resBaseFc !== reqFc) return true;
+  if (resFc & 128) {
+    return res.length !== 5;
+  }
+  switch (reqFc) {
+    case FC_READ_COILS:
+    case FC_READ_DISCRETE_INPUTS: {
+      if (req.length < 6 || res.length < 3) return false;
+      const quantity = u16be(req, 4);
+      const expectedByteCount = Math.ceil(quantity / 8);
+      if (res[2] !== expectedByteCount) return true;
+      if (res.length !== 3 + expectedByteCount + 2) return true;
+      return false;
+    }
+    case FC_READ_HOLDING_REGISTERS:
+    case FC_READ_INPUT_REGISTERS: {
+      if (req.length < 6 || res.length < 3) return false;
+      const quantity = u16be(req, 4);
+      const expectedByteCount = quantity * 2;
+      if (res[2] !== expectedByteCount) return true;
+      if (res.length !== 3 + expectedByteCount + 2) return true;
+      return false;
+    }
+    case FC_WRITE_SINGLE_COIL:
+    case FC_WRITE_SINGLE_HOLDING_REGISTER:
+    case FC_MASK_WRITE_REGISTER: {
+      if (req.length < 8 || res.length < 8) return false;
+      if (res.length !== req.length) return true;
+      if (!bytesEqual(req, 2, res, 2, req.length - 4)) return true;
+      return false;
+    }
+    case FC_WRITE_MULTIPLE_COILS:
+    case FC_WRITE_MULTIPLE_HOLDING_REGISTERS: {
+      if (req.length < 6 || res.length < 8) return false;
+      if (res.length !== 8) return true;
+      if (!bytesEqual(req, 2, res, 2, 4)) return true;
+      return false;
+    }
+    case FC_READ_WRITE_MULTIPLE_REGISTERS: {
+      if (req.length < 10 || res.length < 3) return false;
+      const readQuantity = u16be(req, 4);
+      const expectedByteCount = readQuantity * 2;
+      if (res[2] !== expectedByteCount) return true;
+      if (res.length !== 3 + expectedByteCount + 2) return true;
+      return false;
+    }
+    case FC_READ_FIFO_QUEUE: {
+      if (res.length < 6) return true;
+      const byteCount = u16be(res, 2);
+      if (byteCount < 2) return true;
+      if (res.length !== 4 + byteCount + 2) return true;
+      const fifoDataBytes = byteCount - 2;
+      if (fifoDataBytes % 2 !== 0) return true;
+      return false;
+    }
+    case FC_READ_FILE_RECORD:
+    case FC_WRITE_FILE_RECORD: {
+      if (res.length < 5) return true;
+      const byteCount = res[2];
+      if (res.length !== 3 + byteCount + 2) return true;
+      return false;
+    }
+    default:
+      return false;
+  }
+}
 function concat(a, b) {
   const out = new Uint8Array(a.length + b.length);
   out.set(a, 0);
   out.set(b, a.length);
   return out;
 }
-
-// src/core/types.ts
-var FC_READ_HOLDING_REGISTERS = 3;
-var FC_WRITE_SINGLE_HOLDING_REGISTER = 6;
-var FC_WRITE_MULTIPLE_HOLDING_REGISTERS = 16;
-var FC_READ_COILS = 1;
-var FC_WRITE_SINGLE_COIL = 5;
-var FC_WRITE_MULTIPLE_COILS = 15;
-var FC_READ_INPUT_REGISTERS = 4;
-var FC_READ_DISCRETE_INPUTS = 2;
-var FC_READ_FILE_RECORD = 20;
-var FC_WRITE_FILE_RECORD = 21;
-var FC_MASK_WRITE_REGISTER = 22;
-var FC_READ_WRITE_MULTIPLE_REGISTERS = 23;
-var FC_READ_FIFO_QUEUE = 24;
+function u16be(buf, offset) {
+  return buf[offset] << 8 | buf[offset + 1];
+}
+function bytesEqual(a, aStart, b, bStart, len) {
+  for (let i = 0; i < len; i++) {
+    if (a[aStart + i] !== b[bStart + i]) return false;
+  }
+  return true;
+}
+async function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 
 // src/core/frames.ts
 function buildReadHolding(id, addr, len) {
@@ -662,11 +851,20 @@ var ModbusRTU = class _ModbusRTU {
     return { data: parseReadFifoQueue(raw), raw };
   }
 };
+
+// src/index.ts
+var BUILD_INFO = {
+  version: "0.11.0",
+  commit: "0107e92",
+  buildTime: "2026-03-13T07:30:43.483Z"
+};
 export {
+  BUILD_INFO,
   CrcError,
   ExceptionError,
   ModbusRTU,
   ResyncError,
+  StreamClosedError,
   TimeoutError,
   buildMaskWriteRegister,
   buildReadCoils,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "modbus-webserial",
-  "version": "0.10.3",
-  "description": "Tiny TypeScript library for speaking Modbus-RTU from the browser via Web Serial",
+  "version": "0.11.0",
+  "description": "ESM library for speaking Modbus-RTU from the browser via Web Serial",
   "type": "module",
   "author": "Antti Kotajärvi <antti.kotajarvi@hotmail.com>",
   "license": "MIT",