node:timers

O módulo node:timers no Azion Runtime: timeouts, intervalos, immediates, os timers baseados em Promise, exemplos e as APIs com suporte.

Última atualização

Ver como Markdown Configurar agente

O módulo node:timers reúne as funções do Node.js que agendam a execução de código após um atraso ou em intervalos regulares. Use-o para gerenciar o trabalho assíncrono e para controlar quando cada parte de uma function é executada: adiar trabalho, adicionar um atraso curto ou coordenar tarefas assíncronas com setTimeout(). O Azion Runtime fornece o módulo por meio da compatibilidade com Node.js, e os timers baseados em Promise vêm de node:timers/promises.

nota — Com azion dev, dois comportamentos diferem de uma function após o deploy. Date.now() avança durante uma requisição, por isso os tempos decorridos dos exemplos não são 0. Um callback que não é uma função lança TypeError: The "callback" argument must be of type function em vez de EvalError: eval not allowed on setTimeout/setInterval parameter.

Exemplos

Cada exemplo é uma function completa. Quando um exemplo mostra uma resposta, ela é a que uma function com deploy feito retorna.

setTimeout básico

Esta function registra duas linhas no log, aguarda 2.000 ms em um timer envolvido em uma Promise e depois responde:

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;

A function responde após a espera:

Done!

Execução adiada com setTimeout

Esta function agenda dois atrasos sequenciais de 100 ms e retorna as etapas que registrou e o tempo total em milissegundos:

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;

O helper setTimeoutAsync envolve timers.setTimeout() em uma Promise. No Azion Runtime, util.promisify() não transforma timers.setTimeout() em um timer baseado em Promise: a função promisificada passa o atraso na posição do callback, e a chamada lança EvalError: eval not allowed on setTimeout/setInterval parameter. Após o deploy, totalTimeMs não mede a espera, porque Date.now() não avança durante uma requisição.

Operações periódicas com setInterval

Esta function executa um callback em um intervalo de 50 ms durante 250 ms, limpa o intervalo e retorna cada tick com o seu tempo decorrido:

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;

A function responde com quatro ticks:

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

Todos os valores de elapsed e o valor de durationMs são 0 porque, após o deploy, Date.now() não avança durante uma requisição. performance.now() avança. Para mais informações, consulte Globais.

Execução imediata com setImmediate

Esta function enfileira um callback de setImmediate(), um callback de setTimeout() com atraso de 0 ms e um callback de process.nextTick(), e depois registra a ordem em que eles são executados:

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;

A function responde com a ordem dos callbacks: primeiro setImmediate(), depois setTimeout() com atraso de 0 ms e por último 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 com cancelamento

Esta function cancela um timeout de 500 ms antes que ele dispare e depois chama uma API com um timeout que aborta a requisição por meio de um 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;

A function responde com o cancelamento e o resultado da API. O callback cancelado nunca adiciona Timeout executed:

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

Promises de timer

Esta function usa os timers baseados em Promise de node:timers/promises, descritos na documentação do timers/promises do Node.js:

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;

A function responde com as etapas que registrou:

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

O iterador assíncrono que setInterval() retorna produz um valor e depois termina, por isso o loop registra apenas Interval tick 1. Os tempos decorridos são 0 porque, após o deploy, Date.now() não avança durante uma requisição.

Lógica de retry com backoff exponencial

Esta function repete uma operação que falha, com backoff exponencial a partir de um atraso inicial de 50 ms, coloca uma operação de 200 ms em disputa com um timeout de 50 ms e retorna os dois resultados como 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;

O helper setTimeoutAsync envolve timers.setTimeout() em uma Promise, a forma que aguarda o atraso no Azion Runtime. Um helper criado com util.promisify(timers.setTimeout) lança EvalError: eval not allowed on setTimeout/setInterval parameter no primeiro atraso.

APIs com suporte

A tabela lista o status de cada API de node:timers e de node:timers/promises no Azion Runtime:

APIStatus
setTimeout()🟢 Com suporte
clearTimeout()🟢 Com suporte
setInterval()🟢 Com suporte
clearInterval()🟢 Com suporte
setImmediate()🟢 Com suporte
clearImmediate()🟢 Com suporte
timers/promises.setTimeout()🟡 Parcialmente suportado
timers/promises.setInterval()🟡 Parcialmente suportado
timers/promises.setImmediate()🟢 Com suporte
timers.active()🟡 Parcialmente suportado
timers.enroll()🔴 Sem suporte
timers.unenroll()🔴 Sem suporte
timers.getActive()🟡 Parcialmente suportado

As APIs marcadas como 🟡 Parcialmente suportado têm funcionalidade limitada em comparação com a implementação completa do Node.js. timers/promises.setTimeout() resolve com o valor passado a ela; com azion dev, ela é resolvida na hora, sem aguardar o atraso. O iterador assíncrono que timers/promises.setInterval() retorna produz um valor e depois termina. Para aguardar um atraso, envolva timers.setTimeout() em uma Promise: new Promise((resolve) => timers.setTimeout(resolve, ms)). O Node.js marca enroll() e unenroll() como obsoletas, e o Azion Runtime não oferece suporte a elas.

Um callback de timer precisa ser uma função. Após o deploy, uma string ou um número no lugar dele lança EvalError: eval not allowed on setTimeout/setInterval parameter. timers.setTimeout() retorna um objeto de timer com os métodos ref() e unref(), e o refresh() desse objeto não está definido. O módulo node:timers/promises exporta scheduler, setImmediate, setInterval e setTimeout, além de um export default.

Recursos relacionados

APIs do Node.js

O status de cada módulo do Node.js no Azion Runtime, incluindo timers.

Use APIs do Node.js com polyfills

Como o build transforma imports node: em código que é executado no Azion Runtime.

Globais

Os objetos globais do Azion Runtime e como Date.now() e performance.now() se comportam dentro de uma requisição.

Documentação de timers do Node.js

A referência completa do Node.js para cada API de node:timers da tabela.