njs-modbus 3.1.1 → 3.2.0

package/dist/utils.cjs

@@ -0,0 +1,439 @@
+'use strict';
+
+/**
+ * Convert a number of bits to milliseconds at a given baud rate.
+ *
+ * Used to derive Modbus RTU timing intervals from bit counts — e.g. 38.5 bits
+ * = 3.5 character times at 11 bits/char (t3.5 inter-frame silence), or 16.5
+ * bits = 1.5 character times (t1.5 inter-character timeout), per Modbus V1.02
+ * §2.5.1.1.
+ *
+ * @param baudRate Serial port baud rate.
+ * @param bits Number of bits to convert.
+ * @returns Duration in milliseconds.
+ */
+function bitsToMs(baudRate, bits) {
+    return (bits * 1000) / baudRate;
+}
+
+/**
+ * Drain a pending-callback array: invoke each callback with the given error (or null).
+ *
+ * Handles `null`/`undefined` entries (from optional `cb?` parameters) gracefully.
+ * Used by physical layers and connections to resolve queued
+ * open / close / destroy callbacks.
+ */
+function drainCbs(cbs, err) {
+    if (!cbs)
+        return;
+    for (const cb of cbs) {
+        cb?.(err);
+    }
+}
+
+function inRange(n, [min, max]) {
+    return n >= min && n <= max;
+}
+function isRangeArray(range) {
+    return Array.isArray(range[0]);
+}
+function checkRange(value, range) {
+    if (!range || range.length === 0) {
+        return true;
+    }
+    const values = Array.isArray(value) ? value : [value];
+    if (isRangeArray(range)) {
+        for (const r of range) {
+            const [min, max] = r;
+            const [lo, hi] = min <= max ? [min, max] : [max, min];
+            if (values.every((n) => inRange(n, [lo, hi]))) {
+                return true;
+            }
+        }
+        return false;
+    }
+    const [min, max] = range;
+    const [lo, hi] = min <= max ? [min, max] : [max, min];
+    return values.every((n) => inRange(n, [lo, hi]));
+}
+
+const TABLE = [
+    0x0000, 0xc0c1, 0xc181, 0x0140, 0xc301, 0x03c0, 0x0280, 0xc241, 0xc601, 0x06c0, 0x0780, 0xc741, 0x0500, 0xc5c1, 0xc481, 0x0440, 0xcc01,
+    0x0cc0, 0x0d80, 0xcd41, 0x0f00, 0xcfc1, 0xce81, 0x0e40, 0x0a00, 0xcac1, 0xcb81, 0x0b40, 0xc901, 0x09c0, 0x0880, 0xc841, 0xd801, 0x18c0,
+    0x1980, 0xd941, 0x1b00, 0xdbc1, 0xda81, 0x1a40, 0x1e00, 0xdec1, 0xdf81, 0x1f40, 0xdd01, 0x1dc0, 0x1c80, 0xdc41, 0x1400, 0xd4c1, 0xd581,
+    0x1540, 0xd701, 0x17c0, 0x1680, 0xd641, 0xd201, 0x12c0, 0x1380, 0xd341, 0x1100, 0xd1c1, 0xd081, 0x1040, 0xf001, 0x30c0, 0x3180, 0xf141,
+    0x3300, 0xf3c1, 0xf281, 0x3240, 0x3600, 0xf6c1, 0xf781, 0x3740, 0xf501, 0x35c0, 0x3480, 0xf441, 0x3c00, 0xfcc1, 0xfd81, 0x3d40, 0xff01,
+    0x3fc0, 0x3e80, 0xfe41, 0xfa01, 0x3ac0, 0x3b80, 0xfb41, 0x3900, 0xf9c1, 0xf881, 0x3840, 0x2800, 0xe8c1, 0xe981, 0x2940, 0xeb01, 0x2bc0,
+    0x2a80, 0xea41, 0xee01, 0x2ec0, 0x2f80, 0xef41, 0x2d00, 0xedc1, 0xec81, 0x2c40, 0xe401, 0x24c0, 0x2580, 0xe541, 0x2700, 0xe7c1, 0xe681,
+    0x2640, 0x2200, 0xe2c1, 0xe381, 0x2340, 0xe101, 0x21c0, 0x2080, 0xe041, 0xa001, 0x60c0, 0x6180, 0xa141, 0x6300, 0xa3c1, 0xa281, 0x6240,
+    0x6600, 0xa6c1, 0xa781, 0x6740, 0xa501, 0x65c0, 0x6480, 0xa441, 0x6c00, 0xacc1, 0xad81, 0x6d40, 0xaf01, 0x6fc0, 0x6e80, 0xae41, 0xaa01,
+    0x6ac0, 0x6b80, 0xab41, 0x6900, 0xa9c1, 0xa881, 0x6840, 0x7800, 0xb8c1, 0xb981, 0x7940, 0xbb01, 0x7bc0, 0x7a80, 0xba41, 0xbe01, 0x7ec0,
+    0x7f80, 0xbf41, 0x7d00, 0xbdc1, 0xbc81, 0x7c40, 0xb401, 0x74c0, 0x7580, 0xb541, 0x7700, 0xb7c1, 0xb681, 0x7640, 0x7200, 0xb2c1, 0xb381,
+    0x7340, 0xb101, 0x71c0, 0x7080, 0xb041, 0x5000, 0x90c1, 0x9181, 0x5140, 0x9301, 0x53c0, 0x5280, 0x9241, 0x9601, 0x56c0, 0x5780, 0x9741,
+    0x5500, 0x95c1, 0x9481, 0x5440, 0x9c01, 0x5cc0, 0x5d80, 0x9d41, 0x5f00, 0x9fc1, 0x9e81, 0x5e40, 0x5a00, 0x9ac1, 0x9b81, 0x5b40, 0x9901,
+    0x59c0, 0x5880, 0x9841, 0x8801, 0x48c0, 0x4980, 0x8941, 0x4b00, 0x8bc1, 0x8a81, 0x4a40, 0x4e00, 0x8ec1, 0x8f81, 0x4f40, 0x8d01, 0x4dc0,
+    0x4c80, 0x8c41, 0x4400, 0x84c1, 0x8581, 0x4540, 0x8701, 0x47c0, 0x4680, 0x8641, 0x8201, 0x42c0, 0x4380, 0x8341, 0x4100, 0x81c1, 0x8081,
+    0x4040,
+];
+function crc(data, start = 0, end = data.length) {
+    let crc = 0xffff;
+    for (let index = start; index < end; index++) {
+        crc = (TABLE[(crc ^ data[index]) & 0xff] ^ (crc >> 8)) & 0xffff;
+    }
+    return crc;
+}
+
+/**
+ * Returns true when `n` is an integer in the unsigned-byte range [0, 255].
+ *
+ * Used for byte-level Modbus payload validation (function-code values, raw
+ * byte arrays in FC17/FC43 responses) — rejects negative, fractional, NaN,
+ * Infinity, and out-of-range values uniformly.
+ */
+function isUint8(n) {
+    return Number.isInteger(n) && n >= 0 && n <= 255;
+}
+
+function lrc(data, start = 0, end = data.length) {
+    let sum = 0;
+    for (let i = start; i < end; i++) {
+        sum += data[i];
+    }
+    return (~sum + 1) & 0xff;
+}
+
+/**
+ * Standard Modbus function codes (V1.1b3 §6).
+ */
+var FunctionCode;
+(function (FunctionCode) {
+    FunctionCode[FunctionCode["READ_COILS"] = 1] = "READ_COILS";
+    FunctionCode[FunctionCode["READ_DISCRETE_INPUTS"] = 2] = "READ_DISCRETE_INPUTS";
+    FunctionCode[FunctionCode["READ_HOLDING_REGISTERS"] = 3] = "READ_HOLDING_REGISTERS";
+    FunctionCode[FunctionCode["READ_INPUT_REGISTERS"] = 4] = "READ_INPUT_REGISTERS";
+    FunctionCode[FunctionCode["WRITE_SINGLE_COIL"] = 5] = "WRITE_SINGLE_COIL";
+    FunctionCode[FunctionCode["WRITE_SINGLE_REGISTER"] = 6] = "WRITE_SINGLE_REGISTER";
+    FunctionCode[FunctionCode["WRITE_MULTIPLE_COILS"] = 15] = "WRITE_MULTIPLE_COILS";
+    FunctionCode[FunctionCode["WRITE_MULTIPLE_REGISTERS"] = 16] = "WRITE_MULTIPLE_REGISTERS";
+    FunctionCode[FunctionCode["REPORT_SERVER_ID"] = 17] = "REPORT_SERVER_ID";
+    FunctionCode[FunctionCode["MASK_WRITE_REGISTER"] = 22] = "MASK_WRITE_REGISTER";
+    FunctionCode[FunctionCode["READ_WRITE_MULTIPLE_REGISTERS"] = 23] = "READ_WRITE_MULTIPLE_REGISTERS";
+    FunctionCode[FunctionCode["READ_DEVICE_IDENTIFICATION"] = 43] = "READ_DEVICE_IDENTIFICATION";
+})(FunctionCode || (FunctionCode = {}));
+/** Exception response FC = request FC | EXCEPTION_OFFSET (V1.1b3 §7). */
+const EXCEPTION_OFFSET = 0x80;
+/** FC 0x2B MEI sub-function selecting Read Device Identification (V1.1b3 §6.21). */
+const MEI_READ_DEVICE_ID = 0x0e;
+/** Read Device ID code values inside an FC 0x2B / MEI 0x0E request. */
+var ReadDeviceIDCode;
+(function (ReadDeviceIDCode) {
+    ReadDeviceIDCode[ReadDeviceIDCode["BASIC_STREAM"] = 1] = "BASIC_STREAM";
+    ReadDeviceIDCode[ReadDeviceIDCode["REGULAR_STREAM"] = 2] = "REGULAR_STREAM";
+    ReadDeviceIDCode[ReadDeviceIDCode["EXTENDED_STREAM"] = 3] = "EXTENDED_STREAM";
+    ReadDeviceIDCode[ReadDeviceIDCode["SPECIFIC_ACCESS"] = 4] = "SPECIFIC_ACCESS";
+})(ReadDeviceIDCode || (ReadDeviceIDCode = {}));
+/** Conformity level reported in an FC 0x2B / MEI 0x0E response. */
+var ConformityLevel;
+(function (ConformityLevel) {
+    ConformityLevel[ConformityLevel["BASIC"] = 129] = "BASIC";
+    ConformityLevel[ConformityLevel["REGULAR"] = 130] = "REGULAR";
+    ConformityLevel[ConformityLevel["EXTENDED"] = 131] = "EXTENDED";
+})(ConformityLevel || (ConformityLevel = {}));
+/** Shared empty Buffer to avoid repeated allocations. */
+Buffer.alloc(0);
+
+const REQUEST_FIXED_LENGTHS = {
+    [FunctionCode.READ_COILS]: 8,
+    [FunctionCode.READ_DISCRETE_INPUTS]: 8,
+    [FunctionCode.READ_HOLDING_REGISTERS]: 8,
+    [FunctionCode.READ_INPUT_REGISTERS]: 8,
+    [FunctionCode.WRITE_SINGLE_COIL]: 8,
+    [FunctionCode.WRITE_SINGLE_REGISTER]: 8,
+    [FunctionCode.REPORT_SERVER_ID]: 4,
+    [FunctionCode.MASK_WRITE_REGISTER]: 10,
+    [FunctionCode.READ_DEVICE_IDENTIFICATION]: 7,
+};
+const REQUEST_BYTE_COUNT = {
+    [FunctionCode.WRITE_MULTIPLE_COILS]: { offset: 6, extra: 9 },
+    [FunctionCode.WRITE_MULTIPLE_REGISTERS]: { offset: 6, extra: 9 },
+    [FunctionCode.READ_WRITE_MULTIPLE_REGISTERS]: { offset: 10, extra: 13 },
+};
+const RESPONSE_FIXED_LENGTHS = {
+    [FunctionCode.WRITE_SINGLE_COIL]: 8,
+    [FunctionCode.WRITE_SINGLE_REGISTER]: 8,
+    [FunctionCode.WRITE_MULTIPLE_COILS]: 8,
+    [FunctionCode.WRITE_MULTIPLE_REGISTERS]: 8,
+    [FunctionCode.MASK_WRITE_REGISTER]: 10,
+};
+const RESPONSE_BYTE_COUNT = {
+    [FunctionCode.READ_COILS]: { offset: 2, extra: 5 },
+    [FunctionCode.READ_DISCRETE_INPUTS]: { offset: 2, extra: 5 },
+    [FunctionCode.READ_HOLDING_REGISTERS]: { offset: 2, extra: 5 },
+    [FunctionCode.READ_INPUT_REGISTERS]: { offset: 2, extra: 5 },
+    [FunctionCode.REPORT_SERVER_ID]: { offset: 2, extra: 5 },
+    [FunctionCode.READ_WRITE_MULTIPLE_REGISTERS]: { offset: 2, extra: 5 },
+};
+/** Sentinel: caller needs to feed more bytes before length can be determined. */
+const PREDICT_NEED_MORE = 0;
+/** Sentinel: function code is not in the standard tables. */
+const PREDICT_UNKNOWN = -1;
+/**
+ * Predict the total RTU frame length (PDU + 2-byte CRC) given the leading bytes.
+ *
+ * Returns a sentinel-encoded number to avoid per-call object allocation on the
+ * RTU decode hot path:
+ * - Positive integer (>= 4): total frame length, function code is known.
+ * - {@link PREDICT_NEED_MORE} (0): function code is known but more bytes are
+ *   required (typically waiting on the byteCount byte).
+ * - {@link PREDICT_UNKNOWN} (-1): function code is not in the standard tables —
+ *   the framing layer must defer to a registered `CustomFunctionCode` or treat
+ *   this as a framing error.
+ */
+function predictRtuFrameLength(buffer, start, end, isResponse) {
+    if (end - start < 2) {
+        return PREDICT_NEED_MORE;
+    }
+    const fc = buffer[start + 1];
+    if (isResponse && (fc & EXCEPTION_OFFSET) !== 0) {
+        return 5;
+    }
+    const fixed = (isResponse ? RESPONSE_FIXED_LENGTHS : REQUEST_FIXED_LENGTHS)[fc];
+    if (fixed !== undefined) {
+        return fixed;
+    }
+    const bc = (isResponse ? RESPONSE_BYTE_COUNT : REQUEST_BYTE_COUNT)[fc];
+    if (bc !== undefined) {
+        if (end - start <= bc.offset) {
+            return PREDICT_NEED_MORE;
+        }
+        return bc.extra + buffer[start + bc.offset];
+    }
+    if (isResponse && fc === FunctionCode.READ_DEVICE_IDENTIFICATION) {
+        return predictFc43_14Response(buffer, start, end);
+    }
+    return PREDICT_UNKNOWN;
+}
+/**
+ * Walk the variable-length FC 0x2B / MEI 0x0E (Read Device Identification)
+ * response structure per Modbus V1.1b3 §6.21.
+ *
+ * Layout (after unit and fc):
+ *   mei(1) rdic(1) conformity(1) more(1) nextObjId(1) numObjs(1)
+ *   [objId(1) objLen(1) objData(objLen)] × numObjs
+ *   CRC(2)
+ */
+function predictFc43_14Response(buffer, start, end) {
+    if (end - start < 8) {
+        return PREDICT_NEED_MORE;
+    }
+    if (buffer[start + 2] !== MEI_READ_DEVICE_ID) {
+        return PREDICT_UNKNOWN;
+    }
+    const numObjs = buffer[start + 7];
+    let cursor = start + 8;
+    for (let i = 0; i < numObjs; i++) {
+        if (end < cursor + 2) {
+            return PREDICT_NEED_MORE;
+        }
+        const objLen = buffer[cursor + 1];
+        cursor += 2 + objLen;
+    }
+    return cursor - start + 2;
+}
+
+/**
+ * Convert a callback-style `(cb: (err?) => void) => void` call into a Promise.
+ */
+function promisifyCb(fn) {
+    return new Promise((resolve, reject) => {
+        fn((err) => {
+            if (err)
+                reject(err);
+            else
+                resolve();
+        });
+    });
+}
+
+/**
+ * Resolve a single RTU timing parameter to milliseconds.
+ *
+ * Returns `undefined` when the caller did not supply the parameter at all
+ * (so the caller knows to fall back to a spec default). An explicit `0` or
+ * `{ value: 0 }` returns `0` — the parameter is set, just disabled.
+ */
+function resolveOne(value, baudRate, fastBaudMs) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value === 'number') {
+        return value;
+    }
+    if (value.unit === 'ms') {
+        return value.value;
+    }
+    // unit === 'bit' — needs baudRate to convert
+    if (baudRate === undefined) {
+        return undefined;
+    }
+    return baudRate > 19200 ? fastBaudMs : Math.ceil(bitsToMs(baudRate, value.value));
+}
+/**
+ * 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. Pass `0` to disable.
+ * - `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.
+ */
+function resolveRtuTiming(opts = {}, baudRate) {
+    let intervalBetweenFrames = resolveOne(opts.intervalBetweenFrames, baudRate, 1.75);
+    if (intervalBetweenFrames === undefined) {
+        // Spec default: t3.5 derived from baudRate, or 0 when neither option nor
+        // baudRate were supplied.
+        intervalBetweenFrames = baudRate !== undefined ? (baudRate > 19200 ? 1.75 : Math.ceil(bitsToMs(baudRate, 38.5))) : 0;
+    }
+    let interCharTimeout = resolveOne(opts.interCharTimeout, baudRate, 0.75);
+    if (interCharTimeout === undefined) {
+        // t1.5 is opt-in — no spec-default fallback.
+        interCharTimeout = 0;
+    }
+    return { intervalBetweenFrames, interCharTimeout };
+}
+
+/** @internal
+ * Zero-allocation binary min-heap for coalescing per-request timeouts.
+ *
+ * Uses two parallel numeric arrays (no object allocation per entry).
+ * Lazy deletion: callers never remove from the heap; expired entries
+ * are silently dropped when they surface at the top.
+ */
+class TimerHeap {
+    _deadlines = [];
+    _ids = [];
+    _timer = null;
+    _onFire;
+    /** Pre-bound tick handler to avoid creating a new arrow function on every setTimeout. */
+    _boundTick;
+    constructor(onFire) {
+        this._onFire = onFire;
+        this._boundTick = this._onTick.bind(this);
+    }
+    /** Number of pending timers in the heap. */
+    get size() {
+        return this._deadlines.length;
+    }
+    /** Schedule an entry. If it becomes the new top, the global timer is re-scheduled (pre-emption). */
+    add(id, ms) {
+        const deadline = performance.now() + ms;
+        let i = this._deadlines.length;
+        this._deadlines.push(deadline);
+        this._ids.push(id);
+        // sift up
+        while (i > 0) {
+            const p = (i - 1) >> 1;
+            if (this._deadlines[p] <= deadline)
+                break;
+            this._deadlines[i] = this._deadlines[p];
+            this._ids[i] = this._ids[p];
+            i = p;
+        }
+        this._deadlines[i] = deadline;
+        this._ids[i] = id;
+        // Only reschedule when the new entry became the heap top.
+        if (i === 0)
+            this._refresh();
+    }
+    /** Dispose without firing callbacks. */
+    clear() {
+        if (this._timer) {
+            clearTimeout(this._timer);
+            this._timer = null;
+        }
+        this._deadlines.length = 0;
+        this._ids.length = 0;
+    }
+    _refresh() {
+        if (this._timer) {
+            clearTimeout(this._timer);
+            this._timer = null;
+        }
+        if (this._deadlines.length === 0)
+            return;
+        const delay = Math.max(0, Math.ceil(this._deadlines[0] - performance.now()));
+        this._timer = setTimeout(this._boundTick, delay);
+    }
+    _onTick() {
+        this._timer = null;
+        const now = performance.now();
+        while (this._deadlines.length > 0 && this._deadlines[0] <= now) {
+            const id = this._pop();
+            this._onFire(id);
+        }
+        this._refresh();
+    }
+    /** Pop and return the id with the earliest deadline. Assumes heap is non-empty. */
+    _pop() {
+        const topId = this._ids[0];
+        const lastId = this._ids.pop();
+        const lastDeadline = this._deadlines.pop();
+        const n = this._deadlines.length;
+        if (n > 0) {
+            let i = 0;
+            // sift down
+            while (true) {
+                let min = i;
+                const l = i * 2 + 1;
+                const r = l + 1;
+                if (l < n && this._deadlines[l] < this._deadlines[min])
+                    min = l;
+                if (r < n && this._deadlines[r] < this._deadlines[min])
+                    min = r;
+                if (min === i)
+                    break;
+                this._deadlines[i] = this._deadlines[min];
+                this._ids[i] = this._ids[min];
+                i = min;
+            }
+            this._deadlines[i] = lastDeadline;
+            this._ids[i] = lastId;
+        }
+        return topId;
+    }
+}
+
+/**
+ * Normalize an IP address by stripping the IPv4-mapped IPv6 prefix.
+ * This ensures consistent comparison of addresses like `::ffff:192.168.1.1`.
+ */
+function normalizeAddress(address = '') {
+    return address.replace(/^::ffff:/, '');
+}
+/**
+ * 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.
+ */
+function isWhitelisted(address, whitelist) {
+    if (!whitelist || whitelist.length === 0) {
+        return true;
+    }
+    const normalized = normalizeAddress(address);
+    return whitelist.includes(normalized);
+}
+
+exports.PREDICT_NEED_MORE = PREDICT_NEED_MORE;
+exports.PREDICT_UNKNOWN = PREDICT_UNKNOWN;
+exports.TimerHeap = TimerHeap;
+exports.bitsToMs = bitsToMs;
+exports.checkRange = checkRange;
+exports.crc = crc;
+exports.drainCbs = drainCbs;
+exports.isUint8 = isUint8;
+exports.isWhitelisted = isWhitelisted;
+exports.lrc = lrc;
+exports.predictRtuFrameLength = predictRtuFrameLength;
+exports.promisifyCb = promisifyCb;
+exports.resolveRtuTiming = resolveRtuTiming;

package/dist/utils.d.ts

@@ -0,0 +1,161 @@
+/**
+ * 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;
+}
+/** Resolved RTU timing values in milliseconds. */
+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. Pass `0` to disable.
+ * - `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.
+ */
+declare function resolveRtuTiming(opts?: RtuProtocolOptions, baudRate?: number): ResolvedRtuTiming;
+
+/**
+ * Convert a number of bits to milliseconds at a given baud rate.
+ *
+ * Used to derive Modbus RTU timing intervals from bit counts — e.g. 38.5 bits
+ * = 3.5 character times at 11 bits/char (t3.5 inter-frame silence), or 16.5
+ * bits = 1.5 character times (t1.5 inter-character timeout), per Modbus V1.02
+ * §2.5.1.1.
+ *
+ * @param baudRate Serial port baud rate.
+ * @param bits Number of bits to convert.
+ * @returns Duration in milliseconds.
+ */
+declare function bitsToMs(baudRate: number, bits: number): number;
+
+/**
+ * Drain a pending-callback array: invoke each callback with the given error (or null).
+ *
+ * Handles `null`/`undefined` entries (from optional `cb?` parameters) gracefully.
+ * Used by physical layers and connections to resolve queued
+ * open / close / destroy callbacks.
+ */
+declare function drainCbs(cbs: (((err?: Error | null) => void) | undefined)[] | null, err?: Error | null): void;
+
+declare function checkRange(value: number | number[], range?: [number, number] | [number, number][]): boolean;
+
+declare function crc(data: Uint8Array, start?: number, end?: number): number;
+
+/**
+ * Returns true when `n` is an integer in the unsigned-byte range [0, 255].
+ *
+ * Used for byte-level Modbus payload validation (function-code values, raw
+ * byte arrays in FC17/FC43 responses) — rejects negative, fractional, NaN,
+ * Infinity, and out-of-range values uniformly.
+ */
+declare function isUint8(n: number): boolean;
+
+declare function lrc(data: Uint8Array, start?: number, end?: number): number;
+
+/** Sentinel: caller needs to feed more bytes before length can be determined. */
+declare const PREDICT_NEED_MORE = 0;
+/** Sentinel: function code is not in the standard tables. */
+declare const PREDICT_UNKNOWN = -1;
+/**
+ * Predict the total RTU frame length (PDU + 2-byte CRC) given the leading bytes.
+ *
+ * Returns a sentinel-encoded number to avoid per-call object allocation on the
+ * RTU decode hot path:
+ * - Positive integer (>= 4): total frame length, function code is known.
+ * - {@link PREDICT_NEED_MORE} (0): function code is known but more bytes are
+ *   required (typically waiting on the byteCount byte).
+ * - {@link PREDICT_UNKNOWN} (-1): function code is not in the standard tables —
+ *   the framing layer must defer to a registered `CustomFunctionCode` or treat
+ *   this as a framing error.
+ */
+declare function predictRtuFrameLength(buffer: Buffer, start: number, end: number, isResponse: boolean): number;
+
+/**
+ * Convert a callback-style `(cb: (err?) => void) => void` call into a Promise.
+ */
+declare function promisifyCb(fn: (cb: (err?: Error | null) => void) => void): Promise<void>;
+
+/** @internal
+ * Zero-allocation binary min-heap for coalescing per-request timeouts.
+ *
+ * Uses two parallel numeric arrays (no object allocation per entry).
+ * Lazy deletion: callers never remove from the heap; expired entries
+ * are silently dropped when they surface at the top.
+ */
+declare class TimerHeap {
+    private _deadlines;
+    private _ids;
+    private _timer;
+    private _onFire;
+    /** Pre-bound tick handler to avoid creating a new arrow function on every setTimeout. */
+    private _boundTick;
+    constructor(onFire: (id: number) => void);
+    /** Number of pending timers in the heap. */
+    get size(): number;
+    /** Schedule an entry. If it becomes the new top, the global timer is re-scheduled (pre-emption). */
+    add(id: number, ms: number): void;
+    /** Dispose without firing callbacks. */
+    clear(): void;
+    private _refresh;
+    private _onTick;
+    /** Pop and return the id with the earliest deadline. Assumes heap is non-empty. */
+    private _pop;
+}
+
+/**
+ * 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.
+ */
+declare function isWhitelisted(address: string | undefined, whitelist: string[] | undefined): boolean;
+
+export { PREDICT_NEED_MORE, PREDICT_UNKNOWN, TimerHeap, bitsToMs, checkRange, crc, drainCbs, isUint8, isWhitelisted, lrc, predictRtuFrameLength, promisifyCb, resolveRtuTiming };
+export type { ResolvedRtuTiming, RtuProtocolOptions };