njs-modbus 3.1.0 → 3.2.0

package/dist/index.d.ts

@@ -44,10 +44,30 @@ 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.
+     * @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 +135,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;
@@ -206,7 +228,8 @@ declare class TcpClientPhysicalLayer extends AbstractPhysicalLayer {
     get state(): PhysicalState;
     get socket(): Socket | null;
     constructor(options?: SocketConstructorOpts);
-    open(options?: SocketConnectOpts | ((err?: Error | null) => void), cb?: (err?: Error | null) => void): void;
+    open(cb?: (err?: Error | null) => void): void;
+    open(options: SocketConnectOpts, cb?: (err?: Error | null) => void): void;
     close(cb?: (err?: Error | null) => void): void;
 }
 
@@ -232,7 +255,8 @@ declare class TcpServerPhysicalLayer extends AbstractPhysicalLayer {
     get state(): PhysicalState;
     get server(): Server | null;
     constructor(options?: TcpServerPhysicalLayerOptions);
-    open(options?: ListenOptions | ((err?: Error | null) => void), cb?: (err?: Error | null) => void): void;
+    open(cb?: (err?: Error | null) => void): void;
+    open(options: ListenOptions, cb?: (err?: Error | null) => void): void;
     close(cb?: (err?: Error | null) => void): void;
 }
 
@@ -248,10 +272,11 @@ declare class UdpClientPhysicalLayer extends AbstractPhysicalLayer {
     get state(): PhysicalState;
     get socket(): Socket$1 | null;
     constructor(options?: Partial<SocketOptions>);
-    open(remote?: {
+    open(cb?: (err?: Error | null) => void): void;
+    open(remote: {
         port?: number;
         address?: string;
-    } | ((err?: Error | null) => void), cb?: (err?: Error | null) => void): void;
+    }, cb?: (err?: Error | null) => void): void;
     close(cb?: (err?: Error | null) => void): void;
 }
 
@@ -283,7 +308,8 @@ declare class UdpServerPhysicalLayer extends AbstractPhysicalLayer {
      * @param options Bind options (port, address, etc.). Defaults to port 502.
      * @param cb Callback invoked when binding completes or fails.
      */
-    open(options?: BindOptions | ((err?: Error | null) => void), cb?: (err?: Error | null) => void): void;
+    open(cb?: (err?: Error | null) => void): void;
+    open(options: BindOptions, cb?: (err?: Error | null) => void): void;
     close(cb?: (err?: Error | null) => void): void;
 }
 
@@ -349,25 +375,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.
  *
@@ -375,10 +413,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;
@@ -399,7 +443,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;
@@ -428,10 +472,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;
@@ -445,7 +497,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;
@@ -542,19 +594,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;
@@ -715,7 +769,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;
@@ -738,7 +792,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;
@@ -766,5 +832,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 };