njs-modbus 3.3.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 | 读取线圈 |
@@ -116,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({
@@ -145,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: {
@@ -211,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 |
@@ -237,11 +260,13 @@ protocol: {
 
 ## 从站 API
 
+### 构造函数
+
 ```typescript
 new ModbusSlave({
   physical: { type: 'TCP_SERVER' },
   protocol: { type: 'TCP' },
-  concurrent?: false, // 每连接并发（协议：仅 TCP）
+  concurrent?: false, // 每连接并发（仅 TCP）
 })
 ```
 
@@ -254,8 +279,8 @@ slave.add({
   // 可选：在默认分发前拦截任意功能码
   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,
 
@@ -282,31 +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` 接收共享池缓冲区及字节偏移量（`start`、`end`）。边界检查应使用 `end - start` 而非 `buffer.length`。
+`predictRequestLength` / `predictResponseLength` 接收 `getByte` 访问器和当前可用字节数 `length`。请使用 `length` 做边界检查，不要直接访问缓冲区。
 
 ```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; // 需要更多字节
+    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]]);
@@ -347,82 +411,65 @@ slave.add({
 });
 ```
 
-## 性能
+## 自定义物理层
+
+任何面向字节的传输层都可以通过实现 `AbstractPhysicalLayer` 和 `AbstractPhysicalConnection` 来使用，然后传入 `{ type: 'CUSTOM', layer: yourLayer }`。
 
-与 [jsmodbus](https://github.com/Cloud-Automation/node-modbus) 和 [modbus-serial](https://github.com/yaacov/node-modbus-serial) 的对比。
+```typescript
+import { AbstractPhysicalLayer, AbstractPhysicalConnection } from 'njs-modbus';
 
-| 指标 | njs-modbus | jsmodbus | modbus-serial |
-|------|-----------|----------|---------------|
-| 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) |
+class MyPhysicalLayer extends AbstractPhysicalLayer { /* open / close */ }
+class MyConnection extends AbstractPhysicalConnection { /* write / destroy, emit 'data' */ }
 
-<details>
-<summary>完整基准测试结果</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 次运行 × 120 秒 · [完整报告](./benchmark/RESULTS.md)
+查看 [`examples/websocket`](./examples/websocket) 获取完整的 **WebSocket 承载 Modbus TCP** 实现。
 
-### TCP 吞吐量（单连接）
+查看 [`examples/bluetooth`](./examples/bluetooth) 获取基于 Nordic UART Service (NUS) 的 **BLE 承载 Modbus TCP** 实现。
 
-```
-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 连接）
+与 [jsmodbus](https://github.com/Cloud-Automation/node-modbus) v4.0.10 和 [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
-```
+测试环境：AMD Ryzen 7 9800X3D 8-Core Processor · Node.js v24.16.0 · [完整报告](./benchmark/report_presentation.md)
 
-### RTU 串口（socat PTY 模拟 115200 波特率）
+### 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
-```
+| 指标 | 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 微基准测试）
+### 帧编码 / 解码（CPU 微基准）
 
-```
-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
-```
+| 基准测试 | 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 吞吐量（常规负载）
+### 全功能码 TCP 吞吐（100 线圈 / 50 寄存器负载）
 
 | 功能码 | 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>
+| 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 支持。
 
 ## 许可证