njs-modbus 2.1.0 → 3.0.2

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

@@ -1,11 +1,9 @@
-import type { AbstractApplicationLayer } from '../layers/application';
-import type { AbstractPhysicalLayer } from '../layers/physical';
+import type { AsciiApplicationLayerOptions } from '../layers/application';
+import type { AbstractPhysicalLayer, AbstractPhysicalLayerEvents, OpenArgs, PhysicalConfig } from '../layers/physical';
 import type { CustomFunctionCode, DeviceIdentification, ServerId } from '../types';
+import type { RtuProtocolOptions } from '../utils';
 import EventEmitter from 'node:events';
-interface ModbusMasterEvents {
-    error: [error: Error];
-    close: [];
-}
+import { PhysicalState } from '../layers/physical';
 interface ReturnValue<T> {
     transaction?: number;
     unit: number;
@@ -22,20 +20,34 @@ export interface ModbusMasterOptions {
      * Default false (FIFO queue, requests are serialized).
      */
     concurrent?: boolean;
+    physical: PhysicalConfig;
+    protocol: {
+        type: 'RTU';
+        opts?: RtuProtocolOptions;
+    } | {
+        type: 'TCP';
+    } | {
+        type: 'ASCII';
+        opts?: AsciiApplicationLayerOptions;
+    };
 }
-export declare class ModbusMaster<A extends AbstractApplicationLayer, P extends AbstractPhysicalLayer> extends EventEmitter<ModbusMasterEvents> {
-    private applicationLayer;
-    private physicalLayer;
+export declare class ModbusMaster<T extends ModbusMasterOptions = ModbusMasterOptions> extends EventEmitter<AbstractPhysicalLayerEvents> {
+    readonly timeout: number;
+    readonly concurrent: boolean;
     private _masterSession;
+    private _physicalLayer;
+    private _protocol;
+    private _appLayer?;
+    private _customFunctionCodes;
     private _queue;
     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 _exchange;
@@ -97,8 +109,24 @@ export declare class ModbusMaster<A extends AbstractApplicationLayer, P extends
     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>;
 }
 export {};

package/dist/src/slave/slave.d.ts

@@ -1,7 +1,9 @@
-import type { AbstractApplicationLayer } from '../layers/application';
-import type { AbstractPhysicalLayer } from '../layers/physical';
-import type { CustomFunctionCode, FConvertPromise, ServerId } from '../types';
+import type { AsciiApplicationLayerOptions } from '../layers/application';
+import type { AbstractPhysicalLayer, AbstractPhysicalLayerEvents, OpenArgs, PhysicalConfig } from '../layers/physical';
+import type { CustomFunctionCode, MaybeAsyncFunction, ServerId } from '../types';
+import type { RtuProtocolOptions } from '../utils';
 import EventEmitter from 'node:events';
+import { PhysicalState } from '../layers/physical';
 export interface ModbusSlaveModel {
     unit?: number;
     /**
@@ -10,27 +12,27 @@ export 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?: () => {
@@ -40,10 +42,6 @@ export interface ModbusSlaveModel {
         holdingRegisters?: [number, number] | [number, number][];
     };
 }
-interface ModbusSlaveEvents {
-    error: [error: Error];
-    close: [];
-}
 export interface ModbusSlaveOptions {
     /**
      * Pipelined concurrent processing of requests within one connection.
@@ -51,19 +49,31 @@ export 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;
+    };
 }
-export declare class ModbusSlave<A extends AbstractApplicationLayer, P extends AbstractPhysicalLayer> extends EventEmitter<ModbusSlaveEvents> {
-    private applicationLayer;
-    private physicalLayer;
-    models: Map<number, ModbusSlaveModel>;
+export 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;
@@ -80,15 +90,29 @@ export declare class ModbusSlave<A extends AbstractApplicationLayer, P extends A
     private _drain;
     private _processFrame;
     private _intercept;
-    private withAddressLock;
+    private _withAddressLock;
     private _handleFC;
     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 {};

package/dist/src/types.d.ts

@@ -1,5 +1,5 @@
 export type Callback<T> = (error: Error | null, value: T) => void;
-export type FConvertPromise<F extends (...args: any) => any> = F extends (...args: infer A) => infer R ? ((...args: A) => Promise<R>) | ((...args: A) => R) : never;
+export type MaybeAsyncFunction<F extends (...args: any) => any> = F extends (...args: infer A) => infer R ? ((...args: A) => Promise<R>) | ((...args: A) => R) : never;
 export interface ApplicationDataUnit {
     transaction?: number;
     unit: number;
@@ -50,5 +50,5 @@ export 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>;
 }

package/dist/src/utils/index.d.ts

@@ -1,8 +1,10 @@
+export type { PredictResult } from './predictRtuFrameLength';
+export type { RtuProtocolOptions, ResolvedRtuTiming } from './rtu-timing';
 export { checkRange } from './checkRange';
 export { crc } from './crc';
-export { genConnectionId } from './genConnectionId';
 export { bitsToMs } from './bitsToMs';
 export { isUint8 } from './isUint8';
 export { lrc } from './lrc';
 export { predictRtuFrameLength } from './predictRtuFrameLength';
-export type { PredictResult } from './predictRtuFrameLength';
+export { resolveRtuTiming } from './rtu-timing';
+export { isWhitelisted } from './whitelist';

package/dist/src/utils/rtu-timing.d.ts

@@ -0,0 +1,49 @@
+/** User-facing RTU protocol options (supports both bit and ms units). */
+export interface RtuProtocolOptions {
+    /**
+     * Inter-frame silence (Modbus RTU t3.5).
+     * - `{ unit: 'bit', value: 38.5 }` — spec bit-time approximation (default when `baudRate` is provided)
+     * - `{ unit: 'ms', value: 20 }` — explicit milliseconds
+     *
+     * 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?: {
+        unit: 'bit' | 'ms';
+        value: number;
+    };
+    /**
+     * Inter-character timeout (Modbus RTU t1.5). Opt-in; **disabled** by default.
+     * - `{ 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 a fixed 0.75 ms is used
+     * regardless of the bit value.
+     */
+    interCharTimeout?: {
+        unit: 'bit' | 'ms';
+        value: 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.
+     */
+    poolSize?: number;
+}
+/** Resolved RTU timing values in milliseconds. */
+export interface ResolvedRtuTiming {
+    intervalBetweenFrames: number;
+    interCharTimeout: number;
+}
+/**
+ * Resolve Modbus RTU timing parameters from user options into milliseconds.
+ *
+ * - `intervalBetweenFrames` (t3.5): if omitted and `baudRate` is present,
+ *   defaults to 38.5 bits per Modbus V1.02 §2.5.1.1.
+ * - `interCharTimeout` (t1.5): opt-in; only resolved when explicitly provided.
+ *
+ * Per the spec, at baud rates > 19200 fixed values are used
+ * (1.75 ms for t3.5, 0.75 ms for t1.5) regardless of the bit value.
+ */
+export declare function resolveRtuTiming(opts?: RtuProtocolOptions, baudRate?: number): ResolvedRtuTiming;

package/dist/src/utils/whitelist.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Normalize an IP address by stripping the IPv4-mapped IPv6 prefix.
+ * This ensures consistent comparison of addresses like `::ffff:192.168.1.1`.
+ */
+export declare function normalizeAddress(address?: string): string;
+/**
+ * Check whether a remote address is allowed by the given whitelist.
+ * IPv4-mapped IPv6 addresses are normalized before comparison.
+ * Returns `true` when whitelist is absent or empty.
+ */
+export declare function isWhitelisted(address: string | undefined, whitelist: string[] | undefined): boolean;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "njs-modbus",
-  "version": "2.1.0",
-  "description": "A pure JavaScript implemetation of Modbus for NodeJS.",
+  "version": "3.0.2",
+  "description": "A pure JavaScript implementation of Modbus for Node.js.",
   "keywords": [
     "modbus",
     "rtu",
@@ -10,17 +10,16 @@
     "tcp",
     "udp"
   ],
-  "homepage": "https://github.com/xiejay97/njs-modbus/tree/main/packages/ui#readme",
+  "homepage": "https://github.com/xiejay97/njs-modbus/tree/main#readme",
   "bugs": {
     "url": "https://github.com/xiejay97/njs-modbus/issues"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/xiejay97/njs-modbus.git"
+    "url": "git+https://github.com/xiejay97/njs-modbus.git"
   },
   "license": "MIT",
   "author": "Xie Jay <xiejay97@gmail.com>",
-  "packageManager": "pnpm@10.10.0",
   "sideEffects": false,
   "type": "module",
   "main": "dist/index.cjs",
@@ -32,8 +31,8 @@
     "*.d.ts"
   ],
   "scripts": {
-    "build": "rollup -c",
-    "test": "tsx --test test/*.test.ts",
+    "build": "node -e \"fs.rmSync('dist', {recursive: true, force: true})\" && rollup -c",
+    "test": "tsx --test test/**/*.test.ts",
     "util:sort-package-json": "sort-package-json"
   },
   "devDependencies": {
@@ -62,7 +61,8 @@
     "tslib": "^2.8.1",
     "tsx": "^4.21.0",
     "typescript": "~5.8.3",
-    "typescript-eslint": "^8.34.0"
+    "typescript-eslint": "^8.34.0",
+    "why-is-node-running": "^3.2.2"
   },
   "peerDependencies": {
     "serialport": ">=12.0.0"

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

@@ -1,42 +0,0 @@
-import type { BindOptions, SocketOptions } from 'node:dgram';
-import { AbstractPhysicalLayer } from './abstract-physical-layer';
-export 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?: {
-        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.
-     */
-    idleTimeout?: number;
-}
-export declare class UdpPhysicalLayer extends AbstractPhysicalLayer {
-    TYPE: 'SERIAL' | 'NET';
-    private _socket;
-    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>;
-}

package/dist/src/utils/genConnectionId.d.ts

@@ -1,2 +0,0 @@
-/** Cross-process unique id: `${prefix}-${uuid-v4}`. */
-export declare function genConnectionId(prefix: string): string;

package/dist/test/adu-buffer.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/ascii-hex-sentry.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/ascii-hex-validation.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/ascii-tcp-fragmentation.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/check-range.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/fallback-atomic.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/fallback-serial.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/fc17-serverid-validation.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/fc43-conformity.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/fc43-utf8-objects.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/gen-connection-id.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/helpers/raw-tcp.d.ts

@@ -1,38 +0,0 @@
-import type { Server } from 'node:net';
-import { Socket } from 'node:net';
-export interface RawClient {
-    socket: Socket;
-    write: (data: Buffer) => Promise<void>;
-    end: () => Promise<void>;
-    onData: (callback: (chunk: Buffer) => void) => void;
-    collected: () => Buffer;
-}
-export declare function connectRawClient(port: number, host?: string): Promise<RawClient>;
-export interface RawServer {
-    server: Server;
-    port: number;
-    /** Resolves with the first accepted socket. */
-    firstSocket: Promise<Socket>;
-    close: () => Promise<void>;
-}
-export declare function startRawServer(port?: number, host?: string): Promise<RawServer>;
-export declare function sleep(ms: number): Promise<void>;
-/** Build a Modbus TCP MBAP request frame. */
-export declare function buildMbapRequest(opts: {
-    transaction: number;
-    unit: number;
-    fc: number;
-    data: Buffer | number[];
-}): Buffer;
-/** Build a Modbus RTU frame (PDU + 2-byte CRC, little-endian). */
-export declare function buildRtuFrame(opts: {
-    unit: number;
-    fc: number;
-    data: Buffer | number[];
-}): Buffer;
-/** Build a Modbus ASCII frame: `:` + hex(unit + fc + data + LRC) + CRLF. */
-export declare function buildAsciiFrame(opts: {
-    unit: number;
-    fc: number;
-    data: Buffer | number[];
-}): Buffer;

package/dist/test/master-concurrent.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/modbus-error.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/physical-lifecycle.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/predict-rtu.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/rtu-custom-fc.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/rtu-pool-overflow.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/rtu-t15-timing.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/rtu-t35-default.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/rtu-t35-strict.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/rtu-tcp-fragmentation.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/serial-e2e.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/slave-multi-connection.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/slave.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/tcp-fragmentation.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/udp-multi-client.test.d.ts

@@ -1 +0,0 @@
-export {};