njs-modbus 3.2.0 → 3.3.0

package/dist/utils.cjs

@@ -24,40 +24,75 @@ function bitsToMs(baudRate, bits) {
  * open / close / destroy callbacks.
  */
 function drainCbs(cbs, err) {
-    if (!cbs)
+    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]))) {
+    const isMultiRange = Array.isArray(range[0]);
+    const isValueArray = Array.isArray(value);
+    if (!isValueArray && !isMultiRange) {
+        const r = range;
+        const min = r[0], max = r[1];
+        const v = value;
+        return min <= max ? v >= min && v <= max : v >= max && v <= min;
+    }
+    if (!isValueArray && isMultiRange) {
+        const ranges = range;
+        const v = value;
+        for (let i = 0; i < ranges.length; i++) {
+            const min = ranges[i][0], max = ranges[i][1];
+            const lo = min <= max ? min : max;
+            const hi = min <= max ? max : min;
+            if (v >= lo && v <= 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 values = value;
+    if (values.length === 0) {
+        return true;
+    }
+    if (!isMultiRange) {
+        const r = range;
+        const min = r[0], max = r[1];
+        const lo = min <= max ? min : max;
+        const hi = min <= max ? max : min;
+        for (let i = 0; i < values.length; i++) {
+            if (values[i] < lo || values[i] > hi) {
+                return false;
+            }
+        }
+        return true;
+    }
+    const ranges = range;
+    for (let i = 0; i < ranges.length; i++) {
+        const min = ranges[i][0], max = ranges[i][1];
+        const lo = min <= max ? min : max;
+        const hi = min <= max ? max : min;
+        let allInRange = true;
+        for (let j = 0; j < values.length; j++) {
+            if (values[j] < lo || values[j] > hi) {
+                allInRange = false;
+                break;
+            }
+        }
+        if (allInRange) {
+            return true;
+        }
+    }
+    return false;
 }
 
-const TABLE = [
+const TABLE = new Uint16Array([
     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,
@@ -74,11 +109,11 @@ const TABLE = [
     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) {
+]);
+function crc(data, start, end) {
     let crc = 0xffff;
     for (let index = start; index < end; index++) {
-        crc = (TABLE[(crc ^ data[index]) & 0xff] ^ (crc >> 8)) & 0xffff;
+        crc = TABLE[(crc ^ data[index]) & 0xff] ^ (crc >> 8);
     }
     return crc;
 }
@@ -91,15 +126,15 @@ function crc(data, start = 0, end = data.length) {
  * Infinity, and out-of-range values uniformly.
  */
 function isUint8(n) {
-    return Number.isInteger(n) && n >= 0 && n <= 255;
+    return (n & 0xff) === n;
 }
 
-function lrc(data, start = 0, end = data.length) {
+function lrc(data, start, end) {
     let sum = 0;
     for (let i = start; i < end; i++) {
         sum += data[i];
     }
-    return (~sum + 1) & 0xff;
+    return -sum & 0xff;
 }
 
 /**
@@ -142,103 +177,93 @@ var 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.
- */
+const REQ_TABLE = new Int32Array(256);
+const RES_TABLE = new Int32Array(256);
+(function initTables() {
+    REQ_TABLE[FunctionCode.READ_COILS] = 8;
+    REQ_TABLE[FunctionCode.READ_DISCRETE_INPUTS] = 8;
+    REQ_TABLE[FunctionCode.READ_HOLDING_REGISTERS] = 8;
+    REQ_TABLE[FunctionCode.READ_INPUT_REGISTERS] = 8;
+    REQ_TABLE[FunctionCode.WRITE_SINGLE_COIL] = 8;
+    REQ_TABLE[FunctionCode.WRITE_SINGLE_REGISTER] = 8;
+    REQ_TABLE[FunctionCode.REPORT_SERVER_ID] = 4;
+    REQ_TABLE[FunctionCode.MASK_WRITE_REGISTER] = 10;
+    REQ_TABLE[FunctionCode.READ_DEVICE_IDENTIFICATION] = 7;
+    REQ_TABLE[FunctionCode.WRITE_MULTIPLE_COILS] = -1545;
+    REQ_TABLE[FunctionCode.WRITE_MULTIPLE_REGISTERS] = -1545;
+    REQ_TABLE[FunctionCode.READ_WRITE_MULTIPLE_REGISTERS] = -2573;
+    RES_TABLE[FunctionCode.WRITE_SINGLE_COIL] = 8;
+    RES_TABLE[FunctionCode.WRITE_SINGLE_REGISTER] = 8;
+    RES_TABLE[FunctionCode.WRITE_MULTIPLE_COILS] = 8;
+    RES_TABLE[FunctionCode.WRITE_MULTIPLE_REGISTERS] = 8;
+    RES_TABLE[FunctionCode.MASK_WRITE_REGISTER] = 10;
+    RES_TABLE[FunctionCode.READ_COILS] = -517;
+    RES_TABLE[FunctionCode.READ_DISCRETE_INPUTS] = -517;
+    RES_TABLE[FunctionCode.READ_HOLDING_REGISTERS] = -517;
+    RES_TABLE[FunctionCode.READ_INPUT_REGISTERS] = -517;
+    RES_TABLE[FunctionCode.REPORT_SERVER_ID] = -517;
+    RES_TABLE[FunctionCode.READ_WRITE_MULTIPLE_REGISTERS] = -517;
+    RES_TABLE[FunctionCode.READ_DEVICE_IDENTIFICATION] = -999;
+})();
 function predictRtuFrameLength(buffer, start, end, isResponse) {
-    if (end - start < 2) {
+    const len = end - start;
+    if (len < 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;
+    if (isResponse) {
+        if ((fc & EXCEPTION_OFFSET) !== 0) {
+            return 5;
+        }
+        const val = RES_TABLE[fc];
+        if (val > 0) {
+            return val;
+        }
+        if (val < 0) {
+            if (val === -999) {
+                // FC 43 / MEI 14 response — inline to avoid function-call overhead on
+                // the framing hot path (even though this FC is uncommon).
+                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;
+                    }
+                    cursor += 2 + buffer[cursor + 1];
+                }
+                return cursor - start + 2;
+            }
+            const decode = -val;
+            const offset = decode >> 8;
+            if (len <= offset) {
+                return PREDICT_NEED_MORE;
+            }
+            return (decode & 0xff) + buffer[start + offset];
         }
-        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;
+    else {
+        const val = REQ_TABLE[fc];
+        if (val > 0) {
+            return val;
+        }
+        if (val < 0) {
+            const decode = -val;
+            const offset = decode >> 8;
+            if (len <= offset) {
+                return PREDICT_NEED_MORE;
+            }
+            return (decode & 0xff) + buffer[start + offset];
         }
-        const objLen = buffer[cursor + 1];
-        cursor += 2 + objLen;
     }
-    return cursor - start + 2;
+    return PREDICT_UNKNOWN;
 }
 
 /**
@@ -247,10 +272,12 @@ function predictFc43_14Response(buffer, start, end) {
 function promisifyCb(fn) {
     return new Promise((resolve, reject) => {
         fn((err) => {
-            if (err)
+            if (err) {
                 reject(err);
-            else
+            }
+            else {
                 resolve();
+            }
         });
     });
 }
@@ -303,102 +330,172 @@ function resolveRtuTiming(opts = {}, baudRate) {
     return { intervalBetweenFrames, interCharTimeout };
 }
 
-/** @internal
- * Zero-allocation binary min-heap for coalescing per-request timeouts.
+/**
+ * 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[]
  *
- * 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.
+ * 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.
  */
 class TimerHeap {
     _deadlines = [];
     _ids = [];
+    _seqs = [];
+    _counter = 0;
     _timer = null;
     _onFire;
-    /** Pre-bound tick handler to avoid creating a new arrow function on every setTimeout. */
     _boundTick;
-    constructor(onFire) {
+    _threshold;
+    _mode = 'direct';
+    _directTimers = new Map();
+    /**
+     * @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, concurrentThreshold = 2) {
         this._onFire = onFire;
         this._boundTick = this._onTick.bind(this);
+        this._threshold = concurrentThreshold;
     }
-    /** Number of pending timers in the heap. */
     get size() {
-        return this._deadlines.length;
+        return this._mode === 'direct' ? this._directTimers.size : this._deadlines.length;
     }
-    /** Schedule an entry. If it becomes the new top, the global timer is re-scheduled (pre-emption). */
     add(id, ms) {
+        if (this._mode === 'direct' && this._directTimers.size + 1 <= this._threshold) {
+            const deadline = performance.now() + ms;
+            const handle = setTimeout(() => {
+                if (this._mode !== 'direct') {
+                    return;
+                }
+                this._directTimers.delete(id);
+                this._onFire(id);
+            }, ms);
+            this._directTimers.set(id, { handle, deadline });
+            return;
+        }
+        if (this._mode === 'direct') {
+            this._mode = 'heap';
+            for (const [existingId, { handle, deadline }] of this._directTimers) {
+                clearTimeout(handle);
+                const remaining = Math.max(0, Math.ceil(deadline - performance.now()));
+                if (remaining === 0) {
+                    this._onFire(existingId);
+                }
+                else {
+                    this._heapAdd(existingId, remaining);
+                }
+            }
+            this._directTimers.clear();
+        }
+        this._heapAdd(id, ms);
+    }
+    clear() {
+        for (const { handle } of this._directTimers.values()) {
+            clearTimeout(handle);
+        }
+        this._directTimers.clear();
+        this._mode = 'direct';
+        if (this._timer) {
+            clearTimeout(this._timer);
+            this._timer = null;
+        }
+        this._deadlines.length = 0;
+        this._ids.length = 0;
+        this._seqs.length = 0;
+        this._counter = 0;
+    }
+    _heapAdd(id, ms) {
         const deadline = performance.now() + ms;
+        const seq = this._counter++;
         let i = this._deadlines.length;
         this._deadlines.push(deadline);
         this._ids.push(id);
-        // sift up
+        this._seqs.push(seq);
         while (i > 0) {
             const p = (i - 1) >> 1;
-            if (this._deadlines[p] <= deadline)
+            const parentComesFirst = this._deadlines[p] < deadline || (this._deadlines[p] === deadline && this._seqs[p] < seq);
+            if (parentComesFirst) {
                 break;
+            }
             this._deadlines[i] = this._deadlines[p];
             this._ids[i] = this._ids[p];
+            this._seqs[i] = this._seqs[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._seqs[i] = seq;
+        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)
+        if (this._deadlines.length === 0) {
             return;
+        }
         const delay = Math.max(0, Math.ceil(this._deadlines[0] - performance.now()));
-        this._timer = setTimeout(this._boundTick, delay);
+        const safeDelay = Math.min(delay, 2147483647);
+        this._timer = setTimeout(this._boundTick, safeDelay);
     }
     _onTick() {
         this._timer = null;
         const now = performance.now();
-        while (this._deadlines.length > 0 && this._deadlines[0] <= now) {
-            const id = this._pop();
-            this._onFire(id);
+        try {
+            while (this._deadlines.length > 0 && this._deadlines[0] <= now) {
+                const id = this._pop();
+                this._onFire(id);
+            }
+        }
+        finally {
+            this._refresh();
         }
-        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 lastSeq = this._seqs.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)
+            const half = n >> 1;
+            while (i < half) {
+                let minChild = (i << 1) + 1;
+                const rightChild = minChild + 1;
+                if (rightChild < n) {
+                    const rightComesFirst = this._deadlines[rightChild] < this._deadlines[minChild] ||
+                        (this._deadlines[rightChild] === this._deadlines[minChild] && this._seqs[rightChild] < this._seqs[minChild]);
+                    if (rightComesFirst) {
+                        minChild = rightChild;
+                    }
+                }
+                const lastComesFirst = lastDeadline < this._deadlines[minChild] || (lastDeadline === this._deadlines[minChild] && lastSeq < this._seqs[minChild]);
+                if (lastComesFirst) {
                     break;
-                this._deadlines[i] = this._deadlines[min];
-                this._ids[i] = this._ids[min];
-                i = min;
+                }
+                this._deadlines[i] = this._deadlines[minChild];
+                this._ids[i] = this._ids[minChild];
+                this._seqs[i] = this._seqs[minChild];
+                i = minChild;
             }
             this._deadlines[i] = lastDeadline;
             this._ids[i] = lastId;
+            this._seqs[i] = lastSeq;
         }
         return topId;
     }

package/dist/utils.d.ts

@@ -87,7 +87,7 @@ declare function drainCbs(cbs: (((err?: Error | null) => void) | undefined)[] |
 
 declare function checkRange(value: number | number[], range?: [number, number] | [number, number][]): boolean;
 
-declare function crc(data: Uint8Array, start?: number, end?: number): number;
+declare function crc(data: Uint8Array, start: number, end: number): number;
 
 /**
  * Returns true when `n` is an integer in the unsigned-byte range [0, 255].
@@ -98,24 +98,10 @@ declare function crc(data: Uint8Array, start?: number, end?: number): number;
  */
 declare function isUint8(n: number): boolean;
 
-declare function lrc(data: Uint8Array, start?: number, end?: number): number;
+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;
 
 /**
@@ -123,30 +109,46 @@ declare function predictRtuFrameLength(buffer: Buffer, start: number, end: numbe
  */
 declare function promisifyCb(fn: (cb: (err?: Error | null) => void) => void): Promise<void>;
 
-/** @internal
- * Zero-allocation binary min-heap for coalescing per-request timeouts.
+/**
+ * Hybrid timer manager: uses native `setTimeout` for low concurrency
+ * and switches to a binary min-heap when concurrency exceeds the threshold.
  *
- * 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.
+ * 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;
-    /** 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. */
+    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;
-    /** 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 _heapAdd;
     private _refresh;
     private _onTick;
-    /** Pop and return the id with the earliest deadline. Assumes heap is non-empty. */
     private _pop;
 }