njs-modbus 3.2.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 (TCP only)
-- **Slave:** Per-connection FIFO or concurrent processing (TCP only)
+- **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 |
@@ -39,6 +42,8 @@ A pure JavaScript implementation of Modbus for Node.js.
 
 ## Installation
 
+Requires **Node.js ≥ 18.19**.
+
 ```bash
 npm install njs-modbus
 ```
@@ -114,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.
+
+## Physical Layer
 
-All physical layers expose `open()` / `close()`, a `state` property, and events: `'open'`, `'connect'`, `'close'`, `'error'`.
+All physical layers expose `open()` / `close()`, a `state` property, and the events documented in [Events](#events).
 
-| 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)* |
+| 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 |
 
-### Server options
+### TCP Server options
 
 ```typescript
 const slave = new ModbusSlave({
@@ -143,7 +173,7 @@ const slave = new ModbusSlave({
 });
 ```
 
-### Physical layer options
+### Physical layer option reference
 
 | Option | Type | Description |
 |--------|------|-------------|
@@ -152,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 (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: {
@@ -210,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 |
@@ -236,6 +260,8 @@ Broadcast (`unit = 0`) resolves `void` — slaves never respond.
 
 ## Slave API
 
+### Constructor
+
 ```typescript
 new ModbusSlave({
   physical: { type: 'TCP_SERVER' },
@@ -253,10 +279,10 @@ slave.add({
   // Optional: intercept any FC before default dispatch
   interceptor?: (fc, data) => Buffer | undefined,
 
-  readCoils?: (address, length) => boolean[],
-  readDiscreteInputs?: (address, length) => boolean[],
-  readHoldingRegisters?: (address, length) => number[],
-  readInputRegisters?: (address, length) => number[],
+  readCoils?: (address, length) => Uint8Array,
+  readDiscreteInputs?: (address, length) => Uint8Array,
+  readHoldingRegisters?: (address, length) => number[] | Uint16Array,
+  readInputRegisters?: (address, length) => number[] | Uint16Array,
 
   writeSingleCoil?: (address, value) => void,
   writeMultipleCoils?: (address, values) => void,
@@ -281,29 +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 `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) => {
-    if (buffer.length < 2) return null;
-    return 4 + buffer[1];
+  predictRequestLength: (getByte, length) => {
+    if (length < 2) return 0; // need more bytes
+    return 4 + getByte(1);
   },
-  predictResponseLength: (buffer) => {
-    if (buffer.length < 2) return null;
-    return 4 + buffer[1];
+  predictResponseLength: (getByte, length) => {
+    if (length < 2) return 0;
+    return 4 + getByte(1);
   },
   handle: async (data, unit) => {
     return Buffer.from([data[1], data[0]]);
@@ -344,57 +411,65 @@ slave.add({
 });
 ```
 
-## Performance
-
-Benchmarked against [jsmodbus](https://github.com/Cloud-Automation/node-modbus) and [modbus-serial](https://github.com/yaacov/node-modbus-serial).
-
-| Metric | njs-modbus | jsmodbus | modbus-serial |
-|--------|-----------|----------|---------------|
-| TCP Throughput | **5,527 ops/sec** | 3,239 (0.59x) | 371 (0.07x) |
-| TCP P99 Latency | **2.71 ms** | 4.73 ms (1.75x) | 12.48 ms (4.61x) |
-| TCP CPU Efficiency | **1,116 µs/op** | 1,950 (1.75x) | 16,715 (14.98x) |
-| Concurrent (8 conn) | **5,274 ops/sec** | 3,416 (0.65x) | 1,815 (0.34x) |
-| RTU CPU Efficiency | **1,762 µs/op** | 1,760 (1.00x) | 2,144 (1.22x) |
-| TCP Res Encode | **2.04M ops/sec** | 373K (0.18x) | 411K (0.20x) |
-| TCP Res Decode | **1.91M ops/sec** | 538K (0.28x) | 231K (0.12x) |
+## Custom Physical Layer
 
-<details>
-<summary>Full benchmark results</summary>
+Any byte-oriented transport can be used by implementing `AbstractPhysicalLayer` and `AbstractPhysicalConnection`, then passing `{ type: 'CUSTOM', layer: yourLayer }`.
 
-Node.js v24.15.0 · linux x64 · 3 runs × 300 s · [full report](./benchmark/RESULTS.md)
+```typescript
+import { AbstractPhysicalLayer, AbstractPhysicalConnection } from 'njs-modbus';
 
-### TCP Throughput (Single Connection)
+class MyPhysicalLayer extends AbstractPhysicalLayer { /* open / close */ }
+class MyConnection extends AbstractPhysicalConnection { /* write / destroy, emit 'data' */ }
 
-```
-njs-modbus    │ 5,527 ops/sec 🏆   CPU: 1,116 µs/op
-jsmodbus      │ 3,239 ops/sec (0.59x)  CPU: 1,950 µs/op
-modbus-serial │   371 ops/sec (0.07x)  CPU: 16,715 µs/op
+const master = new ModbusMaster({
+  physical: { type: 'CUSTOM', layer: new MyPhysicalLayer() },
+  protocol: { type: 'TCP' },
+});
 ```
 
-### Concurrent (8 Connections)
+See [`examples/websocket`](./examples/websocket) for a complete **Modbus TCP over WebSocket** implementation.
 
-```
-njs-modbus    │ 5,274 ops/sec 🏆   CPU: 1,392 µs/op
-jsmodbus      │ 3,416 ops/sec (0.65x)  CPU: 2,131 µs/op
-modbus-serial │ 1,815 ops/sec (0.34x)  CPU: 3,962 µs/op
-```
+See [`examples/bluetooth`](./examples/bluetooth) for a **Modbus TCP over BLE** implementation using the Nordic UART Service (NUS).
 
-### RTU Serial (115200 baud simulated)
+## Performance
 
-```
-njs-modbus    │ 44 ops/sec   CPU: 1,762 µs/op
-jsmodbus      │ 44 ops/sec   CPU: 1,760 µs/op
-modbus-serial │ 44 ops/sec   CPU: 2,144 µs/op
-```
+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.
 
-### Encode / Decode (CPU Micro-benchmark)
+Environment: AMD Ryzen 7 9800X3D 8-Core Processor · Node.js v24.16.0 · [full report](./benchmark/report_presentation.md)
 
-```
-tcpResEncode: njs-modbus 2.04M ops/sec  (jsmodbus 0.18x, modbus-serial 0.20x)
-tcpResDecode: njs-modbus 1.91M ops/sec  (jsmodbus 0.28x, modbus-serial 0.12x)
-```
+### End-to-end TCP
 
-</details>
+| 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)
+
+| 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 (100 coils / 50 registers)
+
+| Function Code | njs-modbus | jsmodbus | modbus-serial |
+|---------------|-----------|----------|---------------|
+| 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