njs-modbus 3.1.1 → 3.3.0

package/dist/index.d.ts

@@ -12,7 +12,7 @@ interface ApplicationDataUnit {
     data: Buffer;
 }
 interface ServerId {
-    /** Server ID; may be 1 byte (number) or multi-byte (number[]) per device spec. */
+    /** Server ID as a byte array (e.g. single-byte IDs use `[id]`). */
     serverId?: number[];
     runIndicatorStatus?: boolean;
     additionalData?: number[];
@@ -44,10 +44,32 @@ interface DeviceIdentification {
  */
 interface CustomFunctionCode {
     fc: number;
-    /** Predict total RTU frame length for an incoming request (slave-side framing). */
-    predictRequestLength: (buffer: Buffer) => number | null;
-    /** Predict total RTU frame length for an incoming response (master-side framing). */
-    predictResponseLength: (buffer: Buffer) => number | null;
+    /**
+     * Predict total RTU frame length for an incoming request (slave-side framing).
+     *
+     * @param buffer — The raw frame buffer (a shared pool or incoming chunk). Do NOT
+     *   modify it; the framing layer owns the memory.
+     * @param start — Byte offset in `buffer` where the current candidate frame begins
+     *   (the unit ID byte). Read the function code at `buffer[start + 1]` and derive
+     *   the total frame length from the trailing bytes.
+     * @param end — Byte offset one past the last valid byte. Bounds checks must use
+     *   `end - start` as available bytes, NOT `buffer.length` (pool capacity).
+     * @returns Total frame length (>= 4, <= 256), or `null` if more bytes are needed.
+     */
+    predictRequestLength: (buffer: Buffer, start: number, end: number) => number | null;
+    /**
+     * Predict total RTU frame length for an incoming response (master-side framing).
+     *
+     * @param buffer — The raw frame buffer (a shared pool or incoming chunk). Do NOT
+     *   modify it; the framing layer owns the memory.
+     * @param start — Byte offset in `buffer` where the current candidate frame begins
+     *   (the unit ID byte). Read the function code at `buffer[start + 1]` and derive
+     *   the total frame length from the trailing bytes.
+     * @param end — Byte offset one past the last valid byte. Bounds checks must use
+     *   `end - start` as available bytes, NOT `buffer.length` (pool capacity).
+     * @returns Total frame length (>= 4, <= 256), or `null` if more bytes are needed.
+     */
+    predictResponseLength: (buffer: Buffer, start: number, end: number) => number | null;
     /**
      * Slave-side handler. Receives PDU payload (bytes after `fc`, before CRC) and
      * the unit ID being addressed; must return the PDU payload of the response.
@@ -115,6 +137,8 @@ declare enum ConformityLevel {
 }
 /** Shared empty Buffer to avoid repeated allocations. */
 declare const EMPTY_BUFFER: Buffer<ArrayBuffer>;
+/** Shared no-op function to avoid repeated allocations. */
+declare const NOOP: () => void;
 /** Modbus V1.1b3 PDU quantity limits. */
 declare const LIMITS: {
     readonly READ_COILS_MIN: 1;
@@ -353,25 +377,37 @@ type PhysicalConfig = {
     type: 'CUSTOM';
     layer: AbstractPhysicalLayer;
 };
+/**
+ * User-facing arguments for `Master.open()` / `Slave.open()`.
+ *
+ * These match the physical layer's `open()` signatures **without** the trailing
+ * callback — `promisifyCb` appends it internally so the user gets a `Promise`.
+ *
+ * | Config        | User-facing args                     |
+ * |---------------|--------------------------------------|
+ * | SERIAL        | `()` — configured at construction    |
+ * | TCP_CLIENT    | `(opts?)` — `SocketConnectOpts`      |
+ * | TCP_SERVER    | `(opts?)` — `ListenOptions`          |
+ * | UDP_CLIENT    | `(remote?)` — `{ port?, address? }`  |
+ * | UDP_SERVER    | `(opts?)` — `BindOptions`            |
+ * | CUSTOM        | `never` — call `layer.open()` directly |
+ */
 type OpenArgs<T extends PhysicalConfig> = T extends {
     type: 'SERIAL';
-} ? Parameters<SerialPhysicalLayer['open']> : T extends {
+} ? [] : T extends {
     type: 'TCP_CLIENT';
-} ? Parameters<TcpClientPhysicalLayer['open']> : T extends {
+} ? [options?: SocketConnectOpts] : T extends {
     type: 'TCP_SERVER';
-} ? Parameters<TcpServerPhysicalLayer['open']> : T extends {
+} ? [options?: ListenOptions] : T extends {
     type: 'UDP_CLIENT';
-} ? Parameters<UdpClientPhysicalLayer['open']> : T extends {
+} ? [remote?: {
+    port?: number;
+    address?: string;
+}] : T extends {
     type: 'UDP_SERVER';
-} ? Parameters<UdpServerPhysicalLayer['open']> : never;
+} ? [options?: BindOptions] : never;
 declare function createPhysicalLayer(config: PhysicalConfig): AbstractPhysicalLayer;
 
-interface AbstractApplicationLayerEvents {
-    framing: [frame: ApplicationDataUnit & {
-        buffer: Buffer;
-    }];
-    'framing-error': [error: Error];
-}
 /**
  * Application-layer protocol handler bound to a single physical connection.
  *
@@ -379,10 +415,16 @@ interface AbstractApplicationLayerEvents {
  * established and discarded when the connection closes. Subclasses implement
  * ASCII, RTU, or TCP framing rules.
  */
-declare abstract class AbstractApplicationLayer extends EventEmitter<AbstractApplicationLayerEvents> {
+declare abstract class AbstractApplicationLayer {
     abstract readonly PROTOCOL: 'ASCII' | 'RTU' | 'TCP';
     abstract ROLE: 'MASTER' | 'SLAVE';
     abstract readonly connection: AbstractPhysicalConnection;
+    /** Called when a complete frame is decoded. Defaults to no-op. */
+    onFraming: (frame: ApplicationDataUnit & {
+        buffer: Buffer;
+    }) => void;
+    /** Called when a framing error is detected. Defaults to no-op. */
+    onFramingError: (error: Error) => void;
     flush(): void;
     addCustomFunctionCode(cfc: CustomFunctionCode): void;
     removeCustomFunctionCode(fc: number): void;
@@ -403,7 +445,7 @@ declare class AsciiApplicationLayer extends AbstractApplicationLayer {
     readonly lenientHex: boolean;
     private _connection;
     private _state;
-    private _cleanupFns;
+    private _cleanupCbs;
     get connection(): AbstractPhysicalConnection;
     constructor(role: 'MASTER' | 'SLAVE', connection: AbstractPhysicalConnection, options?: AsciiApplicationLayerOptions);
     private framing;
@@ -432,10 +474,18 @@ declare class RtuApplicationLayer extends AbstractApplicationLayer {
     private _threePointFiveT;
     private _onePointFiveT;
     private _customFunctionCodes;
-    private _cleanupFns;
+    private _cleanupCbs;
     get connection(): AbstractPhysicalConnection;
     constructor(role: 'MASTER' | 'SLAVE', connection: AbstractPhysicalConnection, options?: RtuApplicationLayerOptions);
     private clearStateTimers;
+    /**
+     * Shared handler for every "frame is not yet complete" exit in `flushBuffer`.
+     * Returns `true` when the caller should `return` (strict reset), `false` to
+     * `break` the parse loop. Hot path never reaches here — only error/incomplete
+     * edges. Extracted as a method so it is not recreated on every `flushBuffer`
+     * call.
+     */
+    private _handleIncomplete;
     private flushBuffer;
     flush(): void;
     addCustomFunctionCode(cfc: CustomFunctionCode): void;
@@ -449,7 +499,7 @@ declare class TcpApplicationLayer extends AbstractApplicationLayer {
     private _connection;
     private _transactionId;
     private _buffer;
-    private _cleanupFns;
+    private _cleanupCbs;
     get connection(): AbstractPhysicalConnection;
     constructor(role: 'MASTER' | 'SLAVE', connection: AbstractPhysicalConnection);
     private tryExtract;
@@ -546,19 +596,21 @@ declare class ModbusMaster<T extends ModbusMasterOptions = ModbusMasterOptions>
     private _queueDatas;
     private _queueTimeouts;
     private _queueBroadcasts;
-    private _queueResolves;
-    private _queueRejects;
+    private _queueCallbacks;
     private _queueHead;
     private _queueLen;
     private _draining;
     private _nextTid;
     private _cleanupFns;
     private _closePromise;
+    private _nextExchangeId;
+    private _pendingExchanges;
+    private _timerHeap;
     get state(): PhysicalState;
     get physicalLayer(): AbstractPhysicalLayer;
     constructor(options: T);
     private _createAppLayer;
-    private send;
+    private _send;
     private _drain;
     private _processNext;
     private _exchange;
@@ -620,7 +672,7 @@ declare class ModbusMaster<T extends ModbusMasterOptions = ModbusMasterOptions>
     sendCustomFC(unit: 0, fc: number, data: Buffer | number[], timeout?: number): Promise<void>;
     sendCustomFC(unit: number, fc: number, data: Buffer | number[], timeout?: number): Promise<Buffer>;
     /**
-     * Open the underlying physical layer and begin accepting connections.
+     * Open the underlying physical layer and establish a connection.
      *
      * A `ModbusMaster` instance can only be opened once. Once {@link close}
      * is called — explicitly or because the physical layer disconnected —
@@ -665,15 +717,19 @@ interface ModbusSlaveModel {
      * Otherwise keep the default read and write behavior.
      */
     interceptor?: MaybeAsyncFunction<(fc: number, data: Buffer) => Buffer | undefined>;
-    readDiscreteInputs?: MaybeAsyncFunction<(address: number, length: number) => boolean[]>;
-    readCoils?: MaybeAsyncFunction<(address: number, length: number) => boolean[]>;
+    /** Return `Uint8Array` to avoid the `Array.from` allocation overhead. */
+    readDiscreteInputs?: MaybeAsyncFunction<(address: number, length: number) => boolean[] | Uint8Array>;
+    /** Return `Uint8Array` to avoid the `Array.from` allocation overhead. */
+    readCoils?: MaybeAsyncFunction<(address: number, length: number) => boolean[] | Uint8Array>;
     writeSingleCoil?: MaybeAsyncFunction<(address: number, value: boolean) => void>;
     /**
      * If omitted, defaults to loop and call `writeSingleCoil`.
      */
     writeMultipleCoils?: MaybeAsyncFunction<(address: number, value: boolean[]) => void>;
-    readInputRegisters?: MaybeAsyncFunction<(address: number, length: number) => number[]>;
-    readHoldingRegisters?: MaybeAsyncFunction<(address: number, length: number) => number[]>;
+    /** Return `Uint16Array` to avoid the `Array.from` allocation overhead. */
+    readInputRegisters?: MaybeAsyncFunction<(address: number, length: number) => number[] | Uint16Array>;
+    /** Return `Uint16Array` to avoid the `Array.from` allocation overhead. */
+    readHoldingRegisters?: MaybeAsyncFunction<(address: number, length: number) => number[] | Uint16Array>;
     writeSingleRegister?: MaybeAsyncFunction<(address: number, value: number) => void>;
     /**
      * If omitted, defaults to loop and call `writeSingleRegister`.
@@ -719,7 +775,7 @@ declare class ModbusSlave<T extends ModbusSlaveOptions = ModbusSlaveOptions> ext
     private _protocol;
     private _appLayers;
     private _customFunctionCodes;
-    private _locks;
+    private _intervalLocks;
     private _cleanupFns;
     private _closePromise;
     get state(): PhysicalState;
@@ -742,7 +798,19 @@ declare class ModbusSlave<T extends ModbusSlaveOptions = ModbusSlaveOptions> ext
     private _drain;
     private _processFrame;
     private _intercept;
-    private _withAddressLock;
+    /**
+     * Serialize a code block over the half-open address interval `[lo, hi)`.
+     * The block runs after all previously-installed locks whose intervals
+     * overlap with this one have completed. Two non-overlapping intervals
+     * execute in parallel.
+     *
+     * Locks are tracked in a flat array (`_intervalLocks`); the typical depth
+     * is 0-2 entries, so the linear overlap scan is sub-µs. Compare with the
+     * old per-address Map design, where FC23 writing 121 registers allocated
+     * ~125 objects per request (one Promise.resolve / address + Set + sort +
+     * Promise.all); this version allocates 1-3.
+     */
+    private _withIntervalLock;
     private _handleFC;
     private _handleCustomFC;
     add(model: ModbusSlaveModel): void;
@@ -770,5 +838,5 @@ declare class ModbusSlave<T extends ModbusSlaveOptions = ModbusSlaveOptions> ext
     close(): Promise<void>;
 }
 
-export { AbstractApplicationLayer, AbstractPhysicalConnection, AbstractPhysicalLayer, AsciiApplicationLayer, COIL_OFF, COIL_ON, ConformityLevel, EMPTY_BUFFER, EXCEPTION_OFFSET, ErrorCode, FunctionCode, LIMITS, MEI_READ_DEVICE_ID, MasterSession, ModbusError, ModbusMaster, ModbusSlave, PhysicalConnectionState, PhysicalState, ReadDeviceIDCode, RtuApplicationLayer, SerialPhysicalLayer, TcpApplicationLayer, TcpClientPhysicalLayer, TcpServerPhysicalLayer, UdpClientPhysicalLayer, UdpServerPhysicalLayer, createPhysicalLayer, getCodeByError, getErrorByCode };
+export { AbstractApplicationLayer, AbstractPhysicalConnection, AbstractPhysicalLayer, AsciiApplicationLayer, COIL_OFF, COIL_ON, ConformityLevel, EMPTY_BUFFER, EXCEPTION_OFFSET, ErrorCode, FunctionCode, LIMITS, MEI_READ_DEVICE_ID, MasterSession, ModbusError, ModbusMaster, ModbusSlave, NOOP, PhysicalConnectionState, PhysicalState, ReadDeviceIDCode, RtuApplicationLayer, SerialPhysicalLayer, TcpApplicationLayer, TcpClientPhysicalLayer, TcpServerPhysicalLayer, UdpClientPhysicalLayer, UdpServerPhysicalLayer, createPhysicalLayer, getCodeByError, getErrorByCode };
 export type { AbstractPhysicalLayerEvents, ApplicationDataUnit, AsciiApplicationLayerOptions, Callback$1 as Callback, CustomFunctionCode, DeviceIdentification, MaybeAsyncFunction, ModbusMasterOptions, ModbusSlaveModel, ModbusSlaveOptions, OpenArgs, PhysicalConfig, RtuApplicationLayerOptions, ServerId, TcpServerPhysicalLayerOptions, UdpServerPhysicalLayerOptions };