njs-modbus 3.4.0 → 4.0.0

package/dist/utils.d.ts

@@ -1,164 +0,0 @@
-/**
- * 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;
-    /**
-     * Enforces strict Modbus RTU timing. When true, any frame containing a t1.5
-     * inter-character timeout event will be discarded immediately, even if the
-     * CRC16 is valid.
-     * @default false
-     */
-    strictTiming?: boolean;
-}
-/** 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 const CRC_TABLE: Uint16Array<ArrayBuffer>;
-/** CRC-16 (Modbus) over a single contiguous buffer. */
-declare function crcFixed(data: Uint8Array, start: number, end: number): number;
-/**
- * CRC-16 (Modbus) over two contiguous buffer segments.
- * Computes CRC(head[headOff:headOff+headLen]) followed by CRC(tail[tailOff:tailOff+tailLen]).
- */
-declare function crcDual(head: Uint8Array, headOff: number, headLen: number, tail: Uint8Array, tailOff: number, tailLen: number): number;
-
-declare function lrc(data: Uint8Array, start: number, end: number): number;
-
-declare const PREDICT_NEED_MORE = 0;
-declare const PREDICT_UNKNOWN = -1;
-declare const REQ_TABLE: Int32Array<ArrayBuffer>;
-declare const RES_TABLE: Int32Array<ArrayBuffer>;
-declare function predictRtuFrameLength(residual: Buffer, data: Buffer, residualLen: number, 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>;
-
-/**
- * Hybrid timer manager: uses native `setTimeout` for low concurrency
- * and switches to a binary min-heap when concurrency exceeds the threshold.
- *
- * Benchmarks (add + clear throughput, Node 24, x64):
- *   1 concurrent:  setTimeout ~1.7× faster than heap
- *   2 concurrent:  setTimeout ~1.6× faster than heap
- *   5 concurrent:  setTimeout ~1.5-1.9× faster than heap
- *  10 concurrent:  roughly equal
- *  20 concurrent:  heap ~1.3× faster than setTimeout[]
- *  50 concurrent:  heap ~1.4-1.7× faster than setTimeout[]
- *
- * The crossover point is around 10 concurrent timers, so the default
- * `concurrentThreshold = 2` keeps the common 1-2 request case on the
- * fast direct path while delegating to the heap for larger batches.
- */
-declare class TimerHeap {
-    private _deadlines;
-    private _ids;
-    private _seqs;
-    private _counter;
-    private _timer;
-    private _onFire;
-    private _boundTick;
-    private _threshold;
-    private _mode;
-    private _directTimers;
-    /**
-     * @param onFire  Callback invoked with the timer id when it expires.
-     * @param concurrentThreshold  Maximum number of timers kept as individual
-     *     native `setTimeout` handles. Once exceeded, all timers migrate to
-     *     the internal heap and share a single native timer. Default is 2.
-     */
-    constructor(onFire: (id: number) => void, concurrentThreshold?: number);
-    get size(): number;
-    add(id: number, ms: number): void;
-    clear(): void;
-    private _heapAdd;
-    private _refresh;
-    private _onTick;
-    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 { CRC_TABLE, PREDICT_NEED_MORE, PREDICT_UNKNOWN, REQ_TABLE, RES_TABLE, TimerHeap, bitsToMs, checkRange, crcDual, crcFixed, drainCbs, isWhitelisted, lrc, predictRtuFrameLength, promisifyCb, resolveRtuTiming };
-export type { ResolvedRtuTiming, RtuProtocolOptions };