Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Globals and Console

The Node.js Timeout object

Reference for the Timeout object returned by setTimeout() and setInterval() in Node.js: ref(), unref(), hasRef(), refresh() and conversion to a number.

setTimeout() and setInterval() return a Timeout object, not a number as browsers do. The object has a few methods that control the timer after it has been created: ref() and unref() decide whether the timer keeps the process alive, hasRef() reports the current setting, and refresh() restarts the countdown.

Most code never touches these methods, but unref() is important for background timers and refresh() is a neat way to build idle timeouts and debouncing.

NODE
const timer = setTimeout(() => {}, 5000);
timer.unref();

Try it

Node.js unref lets the process exit

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js refresh for an idle timeout

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
timeout.ref(): Timeout
timeout.unref(): Timeout
timeout.hasRef(): boolean
timeout.refresh(): Timeout
timeout[Symbol.toPrimitive](): number
Method Description
ref() Makes the timer keep the event loop alive again (the default). Returns the timer.
unref() Lets the process exit even if this timer is pending. Returns the timer.
hasRef() Returns true if the timer keeps the event loop alive.
refresh() Resets the start time to now and reschedules with the original delay. Returns the timer.
[Symbol.toPrimitive]() Returns a numeric id, so +timer works and the id can be passed to clearTimeout().

Errors: none of these methods throw for normal use.

Usage notes

  • Why unref(): a cache sweeper, a heartbeat or a metrics flush should not stop Node.js from exiting once the real work is done. Unref them.
  • Unref is not cancel. If something else keeps the loop alive, an unref'd timer still fires on schedule.
  • ref() is the default, so calling it is only needed to undo an earlier unref().
  • refresh() on a fired timer schedules it again, even for a one-shot setTimeout, so you can reuse one timer object instead of clearing and recreating it. It does not change the callback or the arguments.
  • refresh() on a cleared timer has no effect; create a new timer instead.
  • Intervals: refresh() restarts the interval period from now.
  • Do not store it in a number field. A Timeout references its callback and arguments, so keeping stale handles around can retain memory. Set the variable to undefined after clearing.
  • Console output: printing a timer shows internal fields that change between versions. Do not rely on its shape; use the methods above.
  • close() exists as a legacy alias for cancelling a timer, but clearTimeout() is the supported way.
  • Disposal: timers also support Symbol.dispose, so they can be used with a using declaration in runtimes that support explicit resource management.