njs-modbus 2.1.0 → 3.1.0

package/dist/src/error-code.d.ts

@@ -9,31 +9,9 @@ export declare enum ErrorCode {
     GATEWAY_PATH_UNAVAILABLE = 10,
     GATEWAY_TARGET_DEVICE_FAILED_TO_RESPOND = 11
 }
-/** Internal error codes for programmatic error handling. */
-export 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";
-};
 export declare class ModbusError extends Error {
-    readonly code: string;
-    constructor(code: string, message?: string);
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode, message?: string);
 }
 export declare function getErrorByCode(code: ErrorCode): ModbusError;
 export declare function getCodeByError(err: Error): ErrorCode;

package/dist/src/layers/application/abstract-application-layer.d.ts

@@ -1,21 +1,26 @@
 import type { ApplicationDataUnit, CustomFunctionCode } from '../../types';
-import type { PhysicalConnection } from '../physical';
+import type { AbstractPhysicalConnection } from '../physical';
 import EventEmitter from 'node:events';
 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.
+ */
 export 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;
 }
 export {};

package/dist/src/layers/application/ascii-application-layer.d.ts

@@ -1,6 +1,4 @@
-import type { ApplicationDataUnit } from '../../types';
-import type { TcpClientPhysicalLayer, TcpServerPhysicalLayer, UdpPhysicalLayer } from '../physical';
-import type { SerialPhysicalLayer } from '../physical';
+import type { AbstractPhysicalConnection } from '../physical';
 import { AbstractApplicationLayer } from './abstract-application-layer';
 export interface AsciiApplicationLayerOptions {
     /**
@@ -12,14 +10,14 @@ export interface AsciiApplicationLayerOptions {
 }
 export 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;
 }

package/dist/src/layers/application/rtu-application-layer.d.ts

@@ -1,61 +1,34 @@
-import type { ApplicationDataUnit, CustomFunctionCode } from '../../types';
-import type { TcpClientPhysicalLayer, TcpServerPhysicalLayer, UdpPhysicalLayer } from '../physical';
-import type { SerialPhysicalLayer } from '../physical';
+import type { CustomFunctionCode } from '../../types';
+import type { AbstractPhysicalConnection } from '../physical';
 import { AbstractApplicationLayer } from './abstract-application-layer';
 export 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.
+     * 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.
      */
-    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.
-     */
-    interCharTimeout?: {
-        unit: 'bit' | 'ms';
-        value: number;
-    };
+    poolSize?: number;
 }
 export 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;
 }

package/dist/src/layers/application/tcp-application-layer.d.ts

@@ -1,15 +1,16 @@
-import type { ApplicationDataUnit } from '../../types';
-import type { TcpClientPhysicalLayer, TcpServerPhysicalLayer, UdpPhysicalLayer } from '../physical';
+import type { AbstractPhysicalConnection } from '../physical';
 import { AbstractApplicationLayer } from './abstract-application-layer';
 export 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;
 }

package/dist/src/layers/physical/abstract-physical-layer.d.ts

@@ -1,21 +1,50 @@
+import type { SerialPhysicalLayer } from './serial-physical-layer';
+import type { TcpClientPhysicalLayer } from './tcp-client-physical-layer';
+import type { TcpServerPhysicalLayer } from './tcp-server-physical-layer';
+import type { UdpClientPhysicalLayer } from './udp-client-physical-layer';
+import type { UdpServerPhysicalLayer } from './udp-server-physical-layer';
+import type { PhysicalConnectionState, PhysicalState } from './vars';
 import EventEmitter from 'node:events';
-export interface PhysicalConnection {
-    readonly id: string | number;
+interface AbstractPhysicalConnectionEvents {
+    data: [data: Buffer];
+    close: [];
 }
-interface AbstractPhysicalLayerEvents {
-    data: [data: Buffer, response: (data: Buffer) => Promise<void>, connection: PhysicalConnection];
-    write: [data: Buffer];
-    error: [error: Error];
-    'connection-close': [connection: PhysicalConnection];
+/**
+ * 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.
+ */
+export 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;
+}
+export 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.
+ */
 export 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>;
+    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;
 }
 export {};

package/dist/src/layers/physical/index.d.ts

@@ -1,6 +1,12 @@
-export type { PhysicalConnection } from './abstract-physical-layer';
-export { AbstractPhysicalLayer } from './abstract-physical-layer';
+export type { AbstractPhysicalLayerEvents } from './abstract-physical-layer';
+export type { PhysicalConfig, OpenArgs } from './utils';
+export type { TcpServerPhysicalLayerOptions } from './tcp-server-physical-layer';
+export type { UdpServerPhysicalLayerOptions } from './udp-server-physical-layer';
+export { AbstractPhysicalConnection, AbstractPhysicalLayer } from './abstract-physical-layer';
 export { SerialPhysicalLayer } from './serial-physical-layer';
 export { TcpClientPhysicalLayer } from './tcp-client-physical-layer';
 export { TcpServerPhysicalLayer } from './tcp-server-physical-layer';
-export { UdpPhysicalLayer } from './udp-physical-layer';
+export { UdpClientPhysicalLayer } from './udp-client-physical-layer';
+export { UdpServerPhysicalLayer } from './udp-server-physical-layer';
+export { PhysicalState, PhysicalConnectionState } from './vars';
+export { createPhysicalLayer } from './utils';

package/dist/src/layers/physical/serial-physical-layer.d.ts

@@ -1,4 +1,6 @@
-import { AbstractPhysicalLayer } from './abstract-physical-layer';
+import { SerialPort } from 'serialport';
+import { AbstractPhysicalConnection, AbstractPhysicalLayer } from './abstract-physical-layer';
+import { PhysicalConnectionState, PhysicalState } from './vars';
 export interface SerialPhysicalLayerOptions {
     /** The system path of the serial port you want to open. For example, `/dev/tty.XXX` on Mac/Linux, or `COM1` on Windows */
     path: string;
@@ -6,37 +8,63 @@ export 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';
+}
+export declare class SerialPhysicalConnection extends AbstractPhysicalConnection {
+    private _state;
+    private _physicalLayer;
+    private _serialport;
+    private _pendingDestroyCbs;
+    private _cleanupFns;
+    get state(): PhysicalConnectionState;
+    get physicalLayer(): AbstractPhysicalLayer;
+    constructor(physicalLayer: SerialPhysicalLayer, serialport: SerialPort);
+    write(data: Buffer, cb?: (err?: Error | null) => void): void;
+    destroy(cb?: (err?: Error | null) => void): void;
 }
 export 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;
 }

package/dist/src/layers/physical/tcp-client-physical-layer.d.ts

@@ -1,18 +1,19 @@
 import type { SocketConstructorOpts, SocketConnectOpts } from 'node:net';
+import { Socket } from 'node:net';
 import { AbstractPhysicalLayer } from './abstract-physical-layer';
+import { PhysicalState } from './vars';
 export 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;
 }

package/dist/src/layers/physical/tcp-physical-connection.d.ts

@@ -0,0 +1,16 @@
+import type { AbstractPhysicalLayer } from './abstract-physical-layer';
+import type { Socket } from 'node:net';
+import { AbstractPhysicalConnection } from './abstract-physical-layer';
+import { PhysicalConnectionState } from './vars';
+export declare class TcpPhysicalConnection extends AbstractPhysicalConnection {
+    private _state;
+    private _physicalLayer;
+    private _socket;
+    private _pendingDestroyCbs;
+    private _cleanupFns;
+    get state(): PhysicalConnectionState;
+    get physicalLayer(): AbstractPhysicalLayer;
+    constructor(physicalLayer: AbstractPhysicalLayer, socket: Socket);
+    write(data: Buffer, cb?: (err?: Error | null) => void): void;
+    destroy(cb?: (err?: Error | null) => void): void;
+}

package/dist/src/layers/physical/tcp-server-physical-layer.d.ts

@@ -1,18 +1,28 @@
-import type { NetConnectOpts, ListenOptions } from 'node:net';
+import type { Server, ListenOptions, ServerOpts } from 'node:net';
 import { AbstractPhysicalLayer } from './abstract-physical-layer';
+import { PhysicalState } from './vars';
+export 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;
+}
 export 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;
 }

package/dist/src/layers/physical/udp-client-physical-layer.d.ts

@@ -0,0 +1,33 @@
+import type { Socket, SocketOptions } from 'node:dgram';
+import { AbstractPhysicalConnection, AbstractPhysicalLayer } from './abstract-physical-layer';
+import { PhysicalConnectionState, PhysicalState } from './vars';
+export declare class UdpClientPhysicalConnection extends AbstractPhysicalConnection {
+    private _state;
+    private _physicalLayer;
+    private _socket;
+    private _pendingDestroyCbs;
+    private _cleanupFns;
+    get state(): PhysicalConnectionState;
+    get physicalLayer(): AbstractPhysicalLayer;
+    constructor(physicalLayer: UdpClientPhysicalLayer, socket: Socket);
+    write(data: Buffer, cb?: (err?: Error | null) => void): void;
+    destroy(cb?: (err?: Error | null) => void): void;
+}
+export 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 | null;
+    constructor(options?: Partial<SocketOptions>);
+    open(remote?: {
+        port?: number;
+        address?: string;
+    } | ((err?: Error | null) => void), cb?: (err?: Error | null) => void): void;
+    close(cb?: (err?: Error | null) => void): void;
+}

package/dist/src/layers/physical/udp-server-physical-layer.d.ts

@@ -0,0 +1,50 @@
+import type { BindOptions, RemoteInfo, Socket, SocketOptions } from 'node:dgram';
+import { AbstractPhysicalConnection, AbstractPhysicalLayer } from './abstract-physical-layer';
+import { PhysicalConnectionState, PhysicalState } from './vars';
+export 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>;
+}
+export declare class UdpServerPhysicalConnection extends AbstractPhysicalConnection {
+    private _state;
+    private _physicalLayer;
+    private _socket;
+    private _remote;
+    private _idleTid;
+    private _cleanupFns;
+    get state(): PhysicalConnectionState;
+    get physicalLayer(): AbstractPhysicalLayer;
+    constructor(physicalLayer: UdpServerPhysicalLayer, socket: Socket, remote: RemoteInfo, idleTimeout: number, messageEventDelegation: {
+        add: (listener: (msg: Buffer, rinfo: RemoteInfo) => void) => void;
+        remove: (listener: (...args: any[]) => void) => void;
+    });
+    write(data: Buffer, cb?: (err?: Error | null) => void): void;
+    destroy(cb?: (err?: Error | null) => void): void;
+}
+export declare class UdpServerPhysicalLayer extends AbstractPhysicalLayer {
+    readonly TYPE: "UDP_SERVER";
+    private _state;
+    private _connections;
+    private _socket;
+    private _opts;
+    private _pendingOpenCbs;
+    private _pendingCloseCbs;
+    private _cleanupFns;
+    get state(): PhysicalState;
+    get socket(): Socket | 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;
+}

package/dist/src/layers/physical/utils.d.ts

@@ -0,0 +1,39 @@
+import type { AbstractPhysicalLayer } from './abstract-physical-layer';
+import type { SocketOptions } from 'node:dgram';
+import type { SocketConstructorOpts } from 'node:net';
+import { SerialPhysicalLayer, type SerialPhysicalLayerOptions } from './serial-physical-layer';
+import { TcpClientPhysicalLayer } from './tcp-client-physical-layer';
+import { TcpServerPhysicalLayer, type TcpServerPhysicalLayerOptions } from './tcp-server-physical-layer';
+import { UdpClientPhysicalLayer } from './udp-client-physical-layer';
+import { UdpServerPhysicalLayer, type UdpServerPhysicalLayerOptions } from './udp-server-physical-layer';
+export 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;
+};
+export 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;
+export declare function createPhysicalLayer(config: PhysicalConfig): AbstractPhysicalLayer;

package/dist/src/layers/physical/vars.d.ts

@@ -0,0 +1,11 @@
+export declare enum PhysicalState {
+    OPENING = "opening",
+    OPEN = "open",
+    CLOSING = "closing",
+    CLOSED = "closed"
+}
+export declare enum PhysicalConnectionState {
+    CONNECTED = "connected",
+    DESTROYING = "destroying",
+    DESTROYED = "destroyed"
+}

package/dist/src/master/master-session.d.ts

@@ -2,17 +2,17 @@ import type { ApplicationDataUnit } from '../types';
 type Frame = ApplicationDataUnit & {
     buffer: Buffer;
 };
-type PreCheck = (frame: Frame) => boolean | number | undefined;
 type Callback = (error: Error | null, frame?: Frame) => void;
 export declare const FIFO_KEY: "fifo";
 export 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;
 }
 export {};