njs-modbus 3.3.0 → 3.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](./README.zh-CN.md)
 
-A pure JavaScript implementation of Modbus for Node.js.
+A pure JavaScript implementation of Modbus for Node.js, optimized for throughput and low GC pressure.
 
 <!-- prettier-ignore-start -->
 [![npm download](http://img.shields.io/npm/dw/njs-modbus.svg?style=flat-square)](http://www.npm-stats.com/~packages/njs-modbus)
@@ -11,17 +11,20 @@ A pure JavaScript implementation of Modbus for Node.js.
 [![CI](https://img.shields.io/github/actions/workflow/status/xiejay97/njs-modbus/ci.yml?branch=main&style=flat-square)](https://github.com/xiejay97/njs-modbus/actions)
 <!-- prettier-ignore-end -->
 
-## Features
+## Highlights
 
-- **Protocols:** Modbus TCP, RTU, ASCII
-- **Transports:** Serial, TCP client/server, UDP client/server
-- **Master:** FIFO or pipelined concurrent requests (protocol must be TCP)
-- **Slave:** Per-connection FIFO or concurrent processing (protocol must be TCP)
+- **Protocols** — Modbus TCP, RTU, ASCII
+- **Transports** — Serial, TCP client/server, UDP client/server, plus pluggable custom layers
+- **Performance-first** — Parallel FIFO queues, lazy-deletion timer heap, inline BE reads/writes, zero-allocation hot paths
+- **Master** — FIFO or pipelined concurrent requests (TCP only)
+- **Slave** — Per-connection FIFO or concurrent processing (TCP only)
 - **Custom function codes** with pluggable framing
-- **Broadcasting** (unit = 0)
+- **Broadcasting** (`unit = 0`)
 - **Full TypeScript**
 - **Zero runtime dependencies** (peer-depends on `serialport` for serial)
 
+## Supported Function Codes
+
 | Code | Name |
 |------|------|
 | 01 | Read Coils |
@@ -116,20 +119,45 @@ const master = new ModbusMaster({
 });
 ```
 
-## Physical Layers
+## Architecture
+
+The library follows a strict two-layer design:
+
+```
+┌─────────────────────────────────────────┐
+│         ModbusMaster / ModbusSlave        │  ← User API, session/queue management
+├─────────────────────────────────────────┤
+│      TcpApplicationLayer                │  ← Protocol framing (MBAP / CRC16 / LRC)
+│      RtuApplicationLayer                │
+│      AsciiApplicationLayer              │
+├─────────────────────────────────────────┤
+│      AbstractPhysicalConnection         │  ← Per-connection I/O
+├─────────────────────────────────────────┤
+│      AbstractPhysicalLayer              │  ← Resource ownership (port/socket/server)
+│      ├── TcpClientPhysicalLayer         │
+│      ├── TcpServerPhysicalLayer         │
+│      ├── UdpClientPhysicalLayer         │
+│      ├── UdpServerPhysicalLayer         │
+│      └── SerialPhysicalLayer            │
+└─────────────────────────────────────────┘
+```
+
+Every transport is modeled as connection-oriented: physical layers emit `'connect'` with an `AbstractPhysicalConnection`, and a dedicated application layer instance is created per connection.
 
-All physical layers expose `open()` / `close()`, a `state` property, and events: `'open'`, `'connect'`, `'close'`, `'error'`.
+## Physical Layer
 
-| Type | Class | `open(...)` args |
-|------|-------|-----------------|
-| `SERIAL` | `SerialPhysicalLayer` | none |
-| `TCP_CLIENT` | `TcpClientPhysicalLayer` | `SocketConnectOpts` |
-| `TCP_SERVER` | `TcpServerPhysicalLayer` | `ListenOptions` |
-| `UDP_CLIENT` | `UdpClientPhysicalLayer` | `{ port, address }` |
-| `UDP_SERVER` | `UdpServerPhysicalLayer` | `BindOptions` |
-| `CUSTOM` | *(user-provided)* | *(user-defined)* |
+All physical layers expose `open()` / `close()`, a `state` property, and the events documented in [Events](#events).
 
-### Server options
+| Type | `open(...)` Args | Description |
+|------|-----------------|-------------|
+| `SERIAL` | `()` | Serial port via `serialport` package |
+| `TCP_CLIENT` | `SocketConnectOpts` | TCP client socket |
+| `TCP_SERVER` | `ListenOptions` | TCP server |
+| `UDP_CLIENT` | `{ port?, address? }` | UDP client |
+| `UDP_SERVER` | `BindOptions` | UDP server |
+| `CUSTOM` | *(user-defined)* | User-provided `AbstractPhysicalLayer` instance |
+
+### TCP Server options
 
 ```typescript
 const slave = new ModbusSlave({
@@ -145,7 +173,7 @@ const slave = new ModbusSlave({
 });
 ```
 
-### Physical layer options
+### Physical layer option reference
 
 | Option | Type | Description |
 |--------|------|-------------|
@@ -154,54 +182,35 @@ const slave = new ModbusSlave({
 | `idleTimeout` | `number` | Idle timeout in ms before evicting a connection. Default `30000`. Pass `0` to disable. |
 | `socketOpts` / `serverOpts` | `object` | Forwarded to Node.js `createSocket()` / `createServer()`. |
 
-## Custom Physical Layer
-
-Any byte-oriented transport can be used by implementing `AbstractPhysicalLayer` and `AbstractPhysicalConnection`, then passing `{ type: 'CUSTOM', layer: yourLayer }`.
-
-```typescript
-import { AbstractPhysicalLayer, AbstractPhysicalConnection } from 'njs-modbus';
-
-class MyPhysicalLayer extends AbstractPhysicalLayer { /* open / close */ }
-class MyConnection extends AbstractPhysicalConnection { /* write / destroy, emit 'data' */ }
-
-const master = new ModbusMaster({
-  physical: { type: 'CUSTOM', layer: new MyPhysicalLayer() },
-  protocol: { type: 'TCP' },
-});
-```
-
-See [`examples/websocket`](./examples/websocket) for a complete **Modbus TCP over WebSocket** implementation — client/server physical layers with a working demo.
+## Protocol Layer
 
-See [`examples/bluetooth`](./examples/bluetooth) for a **Modbus TCP over BLE** implementation using the Nordic UART Service (NUS) — includes a loopback test that runs without real BLE hardware.
+| Protocol | Options | Description |
+|----------|---------|-------------|
+| `TCP` | none | Modbus TCP with MBAP header |
+| `RTU` | `RtuProtocolOptions` | Modbus RTU with CRC16 |
+| `ASCII` | `AsciiApplicationLayerOptions` | Modbus ASCII with LRC |
 
-## Master API
-
-```typescript
-new ModbusMaster({
-  physical: { type: 'TCP_CLIENT' },
-  protocol: { type: 'TCP' },          // 'TCP' | 'RTU' | 'ASCII'
-  timeout?: 1000,                     // per-request timeout (ms)
-  concurrent?: false,                 // pipelined mode (protocol: TCP only)
-})
-```
-
-RTU framing options:
+### RTU options
 
 ```typescript
 protocol: {
   type: 'RTU',
   opts: {
-    // Either a bare number (milliseconds), or `{ unit: 'bit' | 'ms', value: N }`.
-    // Use `0` to disable the timer entirely (useful for lossless transports
-    // such as RTU-over-TCP).
-    intervalBetweenFrames: 20,                          // 20 ms
-    interCharTimeout: { unit: 'bit', value: 10 },       // bit-time, needs baudRate
-    poolSize: 1024,
+    // t3.5 inter-frame silence.
+    // Either a bare number (ms) or { unit: 'bit' | 'ms', value: N }.
+    // Use 0 to disable (useful for lossless transports like RTU-over-TCP).
+    intervalBetweenFrames: 20,
+
+    // t1.5 inter-character timeout (opt-in).
+    interCharTimeout: { unit: 'bit', value: 10 },
+
+    // Discard frames with t1.5 timing violations.
+    strictTiming: true,
   },
 }
 ```
 
-ASCII options:
+### ASCII options
 
 ```typescript
 protocol: {
@@ -212,11 +221,24 @@ protocol: {
 }
 ```
 
+## Master API
+
+### Constructor
+
+```typescript
+new ModbusMaster({
+  physical: { type: 'TCP_CLIENT' },
+  protocol: { type: 'TCP' },          // 'TCP' | 'RTU' | 'ASCII'
+  timeout?: 1000,                     // per-request timeout (ms)
+  concurrent?: false,                 // pipelined mode (TCP only)
+})
+```
+
 ### Methods
 
 | Method | Description |
 |--------|-------------|
-| `open(...args)` | Open the physical layer. Can only be called once; after `close()` the instance is dead. |
+| `open(...args)` | Open the physical layer. One-shot: cannot reopen after `close()`. |
 | `close()` | Close immediately. In-flight and queued requests are rejected. |
 | `readCoils(unit, address, length, timeout?)` | FC 01 |
 | `readDiscreteInputs(unit, address, length, timeout?)` | FC 02 |
@@ -238,11 +260,13 @@ Broadcast (`unit = 0`) resolves `void` — slaves never respond.
 
 ## Slave API
 
+### Constructor
+
 ```typescript
 new ModbusSlave({
   physical: { type: 'TCP_SERVER' },
   protocol: { type: 'TCP' },
-  concurrent?: false, // per-connection concurrent (protocol: TCP only)
+  concurrent?: false, // per-connection concurrent (TCP only)
 })
 ```
 
@@ -255,8 +279,8 @@ slave.add({
   // Optional: intercept any FC before default dispatch
   interceptor?: (fc, data) => Buffer | undefined,
 
-  readCoils?: (address, length) => boolean[] | Uint8Array,
-  readDiscreteInputs?: (address, length) => boolean[] | Uint8Array,
+  readCoils?: (address, length) => Uint8Array,
+  readDiscreteInputs?: (address, length) => Uint8Array,
   readHoldingRegisters?: (address, length) => number[] | Uint16Array,
   readInputRegisters?: (address, length) => number[] | Uint16Array,
 
@@ -283,31 +307,70 @@ slave.add({
 
 Missing handlers return `ILLEGAL_FUNCTION`. Out-of-range addresses return `ILLEGAL_DATA_ADDRESS`. Handler throws become `SERVER_DEVICE_FAILURE` unless the error is a `ModbusError`.
 
+### Methods
+
 | Method | Description |
 |--------|-------------|
 | `add(model)` | Register a slave model |
-| `remove(unit)` | Remove a slave model |
-| `open(...args)` | Open the physical layer. One-shot: cannot reopen after `close()`. |
+| `remove(unit)` | Remove a model |
+| `open(...args)` | Open and begin accepting connections. One-shot. |
 | `close()` | Close immediately |
-| `addCustomFunctionCode(cfc)` | Register a custom FC |
-| `removeCustomFunctionCode(fc)` | Unregister a custom FC |
+| `addCustomFunctionCode(cfc)` | Register custom FC |
+| `removeCustomFunctionCode(fc)` | Unregister custom FC |
+
+## Events
+
+Both `ModbusMaster` and `ModbusSlave` are `EventEmitter`s. All events are typed.
+
+### Physical layer events
+
+| Event | Arguments | Description |
+|-------|-----------|-------------|
+| `open` | `()` | Physical layer is ready to accept connections |
+| `connect` | `(connection)` | A new connection has been established |
+| `close` | `()` | Physical layer has closed |
+| `error` | `(error)` | Physical layer error |
+
+### Connection debug events
+
+| Event | Arguments | Description |
+|-------|-----------|-------------|
+| `tx` | `(buffer, connection)` | Raw data written to the wire |
+| `rx` | `(buffer, connection)` | Raw data received from the wire |
+
+### Application layer events
+
+| Event | Arguments | Description |
+|-------|-----------|-------------|
+| `framing` | `(frame, connection)` | A complete frame has been decoded |
+| `framingError` | `(error, connection)` | Framing error (CRC/LRC failure, malformed MBAP, timing violation, etc.) |
+
+```typescript
+master.on('framing', (frame, connection) => {
+  console.log('frame:', frame.unit, frame.fc, frame.transaction);
+});
+
+master.on('framingError', (error, connection) => {
+  console.log('framing error:', error.message);
+});
+```
 
 ## Custom Function Codes
 
-`predictRequestLength` / `predictResponseLength` receive a shared pool buffer and byte offsets (`start`, `end`). Use `end - start` for bounds checks rather than `buffer.length`.
+`predictRequestLength` / `predictResponseLength` receive a `getByte` accessor and the number of available `length` bytes. Use `length` for bounds checks — do not access the buffer directly.
 
 ```typescript
 import type { CustomFunctionCode } from 'njs-modbus';
 
 const cfc: CustomFunctionCode = {
   fc: 0x50,
-  predictRequestLength: (buffer, start, end) => {
-    if (end - start < 2) return null;
-    return 4 + buffer[start + 1];
+  predictRequestLength: (getByte, length) => {
+    if (length < 2) return 0; // need more bytes
+    return 4 + getByte(1);
   },
-  predictResponseLength: (buffer, start, end) => {
-    if (end - start < 2) return null;
-    return 4 + buffer[start + 1];
+  predictResponseLength: (getByte, length) => {
+    if (length < 2) return 0;
+    return 4 + getByte(1);
   },
   handle: async (data, unit) => {
     return Buffer.from([data[1], data[0]]);
@@ -348,82 +411,65 @@ slave.add({
 });
 ```
 
-## Performance
+## Custom Physical Layer
+
+Any byte-oriented transport can be used by implementing `AbstractPhysicalLayer` and `AbstractPhysicalConnection`, then passing `{ type: 'CUSTOM', layer: yourLayer }`.
 
-Benchmarked against [jsmodbus](https://github.com/Cloud-Automation/node-modbus) and [modbus-serial](https://github.com/yaacov/node-modbus-serial).
+```typescript
+import { AbstractPhysicalLayer, AbstractPhysicalConnection } from 'njs-modbus';
 
-| Metric | njs-modbus | jsmodbus | modbus-serial |
-|--------|-----------|----------|---------------|
-| TCP Throughput | **70,544 ops/sec** | 39,827 (0.56x) | 786 (0.01x) |
-| TCP P99 Latency | **53 µs** | 98 µs (1.83x) | 2,331 µs (43.7x) |
-| Concurrent (8 conn) | **75,810 ops/sec** | 41,754 (0.55x) | 5,620 (0.07x) |
-| RTU Serial (115200 baud) | **44 ops/sec** | 44 ops/sec | 45 ops/sec |
-| TCP Response Encode | **6.57M ops/sec** | 1.22M (0.19x) | 1.18M (0.18x) |
-| TCP Response Decode | **6.78M ops/sec** | 1.94M (0.29x) | 0.67M (0.10x) |
-| FC01 Read Coils | **85,170 ops/sec** | 617 (0.01x) | 861 (0.01x) |
+class MyPhysicalLayer extends AbstractPhysicalLayer { /* open / close */ }
+class MyConnection extends AbstractPhysicalConnection { /* write / destroy, emit 'data' */ }
 
-<details>
-<summary>Full benchmark results</summary>
+const master = new ModbusMaster({
+  physical: { type: 'CUSTOM', layer: new MyPhysicalLayer() },
+  protocol: { type: 'TCP' },
+});
+```
 
-Node.js v24.16.0 · AMD Ryzen 7 9800X3D · linux x64 · 3 runs × 120 s · [full report](./benchmark/RESULTS.md)
+See [`examples/websocket`](./examples/websocket) for a complete **Modbus TCP over WebSocket** implementation.
 
-### TCP Throughput (Single Connection)
+See [`examples/bluetooth`](./examples/bluetooth) for a **Modbus TCP over BLE** implementation using the Nordic UART Service (NUS).
 
-```
-njs-modbus    │ ██████████████████████████████ 70,544 ops/sec 🏆   p99: 53 µs   CPU: 91 µs/op
-jsmodbus      │ █████████████████░░░░░░░░░░░░░ 39,827 ops/sec (0.56x)  p99: 98 µs   CPU: 161 µs/op
-modbus-serial │ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░    786 ops/sec (0.01x)  p99: 2,331 µs CPU: 8,176 µs/op
-```
+## Performance
 
-### Concurrent (8 Connections)
+Benchmarked against [jsmodbus](https://github.com/Cloud-Automation/node-modbus) v4.0.10 and [modbus-serial](https://github.com/yaacov/node-modbus-serial) v8.0.25.
 
-```
-njs-modbus    │ ██████████████████████████████ 75,810 ops/sec 🏆   p99: 258 µs  CPU: 91 µs/op
-jsmodbus      │ █████████████████░░░░░░░░░░░░░ 41,754 ops/sec (0.55x)  p99: 543 µs  CPU: 167 µs/op
-modbus-serial │ ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░  5,620 ops/sec (0.07x)  p99: 3,180 µs CPU: 1,237 µs/op
-```
+Environment: AMD Ryzen 7 9800X3D 8-Core Processor · Node.js v24.16.0 · [full report](./benchmark/report_presentation.md)
 
-### RTU Serial (115200 baud via socat PTY)
+### End-to-end TCP
 
-```
-njs-modbus    │ 44 ops/sec   p99: 993 µs   CPU: 729 µs/op   GC: 2,613 ns/op
-jsmodbus      │ 44 ops/sec   p99: 1,019 µs  CPU: 694 µs/op   GC: 2,609 ns/op
-modbus-serial │ 45 ops/sec   p99: 3,228 µs  CPU: 765 µs/op   GC: 3,864 ns/op
-```
+| Metric | njs-modbus | jsmodbus | modbus-serial |
+|--------|-----------|----------|---------------|
+| Single connection | **74,964 ops/sec** 🏆 | 55,996 (0.75x) | 853 (0.01x) |
+| 8 concurrent clients | **10,188 ops/sec** 🏆 | 5,918 (0.58x) | 728 (0.07x) |
+| P99 latency (single) | **17 µs** 🏆 | 15 µs (0.88x) | 1,206 µs (70.9x) |
 
-### Frame Encode / Decode (CPU Micro-benchmark)
+### Frame encode / decode (CPU micro-benchmark)
 
-```
-tcpReqEncode:  njs-modbus 6.90M ops/sec 🏆  jsmodbus 0.78x  modbus-serial 0.19x
-tcpResEncode:  njs-modbus 6.57M ops/sec 🏆  jsmodbus 0.19x  modbus-serial 0.18x
-tcpReqDecode:  njs-modbus 6.80M ops/sec 🏆  jsmodbus 0.81x  modbus-serial 0.17x
-tcpResDecode:  njs-modbus 6.78M ops/sec 🏆  jsmodbus 0.29x  modbus-serial 0.10x
-rtuReqEncode:  njs-modbus 7.26M ops/sec 🏆  jsmodbus 0.35x  modbus-serial 0.76x
-rtuReqDecode:  njs-modbus 3.97M ops/sec     jsmodbus 1.21x  modbus-serial 1.78x 🏆
-asciiReqEncode: njs-modbus 5.64M ops/sec 🏆  modbus-serial 0.57x
-asciiReqDecode: njs-modbus 3.37M ops/sec 🏆  modbus-serial 0.34x
-```
+| Benchmark | njs-modbus | jsmodbus | modbus-serial |
+|-----------|-----------|----------|---------------|
+| TCP request encode | **9.61M ops/sec** 🏆 | 6.32M (0.66x) | 0.68M (0.07x) |
+| TCP response encode | **7.51M ops/sec** 🏆 | 1.18M (0.16x) | 0.44M (0.06x) |
+| TCP response decode | **8.55M ops/sec** 🏆 | 2.04M (0.24x) | 0.70M (0.08x) |
+| RTU request encode | **9.42M ops/sec** 🏆 | 3.03M (0.32x) | 6.57M (0.70x) |
+| ASCII request encode | **7.09M ops/sec** 🏆 | — | 4.11M (0.58x) |
+| ASCII request decode | **4.91M ops/sec** 🏆 | — | 1.19M (0.24x) |
 
-### Per-Function-Code TCP Throughput (Normal Payload)
+### Per-function-code TCP throughput (100 coils / 50 registers)
 
 | Function Code | njs-modbus | jsmodbus | modbus-serial |
 |---------------|-----------|----------|---------------|
-| FC01 Read Coils | **85,170** 🏆 | 617 (0.01x) | 861 (0.01x) |
-| FC02 Read Discrete Inputs | **85,570** 🏆 | 525 (0.01x) | 861 (0.01x) |
-| FC03 Read Holding Registers | **75,344** 🏆 | 40,081 (0.53x) | 852 (0.01x) |
-| FC04 Read Input Registers | **75,757** 🏆 | 49,524 (0.65x) | 866 (0.01x) |
-| FC05 Write Single Coil | **92,852** 🏆 | 53,521 (0.58x) | 871 (0.01x) |
-| FC06 Write Single Register | **92,864** 🏆 | 53,684 (0.58x) | 872 (0.01x) |
-| FC15 Write Multiple Coils | **86,434** 🏆 | 319 (0.00x) | 869 (0.01x) |
-| FC16 Write Multiple Registers | **76,053** 🏆 | 39,356 (0.52x) | 852 (0.01x) |
-| FC17 Report Server ID | **74,697** 🏆 | — | — |
-| FC22 Mask Write Register | **90,717** 🏆 | — | — |
-| FC23 Read/Write Multiple Registers | **85,652** 🏆 | — | — |
-| FC43 Read Device Identification | **78,030** 🏆 | — | 865 (0.01x) |
-
-> FC17 / FC22 / FC23 are not supported by jsmodbus or modbus-serial.
-
-</details>
+| FC01 Read Coils | **75,430** 🏆 | 488 (0.01x) | 859 (0.01x) |
+| FC03 Read Holding Registers | **82,028** 🏆 | 46,596 (0.57x) | 864 (0.01x) |
+| FC06 Write Single Register | **86,110** 🏆 | 51,084 (0.59x) | 871 (0.01x) |
+| FC15 Write Multiple Coils | **78,766** 🏆 | — | 867 (0.01x) |
+| FC17 Report Server ID | **79,185** 🏆 | — | — |
+| FC22 Mask Write Register | **73,060** 🏆 | — | — |
+| FC23 Read/Write Multiple Registers | **68,429** 🏆 | — | — |
+| FC43 Read Device Identification | **62,176** 🏆 | — | 868 (0.01x) |
+
+> FC17 / FC22 / FC23 / FC43 are not supported by jsmodbus.
 
 ## License