timers: allow setTimeout to accept a delay of 0

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: #46596

Assisted-by: pi
Signed-off-by: Matteo Collina <matteo.collina@gmail.com>

Author: mcollina

doc/api/timers.md

@@ -276,8 +276,10 @@ 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.
 
-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.
+When `delay` is larger than `2147483647`, a negative number, or `NaN`, the
+`delay` will be set to `1`. A delay of `0` (or a positive sub-millisecond
+value, which is truncated to `0`) schedules the callback as soon as possible.
+Non-integer delays are truncated to an integer.
 
 If `callback` is not a function, a [`TypeError`][] will be thrown.
 

lib/internal/timers.js

@@ -239,7 +239,15 @@ class Timeout {
                             '\nTimeout duration was set to 1.',
                             'TimeoutNaNWarning');
       }
-      after = 1; // Schedule on next tick, follows browser behavior
+
+      // setTimeout() accepts a delay of 0 or a positive sub-millisecond
+      // delay, which is truncated to 0 by insert() and thus scheduled as
+      // soon as possible, matching browsers. Every other invalid delay (and
+      // every setInterval() delay below 1 ms, so it does not fire as fast as
+      // the event loop allows) is still clamped to 1 ms.
+      if (isRepeat || after < 0 || NumberIsNaN(after) || after > TIMEOUT_MAX) {
+        after = 1; // Schedule on next tick, follows browser behavior
+      }
     }
 
     this._idleTimeout = after;

test/parallel/test-timers-zero-delay-ordering.js

@@ -0,0 +1,25 @@
+'use strict';
+const common = require('../common');
+const assert = require('assert');
+
+// setTimeout with a delay of 0 should schedule the callback as soon as
+// possible, so that it runs before a timer scheduled with a 1 ms delay.
+// See https://github.com/nodejs/node/issues/46596
+
+const order = [];
+
+setTimeout(common.mustCall(() => order.push('one')), 1);
+setTimeout(common.mustCall(() => order.push('zero')), 0);
+
+setTimeout(common.mustCall(() => {
+  assert.deepStrictEqual(order, ['zero', 'one']);
+}), 2);
+
+// A zero-millisecond delay must still be allowed for the promisified variant.
+let resolved;
+const p = require('node:timers/promises').setTimeout(0);
+p.then(() => { resolved = true; });
+
+setTimeout(common.mustCall(() => {
+  assert.strictEqual(resolved, true);
+}), 2);

test/parallel/test-timers.js

@@ -65,8 +65,8 @@ inputs.forEach((value, index) => {
   }, value);
 });
 
-// All values in inputs array coerce to 1 ms. Therefore, they should all run
-// before a timer set here for 2 ms.
+// All values in inputs array coerce to a short delay (0 ms or 1 ms).
+// Therefore, they should all run before a timer set here for 2 ms.
 
 setTimeout(common.mustCall(() => {
   // Assert that all other timers have run