Skip to content

timers: allow setTimeout to accept a delay of 0 - #66155

Open
mcollina wants to merge 1 commit into
nodejs:mainfrom
mcollina:timers-set-timeout-zero-delay
Open

mcollina wants to merge 1 commit into
nodejs:mainfrom
mcollina:timers-set-timeout-zero-delay

Conversation

@mcollina

Copy link
Copy Markdown
Member

Summary

setTimeout() now accepts a delay of 0 (and positive sub-millisecond delays, which are truncated to 0 by insert()), scheduling the callback as soon as possible instead of silently clamping it to 1 ms. This matches browser (Chrome) behavior and resolves the ordering surprise described in #46596.

Negative delays, NaN, and values above TIMEOUT_MAX are still clamped to 1 ms with the existing warnings. setInterval() continues to clamp delays below 1 ms to 1 ms so it does not fire as fast as the event loop allows.

Behavior change

Before:

setTimeout(() => console.log('1st'), 1);
setTimeout(() => console.log('2nd'), 0);
// 1st
// 2nd

After (matches browsers):

setTimeout(() => console.log('1st'), 1);
setTimeout(() => console.log('2nd'), 0);
// 2nd
// 1st

Test plan

  • New test test/parallel/test-timers-zero-delay-ordering.js verifies setTimeout(fn, 0) runs before setTimeout(fn, 1) and that timers/promises.setTimeout(0) resolves.
  • All 72 test-timers* / mock-timers / promisified tests pass, plus a broader cross-subsystem subset (vm, worker, stream, http, net).

Refs: #46596

@nodejs-github-bot nodejs-github-bot added needs-ci PRs that need a full CI run. timers Issues and PRs related to timers, setImmediate(), setInterval(), and setTimeout(). labels Sep 20, 2026
@codecov

codecov Bot commented Sep 20, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.30%. Comparing base (ebef774) to head (8d92515).
⚠️ Report is 43 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff             @@
##             main   #66155      +/-   ##
==========================================
+ Coverage   90.28%   90.30%   +0.02%     
==========================================
  Files         790      790              
  Lines      271642   272051     +409     
  Branches    51846    51938      +92     
==========================================
+ Hits       245260   245686     +426     
+ Misses      16889    16879      -10     
+ Partials     9493     9486       -7     
Files with missing lines Coverage Δ
lib/internal/timers.js 100.00% <100.00%> (ø)

... and 63 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@jasnell

jasnell commented Sep 20, 2026

Copy link
Copy Markdown
Member

... as soon as possible

Does this mean at least one event loop turn or within an event loop turn?

@jasnell jasnell left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM once CI is green and the "as soon as possible" is clarified.

A setTimeout() delay of 0 (or a positive sub-millisecond delay, which
is truncated to 0 by insert()) is now scheduled as soon as possible
instead of being clamped to 1 ms, matching browser behavior. Negative
delays, NaN, and values above TIMEOUT_MAX are still clamped to 1 ms, and
setInterval() keeps clamping delays below 1 ms to 1 ms to avoid firing
as fast as the event loop allows.

Refs: nodejs#46596
PR-URL: nodejs#66155
Assisted-by: pi
Signed-off-by: Matteo Collina <matteo.collina@gmail.com>
@mcollina
mcollina force-pushed the timers-set-timeout-zero-delay branch from 1ddf9b2 to 8d92515 Compare September 21, 2026 05:34
const order = [];

setTimeout(common.mustCall(() => order.push('one')), 1);
setTimeout(common.mustCall(() => order.push('zero')), 0);

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the CI test failure.. was worried about this. The "as soon as possible" means that it's going to race against non-zero but very short deadline timers in some cases. Think we need to put some exact timing semantics around it.

[
+   'one',
    'zero',
-   'one'
  ]

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs-ci PRs that need a full CI run. timers Issues and PRs related to timers, setImmediate(), setInterval(), and setTimeout().

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants