util and diagnostics

node:util bridges callbacks to Promises, formats objects for logs, and provides debugging helpers - pair with node:diagnostics_channel and perf_hooks for deeper production insight.

Recipe

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' });

When to reach for this:

• Promisifying legacy callback APIs
• Logging nested objects without JSON.stringify failures
• Gated debug output with NODE_DEBUG=billing
• CLI tools coloring output with styleText

Working Example

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');

What this demonstrates:

• inspect truncates depth/array for readable logs vs circular JSON errors
• debuglog only prints when NODE_DEBUG=api or NODE_DEBUG=*
• diagnostics_channel publishes/subscribes cross-cutting events without tight coupling
• parseEnv parses dotenv-style strings in tests without files

Deep Dive

How It Works

• promisify assumes (err, result) callback last - returns Promise-returning function.
• callbackify inverse for legacy - rare in new code.
• inspect customizes util.inspect.custom on classes for redacted representations.
• diagnostics_channel - lightweight pub/sub for APM hooks and internal tracing.

util vs dedicated modules

TypeScript Notes

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

Gotchas

• Logging huge objects in production - cost and PII risk. Fix: inspect limits + redaction.
• promisify non-standard callbacks - hangs. Fix: manual Promise wrapper.
• Leaving NODE_DEBUG= on in prod* - verbose stderr I/O. Fix: dev/staging only.
• Relying on inspect for serialization - not JSON - use JSON.stringify for wire format.
• Subscribing diagnostics_channel without unsubscribe - test leaks. Fix: unsubscribe in teardown.

Alternatives

FAQs

Related

• Callbacks vs Promises Migration - promisify patterns
• Reading Official Docs - NODE_DEBUG
• pino - production logging
• OpenTelemetry Node SDK - tracing

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.