util y diagnósticos

node:util conecta callbacks con Promises, formatea objetos para registros y proporciona ayudantes de depuración. Combínalo con node:diagnostics_channel y perf_hooks para una visión más profunda de la producción.

Receta

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

Cuándo usarlo:

• Promisificar APIs de callback heredadas
• Registrar objetos anidados sin fallos de JSON.stringify
• Salida de depuración controlada con NODE_DEBUG=billing
• Herramientas CLI que colorean la salida con styleText

Ejemplo de trabajo

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('order event', inspect(message, { depth: 2, maxArrayLength: 10 }));
});
 
export async function compressJson(obj: unknown): Promise<Buffer> {
  const json = JSON.stringify(obj);
  debug('compress input bytes', json.length);
  return gzipAsync(Buffer.from(json, 'utf8'));
}
 
console.log(styleText('cyan', 'info'), 'server boot');

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

Lo que esto demuestra:

• inspect trunca la profundidad/array para registros legibles frente a errores JSON circulares
• debuglog solo imprime cuando NODE_DEBUG=api o NODE_DEBUG=*
• diagnostics_channel publica/suscribe eventos transversales sin un acoplamiento estricto
• parseEnv analiza cadenas de estilo dotenv en pruebas sin archivos

Análisis profundo

Cómo funciona

• promisify asume (err, result) callback al final - devuelve una función que retorna una Promise.
• callbackify inverso para lo heredado - raro en código nuevo.
• inspect personaliza util.inspect.custom en clases para representaciones redactadas.
• diagnostics_channel - pub/sub ligero para hooks APM y rastreo interno.

util vs módulos dedicados

Notas de TypeScript

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

Errores comunes

• Registrar objetos enormes en producción - costo y riesgo de PII. Solución: límites de inspect + redacción.
• promisify callbacks no estándar - cuelgues. Solución: envoltorio manual de Promise.
• Dejar NODE_DEBUG= activado en producción* - E/S de stderr verbosa. Solución: solo desarrollo/staging.
• Confiar en inspect para la serialización - no es JSON - usa JSON.stringify para el formato de cable.
• Suscribirse a diagnostics_channel sin anular la suscripción - fugas en pruebas. Solución: anular la suscripción en la fase de limpieza.

Alternativas

Preguntas frecuentes

Relacionado

• Migración de Callbacks a Promises - patrones de promisify
• Lectura de la documentación oficial - NODE_DEBUG
• pino - registro de producción
• OpenTelemetry Node SDK - trazado

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.