njs-modbus 3.2.0 → 3.4.0

package/dist/index.d.ts

@@ -12,10 +12,11 @@ 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[];
+    /** Additional data bytes. Using Buffer avoids intermediate array conversions. */
+    additionalData?: Buffer;
 }
 interface DeviceIdentification {
     readDeviceIDCode: number;
@@ -39,7 +40,8 @@ interface DeviceIdentification {
  * (PDU + 2-byte CRC) from leading bytes; they are required so the framing FSM
  * can advance without the deleted sliding-window CRC fallback.
  *
- * Return `null` from a predictor to signal "need more bytes before I can decide".
+ * Return `0` (`PREDICT_NEED_MORE`) to signal "need more bytes before I can decide".
+ * Return `-1` (`PREDICT_UNKNOWN`) to signal "cannot determine the length".
  * Return a positive integer (>= 4, <= 256) for the total frame length.
  */
 interface CustomFunctionCode {
@@ -47,27 +49,25 @@ interface CustomFunctionCode {
     /**
      * 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.
-     * @returns Total frame length (>= 4, <= 256), or `null` if more bytes are needed.
+     * @param getByte — Zero-based accessor; `getByte(i)` returns the byte at offset
+     *   `i` within the candidate frame (0 = unit ID, 1 = function code, …).
+     * @param length — Number of bytes available so far. Use this for bounds checks
+     *   rather than any buffer property.
+     * @returns Total frame length (>= 4, <= 256), `0` if more bytes are needed,
+     *   or `-1` if the length cannot be determined.
      */
-    predictRequestLength: (buffer: Buffer, start: number, end: number) => number | null;
+    predictRequestLength: (getByte: (idx: number) => number, length: number) => number;
     /**
      * 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.
+     * @param getByte — Zero-based accessor; `getByte(i)` returns the byte at offset
+     *   `i` within the candidate frame (0 = unit ID, 1 = function code, …).
+     * @param length — Number of bytes available so far. Use this for bounds checks
+     *   rather than any buffer property.
+     * @returns Total frame length (>= 4, <= 256), `0` if more bytes are needed,
+     *   or `-1` if the length cannot be determined.
      */
-    predictResponseLength: (buffer: Buffer, start: number, end: number) => number | null;
+    predictResponseLength: (getByte: (idx: number) => number, length: number) => number;
     /**
      * 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.
@@ -316,6 +316,18 @@ declare class UdpServerPhysicalLayer extends AbstractPhysicalLayer {
 interface AbstractPhysicalConnectionEvents {
     data: [data: Buffer];
     close: [];
+    /**
+     * Emitted when raw data has been successfully written to the wire.
+     * The `buffer` is a live reference — mutating it will corrupt the frame
+     * that the connection is still processing. Treat it as read-only.
+     */
+    tx: [buffer: Buffer];
+    /**
+     * Emitted when raw data is received from the wire.
+     * The `buffer` is a live reference — mutating it will corrupt the frame
+     * that the application layer is about to parse. Treat it as read-only.
+     */
+    rx: [buffer: Buffer];
 }
 /**
  * A one-way data transmission channel.
@@ -335,6 +347,28 @@ interface AbstractPhysicalLayerEvents {
     close: [];
     error: [error: Error];
 }
+/** Debug events emitted by individual connections and proxied through Master/Slave. */
+interface ConnectionDebugEvents {
+    /**
+     * Emitted when raw data has been successfully written to the wire.
+     * The `buffer` is a live reference — mutating it will corrupt the frame
+     * that the connection is still processing. Treat it as read-only.
+     */
+    tx: [buffer: Buffer, connection: AbstractPhysicalConnection];
+    /**
+     * Emitted when raw data is received from the wire.
+     * The `buffer` is a live reference — mutating it will corrupt the frame
+     * that the application layer is about to parse. Treat it as read-only.
+     */
+    rx: [buffer: Buffer, connection: AbstractPhysicalConnection];
+}
+/** Application-layer framing events emitted by Master/Slave per connection. */
+interface ConnectionApplicationEvents {
+    framing: [frame: ApplicationDataUnit & {
+        buffer: Buffer;
+    }, connection: AbstractPhysicalConnection];
+    framingError: [error: Error, connection: AbstractPhysicalConnection];
+}
 /**
  * An abstraction over local hardware or network resources.
  *
@@ -440,7 +474,6 @@ interface AsciiApplicationLayerOptions {
 declare class AsciiApplicationLayer extends AbstractApplicationLayer {
     readonly PROTOCOL: "ASCII";
     readonly ROLE: 'MASTER' | 'SLAVE';
-    readonly lenientHex: boolean;
     private _connection;
     private _state;
     private _cleanupCbs;
@@ -457,34 +490,29 @@ interface RtuApplicationLayerOptions {
     /** Inter-character timeout in milliseconds (Modbus RTU t1.5). Opt-in. */
     interCharTimeout?: number;
     /**
-     * Buffer pool size per connection (bytes). Defaults to `MAX_FRAME_LENGTH * 2`
-     * (512 bytes). Increase this if you expect frames larger than 256 bytes or
-     * heavy pipelining on a single connection.
+     * Enforces strict Modbus RTU timing. When true, any frame containing a t1.5
+     * inter-character timeout event will be discarded immediately, even if the CRC16 is valid.
+     * @default false
      */
-    poolSize?: number;
+    strictTiming?: boolean;
 }
 declare class RtuApplicationLayer extends AbstractApplicationLayer {
     readonly PROTOCOL: "RTU";
     readonly ROLE: 'MASTER' | 'SLAVE';
     private _connection;
-    private _state;
-    private _poolSize;
-    private _threePointFiveT;
-    private _onePointFiveT;
+    private _residual;
+    private _residualLen;
+    private _expectedLen;
+    private _t15Time;
+    private _t35Time;
+    private _t15Strict;
+    private _t15Timer?;
+    private _t35Timer?;
+    private _t15Marker;
     private _customFunctionCodes;
     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;
     removeCustomFunctionCode(fc: number): void;
@@ -496,12 +524,12 @@ declare class TcpApplicationLayer extends AbstractApplicationLayer {
     readonly ROLE: 'MASTER' | 'SLAVE';
     private _connection;
     private _transactionId;
-    private _buffer;
+    private _residual;
+    private _residualLen;
+    private _expectedLen;
     private _cleanupCbs;
     get connection(): AbstractPhysicalConnection;
     constructor(role: 'MASTER' | 'SLAVE', connection: AbstractPhysicalConnection);
-    private tryExtract;
-    private processFrame;
     flush(): void;
     encode(unit: number, fc: number, data: Buffer, transaction?: number): Buffer;
 }
@@ -547,11 +575,12 @@ interface RtuProtocolOptions {
      */
     interCharTimeout?: RtuTimingValue;
     /**
-     * Buffer pool size per connection (bytes). Defaults to `MAX_FRAME_LENGTH * 2`
-     * (512 bytes). Increase this if you expect frames larger than 256 bytes or
-     * heavy pipelining on a single connection.
+     * Enforces strict Modbus RTU timing. When true, any frame containing a t1.5
+     * inter-character timeout event will be discarded immediately, even if the
+     * CRC16 is valid.
+     * @default false
      */
-    poolSize?: number;
+    strictTiming?: boolean;
 }
 
 interface ReturnValue<T> {
@@ -581,7 +610,7 @@ interface ModbusMasterOptions {
         opts?: AsciiApplicationLayerOptions;
     };
 }
-declare class ModbusMaster<T extends ModbusMasterOptions = ModbusMasterOptions> extends EventEmitter<AbstractPhysicalLayerEvents> {
+declare class ModbusMaster<T extends ModbusMasterOptions = ModbusMasterOptions> extends EventEmitter<AbstractPhysicalLayerEvents & ConnectionDebugEvents & ConnectionApplicationEvents> {
     readonly timeout: number;
     readonly concurrent: boolean;
     private _masterSession;
@@ -615,10 +644,10 @@ declare class ModbusMaster<T extends ModbusMasterOptions = ModbusMasterOptions>
     private writeFC1Or2;
     writeFC1: this['readCoils'];
     readCoils(unit: 0, address: number, length: number, timeout?: number): Promise<void>;
-    readCoils(unit: number, address: number, length: number, timeout?: number): Promise<ReturnValue<boolean[]>>;
+    readCoils(unit: number, address: number, length: number, timeout?: number): Promise<ReturnValue<Uint8Array>>;
     writeFC2: this['readDiscreteInputs'];
     readDiscreteInputs(unit: 0, address: number, length: number, timeout?: number): Promise<void>;
-    readDiscreteInputs(unit: number, address: number, length: number, timeout?: number): Promise<ReturnValue<boolean[]>>;
+    readDiscreteInputs(unit: number, address: number, length: number, timeout?: number): Promise<ReturnValue<Uint8Array>>;
     private writeFC3Or4;
     writeFC3: this['readHoldingRegisters'];
     readHoldingRegisters(unit: 0, address: number, length: number, timeout?: number): Promise<void>;
@@ -627,14 +656,14 @@ declare class ModbusMaster<T extends ModbusMasterOptions = ModbusMasterOptions>
     readInputRegisters(unit: 0, address: number, length: number, timeout?: number): Promise<void>;
     readInputRegisters(unit: number, address: number, length: number, timeout?: number): Promise<ReturnValue<number[]>>;
     writeFC5: this['writeSingleCoil'];
-    writeSingleCoil(unit: 0, address: number, value: boolean, timeout?: number): Promise<void>;
-    writeSingleCoil(unit: number, address: number, value: boolean, timeout?: number): Promise<ReturnValue<boolean>>;
+    writeSingleCoil(unit: 0, address: number, value: number, timeout?: number): Promise<void>;
+    writeSingleCoil(unit: number, address: number, value: number, timeout?: number): Promise<ReturnValue<number>>;
     writeFC6: this['writeSingleRegister'];
     writeSingleRegister(unit: 0, address: number, value: number, timeout?: number): Promise<void>;
     writeSingleRegister(unit: number, address: number, value: number, timeout?: number): Promise<ReturnValue<number>>;
     writeFC15: this['writeMultipleCoils'];
-    writeMultipleCoils(unit: 0, address: number, value: boolean[], timeout?: number): Promise<void>;
-    writeMultipleCoils(unit: number, address: number, value: boolean[], timeout?: number): Promise<ReturnValue<boolean[]>>;
+    writeMultipleCoils(unit: 0, address: number, value: Uint8Array, timeout?: number): Promise<void>;
+    writeMultipleCoils(unit: number, address: number, value: Uint8Array, timeout?: number): Promise<ReturnValue<Uint8Array>>;
     writeFC16: this['writeMultipleRegisters'];
     writeMultipleRegisters(unit: 0, address: number, value: number[], timeout?: number): Promise<void>;
     writeMultipleRegisters(unit: number, address: number, value: number[], timeout?: number): Promise<ReturnValue<number[]>>;
@@ -670,7 +699,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 —
@@ -715,15 +744,17 @@ 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[]>;
-    writeSingleCoil?: MaybeAsyncFunction<(address: number, value: boolean) => void>;
+    readDiscreteInputs?: MaybeAsyncFunction<(address: number, length: number) => Uint8Array>;
+    readCoils?: MaybeAsyncFunction<(address: number, length: number) => Uint8Array>;
+    writeSingleCoil?: MaybeAsyncFunction<(address: number, value: number) => 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[]>;
+    writeMultipleCoils?: MaybeAsyncFunction<(address: number, value: Uint8Array) => void>;
+    /** 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`.
@@ -762,7 +793,7 @@ interface ModbusSlaveOptions {
         opts?: AsciiApplicationLayerOptions;
     };
 }
-declare class ModbusSlave<T extends ModbusSlaveOptions = ModbusSlaveOptions> extends EventEmitter<AbstractPhysicalLayerEvents> {
+declare class ModbusSlave<T extends ModbusSlaveOptions = ModbusSlaveOptions> extends EventEmitter<AbstractPhysicalLayerEvents & ConnectionDebugEvents & ConnectionApplicationEvents> {
     readonly models: Map<number, ModbusSlaveModel>;
     readonly concurrent: boolean;
     private _physicalLayer;
@@ -833,4 +864,4 @@ declare class ModbusSlave<T extends ModbusSlaveOptions = ModbusSlaveOptions> ext
 }
 
 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 };
+export type { AbstractPhysicalLayerEvents, ApplicationDataUnit, AsciiApplicationLayerOptions, Callback$1 as Callback, ConnectionApplicationEvents, ConnectionDebugEvents, CustomFunctionCode, DeviceIdentification, MaybeAsyncFunction, ModbusMasterOptions, ModbusSlaveModel, ModbusSlaveOptions, OpenArgs, PhysicalConfig, RtuApplicationLayerOptions, ServerId, TcpServerPhysicalLayerOptions, UdpServerPhysicalLayerOptions };