njs-modbus 3.2.0 → 3.3.0

package/README.md

@@ -15,8 +15,8 @@ A pure JavaScript implementation of Modbus for Node.js.
 
 - **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)
+- **Master:** FIFO or pipelined concurrent requests (protocol must be TCP)
+- **Slave:** Per-connection FIFO or concurrent processing (protocol must be TCP)
 - **Custom function codes** with pluggable framing
 - **Broadcasting** (unit = 0)
 - **Full TypeScript**
@@ -39,6 +39,8 @@ A pure JavaScript implementation of Modbus for Node.js.
 
 ## Installation
 
+Requires **Node.js ≥ 18.19**.
+
 ```bash
 npm install njs-modbus
 ```
@@ -179,7 +181,7 @@ new ModbusMaster({
   physical: { type: 'TCP_CLIENT' },
   protocol: { type: 'TCP' },          // 'TCP' | 'RTU' | 'ASCII'
   timeout?: 1000,                     // per-request timeout (ms)
-  concurrent?: false,                 // pipelined mode (TCP only)
+  concurrent?: false,                 // pipelined mode (protocol: TCP only)
 })
 ```
 
@@ -240,7 +242,7 @@ Broadcast (`unit = 0`) resolves `void` — slaves never respond.
 new ModbusSlave({
   physical: { type: 'TCP_SERVER' },
   protocol: { type: 'TCP' },
-  concurrent?: false, // per-connection concurrent (TCP only)
+  concurrent?: false, // per-connection concurrent (protocol: TCP only)
 })
 ```
 
@@ -253,10 +255,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) => boolean[] | Uint8Array,
+  readDiscreteInputs?: (address, length) => boolean[] | Uint8Array,
+  readHoldingRegisters?: (address, length) => number[] | Uint16Array,
+  readInputRegisters?: (address, length) => number[] | Uint16Array,
 
   writeSingleCoil?: (address, value) => void,
   writeMultipleCoils?: (address, values) => void,
@@ -292,18 +294,20 @@ Missing handlers return `ILLEGAL_FUNCTION`. Out-of-range addresses return `ILLEG
 
 ## 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`.
+
 ```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: (buffer, start, end) => {
+    if (end - start < 2) return null;
+    return 4 + buffer[start + 1];
   },
-  predictResponseLength: (buffer) => {
-    if (buffer.length < 2) return null;
-    return 4 + buffer[1];
+  predictResponseLength: (buffer, start, end) => {
+    if (end - start < 2) return null;
+    return 4 + buffer[start + 1];
   },
   handle: async (data, unit) => {
     return Buffer.from([data[1], data[0]]);
@@ -350,50 +354,75 @@ Benchmarked against [jsmodbus](https://github.com/Cloud-Automation/node-modbus)
 
 | 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) |
+| 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) |
 
 <details>
 <summary>Full benchmark results</summary>
 
-Node.js v24.15.0 · linux x64 · 3 runs × 300 s · [full report](./benchmark/RESULTS.md)
+Node.js v24.16.0 · AMD Ryzen 7 9800X3D · linux x64 · 3 runs × 120 s · [full report](./benchmark/RESULTS.md)
 
 ### TCP Throughput (Single Connection)
 
 ```
-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
+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
 ```
 
 ### Concurrent (8 Connections)
 
 ```
-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
+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
 ```
 
-### RTU Serial (115200 baud simulated)
+### RTU Serial (115200 baud via socat PTY)
 
 ```
-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
+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
 ```
 
-### Encode / Decode (CPU Micro-benchmark)
+### Frame Encode / Decode (CPU Micro-benchmark)
 
 ```
-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)
+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
 ```
 
+### Per-Function-Code TCP Throughput (Normal Payload)
+
+| 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>
 
 ## License

package/README.zh-CN.md

@@ -15,8 +15,8 @@ Node.js 的纯 JavaScript Modbus 实现。
 
 - **协议：** Modbus TCP、RTU、ASCII
 - **传输：** 串口、TCP 客户端/服务端、UDP 客户端/服务端
-- **主站：** FIFO 或流水线并发请求（仅 TCP）
-- **从站：** 每连接 FIFO 或并发处理（仅 TCP）
+- **主站：** FIFO 或流水线并发请求（协议必须为 TCP）
+- **从站：** 每连接 FIFO 或并发处理（协议必须为 TCP）
 - **自定义功能码**，支持可插拔帧解析
 - **广播**（单元号 = 0）
 - **完整 TypeScript**
@@ -39,6 +39,8 @@ Node.js 的纯 JavaScript Modbus 实现。
 
 ## 安装
 
+需要 **Node.js ≥ 18.19**。
+
 ```bash
 npm install njs-modbus
 ```
@@ -179,7 +181,7 @@ new ModbusMaster({
   physical: { type: 'TCP_CLIENT' },
   protocol: { type: 'TCP' },          // 'TCP' | 'RTU' | 'ASCII'
   timeout?: 1000,                     // 单次请求超时（毫秒）
-  concurrent?: false,                 // 流水线模式（仅 TCP）
+  concurrent?: false,                 // 流水线模式（协议：仅 TCP）
 })
 ```
 
@@ -239,7 +241,7 @@ protocol: {
 new ModbusSlave({
   physical: { type: 'TCP_SERVER' },
   protocol: { type: 'TCP' },
-  concurrent?: false, // 每连接并发（仅 TCP）
+  concurrent?: false, // 每连接并发（协议：仅 TCP）
 })
 ```
 
@@ -252,10 +254,10 @@ slave.add({
   // 可选：在默认分发前拦截任意功能码
   interceptor?: (fc, data) => Buffer | undefined,
 
-  readCoils?: (address, length) => boolean[],
-  readDiscreteInputs?: (address, length) => boolean[],
-  readHoldingRegisters?: (address, length) => number[],
-  readInputRegisters?: (address, length) => number[],
+  readCoils?: (address, length) => boolean[] | Uint8Array,
+  readDiscreteInputs?: (address, length) => boolean[] | Uint8Array,
+  readHoldingRegisters?: (address, length) => number[] | Uint16Array,
+  readInputRegisters?: (address, length) => number[] | Uint16Array,
 
   writeSingleCoil?: (address, value) => void,
   writeMultipleCoils?: (address, values) => void,
@@ -291,18 +293,20 @@ slave.add({
 
 ## 自定义功能码
 
+`predictRequestLength` / `predictResponseLength` 接收共享池缓冲区及字节偏移量（`start`、`end`）。边界检查应使用 `end - start` 而非 `buffer.length`。
+
 ```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: (buffer, start, end) => {
+    if (end - start < 2) return null;
+    return 4 + buffer[start + 1];
   },
-  predictResponseLength: (buffer) => {
-    if (buffer.length < 2) return null;
-    return 4 + buffer[1];
+  predictResponseLength: (buffer, start, end) => {
+    if (end - start < 2) return null;
+    return 4 + buffer[start + 1];
   },
   handle: async (data, unit) => {
     return Buffer.from([data[1], data[0]]);
@@ -349,50 +353,75 @@ slave.add({
 
 | 指标 | njs-modbus | jsmodbus | modbus-serial |
 |------|-----------|----------|---------------|
-| TCP 吞吐量 | **5,527 ops/sec** | 3,239 (0.59x) | 371 (0.07x) |
-| TCP P99 延迟 | **2.71 ms** | 4.73 ms (1.75x) | 12.48 ms (4.61x) |
-| TCP CPU 效率 | **1,116 µs/op** | 1,950 (1.75x) | 16,715 (14.98x) |
-| 并发 (8 连接) | **5,274 ops/sec** | 3,416 (0.65x) | 1,815 (0.34x) |
-| RTU CPU 效率 | **1,762 µs/op** | 1,760 (1.00x) | 2,144 (1.22x) |
-| TCP 响应编码 | **2.04M ops/sec** | 373K (0.18x) | 411K (0.20x) |
-| TCP 响应解码 | **1.91M ops/sec** | 538K (0.28x) | 231K (0.12x) |
+| TCP 吞吐量 | **70,544 ops/sec** | 39,827 (0.56x) | 786 (0.01x) |
+| TCP P99 延迟 | **53 µs** | 98 µs (1.83x) | 2,331 µs (43.7x) |
+| 并发 (8 连接) | **75,810 ops/sec** | 41,754 (0.55x) | 5,620 (0.07x) |
+| RTU 串口 (115200 波特率) | **44 ops/sec** | 44 ops/sec | 45 ops/sec |
+| TCP 响应编码 | **6.57M ops/sec** | 1.22M (0.19x) | 1.18M (0.18x) |
+| TCP 响应解码 | **6.78M ops/sec** | 1.94M (0.29x) | 0.67M (0.10x) |
+| FC01 读取线圈 | **85,170 ops/sec** | 617 (0.01x) | 861 (0.01x) |
 
 <details>
 <summary>完整基准测试结果</summary>
 
-Node.js v24.15.0 · linux x64 · 3 次运行 × 300 秒 · [完整报告](./benchmark/RESULTS.md)
+Node.js v24.16.0 · AMD Ryzen 7 9800X3D · linux x64 · 3 次运行 × 120 秒 · [完整报告](./benchmark/RESULTS.md)
 
 ### TCP 吞吐量（单连接）
 
 ```
-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
+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
 ```
 
 ### 并发（8 连接）
 
 ```
-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
+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
 ```
 
-### RTU 串口（模拟 115200 波特率）
+### RTU 串口（socat PTY 模拟 115200 波特率）
 
 ```
-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
+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
 ```
 
-### 编码 / 解码（CPU 微基准测试）
+### 帧编码 / 解码（CPU 微基准测试）
 
 ```
-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)
+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
 ```
 
+### 全功能码 TCP 吞吐量（常规负载）
+
+| 功能码 | njs-modbus | jsmodbus | modbus-serial |
+|--------|-----------|----------|---------------|
+| FC01 读取线圈 | **85,170** 🏆 | 617 (0.01x) | 861 (0.01x) |
+| FC02 读取离散输入 | **85,570** 🏆 | 525 (0.01x) | 861 (0.01x) |
+| FC03 读取保持寄存器 | **75,344** 🏆 | 40,081 (0.53x) | 852 (0.01x) |
+| FC04 读取输入寄存器 | **75,757** 🏆 | 49,524 (0.65x) | 866 (0.01x) |
+| FC05 写单个线圈 | **92,852** 🏆 | 53,521 (0.58x) | 871 (0.01x) |
+| FC06 写单个寄存器 | **92,864** 🏆 | 53,684 (0.58x) | 872 (0.01x) |
+| FC15 写多个线圈 | **86,434** 🏆 | 319 (0.00x) | 869 (0.01x) |
+| FC16 写多个寄存器 | **76,053** 🏆 | 39,356 (0.52x) | 852 (0.01x) |
+| FC17 报告服务器 ID | **74,697** 🏆 | — | — |
+| FC22 掩码写寄存器 | **90,717** 🏆 | — | — |
+| FC23 读/写多个寄存器 | **85,652** 🏆 | — | — |
+| FC43 读取设备标识 | **78,030** 🏆 | — | 865 (0.01x) |
+
+> FC17 / FC22 / FC23 不受 jsmodbus 和 modbus-serial 支持。
+
 </details>
 
 ## 许可证