Node.js: Reject timer delays outside the supported range
A large delay can make a Node.js timer run almost immediately. Node sets delays greater than 2,147,483,647 milliseconds to 1 millisecond. Validate configuration before passing it to a timer, especially when converting days or seconds into milliseconds.
Set up
Tested on Debian 13 Linux with Node.js v24.19.0. Use Bash, Node.js on your PATH, a text editor, and the mktemp, rm and rmdir utilities. No packages or network access are needed. Keep the same terminal through cleanup. Stop if setup fails before saving the source.
start_dir="$PWD"
work_dir="$(mktemp -d)" || exit 1
cd -- "$work_dir" || exit 1Run the example
Save as node-validate-timer-delay.mjs:
import assert from 'node:assert/strict';
import { setTimeout as delay } from 'node:timers/promises';
function timerMilliseconds(value) {
if (!Number.isInteger(value) || value < 1 || value > 2_147_483_647) {
throw new RangeError('Expected 1 through 2147483647 integer milliseconds');
}
return value;
}
assert.equal(timerMilliseconds(1), 1);
assert.equal(timerMilliseconds(2_147_483_647), 2_147_483_647);
const rejected = [0, -1, 1.5, 2_147_483_648, NaN, Infinity, '1000', null];
for (const value of rejected) {
assert.throws(() => timerMilliseconds(value), RangeError);
}
await delay(timerMilliseconds(1));
console.log('Accepted endpoints: 1, 2147483647');
console.log('Rejected invalid values:', rejected.length);
console.log('One short timer completed');Run:
node node-validate-timer-delay.mjsObserved output:
Accepted endpoints: 1, 2147483647
Rejected invalid values: 8
One short timer completedValidate before scheduling
The guard accepts only integer Number values from 1 through 2,147,483,647. Both endpoints are tested, but only the 1-millisecond timer is scheduled. The upper-end assertion validates the number without waiting for a long timer. The test checks completion, not elapsed-time precision.
Node’s timer documentation specifies a 1-millisecond delay for values greater than 2,147,483,647, less than 1, or NaN. Non-integer delays are truncated. This helper rejects those inputs instead of accepting an implicit adjustment. It also rejects strings, null and Infinity.
Validate the final millisecond value after unit conversion. A value that is valid in seconds can exceed the timer range after multiplication. Treat units as part of the configuration format, and report a range error to the caller instead of starting an unexpectedly short retry loop.
Limits of an in-process timer
Node does not guarantee the exact time at which a timeout callback runs. Other work on the event loop can delay it.
The maximum delay is about 24.9 days. Longer schedules need a different design, such as a persisted deadline checked periodically. A process restart also loses an ordinary in-memory timer. Choose persistence and recovery behavior according to the job; increasing the numeric delay does not provide either.
Clean up
Remove the saved file and empty scratch directory. If the directory is not empty, inspect its contents before removing anything else.
rm -- node-validate-timer-delay.mjs
cd -- "$start_dir" || exit 1
rmdir -- "$work_dir"
unset start_dir work_dirAcknowledgements
This post was created with assistance from AI.