node:timers

The node:timers module in Azion Runtime: timeouts, intervals, immediates, the promise-based timers, examples, and the supported APIs.

Last updated

View as Markdown Agent setup

The node:timers module holds the Node.js functions that schedule code to run after a delay or at regular intervals. Use it to manage asynchronous work and to control when each part of a function runs: defer work, add a short delay, or coordinate asynchronous tasks with setTimeout(). Azion Runtime provides the module through its Node.js compatibility, and the promise-based timers come from node:timers/promises.

Under azion dev, two behaviors differ from a deployed function. Date.now() advances during a request, so the elapsed times in the examples are not 0. A callback that is not a function throws TypeError: The "callback" argument must be of type function instead of EvalError: eval not allowed on setTimeout/setInterval parameter.

Examples

Each example is a complete function. Where an example shows a response, it is the one a deployed function returns.

Basic setTimeout

This function logs two lines, waits 2,000 ms on a timer wrapped in a promise, and then responds:

JavaScript
01/**
02 * An example of using Node.js Timers API in an Azion Function.
03 * Support:
04 * - Partially supported (Extended by library `timers-browserify`)
05 * @module runtime-apis/nodejs/timers/main
06 * @example
07 * // Build and run with the Azion CLI:
08 * azion build
09 * azion dev
10 */
11import timers from "node:timers";
12
13/**
14 * An example of using the Node.js Timers API in an Azion Function.
15 * @param {*} event
16 * @returns {Promise<Response>}
17 */
18const main = async (event) => {
19 console.log("Hello, world!");
20 console.log("Waiting for 2 seconds...");
21 await new Promise((resolve) => timers.setTimeout(resolve, 2000));
22 return new Response("Done!", { status: 200 });
23};
24
25export default main;

The function responds after the wait:

Done!

Delayed execution with setTimeout

This function schedules two sequential 100 ms delays and returns the steps it logged and the total time in milliseconds:

JavaScript
01import timers from "node:timers";
02
03// Wrap setTimeout in a promise for async/await usage
04const setTimeoutAsync = (ms) => new Promise((resolve) => timers.setTimeout(resolve, ms));
05
06const main = async (event) => {
07 const startTime = Date.now();
08 const logs = [];
09
10 logs.push(`Start: ${startTime}`);
11
12 // Using the promise-wrapped version - properly awaited
13 await setTimeoutAsync(100);
14 logs.push(`After 100ms delay`);
15
16 // Multiple sequential delays
17 await setTimeoutAsync(100);
18 logs.push(`After additional 100ms`);
19
20 // Calculate total time
21 const totalTime = Date.now() - startTime;
22
23 return new Response(JSON.stringify({
24 logs,
25 totalTimeMs: totalTime
26 }), {
27 headers: { "Content-Type": "application/json" }
28 });
29};
30
31export default main;

The setTimeoutAsync helper wraps timers.setTimeout() in a promise. In Azion Runtime, util.promisify() does not turn timers.setTimeout() into a promise-based timer: the promisified function passes the delay where the callback goes, and the call throws EvalError: eval not allowed on setTimeout/setInterval parameter. Deployed, totalTimeMs does not measure the wait, because Date.now() does not advance during a request.

Periodic operations with setInterval

This function runs a callback on a 50 ms interval for 250 ms, clears the interval, and returns every tick with its elapsed time:

JavaScript
01import timers from "node:timers";
02
03const main = async (event) => {
04 const startTime = Date.now();
05 const ticks = [];
06 let tickCount = 0;
07
08 // Create interval that runs every 50ms
09 const intervalId = timers.setInterval(() => {
10 tickCount++;
11 const elapsed = Date.now() - startTime;
12 ticks.push({ tick: tickCount, elapsed });
13 console.log(`Tick ${tickCount} at ${elapsed}ms`);
14 }, 50);
15
16 // Run for 250ms then stop
17 await new Promise(resolve => timers.setTimeout(resolve, 250));
18
19 // Clear the interval
20 timers.clearInterval(intervalId);
21
22 console.log(`Total ticks: ${tickCount}`);
23
24 return new Response(JSON.stringify({
25 totalTicks: tickCount,
26 ticks,
27 durationMs: Date.now() - startTime
28 }), {
29 headers: { "Content-Type": "application/json" }
30 });
31};
32
33export default main;

The function responds with four ticks:

{"totalTicks":4,"ticks":[{"tick":1,"elapsed":0},{"tick":2,"elapsed":0},{"tick":3,"elapsed":0},{"tick":4,"elapsed":0}],"durationMs":0}

Every elapsed value and durationMs are 0 because, deployed, Date.now() does not advance during a request. performance.now() does advance. For more information, refer to Globals.

Immediate execution with setImmediate

This function queues a setImmediate() callback, a setTimeout() callback with a 0 ms delay, and a process.nextTick() callback, then records the order in which they run:

JavaScript
01import timers from "node:timers";
02
03const main = async (event) => {
04 const executionOrder = [];
05
06 executionOrder.push("1. Start of function");
07
08 // setImmediate runs after current code completes
09 timers.setImmediate(() => {
10 executionOrder.push("setImmediate callback");
11 });
12
13 // setTimeout with 0 delay still goes through timer phase
14 timers.setTimeout(() => {
15 executionOrder.push("setTimeout(0) callback");
16 }, 0);
17
18 // In Azion Runtime, the nextTick callback runs after the two callbacks above
19 if (typeof process?.nextTick === "function") {
20 process.nextTick(() => {
21 executionOrder.push("nextTick callback");
22 });
23 }
24
25 executionOrder.push("2. End of synchronous code");
26
27 // Wait for all callbacks to execute
28 await new Promise(resolve => timers.setTimeout(resolve, 50));
29
30 executionOrder.push("3. After waiting");
31
32 // Note: The execution order between setImmediate and setTimeout(0)
33 // may vary across environments and is not guaranteed.
34 // In Azion Runtime, this order can differ from Node.js.
35
36 return new Response(JSON.stringify({
37 executionOrder,
38 note: "Order between setImmediate and setTimeout(0) may vary"
39 }), {
40 headers: { "Content-Type": "application/json" }
41 });
42};
43
44export default main;

The function responds with the order of the callbacks: setImmediate() first, then setTimeout() with a 0 ms delay, then process.nextTick():

{"executionOrder":["1. Start of function","2. End of synchronous code","setImmediate callback","setTimeout(0) callback","nextTick callback","3. After waiting"],"note":"Order between setImmediate and setTimeout(0) may vary"}

Timeout with cancellation

This function cancels a 500 ms timeout before it fires, then calls an API with a timeout that aborts the request through an AbortController:

JavaScript
01import timers from "node:timers";
02
03const main = async (event) => {
04 const results = [];
05
06 // Create a timeout that can be cancelled
07 const timeoutId = timers.setTimeout(() => {
08 results.push("Timeout executed");
09 }, 500);
10
11 // Cancel the timeout before it fires
12 timers.setTimeout(() => {
13 results.push("Cancelling timeout");
14 timers.clearTimeout(timeoutId);
15 }, 200);
16
17 // Wait to see what happens
18 await new Promise(resolve => timers.setTimeout(resolve, 600));
19
20 // Timeout with race pattern for API calls
21 const fetchWithTimeout = async (url, timeoutMs) => {
22 const controller = new AbortController();
23 const timeout = timers.setTimeout(() => controller.abort(), timeoutMs);
24
25 try {
26 const response = await fetch(url, { signal: controller.signal });
27 timers.clearTimeout(timeout);
28 return { success: true, status: response.status };
29 } catch (error) {
30 timers.clearTimeout(timeout);
31 return { success: false, error: error.message };
32 }
33 };
34
35 // Test with a fast-responding API
36 const apiResult = await fetchWithTimeout(
37 "https://jsonplaceholder.typicode.com/todos/1",
38 5000
39 );
40 results.push(`API result: ${JSON.stringify(apiResult)}`);
41
42 return new Response(JSON.stringify({ results }), {
43 headers: { "Content-Type": "application/json" }
44 });
45};
46
47export default main;

The function responds with the cancellation and the API result. The cancelled callback never adds Timeout executed:

{"results":["Cancelling timeout","API result: {\"success\":true,\"status\":200}"]}

Timer promises

This function uses the promise-based timers of node:timers/promises, which the Node.js timers/promises documentation describes:

JavaScript
01import { setTimeout, setInterval, setImmediate } from "node:timers/promises";
02
03const main = async (event) => {
04 const startTime = Date.now();
05 const logs = [];
06
07 logs.push(`Start: ${startTime}`);
08
09 // Promise-based setTimeout
10 await setTimeout(100);
11 logs.push(`After 100ms: ${Date.now() - startTime}ms elapsed`);
12
13 // setTimeout with value
14 const result = await setTimeout(50, "timer result");
15 logs.push(`Got value: ${result}`);
16
17 // Async iterator for setInterval with proper cancellation
18 // Note: Use AbortController to prevent memory leaks
19 let count = 0;
20 const ac = new AbortController();
21 const interval = setInterval(30, undefined, { signal: ac.signal });
22
23 try {
24 for await (const _ of interval) {
25 count++;
26 logs.push(`Interval tick ${count}`);
27 if (count >= 3) {
28 ac.abort(); // Properly cancel the interval
29 break;
30 }
31 }
32 } catch (error) {
33 // AbortError is expected after the abort
34 if (error.name !== "AbortError") {
35 throw error;
36 }
37 }
38
39 // setImmediate as promise
40 await setImmediate();
41 logs.push("After setImmediate");
42
43 // Calculate total time
44 const totalTime = Date.now() - startTime;
45
46 return new Response(JSON.stringify({
47 logs,
48 totalTimeMs: totalTime
49 }), {
50 headers: { "Content-Type": "application/json" }
51 });
52};
53
54export default main;

The function responds with the steps it logged:

{"logs":["Start: 1767268800000","After 100ms: 0ms elapsed","Got value: timer result","Interval tick 1","After setImmediate"],"totalTimeMs":0}

The async iterator that setInterval() returns yields one value and then ends, so the loop logs Interval tick 1 only. The elapsed values read 0 because, deployed, Date.now() does not advance during a request.

Retry logic with exponential backoff

This function retries a failing operation with an exponential backoff from a 50 ms initial delay, races a 200 ms operation against a 50 ms timeout, and returns both results as JSON:

JavaScript
01import timers from "node:timers";
02
03const setTimeoutAsync = (ms) => new Promise((resolve) => timers.setTimeout(resolve, ms));
04
05// Retry with exponential backoff
06const retryWithBackoff = async (fn, maxRetries, initialDelay = 100) => {
07 let lastError;
08
09 for (let attempt = 0; attempt < maxRetries; attempt++) {
10 try {
11 const result = await fn();
12 return { success: true, result, attempts: attempt + 1 };
13 } catch (error) {
14 lastError = error;
15
16 if (attempt < maxRetries - 1) {
17 const delay = initialDelay * Math.pow(2, attempt);
18 console.log(`Attempt ${attempt + 1} failed, retrying in ${delay}ms`);
19 await setTimeoutAsync(delay);
20 }
21 }
22 }
23
24 return { success: false, error: lastError.message, attempts: maxRetries };
25};
26
27const main = async (event) => {
28 // Simulate a flaky operation
29 let attempts = 0;
30 const flakyOperation = async () => {
31 attempts++;
32 if (attempts < 3) {
33 throw new Error(`Attempt ${attempts} failed`);
34 }
35 return `Success on attempt ${attempts}`;
36 };
37
38 const result = await retryWithBackoff(flakyOperation, 5, 50);
39
40 // Simulate a timeout scenario
41 const timeoutOperation = async () => {
42 await setTimeoutAsync(200);
43 return "This should not appear";
44 };
45
46 const timeoutResult = await Promise.race([
47 timeoutOperation(),
48 setTimeoutAsync(50).then(() => ({ timedOut: true }))
49 ]);
50
51 return new Response(JSON.stringify({
52 retryResult: result,
53 timeoutResult
54 }), {
55 headers: { "Content-Type": "application/json" }
56 });
57};
58
59export default main;

The setTimeoutAsync helper wraps timers.setTimeout() in a promise, the form that waits for its delay in Azion Runtime. A helper built with util.promisify(timers.setTimeout) throws EvalError: eval not allowed on setTimeout/setInterval parameter on its first delay.

Supported APIs

The table lists the status of each node:timers and node:timers/promises API in Azion Runtime:

APIStatus
setTimeout()🟢 Supported
clearTimeout()🟢 Supported
setInterval()🟢 Supported
clearInterval()🟢 Supported
setImmediate()🟢 Supported
clearImmediate()🟢 Supported
timers/promises.setTimeout()🟡 Partially supported
timers/promises.setInterval()🟡 Partially supported
timers/promises.setImmediate()🟢 Supported
timers.active()🟡 Partially supported
timers.enroll()🔴 Not supported
timers.unenroll()🔴 Not supported
timers.getActive()🟡 Partially supported

APIs marked 🟡 Partially supported have limited functionality compared to the full Node.js implementation. timers/promises.setTimeout() resolves with the value passed to it; under azion dev, it resolves at once and does not wait for the delay. The async iterator that timers/promises.setInterval() returns yields one value and then ends. To wait for a delay, wrap timers.setTimeout() in a promise: new Promise((resolve) => timers.setTimeout(resolve, ms)). Node.js deprecates enroll() and unenroll(), and Azion Runtime does not support them.

A timer callback must be a function. Deployed, a string or a number in its place throws EvalError: eval not allowed on setTimeout/setInterval parameter. timers.setTimeout() returns a timer object with ref() and unref() methods, and its refresh() is undefined. The node:timers/promises module exports scheduler, setImmediate, setInterval, and setTimeout, and a default export.

Node.js APIs

The status of every Node.js module in Azion Runtime, timers included.

Use Node.js APIs through polyfills

How the build turns node: imports into code that runs in Azion Runtime.

Globals

The global objects of Azion Runtime, and how Date.now() and performance.now() behave inside a request.

Node.js timers documentation

The full Node.js reference for every node:timers API in the table.