njs-modbus 2.1.0 → 3.1.0

package/dist/index.d.ts

@@ -1,9 +1,10 @@
+import { SerialPort } from 'serialport';
+import { Socket, SocketConstructorOpts, SocketConnectOpts, Server, ServerOpts, ListenOptions } from 'node:net';
+import { Socket as Socket$1, SocketOptions, BindOptions } from 'node:dgram';
 import EventEmitter from 'node:events';
-import { SocketConstructorOpts, SocketConnectOpts, NetConnectOpts, ListenOptions } from 'node:net';
-import { SocketOptions, BindOptions } from 'node:dgram';
 
 type Callback$1<T> = (error: Error | null, value: T) => void;
-type FConvertPromise<F extends (...args: any) => any> = F extends (...args: infer A) => infer R ? ((...args: A) => Promise<R>) | ((...args: A) => R) : never;
+type MaybeAsyncFunction<F extends (...args: any) => any> = F extends (...args: infer A) => infer R ? ((...args: A) => Promise<R>) | ((...args: A) => R) : never;
 interface ApplicationDataUnit {
     transaction?: number;
     unit: number;
@@ -54,7 +55,7 @@ interface CustomFunctionCode {
      * Throwing inside `handle` is turned into a Modbus exception response by the slave.
      * If `handle` is omitted, the slave returns an ILLEGAL_FUNCTION exception for this FC.
      */
-    handle?: FConvertPromise<(data: Buffer, unit: number) => Buffer>;
+    handle?: MaybeAsyncFunction<(data: Buffer, unit: number) => Buffer>;
 }
 
 declare enum ErrorCode {
@@ -68,31 +69,9 @@ declare enum ErrorCode {
     GATEWAY_PATH_UNAVAILABLE = 10,
     GATEWAY_TARGET_DEVICE_FAILED_TO_RESPOND = 11
 }
-/** Internal error codes for programmatic error handling. */
-declare const ModbusErrorCode: {
-    readonly TIMEOUT: "ETIMEOUT";
-    readonly INVALID_RESPONSE: "EINVALID_RESPONSE";
-    readonly INSUFFICIENT_DATA: "EINSUFFICIENT_DATA";
-    readonly MASTER_CLOSED: "EMASTER_CLOSED";
-    readonly MASTER_DESTROYED: "EMASTER_DESTROYED";
-    readonly CONCURRENT_NOT_TCP: "ECONCURRENT_NOT_TCP";
-    readonly PORT_DESTROYED: "EPORT_DESTROYED";
-    readonly PORT_ALREADY_OPEN: "EPORT_ALREADY_OPEN";
-    readonly PORT_NOT_OPEN: "EPORT_NOT_OPEN";
-    readonly NOT_SUPPORTED: "ENOT_SUPPORTED";
-    readonly INVALID_DATA: "EINVALID_DATA";
-    readonly INVALID_HEX: "EINVALID_HEX";
-    readonly CRC_MISMATCH: "ECRC_MISMATCH";
-    readonly LRC_MISMATCH: "ELRC_MISMATCH";
-    readonly INCOMPLETE_FRAME: "EINCOMPLETE_FRAME";
-    readonly T1_5_EXCEEDED: "ET1_5_EXCEEDED";
-    readonly UNKNOWN_FC: "EUNKNOWN_FC";
-    readonly INVALID_ROLE: "EINVALID_ROLE";
-    readonly RANGE: "ERANGE";
-};
 declare class ModbusError extends Error {
-    readonly code: string;
-    constructor(code: string, message?: string);
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode, message?: string);
 }
 declare function getErrorByCode(code: ErrorCode): ModbusError;
 declare function getCodeByError(err: Error): ErrorCode;
@@ -134,6 +113,8 @@ declare enum ConformityLevel {
     REGULAR = 130,
     EXTENDED = 131
 }
+/** Shared empty Buffer to avoid repeated allocations. */
+declare const EMPTY_BUFFER: Buffer<ArrayBuffer>;
 /** Modbus V1.1b3 PDU quantity limits. */
 declare const LIMITS: {
     readonly READ_COILS_MIN: 1;
@@ -145,24 +126,16 @@ declare const LIMITS: {
     readonly RW_REGISTERS_WRITE_MAX: 121;
 };
 
-interface PhysicalConnection {
-    readonly id: string | number;
+declare enum PhysicalState {
+    OPENING = "opening",
+    OPEN = "open",
+    CLOSING = "closing",
+    CLOSED = "closed"
 }
-interface AbstractPhysicalLayerEvents {
-    data: [data: Buffer, response: (data: Buffer) => Promise<void>, connection: PhysicalConnection];
-    write: [data: Buffer];
-    error: [error: Error];
-    'connection-close': [connection: PhysicalConnection];
-    close: [];
-}
-declare abstract class AbstractPhysicalLayer extends EventEmitter<AbstractPhysicalLayerEvents> {
-    abstract readonly TYPE: 'SERIAL' | 'NET';
-    abstract readonly isOpen: boolean;
-    abstract readonly destroyed: boolean;
-    abstract open(...args: any[]): Promise<void>;
-    abstract write(data: Buffer): Promise<void>;
-    abstract close(): Promise<void>;
-    abstract destroy(): Promise<void>;
+declare enum PhysicalConnectionState {
+    CONNECTED = "connected",
+    DESTROYING = "destroying",
+    DESTROYED = "destroyed"
 }
 
 interface SerialPhysicalLayerOptions {
@@ -172,132 +145,244 @@ interface SerialPhysicalLayerOptions {
      * The baud rate of the port to be opened. This should match one of the commonly available baud rates, such as 110, 300, 1200, 2400, 4800, 9600, 14400, 19200, 38400, 57600, or 115200. Custom rates are supported best effort per platform. The device connected to the serial port is not guaranteed to support the requested baud rate, even if the port itself supports that baud rate.
      */
     baudRate: number;
-    /** Must be one of these: 5, 6, 7, or 8 defaults to 8 */
+    /** Must be one of these: 5, 6, 7, or 8. Defaults to 8 */
     dataBits?: 5 | 6 | 7 | 8;
     /** Prevent other processes from opening the port. Windows does not currently support `false`. Defaults to true */
     lock?: boolean;
-    /** Must be 1, 1.5 or 2 defaults to 1 */
+    /** Must be 1, 1.5 or 2. Defaults to 1 */
     stopBits?: 1 | 1.5 | 2;
-    parity?: string;
+    /** Device parity. Defaults to none */
+    parity?: 'none' | 'even' | 'odd' | 'mark' | 'space';
     /** Flow control Setting. Defaults to false */
     rtscts?: boolean;
     /** Flow control Setting. Defaults to false */
     xon?: boolean;
     /** Flow control Setting. Defaults to false */
     xoff?: boolean;
-    /** Flow control Setting defaults to false*/
+    /** Flow control Setting. Defaults to false */
     xany?: boolean;
     /** drop DTR on close. Defaults to true */
     hupcl?: boolean;
+    /** The size of the read and write buffers. Defaults to 64k */
+    highWaterMark?: number;
+    /** Emit 'end' on port close. Defaults to false */
+    endOnClose?: boolean;
+    /** see `man termios`. Defaults to 1 (Darwin/Linux only) */
+    vmin?: number;
+    /** see `man termios`. Defaults to 0 (Darwin/Linux only) */
+    vtime?: number;
+    /** RTS mode. Defaults to handshake (Windows only) */
+    rtsMode?: 'handshake' | 'enable' | 'toggle';
 }
 declare class SerialPhysicalLayer extends AbstractPhysicalLayer {
-    TYPE: 'SERIAL' | 'NET';
+    readonly TYPE: "SERIAL";
+    private _state;
+    private _connections;
     private _serialport;
-    private _connection;
-    private _isOpening;
-    private _destroyed;
+    private _serialportOpts;
+    private _path;
     private _baudRate;
-    get isOpen(): boolean;
-    get destroyed(): boolean;
+    private _pendingOpenCbs;
+    private _pendingCloseCbs;
+    private _cleanupFns;
+    get state(): PhysicalState;
+    get serialport(): SerialPort | null;
+    get path(): string;
     get baudRate(): number;
     constructor(options: SerialPhysicalLayerOptions);
-    open(): Promise<void>;
-    write(data: Buffer): Promise<void>;
-    close(): Promise<void>;
-    destroy(): Promise<void>;
+    open(cb?: (err?: Error | null) => void): void;
+    close(cb?: (err?: Error | null) => void): void;
 }
 
 declare class TcpClientPhysicalLayer extends AbstractPhysicalLayer {
-    TYPE: 'SERIAL' | 'NET';
+    readonly TYPE: "TCP_CLIENT";
+    private _state;
+    private _connections;
     private _socket;
-    private _connection;
-    private _isOpen;
-    private _isOpening;
-    private _destroyed;
-    private _socketOptions?;
-    get isOpen(): boolean;
-    get destroyed(): boolean;
+    private _socketOpts?;
+    private _pendingOpenCbs;
+    private _pendingCloseCbs;
+    private _cleanupFns;
+    get state(): PhysicalState;
+    get socket(): Socket | null;
     constructor(options?: SocketConstructorOpts);
-    open(options?: SocketConnectOpts): Promise<void>;
-    write(data: Buffer): Promise<void>;
-    close(): Promise<void>;
-    destroy(): Promise<void>;
+    open(options?: SocketConnectOpts | ((err?: Error | null) => void), cb?: (err?: Error | null) => void): void;
+    close(cb?: (err?: Error | null) => void): void;
 }
 
+interface TcpServerPhysicalLayerOptions {
+    /** Allowed client IP addresses. IPv4-mapped IPv6 addresses (e.g., ::ffff:192.168.1.1) are normalized before checking. */
+    whitelist?: string[];
+    /** Maximum number of concurrent connections. When exceeded, new connections are silently dropped by Node.js. */
+    maxConnections?: number;
+    /** Idle timeout in ms. Connection is destroyed if no data is received within this time. 0 = disabled. */
+    idleTimeout?: number;
+    /** Forwarded to `net.createServer()`. */
+    serverOpts?: ServerOpts;
+}
 declare class TcpServerPhysicalLayer extends AbstractPhysicalLayer {
-    TYPE: 'SERIAL' | 'NET';
-    private _server;
-    private _isOpen;
-    private _isOpening;
-    private _destroyed;
+    readonly TYPE: "TCP_SERVER";
+    private _state;
     private _connections;
-    private _serverOptions?;
-    get isOpen(): boolean;
-    get destroyed(): boolean;
-    constructor(options?: NetConnectOpts);
-    open(options?: ListenOptions): Promise<void>;
-    write(data: Buffer): Promise<void>;
-    close(): Promise<void>;
-    destroy(): Promise<void>;
+    private _server;
+    private _opts;
+    private _pendingOpenCbs;
+    private _pendingCloseCbs;
+    private _cleanupFns;
+    get state(): PhysicalState;
+    get server(): Server | null;
+    constructor(options?: TcpServerPhysicalLayerOptions);
+    open(options?: ListenOptions | ((err?: Error | null) => void), cb?: (err?: Error | null) => void): void;
+    close(cb?: (err?: Error | null) => void): void;
 }
 
-interface UdpPhysicalLayerOptions {
-    /** dgram Socket creation options. */
-    socket?: Partial<SocketOptions>;
-    /**
-     * Provided → client mode (send to this single remote, filter inbound).
-     * Omitted → server mode (bind locally, accept from any rinfo).
-     */
-    remote?: {
+declare class UdpClientPhysicalLayer extends AbstractPhysicalLayer {
+    readonly TYPE: "UDP_CLIENT";
+    private _state;
+    private _connections;
+    private _socket;
+    private _socketOpts;
+    private _pendingOpenCbs;
+    private _pendingCloseCbs;
+    private _cleanupFns;
+    get state(): PhysicalState;
+    get socket(): Socket$1 | null;
+    constructor(options?: Partial<SocketOptions>);
+    open(remote?: {
         port?: number;
         address?: string;
-    };
-    /**
-     * Server mode only. Each unique rinfo (`address:port`) gets its own
-     * `PhysicalConnection`; if no datagram arrives within this many ms, the
-     * connection is evicted (`connection-close` emitted, upper-layer framing
-     * state released). Default 30000. Set 0 to disable eviction.
-     */
+    } | ((err?: Error | null) => void), cb?: (err?: Error | null) => void): void;
+    close(cb?: (err?: Error | null) => void): void;
+}
+
+interface UdpServerPhysicalLayerOptions {
+    /** Allowed client IP addresses. IPv4-mapped IPv6 addresses (e.g., ::ffff:192.168.1.1) are normalized before checking. */
+    whitelist?: string[];
+    /** Maximum number of concurrent virtual client connections. When exceeded, datagrams from new clients are silently ignored. */
+    maxConnections?: number;
+    /** Connection idle timeout in ms. Pass `0` to disable eviction. Defaults to 30000. */
     idleTimeout?: number;
+    /** Forwarded to `dgram.createSocket()`. */
+    socketOpts?: Partial<SocketOptions>;
 }
-declare class UdpPhysicalLayer extends AbstractPhysicalLayer {
-    TYPE: 'SERIAL' | 'NET';
-    private _socket;
+declare class UdpServerPhysicalLayer extends AbstractPhysicalLayer {
+    readonly TYPE: "UDP_SERVER";
+    private _state;
     private _connections;
-    private _isOpen;
-    private _isOpening;
-    private _destroyed;
-    private _socketOptions?;
-    private _port;
-    private _address?;
-    private _idleTimeout;
-    isServer: boolean;
-    get isOpen(): boolean;
-    get destroyed(): boolean;
-    constructor(options?: UdpPhysicalLayerOptions);
-    open(options?: BindOptions): Promise<void>;
-    private _handleMessage;
-    write(data: Buffer): Promise<void>;
-    close(): Promise<void>;
-    destroy(): Promise<void>;
+    private _socket;
+    private _opts;
+    private _pendingOpenCbs;
+    private _pendingCloseCbs;
+    private _cleanupFns;
+    get state(): PhysicalState;
+    get socket(): Socket$1 | null;
+    constructor(options?: UdpServerPhysicalLayerOptions);
+    /**
+     * Bind the UDP socket and start accepting datagrams.
+     *
+     * @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;
+    close(cb?: (err?: Error | null) => void): void;
+}
+
+interface AbstractPhysicalConnectionEvents {
+    data: [data: Buffer];
+    close: [];
+}
+/**
+ * A one-way data transmission channel.
+ *
+ * State transitions are unidirectional: CONNECTED → DESTROYING → DESTROYED.
+ * Once closed, the instance cannot be reused; create a new connection instead.
+ */
+declare abstract class AbstractPhysicalConnection extends EventEmitter<AbstractPhysicalConnectionEvents> {
+    abstract readonly state: PhysicalConnectionState;
+    abstract readonly physicalLayer: AbstractPhysicalLayer;
+    abstract write(data: Buffer, cb?: (err?: Error | null) => void): void;
+    abstract destroy(cb?: (err?: Error | null) => void): void;
+}
+interface AbstractPhysicalLayerEvents {
+    open: [];
+    connect: [connection: AbstractPhysicalConnection];
+    close: [];
+    error: [error: Error];
+}
+/**
+ * An abstraction over local hardware or network resources.
+ *
+ * `open()` acquires the resource (serial port, TCP socket, UDP socket, etc.).
+ * Once ready, it emits `connect` with an {@link AbstractPhysicalConnection},
+ * unifying serial, TCP client, TCP server, and UDP under a single
+ * "connection-oriented" model similar to a TCP server accepting sockets.
+ */
+declare abstract class AbstractPhysicalLayer extends EventEmitter<AbstractPhysicalLayerEvents> {
+    abstract readonly TYPE: 'SERIAL' | 'TCP_CLIENT' | 'TCP_SERVER' | 'UDP_CLIENT' | 'UDP_SERVER';
+    is(type: 'SERIAL'): this is SerialPhysicalLayer;
+    is(type: 'TCP_CLIENT'): this is TcpClientPhysicalLayer;
+    is(type: 'TCP_SERVER'): this is TcpServerPhysicalLayer;
+    is(type: 'UDP_CLIENT'): this is UdpClientPhysicalLayer;
+    is(type: 'UDP_SERVER'): this is UdpServerPhysicalLayer;
+    abstract readonly state: PhysicalState;
+    /** Last argument is the callback: `(err?: Error | null) => void`. Callback is optional. */
+    abstract open(...args: any[]): void;
+    abstract close(cb?: (err?: Error | null) => void): void;
 }
 
+type PhysicalConfig = {
+    type: 'SERIAL';
+    opts: SerialPhysicalLayerOptions;
+} | {
+    type: 'TCP_CLIENT';
+    socketOpts?: SocketConstructorOpts;
+} | {
+    type: 'TCP_SERVER';
+    opts?: TcpServerPhysicalLayerOptions;
+} | {
+    type: 'UDP_CLIENT';
+    socketOpts?: Partial<SocketOptions>;
+} | {
+    type: 'UDP_SERVER';
+    opts?: UdpServerPhysicalLayerOptions;
+} | {
+    type: 'CUSTOM';
+    layer: AbstractPhysicalLayer;
+};
+type OpenArgs<T extends PhysicalConfig> = T extends {
+    type: 'SERIAL';
+} ? Parameters<SerialPhysicalLayer['open']> : T extends {
+    type: 'TCP_CLIENT';
+} ? Parameters<TcpClientPhysicalLayer['open']> : T extends {
+    type: 'TCP_SERVER';
+} ? Parameters<TcpServerPhysicalLayer['open']> : T extends {
+    type: 'UDP_CLIENT';
+} ? Parameters<UdpClientPhysicalLayer['open']> : T extends {
+    type: 'UDP_SERVER';
+} ? Parameters<UdpServerPhysicalLayer['open']> : never;
+declare function createPhysicalLayer(config: PhysicalConfig): AbstractPhysicalLayer;
+
 interface AbstractApplicationLayerEvents {
     framing: [frame: ApplicationDataUnit & {
         buffer: Buffer;
-    }, response: (data: Buffer) => Promise<void>, connection: PhysicalConnection];
+    }];
     'framing-error': [error: Error];
 }
+/**
+ * Application-layer protocol handler bound to a single physical connection.
+ *
+ * Its lifetime follows the channel: created when the underlying connection is
+ * established and discarded when the connection closes. Subclasses implement
+ * ASCII, RTU, or TCP framing rules.
+ */
 declare abstract class AbstractApplicationLayer extends EventEmitter<AbstractApplicationLayerEvents> {
-    abstract readonly PROTOCOL: 'TCP' | 'RTU' | 'ASCII';
-    private _role?;
-    get role(): 'MASTER' | 'SLAVE';
-    set role(value: 'MASTER' | 'SLAVE');
+    abstract readonly PROTOCOL: 'ASCII' | 'RTU' | 'TCP';
+    abstract ROLE: 'MASTER' | 'SLAVE';
+    abstract readonly connection: AbstractPhysicalConnection;
     flush(): void;
     addCustomFunctionCode(cfc: CustomFunctionCode): void;
     removeCustomFunctionCode(fc: number): void;
-    abstract encode(data: ApplicationDataUnit): Buffer;
-    abstract destroy(): void;
+    abstract encode(unit: number, fc: number, data: Buffer, transaction?: number): Buffer;
 }
 
 interface AsciiApplicationLayerOptions {
@@ -310,93 +395,113 @@ interface AsciiApplicationLayerOptions {
 }
 declare class AsciiApplicationLayer extends AbstractApplicationLayer {
     readonly PROTOCOL: "ASCII";
+    readonly ROLE: 'MASTER' | 'SLAVE';
     readonly lenientHex: boolean;
-    private _states;
-    private _removeAllListeners;
-    private _destroyed;
-    constructor(physicalLayer: SerialPhysicalLayer | TcpServerPhysicalLayer | TcpClientPhysicalLayer | UdpPhysicalLayer, options?: AsciiApplicationLayerOptions);
-    private getState;
-    flush(): void;
+    private _connection;
+    private _state;
+    private _cleanupFns;
+    get connection(): AbstractPhysicalConnection;
+    constructor(role: 'MASTER' | 'SLAVE', connection: AbstractPhysicalConnection, options?: AsciiApplicationLayerOptions);
     private framing;
-    encode(data: ApplicationDataUnit): Buffer;
-    destroy(): void;
+    flush(): void;
+    encode(unit: number, fc: number, data: Buffer, transaction?: number): Buffer;
 }
 
 interface RtuApplicationLayerOptions {
+    /** Inter-frame silence in milliseconds (Modbus RTU t3.5). 0 = disabled (immediate parse). */
+    intervalBetweenFrames?: number;
+    /** Inter-character timeout in milliseconds (Modbus RTU t1.5). Opt-in. */
+    interCharTimeout?: number;
     /**
-     * Inter-frame silence (Modbus RTU t3.5). Defaults to `{ unit: 'bit', value: 38.5 }`
-     * for serial (3.5 character times × 11 bits/char per Modbus V1.02 §2.5.1.1);
-     * ignored for TCP/UDP transports.
-     * - `{ unit: 'bit', value: 38.5 }` — spec bit-time approximation
-     * - `{ unit: 'ms', value: 20 }` — explicit milliseconds
-     *
-     * Per Modbus V1.02 §2.5.1.1, at baud rates > 19200 the spec uses a fixed
-     * 1.75 ms regardless of the bit value supplied.
-     */
-    intervalBetweenFrames?: {
-        unit: 'bit' | 'ms';
-        value: number;
-    };
-    /**
-     * Inter-character timeout (Modbus RTU t1.5). Opt-in; **disabled** by default
-     * because Node.js `setTimeout` precision (~1 ms minimum, ~15.6 ms on Windows)
-     * is too coarse to reliably honor t1.5 at common baud rates without
-     * false-positive frame discards. When set, a mid-frame gap exceeding this
-     * duration discards the in-progress buffer and emits `framing-error`.
-     * Only takes effect on serial transports.
-     *
-     * - `{ unit: 'bit', value: 21 }` — bit-time approximation (~1.5 char times)
-     * - `{ unit: 'ms', value: 1 }` — explicit milliseconds
-     *
-     * Per Modbus V1.02 §2.5.1.1, at baud rates > 19200 the spec uses a fixed
-     * 0.75 ms regardless of the bit value supplied.
+     * 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.
      */
-    interCharTimeout?: {
-        unit: 'bit' | 'ms';
-        value: number;
-    };
+    poolSize?: number;
 }
 declare class RtuApplicationLayer extends AbstractApplicationLayer {
     readonly PROTOCOL: "RTU";
-    private _states;
-    private _customFunctionCodes;
-    private _removeAllListeners;
+    readonly ROLE: 'MASTER' | 'SLAVE';
+    private _connection;
+    private _state;
+    private _poolSize;
     private _threePointFiveT;
     private _onePointFiveT;
-    private _destroyed;
-    constructor(physicalLayer: SerialPhysicalLayer | TcpServerPhysicalLayer | TcpClientPhysicalLayer | UdpPhysicalLayer, options?: RtuApplicationLayerOptions);
-    private getState;
+    private _customFunctionCodes;
+    private _cleanupFns;
+    get connection(): AbstractPhysicalConnection;
+    constructor(role: 'MASTER' | 'SLAVE', connection: AbstractPhysicalConnection, options?: RtuApplicationLayerOptions);
     private clearStateTimers;
-    private clearState;
+    private flushBuffer;
     flush(): void;
     addCustomFunctionCode(cfc: CustomFunctionCode): void;
     removeCustomFunctionCode(fc: number): void;
-    private flushBuffer;
-    private tryExtract;
-    private checkExpected;
-    private crcMatches;
-    private deliverFrame;
-    encode(data: ApplicationDataUnit): Buffer;
-    destroy(): void;
+    encode(unit: number, fc: number, data: Buffer, transaction?: number): Buffer;
 }
 
 declare class TcpApplicationLayer extends AbstractApplicationLayer {
     readonly PROTOCOL: "TCP";
+    readonly ROLE: 'MASTER' | 'SLAVE';
+    private _connection;
     private _transactionId;
-    private _buffers;
-    private _removeAllListeners;
-    private _destroyed;
-    constructor(physicalLayer: TcpServerPhysicalLayer | TcpClientPhysicalLayer | UdpPhysicalLayer);
+    private _buffer;
+    private _cleanupFns;
+    get connection(): AbstractPhysicalConnection;
+    constructor(role: 'MASTER' | 'SLAVE', connection: AbstractPhysicalConnection);
     private tryExtract;
     private processFrame;
-    encode(data: ApplicationDataUnit): Buffer;
-    destroy(): void;
+    flush(): void;
+    encode(unit: number, fc: number, data: Buffer, transaction?: number): Buffer;
 }
 
-interface ModbusMasterEvents {
-    error: [error: Error];
-    close: [];
+/**
+ * RTU timing parameter — accepts either:
+ * - a bare `number` in milliseconds (`0` to disable the timer entirely)
+ * - `{ unit: 'ms', value: N }` — explicit milliseconds (equivalent to bare `N`)
+ * - `{ unit: 'bit', value: N }` — bit-time approximation, derived from `baudRate`
+ *
+ * The bare-number form is the recommended default; the object form exists for
+ * specs that quote bit-time. Pass `0` (or `{ unit: 'ms', value: 0 }`) to disable
+ * the timer; either form short-circuits the baudRate-derived fallback.
+ */
+type RtuTimingValue = number | {
+    unit: 'bit' | 'ms';
+    value: number;
+};
+/** User-facing RTU protocol options (supports both bit and ms units). */
+interface RtuProtocolOptions {
+    /**
+     * Inter-frame silence (Modbus RTU t3.5).
+     *
+     * - `20` or `{ unit: 'ms', value: 20 }` — 20 ms
+     * - `{ unit: 'bit', value: 38.5 }` — spec bit-time approximation (default when `baudRate` is provided)
+     * - `0` — disable t3.5 timing (immediate parse on every chunk; useful for
+     *   lossless transports such as RTU-over-TCP or PTY-based tests where the
+     *   wire's silence semantics do not apply)
+     *
+     * Per Modbus V1.02 §2.5.1.1, at baud rates > 19200 a fixed 1.75 ms is used
+     * regardless of the bit value.
+     */
+    intervalBetweenFrames?: RtuTimingValue;
+    /**
+     * Inter-character timeout (Modbus RTU t1.5). Opt-in; **disabled** by default.
+     *
+     * - `1` or `{ unit: 'ms', value: 1 }` — 1 ms
+     * - `{ unit: 'bit', value: 21 }` — bit-time approximation (~1.5 char times)
+     * - `0` — disable explicitly
+     *
+     * Per Modbus V1.02 §2.5.1.1, at baud rates > 19200 a fixed 0.75 ms is used
+     * regardless of the bit value.
+     */
+    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.
+     */
+    poolSize?: number;
 }
+
 interface ReturnValue<T> {
     transaction?: number;
     unit: number;
@@ -413,22 +518,45 @@ interface ModbusMasterOptions {
      * Default false (FIFO queue, requests are serialized).
      */
     concurrent?: boolean;
+    physical: PhysicalConfig;
+    protocol: {
+        type: 'RTU';
+        opts?: RtuProtocolOptions;
+    } | {
+        type: 'TCP';
+    } | {
+        type: 'ASCII';
+        opts?: AsciiApplicationLayerOptions;
+    };
 }
-declare class ModbusMaster<A extends AbstractApplicationLayer, P extends AbstractPhysicalLayer> extends EventEmitter<ModbusMasterEvents> {
-    private applicationLayer;
-    private physicalLayer;
+declare class ModbusMaster<T extends ModbusMasterOptions = ModbusMasterOptions> extends EventEmitter<AbstractPhysicalLayerEvents> {
+    readonly timeout: number;
+    readonly concurrent: boolean;
     private _masterSession;
-    private _queue;
+    private _physicalLayer;
+    private _protocol;
+    private _appLayer?;
+    private _customFunctionCodes;
+    private _queueUnits;
+    private _queueFcs;
+    private _queueDatas;
+    private _queueTimeouts;
+    private _queueBroadcasts;
+    private _queueResolves;
+    private _queueRejects;
+    private _queueHead;
+    private _queueLen;
     private _draining;
     private _nextTid;
-    private _cleanLevel;
-    timeout: number;
-    readonly concurrent: boolean;
-    get isOpen(): boolean;
-    get destroyed(): boolean;
-    constructor(applicationLayer: A, physicalLayer: P, options?: ModbusMasterOptions);
+    private _cleanupFns;
+    private _closePromise;
+    get state(): PhysicalState;
+    get physicalLayer(): AbstractPhysicalLayer;
+    constructor(options: T);
+    private _createAppLayer;
     private send;
     private _drain;
+    private _processNext;
     private _exchange;
     private writeFC1Or2;
     writeFC1: this['readCoils'];
@@ -487,26 +615,41 @@ declare class ModbusMaster<A extends AbstractApplicationLayer, P extends Abstrac
     removeCustomFunctionCode(fc: number): void;
     sendCustomFC(unit: 0, fc: number, data: Buffer | number[], timeout?: number): Promise<void>;
     sendCustomFC(unit: number, fc: number, data: Buffer | number[], timeout?: number): Promise<Buffer>;
-    private _clean;
-    open(...args: Parameters<P['open']>): Promise<void>;
+    /**
+     * Open the underlying physical layer and begin accepting connections.
+     *
+     * A `ModbusMaster` instance can only be opened once. Once {@link close}
+     * is called — explicitly or because the physical layer disconnected —
+     * the instance is permanently closed and cannot be reopened.
+     * Create a new `ModbusMaster` if a new connection is required.
+     */
+    open(...args: OpenArgs<T['physical']>): Promise<void>;
+    private _close;
+    /**
+     * Permanently close the master and release all resources.
+     *
+     * After calling this method the instance is considered dead:
+     * - No further requests can be sent.
+     * - The instance cannot be reopened via {@link open}.
+     * - All event listeners registered on this master are removed.
+     */
     close(): Promise<void>;
-    destroy(): Promise<void>;
 }
 
 type Frame = ApplicationDataUnit & {
     buffer: Buffer;
 };
-type PreCheck = (frame: Frame) => boolean | number | undefined;
 type Callback = (error: Error | null, frame?: Frame) => void;
 declare class MasterSession {
     private _waiters;
-    start(key: string | number, preCheck: PreCheck[], callback: Callback): void;
+    /** Register a callback for `key`. No timer — timeout is managed by the caller. */
+    start(key: string | number, callback: Callback): void;
+    /** Cancel a pending waiter without firing its callback. */
     stop(key: string | number): void;
     stopAll(error: Error): void;
     has(key: string | number): boolean;
     handleFrame(frame: Frame): void;
     handleError(error: Error): void;
-    private runPreChecks;
 }
 
 interface ModbusSlaveModel {
@@ -517,27 +660,27 @@ interface ModbusSlaveModel {
      * If provide the return value, use this value as data of `PDU` to respond.
      * Otherwise keep the default read and write behavior.
      */
-    interceptor?: FConvertPromise<(fc: number, data: Buffer) => Buffer | undefined>;
-    readDiscreteInputs?: FConvertPromise<(address: number, length: number) => boolean[]>;
-    readCoils?: FConvertPromise<(address: number, length: number) => boolean[]>;
-    writeSingleCoil?: FConvertPromise<(address: number, value: boolean) => void>;
+    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>;
     /**
      * If omitted, defaults to loop and call `writeSingleCoil`.
      */
-    writeMultipleCoils?: FConvertPromise<(address: number, value: boolean[]) => void>;
-    readInputRegisters?: FConvertPromise<(address: number, length: number) => number[]>;
-    readHoldingRegisters?: FConvertPromise<(address: number, length: number) => number[]>;
-    writeSingleRegister?: FConvertPromise<(address: number, value: number) => void>;
+    writeMultipleCoils?: MaybeAsyncFunction<(address: number, value: boolean[]) => void>;
+    readInputRegisters?: MaybeAsyncFunction<(address: number, length: number) => number[]>;
+    readHoldingRegisters?: MaybeAsyncFunction<(address: number, length: number) => number[]>;
+    writeSingleRegister?: MaybeAsyncFunction<(address: number, value: number) => void>;
     /**
      * If omitted, defaults to loop and call `writeSingleRegister`.
      */
-    writeMultipleRegisters?: FConvertPromise<(address: number, value: number[]) => void>;
+    writeMultipleRegisters?: MaybeAsyncFunction<(address: number, value: number[]) => void>;
     /**
      * If omitted, defaults to call `readHoldingRegisters` and `writeSingleRegister`.
      */
-    maskWriteRegister?: FConvertPromise<(address: number, andMask: number, orMask: number) => void>;
-    reportServerId?: FConvertPromise<() => ServerId>;
-    readDeviceIdentification?: FConvertPromise<() => {
+    maskWriteRegister?: MaybeAsyncFunction<(address: number, andMask: number, orMask: number) => void>;
+    reportServerId?: MaybeAsyncFunction<() => ServerId>;
+    readDeviceIdentification?: MaybeAsyncFunction<() => {
         [index: number]: string;
     }>;
     getAddressRange?: () => {
@@ -547,10 +690,6 @@ interface ModbusSlaveModel {
         holdingRegisters?: [number, number] | [number, number][];
     };
 }
-interface ModbusSlaveEvents {
-    error: [error: Error];
-    close: [];
-}
 interface ModbusSlaveOptions {
     /**
      * Pipelined concurrent processing of requests within one connection.
@@ -558,19 +697,31 @@ interface ModbusSlaveOptions {
      * Default false — per-connection FIFO. RTU/ASCII + concurrent=true throws.
      */
     concurrent?: boolean;
+    physical: PhysicalConfig;
+    protocol: {
+        type: 'RTU';
+        opts?: RtuProtocolOptions;
+    } | {
+        type: 'TCP';
+    } | {
+        type: 'ASCII';
+        opts?: AsciiApplicationLayerOptions;
+    };
 }
-declare class ModbusSlave<A extends AbstractApplicationLayer, P extends AbstractPhysicalLayer> extends EventEmitter<ModbusSlaveEvents> {
-    private applicationLayer;
-    private physicalLayer;
-    models: Map<number, ModbusSlaveModel>;
+declare class ModbusSlave<T extends ModbusSlaveOptions = ModbusSlaveOptions> extends EventEmitter<AbstractPhysicalLayerEvents> {
+    readonly models: Map<number, ModbusSlaveModel>;
     readonly concurrent: boolean;
-    private _queues;
+    private _physicalLayer;
+    private _protocol;
+    private _appLayers;
     private _customFunctionCodes;
     private _locks;
-    private _cleanLevel;
-    get isOpen(): boolean;
-    get destroyed(): boolean;
-    constructor(applicationLayer: A, physicalLayer: P, options?: ModbusSlaveOptions);
+    private _cleanupFns;
+    private _closePromise;
+    get state(): PhysicalState;
+    get physicalLayer(): AbstractPhysicalLayer;
+    constructor(options: T);
+    private _createAppLayer;
     private handleFC1;
     private handleFC2;
     private handleFC3;
@@ -587,17 +738,33 @@ declare class ModbusSlave<A extends AbstractApplicationLayer, P extends Abstract
     private _drain;
     private _processFrame;
     private _intercept;
-    private withAddressLock;
+    private _withAddressLock;
     private _handleFC;
+    private _handleCustomFC;
     add(model: ModbusSlaveModel): void;
     remove(unit: number): void;
     addCustomFunctionCode(cfc: CustomFunctionCode): void;
     removeCustomFunctionCode(fc: number): void;
-    private _clean;
-    open(...args: Parameters<P['open']>): Promise<void>;
+    /**
+     * Open the underlying physical layer and begin accepting connections.
+     *
+     * A `ModbusSlave` instance can only be opened once. Once {@link close}
+     * is called — explicitly or because the physical layer disconnected —
+     * the instance is permanently closed and cannot be reopened.
+     * Create a new `ModbusSlave` if a new server is required.
+     */
+    open(...args: OpenArgs<T['physical']>): Promise<void>;
+    private _close;
+    /**
+     * Permanently close the slave and release all resources.
+     *
+     * After calling this method the instance is considered dead:
+     * - No further requests can be processed.
+     * - The instance cannot be reopened via {@link open}.
+     * - All event listeners registered on this slave are removed.
+     */
     close(): Promise<void>;
-    destroy(): Promise<void>;
 }
 
-export { AbstractApplicationLayer, AbstractPhysicalLayer, AsciiApplicationLayer, COIL_OFF, COIL_ON, ConformityLevel, EXCEPTION_OFFSET, ErrorCode, FunctionCode, LIMITS, MEI_READ_DEVICE_ID, MasterSession, ModbusError, ModbusErrorCode, ModbusMaster, ModbusSlave, ReadDeviceIDCode, RtuApplicationLayer, SerialPhysicalLayer, TcpApplicationLayer, TcpClientPhysicalLayer, TcpServerPhysicalLayer, UdpPhysicalLayer, getCodeByError, getErrorByCode };
-export type { ApplicationDataUnit, AsciiApplicationLayerOptions, Callback$1 as Callback, CustomFunctionCode, DeviceIdentification, FConvertPromise, ModbusMasterOptions, ModbusSlaveModel, ModbusSlaveOptions, PhysicalConnection, RtuApplicationLayerOptions, ServerId };
+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 type { AbstractPhysicalLayerEvents, ApplicationDataUnit, AsciiApplicationLayerOptions, Callback$1 as Callback, CustomFunctionCode, DeviceIdentification, MaybeAsyncFunction, ModbusMasterOptions, ModbusSlaveModel, ModbusSlaveOptions, OpenArgs, PhysicalConfig, RtuApplicationLayerOptions, ServerId, TcpServerPhysicalLayerOptions, UdpServerPhysicalLayerOptions };