node:util

O módulo node:util reúne as funções auxiliares do Node.js para tarefas comuns com dados: formatar strings, inspecionar objetos para depuração, converter funções no estilo callback em promises e verificar tipos de valores em tempo de execução. O Azion Runtime oferece suporte ao módulo por meio da compatibilidade com Node.js. Dentro de uma function, use util.promisify() para adaptar código baseado em callbacks a async/await e util.inspect() para registrar dados estruturados no log.

Exemplos

Cada exemplo é uma function completa que importa util de node:util. A resposta abaixo de cada exemplo é a que uma function com deploy feito retorna.

Promisify e inspect

Esta function converte uma função no estilo callback em uma promise, aguarda a promise e registra o resultado no log com util.inspect():

JavaScript

01/**

02 * An example of using Node.js Util API in an Azion Function.

03 * Support:

04 * - Partially supported (Extended by library `util`)

05 * @module runtime-apis/nodejs/util/main

06 * @example

07 * // Build and run with the Azion CLI:

08 * azion build

09 * azion dev

10 */

11import util from "node:util";

13const myTest = (callback) => {

14 try {

15 callback(null, "Success!");

16 } catch (err) {

17 callback(err);

18 }

19};

21/**

22 * An example of using the Node.js Util API in an Azion Function.

23 * @param {*} event

24 * @returns {Promise<Response>}

25 */

26const main = async (event) => {

27 const promisifyTest = util.promisify(myTest);

28 const result = await promisifyTest();

29 console.log(util.inspect(result, { showHidden: false, depth: null }));

31 return new Response("Done!", { status: 200 });

32};

34export default main;

A function registra "Success!" no log e responde com:

Done!

Conversão de callback em promise

Esta function encapsula uma API baseada em callbacks com util.promisify() e a chama duas vezes com await:

JavaScript

01import util from "node:util";

02import { setTimeout } from "node:timers";

04// Simulate a callback-based API

05const fetchData = (id, callback) => {

06 setTimeout(() => {

07 if (id > 0) {

08 callback(null, { id, data: `Item ${id}`, timestamp: Date.now() });

09 } else {

10 callback(new Error("Invalid ID"));

11 }

12 }, 100);

13};

15// Convert to promise-based

16const fetchDataAsync = util.promisify(fetchData);

18const main = async (event) => {

19 try {

20 // Now can use with async/await

21 const result1 = await fetchDataAsync(1);

22 const result2 = await fetchDataAsync(2);

24 console.log("Result 1:", result1);

25 console.log("Result 2:", result2);

27 return new Response(JSON.stringify({ results: [result1, result2] }), {

28 headers: { "Content-Type": "application/json" }

29 });

30 } catch (error) {

31 console.error("Error:", error.message);

32 return new Response(JSON.stringify({ error: error.message }), {

33 status: 400,

34 headers: { "Content-Type": "application/json" }

35 });

36 }

37};

39export default main;

A function responde com os dois resultados:

{"results":[{"id":1,"data":"Item 1","timestamp":1767268800000},{"id":2,"data":"Item 2","timestamp":1767268800000}]}

Os dois timestamps são iguais porque, em uma function após o deploy, Date.now() não avança durante uma requisição.

Inspeção profunda de objetos

Esta function inspeciona os detalhes da requisição e um objeto aninhado, e monta uma string com util.format():

JavaScript

01import util from "node:util";

03const main = async (event) => {

04 // Complex object to inspect

05 const requestInfo = {

06 url: event.request.url,

07 method: event.request.method,

08 headers: Object.fromEntries(event.request.headers),

09 timestamp: new Date().toISOString()

10 };

12 // Nested object

13 const complexData = {

14 level1: {

15 level2: {

16 level3: {

17 value: "deep",

18 array: [1, 2, { nested: true }]

19 }

20 }

21 }

22 };

24 // Inspect with options

25 const inspected = util.inspect(requestInfo, {

26 depth: null, // Unlimited depth

27 colors: false, // Explicitly disabled since output goes into JSON response

28 compact: false, // Multi-line output

29 showHidden: false, // Don't show non-enumerable

30 maxArrayLength: 10 // Limit array display

31 });

33 console.log("Request info:", inspected);

35 // Format string with placeholders

36 const formatted = util.format(

37 "Request %s to %s at %s",

38 requestInfo.method,

39 requestInfo.url,

40 requestInfo.timestamp

41 );

42 console.log(formatted);

44 return new Response(JSON.stringify({

45 requestInfo,

46 formatted,

47 inspectedDepth: util.inspect(complexData, { depth: 2 })

48 }), {

49 headers: { "Content-Type": "application/json" }

50 });

51};

53export default main;

Para uma requisição GET a https://example.com/, a function responde com os detalhes da requisição, a string formatada e o objeto inspecionado:

{"requestInfo":{"url":"https://example.com/","method":"GET","headers":{"accept":"*/*","cdn-loop":"azion.com; steps=1","host":"example.com","user-agent":"curl/8.7.1","x-forwarded-for":"192.0.2.10","x-forwarded-source-port":"6109"},"timestamp":"2026-01-01T12:00:00.000Z"},"formatted":"Request GET to https://example.com/ at 2026-01-01T12:00:00.000Z","inspectedDepth":"{\n  \"level1\": {\n    \"level2\": {\n      \"level3\": {\n        \"value\": \"deep\",\n        \"array\": [\n          1,\n          2,\n          {\n            \"nested\": true\n          }\n        ]\n      }\n    }\n  }\n}"}

No Azion Runtime, util.inspect() imprime complexData como texto JSON indentado, com todos os níveis expandidos, embora a chamada passe depth: 2.

Formatação de strings e descontinuação

Esta function formata strings com placeholders, marca uma função como obsoleta com util.deprecate() e a chama:

JavaScript

01import util from "node:util";

03// Mark a function as deprecated

04const oldFunction = util.deprecate(

05 () => "This is the old function",

06 "oldFunction is deprecated. Use newFunction instead."

07);

09const newFunction = () => "This is the new function";

11const main = async (event) => {

12 const results = [];

14 // String formatting with %s, %d, %j, %%

15 results.push(util.format("Hello %s!", "World"));

16 results.push(util.format("Number: %d, String: %s", 42, "test"));

17 results.push(util.format("JSON: %j", { key: "value" }));

18 results.push(util.format("Percent: %%"));

20 // Style strings (for console output)

21 // Note: ANSI codes are only meaningful in terminal output

22 // They will appear as escape sequences in HTTP responses

23 const styled = util.format(

24 "%s %s %s",

25 "\x1b[31mRed\x1b[0m",

26 "\x1b[32mGreen\x1b[0m",

27 "\x1b[34mBlue\x1b[0m"

28 );

29 console.log(styled); // Useful in logs only

31 // Call the deprecated function and its replacement

32 const oldResult = oldFunction();

33 const newResult = newFunction();

35 // Get object's own property names

36 const obj = { a: 1, b: 2, c: 3 };

37 const keys = Object.keys(obj);

39 return new Response(JSON.stringify({

40 formattedStrings: results,

41 oldFunctionResult: oldResult,

42 newFunctionResult: newResult,

43 objectKeys: keys

44 // Note: styled string not included - ANSI codes not useful in JSON

45 }), {

46 headers: { "Content-Type": "application/json" }

47 });

48};

50export default main;

A function responde com as strings formatadas e o resultado de cada função:

{"formattedStrings":["Hello World!","Number: 42, String: test","JSON: {\"key\":\"value\"}","Percent: %"],"oldFunctionResult":"This is the old function","newFunctionResult":"This is the new function","objectKeys":["a","b","c"]}

Os placeholders %s, %d, %j e %% funcionam como o exemplo mostra. O placeholder %i não é substituído: util.format() mantém %i na saída como foi escrito.

APIs suportadas

A tabela lista o status de cada API de node:util no Azion Runtime:

API	Status
`util.promisify()`	🟢 Com suporte
`util.inspect()`	🟢 Com suporte
`util.format()`	🟢 Com suporte
`util.deprecate()`	🟢 Com suporte
`util.isDeepStrictEqual()`	🟢 Com suporte
`util.inherits()`	🟡 Obsoleta (use classes ES6)
`util.callbackify()`	🟡 Parcialmente suportado
`util.formatWithOptions()`	🟡 Parcialmente suportado
`util.getSystemErrorMap()`	🟡 Parcialmente suportado
`util.getSystemErrorName()`	🟡 Parcialmente suportado
`util.log()`	🟡 Parcialmente suportado
`util.stripVTControlCharacters()`	🟡 Parcialmente suportado
`util.styleText()`	🟡 Parcialmente suportado
`util.types.isDate()`	🟢 Com suporte
`util.types.isRegExp()`	🟢 Com suporte
`util.types.isPromise()`	🟢 Com suporte
`util.types.isArrayBuffer()`	🟢 Com suporte
`util.types.isNativeError()`	🔴 Sem suporte
`util.types.isTypedArray()`	🟢 Com suporte
`util.types.isMap()`	🟢 Com suporte
`util.types.isSet()`	🟢 Com suporte
`util.types.isCryptoKey()`	🟢 Com suporte
`util.types.isKeyObject()`	🟢 Com suporte

As APIs marcadas como 🟡 Parcialmente suportado têm funcionalidade limitada em comparação com a implementação completa do Node.js.

util.types verifica o tipo de um valor em tempo de execução, como alternativa a instanceof. util.types.isDate(), util.types.isPromise() e util.types.isRegExp() retornam true para um valor correspondente. util.types.isNativeError() lança Error: [unenv] util.types.isNativeError is not implemented yet! em uma function após o deploy e com azion dev.

O Node.js considera util.inherits() obsoleta desde a v5.0.0; use a sintaxe class com extends. No Azion Runtime, EventEmitter de node:events é uma classe, então uma função construtora que chama EventEmitter.call(this) para herdar dela lança TypeError: Class constructor e cannot be invoked without 'new'.

Recursos relacionados

APIs do Node.js

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

Use APIs do Node.js com polyfills

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

node:events

A classe EventEmitter, para estender com a sintaxe class em vez de util.inherits().

Documentação de util do Node.js

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