rules/util.md
GitHubnode:util additions
util.debounce(fn, wait[, options]) (v26.10.0, v24.22.0; not on v24.19)
The call returns a Promise for the value of fn. Every call made in one
window settles with the result of the single invocation, which receives the
last call's arguments. Verified: three calls save(1), save(2),
save(3) give fn(3) once, and all three promises resolve to its result.
| Option | Default | Effect |
|---|---|---|
leading |
false |
The first call of a window invokes fn immediately. A trailing invocation happens only if another call arrives within the window (verified: calls 1, 2, 3 invoke fn(1) and then fn(3), while a single call invokes only fn(1)) |
rejectOnCancel |
false |
Superseded calls reject with AbortError instead of sharing the result |
signal |
Aborting rejects pending and future calls with AbortError, with the reason in .cause. An already-aborted signal makes debounce() throw |
Properties of the returned function:
| Member | Effect |
|---|---|
cancel([reason]) |
Rejects the pending promises with AbortError, with cause = reason |
flush() |
Invokes fn now if a call is pending |
pending |
Promise of the latest call, or null |
pendingCount |
Number of calls waiting |
ref(), unref() |
Control whether the timer keeps the loop alive. Both return the function. Verified: after unref() the process exits and the pending promise never settles |
this inside fn is the debounced function. name and length are
preserved (verified).
util.throttle(fn, limit, interval[, options]) (v26.10.0, v24.22.0)
At most limit invocations start per interval ms. Extra calls queue by
default and keep their arguments. Verified: with limit 2 and interval
100, five calls start at about 0, 0, 100, 100 and 200 ms.
| Option | Default | Effect |
|---|---|---|
overflow |
'queue' |
'drop' rejects calls immediately when no capacity is available |
maxPending |
Infinity |
When the queue is full, new calls are rejected (only with 'queue') |
concurrency |
Infinity |
Maximum number of unsettled invocations. Capacity is released when the returned value settles |
strict |
false |
Per the docs, uses a rolling window instead of fixed windows (no bursts at window edges) |
signal |
Same as for debounce |
- Rejected calls (
'drop'or a fullmaxPending) reject withERR_THROTTLED. These promises are already marked handled, so ignoring them does not emitunhandledRejection. limitmust be an integer ≥ 1.throttle(fn, Infinity, ...)throwsERR_OUT_OF_RANGE(verified). For "concurrency only", use a large integerlimit.- Members:
cancel([reason])(rejects the queued calls, leaves started ones alone),hasImmediateCapacity(),pending,pendingCount,activeCount,ref()andunref(). - It does not retry or apply backoff. It only limits when invocations start.
util.markPromiseAsHandled(promise) (v26.10.0, v24.22.0)
Marks the promise so that a rejection does not emit
process.on('unhandledRejection'). Verified: the counter stays 0. Returns
undefined. This replaces p.catch(() => {}), which creates a new promise.
util.isPartialDeepStrictEqual(a, b) (v26.11.0; not on v24)
This is the boolean form of assert.partialDeepStrictEqual: only the
properties present in b are compared, strictly. Verified:
({ a: 1, b: { c: 2, d: 3 } }, { b: { c: 2 } })givestrue.({ a: 1 }, { a: '1' })givesfalse.- Arrays:
[1, 2, 3]vs[1, 3]givestrue(ordered subsequence), and vs[3, 1]givesfalse. - Sets:
new Set([1, 2])vsnew Set([2])givestrue.
util.isDeepStrictEqual(a, b, { skipPrototype }) (v24.9.0)
skipPrototype: true ignores prototype and constructor differences.
util.convertProcessSignalToExitCode(signal) (v25.4.0, v24.14.0)
Returns 128 + signal number, for example 'SIGTERM' → 143 and 'SIGINT' →
130. Unknown names and numbers throw ERR_INVALID_ARG_VALUE, so pass the
signal name. Use it to mirror a child's fate:
process.exitCode = child.status ?? convertProcessSignalToExitCode(child.signal).
util.styleText hex colors (v26.1.0, v24.16.0)
styleText('#f00', s)andstyleText('#ff5733', s)emit 24-bitESC[38;2;r;g;bm … ESC[39m.- They combine with modifiers:
styleText(['#00f', 'bold'], s). - Only
#RGBand#RRGGBBare accepted.#ffffor#gggthrowsERR_INVALID_ARG_VALUE. validateStreamdefaults totrue, which checksprocess.stdout(oroptions.stream) andNO_COLOR/FORCE_COLOR. Verified: when piped withoutFORCE_COLOR, the output is plain text, andFORCE_COLOR=3forces the escapes. An emptyFORCE_COLOR=also forced color in testing. Pass{ validateStream: false }to always emit.