util e diagnósticos

node:util faz a ponte entre callbacks e Promises, formata objetos para logs e fornece helpers de depuração - combine com node:diagnostics_channel e perf_hooks para insights mais profundos em produção.

Receita

import { promisify, inspect, debuglog, styleText, parseEnv } from 'node:util';
import { gzip } from 'node:zlib';
 
const gzipAsync = promisify(gzip);
 
const log = debuglog('billing');
log('processando', { id: '1' });

Quando usar:

• Para transformar APIs legadas de callback em Promises
• Para registrar objetos aninhados sem falhas de JSON.stringify
• Para saída de depuração controlada com NODE_DEBUG=billing
• Para ferramentas CLI colorirem a saída com styleText

Exemplo de Trabalho

import { promisify, inspect, debuglog, styleText } from 'node:util';
import { gzip } from 'node:zlib';
import { diagnostics_channel } from 'node:diagnostics_channel';
 
const gzipAsync = promisify(gzip);
const debug = debuglog('api');
 
const orderChannel = diagnostics_channel.channel('app:order');
 
orderChannel.subscribe((message) => {
  debug('evento de pedido', inspect(message, { depth: 2, maxArrayLength: 10 }));
});
 
export async function compressJson(obj: unknown): Promise<Buffer> {
  const json = JSON.stringify(obj);
  debug('bytes de entrada para compressão', json.length);
  return gzipAsync(Buffer.from(json, 'utf8'));
}
 
console.log(styleText('cyan', 'info'), 'inicialização do servidor');

import { parseEnv } from 'node:util';
 
const parsed = parseEnv('FOO=bar\nBAZ=qux');

O que isto demonstra:

• inspect trunca a profundidade/array para logs legíveis em vez de erros de JSON circular
• debuglog só imprime quando NODE_DEBUG=api ou NODE_DEBUG=*
• diagnostics_channel publica/assina eventos transversais sem acoplamento rígido
• parseEnv analisa strings no estilo dotenv em testes sem arquivos

Mergulho Profundo

Como Funciona

• promisify assume que o callback é (err, result) no final - retorna uma função que retorna Promise.
• callbackify é o inverso para código legado - raro em código novo.
• inspect personaliza util.inspect.custom em classes para representações redigidas.
• diagnostics_channel - pub/sub leve para hooks de APM e rastreamento interno.

util vs módulos dedicados

Notas de TypeScript

import { types } from 'node:util';
 
if (types.isPromise(maybe)) {
  await maybe;
}

Armadilhas

• Registrar objetos enormes em produção - custo e risco de PII. Correção: limites de inspect + redação.
• Usar promisify com callbacks não padrão - trava. Correção: wrapper manual de Promise.
• Manter NODE_DEBUG=* em produção - E/S de stderr verbosa. Correção: apenas em dev/staging.
• Confiar em inspect para serialização - não é JSON - use JSON.stringify para formato de rede.
• Assinar diagnostics_channel sem cancelar a assinatura - vazamentos em testes. Correção: cancelar a assinatura na limpeza.

Alternativas

FAQs

Relacionados

• Migração de Callbacks para Promises - padrões promisify
• Lendo a Documentação Oficial - NODE_DEBUG
• pino - logging em produção
• OpenTelemetry Node SDK - tracing

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.