From f9bfdeca25314429f4b16dbfd131ca7793a2b781 Mon Sep 17 00:00:00 2001 From: V Govindarajan Date: Fri, 27 Mar 2026 16:11:14 -0700 Subject: [PATCH] doc: clarify setTimeout millisecond precision behavior Document that timer delays are tracked with millisecond precision internally, and that callbacks may appear to fire up to 1ms early when measured with sub-millisecond clocks (process.hrtime(), performance.now()). This is caused by rounding at the millisecond boundary and is most noticeable when timers interact with setImmediate() or other I/O. Refs: https://github.com/nodejs/node/issues/26578 Signed-off-by: V Govindarajan --- doc/api/timers.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/doc/api/timers.md b/doc/api/timers.md index 7c91543c4573f7..88d7b8b9f7f2e2 100644 --- a/doc/api/timers.md +++ b/doc/api/timers.md @@ -276,6 +276,13 @@ Node.js makes no guarantees about the exact timing of when callbacks will fire, nor of their ordering. The callback will be called as close as possible to the time specified. +Timer delays are tracked with millisecond precision internally. When measured +with sub-millisecond clocks such as `process.hrtime()`, `process.hrtime.bigint()`, +or `performance.now()`, callbacks may appear to fire up to 1 ms earlier than the +requested delay due to rounding at the millisecond boundary. This is most +noticeable when timers are used together with `setImmediate()` or other I/O, +which can affect when the internal time is updated. + When `delay` is larger than `2147483647` or less than `1` or `NaN`, the `delay` will be set to `1`. Non-integer delays are truncated to an integer.