njs-modbus 3.2.0 → 3.4.0

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](./README.md) | 简体中文
 
-Node.js 的纯 JavaScript Modbus 实现。
+Node.js 的纯 JavaScript Modbus 实现，针对高吞吐量和低 GC 压力优化。
 
 <!-- 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 @@ Node.js 的纯 JavaScript Modbus 实现。
 [![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 -->
 
-## 特性
+## 核心亮点
 
-- **协议：** Modbus TCP、RTU、ASCII
-- **传输：** 串口、TCP 客户端/服务端、UDP 客户端/服务端
-- **主站：** FIFO 或流水线并发请求（仅 TCP）
-- **从站：** 每连接 FIFO 或并发处理（仅 TCP）
+- **协议** — Modbus TCP、RTU、ASCII
+- **传输** — 串口、TCP 客户端/服务端、UDP 客户端/服务端，支持可插拔自定义传输层
+- **性能优先** — 并行 FIFO 队列、惰性删除定时器堆、内联大端读写、零分配热路径
+- **主站** — FIFO 或流水线并发请求（仅 TCP）
+- **从站** — 每连接 FIFO 或并发处理（仅 TCP）
 - **自定义功能码**，支持可插拔帧解析
-- **广播**（单元号 = 0）
+- **广播**（`unit = 0`）
 - **完整 TypeScript**
 - **零运行时依赖**（仅在使用串口时 peer-depends `serialport`）
 
+## 支持的功能码
+
 | 码值 | 名称 |
 |------|------|
 | 01 | 读取线圈 |
@@ -39,6 +42,8 @@ Node.js 的纯 JavaScript Modbus 实现。
 
 ## 安装
 
+需要 **Node.js ≥ 18.19**。
+
 ```bash
 npm install njs-modbus
 ```
@@ -114,20 +119,45 @@ const master = new ModbusMaster({
 });
 ```
 
+## 架构
+
+本库遵循严格的两层设计：
+
+```
+┌─────────────────────────────────────────┐
+│         ModbusMaster / ModbusSlave        │  ← 用户 API，会话/队列管理
+├─────────────────────────────────────────┤
+│      TcpApplicationLayer                │  ← 协议帧解析（MBAP / CRC16 / LRC）
+│      RtuApplicationLayer                │
+│      AsciiApplicationLayer              │
+├─────────────────────────────────────────┤
+│      AbstractPhysicalConnection         │  ← 每连接 I/O
+├─────────────────────────────────────────┤
+│      AbstractPhysicalLayer              │  ← 资源管理（端口/套接字/服务端）
+│      ├── TcpClientPhysicalLayer         │
+│      ├── TcpServerPhysicalLayer         │
+│      ├── UdpClientPhysicalLayer         │
+│      ├── UdpServerPhysicalLayer         │
+│      └── SerialPhysicalLayer            │
+└─────────────────────────────────────────┘
+```
+
+所有传输层都统一为面向连接的模型：物理层在就绪时触发 `'connect'` 事件并传入一个 `AbstractPhysicalConnection`，每个连接会独立创建一个应用层实例。
+
 ## 物理层
 
-所有物理层暴露 `open()` / `close()`、`state` 属性，以及事件：`'open'`、`'connect'`、`'close'`、`'error'`。
+所有物理层暴露 `open()` / `close()`、`state` 属性，以及 [事件](#事件) 章节中列出的事件。
 
-| 类型 | 类 | `open(...)` 参数 |
-|------|-------|-----------------|
-| `SERIAL` | `SerialPhysicalLayer` | 无 |
-| `TCP_CLIENT` | `TcpClientPhysicalLayer` | `SocketConnectOpts` |
-| `TCP_SERVER` | `TcpServerPhysicalLayer` | `ListenOptions` |
-| `UDP_CLIENT` | `UdpClientPhysicalLayer` | `{ port, address }` |
-| `UDP_SERVER` | `UdpServerPhysicalLayer` | `BindOptions` |
-| `CUSTOM` | *(用户自定义)* | *(自定义)* |
+| 类型 | `open(...)` 参数 | 说明 |
+|------|-----------------|------|
+| `SERIAL` | `()` | 通过 `serialport` 包访问串口 |
+| `TCP_CLIENT` | `SocketConnectOpts` | TCP 客户端套接字 |
+| `TCP_SERVER` | `ListenOptions` | TCP 服务端 |
+| `UDP_CLIENT` | `{ port?, address? }` | UDP 客户端 |
+| `UDP_SERVER` | `BindOptions` | UDP 服务端 |
+| `CUSTOM` | *(用户自定义)* | 用户提供的 `AbstractPhysicalLayer` 实例 |
 
-### 服务端配置
+### TCP 服务端配置
 
 ```typescript
 const slave = new ModbusSlave({
@@ -143,62 +173,44 @@ const slave = new ModbusSlave({
 });
 ```
 
-### 物理层选项
+### 物理层选项参考
 
 | 选项 | 类型 | 说明 |
-|--------|------|-------------|
+|------|------|------|
 | `whitelist` | `string[]` | 允许的客户端 IP。`::ffff:` 前缀自动剥离。 |
 | `maxConnections` | `number` | 最大并发连接数。超出后新连接静默丢弃。 |
 | `idleTimeout` | `number` | 空闲超时（毫秒），超时后驱逐连接。默认 `30000`，传 `0` 禁用。 |
 | `socketOpts` / `serverOpts` | `object` | 透传给 Node.js `createSocket()` / `createServer()`。 |
 
-## 自定义物理层
-
-任何面向字节的传输层都可以通过实现 `AbstractPhysicalLayer` 和 `AbstractPhysicalConnection` 来使用，然后传入 `{ 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' },
-});
-```
-
-查看 [`examples/websocket`](./examples/websocket) 获取完整的 **WebSocket 承载 Modbus TCP** 实现——包含客户端/服务端物理层及可运行的演示。
+## 协议层
 
-查看 [`examples/bluetooth`](./examples/bluetooth) 获取 **BLE 承载 Modbus TCP** 实现（基于 Nordic UART Service），包含无需真实蓝牙硬件即可运行的回环测试。
+| 协议 | 选项 | 说明 |
+|------|------|------|
+| `TCP` | 无 | Modbus TCP，带 MBAP 头 |
+| `RTU` | `RtuProtocolOptions` | Modbus RTU，带 CRC16 |
+| `ASCII` | `AsciiApplicationLayerOptions` | Modbus ASCII，带 LRC |
 
-## 主站 API
-
-```typescript
-new ModbusMaster({
-  physical: { type: 'TCP_CLIENT' },
-  protocol: { type: 'TCP' },          // 'TCP' | 'RTU' | 'ASCII'
-  timeout?: 1000,                     // 单次请求超时（毫秒）
-  concurrent?: false,                 // 流水线模式（仅 TCP）
-})
-```
-
-RTU 帧选项：
+### RTU 选项
 
 ```typescript
 protocol: {
   type: 'RTU',
   opts: {
-    // 既可以传裸数字（毫秒），也可以传 `{ unit: 'bit' | 'ms', value: N }`。
-    // 传 `0` 显式禁用该定时器（适用于 RTU-over-TCP 等无丢包传输）。
-    intervalBetweenFrames: 20,                          // 20 毫秒
-    interCharTimeout: { unit: 'bit', value: 10 },       // 按 bit-time，需 baudRate
-    poolSize: 1024,
+    // t3.5 帧间静默时间。
+    // 既可以传裸数字（毫秒），也可以传 { unit: 'bit' | 'ms', value: N }。
+    // 传 0 显式禁用（适用于 RTU-over-TCP 等无丢包传输）。
+    intervalBetweenFrames: 20,
+
+    // t1.5 字符间超时（可选）。
+    interCharTimeout: { unit: 'bit', value: 10 },
+
+    // 丢弃存在 t1.5 时序违规的帧。
+    strictTiming: true,
   },
 }
 ```
 
-ASCII 选项：
+### ASCII 选项
 
 ```typescript
 protocol: {
@@ -209,11 +221,24 @@ protocol: {
 }
 ```
 
+## 主站 API
+
+### 构造函数
+
+```typescript
+new ModbusMaster({
+  physical: { type: 'TCP_CLIENT' },
+  protocol: { type: 'TCP' },          // 'TCP' | 'RTU' | 'ASCII'
+  timeout?: 1000,                     // 单次请求超时（毫秒）
+  concurrent?: false,                 // 流水线模式（仅 TCP）
+})
+```
+
 ### 方法
 
 | 方法 | 说明 |
-|--------|-------------|
-| `open(...args)` | 打开物理层。只能调用一次；`close()` 后实例永久失效。 |
+|------|------|
+| `open(...args)` | 打开物理层。一次性：close() 后不可重新打开。 |
 | `close()` | 立即关闭。进行中和队列中的请求会被 reject。 |
 | `readCoils(unit, address, length, timeout?)` | FC 01 |
 | `readDiscreteInputs(unit, address, length, timeout?)` | FC 02 |
@@ -235,6 +260,8 @@ protocol: {
 
 ## 从站 API
 
+### 构造函数
+
 ```typescript
 new ModbusSlave({
   physical: { type: 'TCP_SERVER' },
@@ -252,10 +279,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) => Uint8Array,
+  readDiscreteInputs?: (address, length) => Uint8Array,
+  readHoldingRegisters?: (address, length) => number[] | Uint16Array,
+  readInputRegisters?: (address, length) => number[] | Uint16Array,
 
   writeSingleCoil?: (address, value) => void,
   writeMultipleCoils?: (address, values) => void,
@@ -280,29 +307,70 @@ slave.add({
 
 缺失的处理器返回 `ILLEGAL_FUNCTION`。越界地址返回 `ILLEGAL_DATA_ADDRESS`。处理器抛出的异常变为 `SERVER_DEVICE_FAILURE`，除非错误是 `ModbusError`。
 
+### 方法
+
 | 方法 | 说明 |
-|--------|-------------|
+|------|------|
 | `add(model)` | 注册从站模型 |
-| `remove(unit)` | 移除从站模型 |
-| `open(...args)` | 打开物理层。一次性：close() 后不可重新打开。 |
+| `remove(unit)` | 移除模型 |
+| `open(...args)` | 打开并开始接受连接。一次性。 |
 | `close()` | 立即关闭 |
 | `addCustomFunctionCode(cfc)` | 注册自定义功能码 |
 | `removeCustomFunctionCode(fc)` | 注销自定义功能码 |
 
+## 事件
+
+`ModbusMaster` 和 `ModbusSlave` 都是 `EventEmitter`，所有事件均带类型定义。
+
+### 物理层事件
+
+| 事件 | 参数 | 说明 |
+|------|------|------|
+| `open` | `()` | 物理层就绪，可接受连接 |
+| `connect` | `(connection)` | 新连接已建立 |
+| `close` | `()` | 物理层已关闭 |
+| `error` | `(error)` | 物理层错误 |
+
+### 连接调试事件
+
+| 事件 | 参数 | 说明 |
+|------|------|------|
+| `tx` | `(buffer, connection)` | 原始数据已写入链路 |
+| `rx` | `(buffer, connection)` | 从链路接收到原始数据 |
+
+### 应用层事件
+
+| 事件 | 参数 | 说明 |
+|------|------|------|
+| `framing` | `(frame, connection)` | 完整帧已解码 |
+| `framingError` | `(error, connection)` | 帧解析错误（CRC/LRC 失败、MBAP 格式错误、时序违规等） |
+
+```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);
+});
+```
+
 ## 自定义功能码
 
+`predictRequestLength` / `predictResponseLength` 接收 `getByte` 访问器和当前可用字节数 `length`。请使用 `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: (getByte, length) => {
+    if (length < 2) return 0; // 需要更多字节
+    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]]);
@@ -343,57 +411,65 @@ slave.add({
 });
 ```
 
-## 性能
-
-与 [jsmodbus](https://github.com/Cloud-Automation/node-modbus) 和 [modbus-serial](https://github.com/yaacov/node-modbus-serial) 的对比。
-
-| 指标 | 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) |
+## 自定义物理层
 
-<details>
-<summary>完整基准测试结果</summary>
+任何面向字节的传输层都可以通过实现 `AbstractPhysicalLayer` 和 `AbstractPhysicalConnection` 来使用，然后传入 `{ type: 'CUSTOM', layer: yourLayer }`。
 
-Node.js v24.15.0 · linux x64 · 3 次运行 × 300 秒 · [完整报告](./benchmark/RESULTS.md)
+```typescript
+import { AbstractPhysicalLayer, AbstractPhysicalConnection } from 'njs-modbus';
 
-### TCP 吞吐量（单连接）
+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' },
+});
 ```
 
-### 并发（8 连接）
+查看 [`examples/websocket`](./examples/websocket) 获取完整的 **WebSocket 承载 Modbus TCP** 实现。
 
-```
-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
-```
+查看 [`examples/bluetooth`](./examples/bluetooth) 获取基于 Nordic UART Service (NUS) 的 **BLE 承载 Modbus TCP** 实现。
 
-### RTU 串口（模拟 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
-```
+与 [jsmodbus](https://github.com/Cloud-Automation/node-modbus) v4.0.10 和 [modbus-serial](https://github.com/yaacov/node-modbus-serial) v8.0.25 的对比。
 
-### 编码 / 解码（CPU 微基准测试）
+测试环境：AMD Ryzen 7 9800X3D 8-Core Processor · Node.js v24.16.0 · [完整报告](./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)
-```
+### TCP 端到端
 
-</details>
+| 指标 | njs-modbus | jsmodbus | modbus-serial |
+|------|-----------|----------|---------------|
+| 单连接 | **74,964 ops/sec** 🏆 | 55,996 (0.75x) | 853 (0.01x) |
+| 8 并发客户端 | **10,188 ops/sec** 🏆 | 5,918 (0.58x) | 728 (0.07x) |
+| P99 延迟（单连接） | **17 µs** 🏆 | 15 µs (0.88x) | 1,206 µs (70.9x) |
+
+### 帧编码 / 解码（CPU 微基准）
+
+| 基准测试 | njs-modbus | jsmodbus | modbus-serial |
+|----------|-----------|----------|---------------|
+| TCP 请求编码 | **9.61M ops/sec** 🏆 | 6.32M (0.66x) | 0.68M (0.07x) |
+| TCP 响应编码 | **7.51M ops/sec** 🏆 | 1.18M (0.16x) | 0.44M (0.06x) |
+| TCP 响应解码 | **8.55M ops/sec** 🏆 | 2.04M (0.24x) | 0.70M (0.08x) |
+| RTU 请求编码 | **9.42M ops/sec** 🏆 | 3.03M (0.32x) | 6.57M (0.70x) |
+| ASCII 请求编码 | **7.09M ops/sec** 🏆 | — | 4.11M (0.58x) |
+| ASCII 请求解码 | **4.91M ops/sec** 🏆 | — | 1.19M (0.24x) |
+
+### 全功能码 TCP 吞吐（100 线圈 / 50 寄存器负载）
+
+| 功能码 | njs-modbus | jsmodbus | modbus-serial |
+|--------|-----------|----------|---------------|
+| FC01 读取线圈 | **75,430** 🏆 | 488 (0.01x) | 859 (0.01x) |
+| FC03 读取保持寄存器 | **82,028** 🏆 | 46,596 (0.57x) | 864 (0.01x) |
+| FC06 写单个寄存器 | **86,110** 🏆 | 51,084 (0.59x) | 871 (0.01x) |
+| FC15 写多个线圈 | **78,766** 🏆 | — | 867 (0.01x) |
+| FC17 报告服务器 ID | **79,185** 🏆 | — | — |
+| FC22 掩码写寄存器 | **73,060** 🏆 | — | — |
+| FC23 读/写多个寄存器 | **68,429** 🏆 | — | — |
+| FC43 读取设备标识 | **62,176** 🏆 | — | 868 (0.01x) |
+
+> FC17 / FC22 / FC23 / FC43 不受 jsmodbus 支持。
 
 ## 许可证