Timers

setTimeout

setTimeout(fn, delay) schedules fn to run as a macrotask after at least delay milliseconds. The delay is a minimum — not a guarantee. If the call stack is busy when the timer fires, the callback waits until the stack is clear.

Node clamps any delay below 1 ms up to 1 ms — a delay of 0 or a negative number both end up firing after about 1 ms (a negative delay also logs a TimeoutNegativeWarning). The commonly cited “4 ms minimum” figure is a browser rule for timers nested 5+ levels deep — it does not apply to Node’s setTimeout.

var id = setTimeout(function() {
  console.log('Runs after at least 100 ms');
}, 100);

// Cancel before it fires:
clearTimeout(id);

setInterval

setInterval(fn, delay) repeatedly schedules fn every delay ms. Use clearInterval to stop it.

var count = 0;
var id = setInterval(function() {
  count++;
  console.log('tick', count);
  if (count >= 3) clearInterval(id);
}, 500);

setTimeout with delay 0

setTimeout(fn, 0) does not mean “run immediately.” It queues fn as a macrotask. Any pending microtasks (Promise callbacks, queueMicrotask) will run first.

setTimeout(function() { console.log('Timer'); }, 0);
Promise.resolve().then(function() { console.log('Promise'); });
// Output: Promise, then Timer

queueMicrotask

To schedule a callback before the next macrotask, use queueMicrotask:

queueMicrotask(function() {
  console.log('This runs in the microtask queue, before any timer');
});

Runnable demo

This demo shows that setTimeout(fn, 0) still runs after a resolved Promise .then, because the timer callback is a macrotask and microtasks drain first.

JavaScript

// @browser
setTimeout(function() {
  console.log('Timer ran second');
}, 0);

Promise.resolve().then(function() {
  console.log('Promise ran first');
});

Output is always: Promise ran first, then Timer ran second.

Promise-based timers: timers/promises and AbortSignal.timeout

node:timers/promises gives you a Promise-returning setTimeout — no callback, so it composes naturally with await, Promise.race, and an AbortSignal. Passing { signal } lets you cancel the wait early instead of letting it run to completion:

Node.js

import { setTimeout as delay } from 'node:timers/promises';

console.log('waiting 30ms with timers/promises...');
await delay(30);
console.log('done waiting');

try {
  await delay(1000, undefined, { signal: AbortSignal.timeout(20) });
  console.log('this never prints');
} catch (err) {
  console.log('aborted:', err.name);
}

Output (verified on Node 24)

waiting 30ms with timers/promises...
done waiting
aborted: AbortError

AbortSignal.timeout(ms) returns a signal that aborts itself after ms — a compact way to say “give up after this long” without wiring your own setTimeout + AbortController pair by hand. It works anywhere a signal is accepted: timers/promises, fetch, and any of your own code that checks signal.aborted or listens for 'abort'.

Mental Model

Every timer API is a promise about a minimum wait, never an exact one: setTimeout/setInterval hand a callback to libuv’s timer phase, which only runs once the call stack is empty and every microtask has drained — the delay you pass is a floor, not a schedule. timers/promises’ setTimeout is the same underlying timer with a Promise wrapped around it instead of a callback, which is precisely why it can be cancelled with a signal (a callback has no way to say “never mind,” but a Promise can reject) — AbortSignal.timeout(ms) is just a pre-built signal that fires its own abort after ms, so you do not have to construct an AbortController and its own setTimeout by hand every time you need a deadline.

Trade-offs

The callback-based timers (setTimeout, setInterval) have no built-in way to say “give up waiting” — you track the ID yourself and call clearTimeout/clearInterval, and there is no equivalent for “stop waiting for this to resolve” once a callback has fired. The Promise-based timers/promises API costs one extra import and a signal object, but buys real cancellation and composes directly with Promise.race/Promise.all — worth it for anything with a real deadline (an upstream call, a job that must not run forever) and unnecessary overhead for a plain “run this later” callback that never needs to change its mind.

Common Misconceptions

“setTimeout(fn, 0) runs before anything else queued.” It runs before the next macrotask, but strictly after every pending microtask (process.nextTick, Promise reactions, queueMicrotask) — see the demo above, where the Promise always logs first.
“setTimeout(fn, 0) is basically the same as process.nextTick(fn).” They are in different queues entirely: nextTick (and microtasks) drain completely after every single callback; setTimeout(fn, 0) waits for the next full pass through the timers phase, which can be many callbacks later under load.
“A 0 or negative delay means the callback runs synchronously.” It never does — even setTimeout(fn, -100) is clamped to Node’s ~1 ms floor and still yields to the event loop first; nothing scheduled with setTimeout ever runs on the current stack frame.

Reading AI-generated code

AI-generated code sometimes uses setTimeout(fn, 0) as an informal substitute for “the next tick” or “right after this async operation finishes” — treating it as a synchronization primitive it was never designed to be.

🐛 Spot the bug

function loadUserThenGreet(fetchUser) {
let user = null;
fetchUser().then(function (u) { user = u; });

setTimeout(function () {
  // AI comment: "setTimeout(fn, 0) runs on the next tick, right after the fetch above"
  console.log('Hello, ' + user.name);
}, 0);
}

Show the answer

setTimeout(fn, 0) is a macrotask with roughly a 1 ms floor — it has no relationship to how long fetchUser() actually takes. If fetchUser() does real I/O (a network call, a database query), user is almost certainly still null when the timeout fires, and user.name throws a TypeError. Even calling this “the next tick” is a misnomer: process.nextTick and Promise microtasks are a separate, earlier-draining queue that has nothing to do with setTimeout’s macrotask queue. The fix is to react to the actual Promise instead of guessing a delay: fetchUser().then(function (u) { console.log('Hello, ' + u.name); }).

Is setTimeout(fn, 0) guaranteed to run fn immediately after the current synchronous code? Yes — delay 0 means run as soon as possible, before anything else No — it queues fn as a macrotask; pending microtasks run first Yes — but only if there are no other pending timers No — setTimeout always waits at least 4 ms regardless of the delay argument

How do you stop a setInterval from firing again? Call clearTimeout with the interval ID Set the interval variable to null Call clearInterval with the interval ID Return false from inside the interval callback

Which function schedules a callback in the microtask queue (not a timer queue)? setTimeout(fn, 0) setImmediate(fn) setInterval(fn, 0) queueMicrotask(fn)

What does this print?

import { setTimeout as delay } from 'node:timers/promises';
try {
  await delay(1000, undefined, { signal: AbortSignal.timeout(10) });
  console.log('finished');
} catch (err) {
  console.log('caught:', err.name);
}

finished (after 1000ms) caught: AbortError (after about 10ms) A TypeError is thrown synchronously before the try block even runs Nothing prints — AbortSignal.timeout is browser-only and undefined in Node

An AI-written function does setTimeout(() => console.log(user.name), 0) right after calling fetchUser().then(u => user = u), with the comment "runs on the next tick, right after the fetch." What is wrong with this reasoning? Nothing — setTimeout(fn, 0) is defined to run immediately after any pending Promise resolves setTimeout(fn, 0) has a roughly 1ms floor with no relation to how long the real fetch takes — user is likely still null when it fires setTimeout only works with delays of 100ms or more The bug is that .then() should have been awaited instead