Node.js Util Module Guide

The util module provides essential utilities for debugging, formatting, and working with callbacks. Here's how to use it.

promisify#

const util = require('util');
const fs = require('fs');

// Convert callback-based function to Promise
const readFile = util.promisify(fs.readFile);
const writeFile = util.promisify(fs.writeFile);

// Use with async/await
async function processFile() {
  const data = await readFile('input.txt', 'utf8');
  const processed = data.toUpperCase();
  await writeFile('output.txt', processed);
  console.log('Done!');
}

// Custom promisify
const sleep = util.promisify(setTimeout);

async function delayedLog(message) {
  await sleep(1000);
  console.log(message);
}

// Multiple callback arguments
const dns = require('dns');
const lookup = util.promisify(dns.lookup);

// Returns { address, family } instead of two args
const result = await lookup('example.com');
console.log(result.address, result.family);

// Custom util.promisify.custom
dns.lookup[util.promisify.custom] = (hostname) => {
  return new Promise((resolve, reject) => {
    dns.lookup(hostname, (err, address, family) => {
      if (err) reject(err);
      else resolve({ address, family });
    });
  });
};

callbackify#

const util = require('util');

// Convert Promise function to callback
async function fetchData(id) {
  const response = await fetch(`/api/data/${id}`);
  return response.json();
}

const fetchDataCb = util.callbackify(fetchData);

// Use with callback
fetchDataCb('123', (err, data) => {
  if (err) {
    console.error(err);
    return;
  }
  console.log(data);
});

// Useful for legacy APIs
async function modernFunction(options) {
  return { success: true, data: options };
}

// Expose as callback for compatibility
module.exports = util.callbackify(modernFunction);

format and formatWithOptions#

const util = require('util');

// Printf-style formatting
console.log(util.format('Hello, %s!', 'World'));
// 'Hello, World!'

console.log(util.format('Count: %d', 42));
// 'Count: 42'

console.log(util.format('Data: %j', { a: 1, b: 2 }));
// 'Data: {"a":1,"b":2}'

console.log(util.format('Object: %o', { a: 1 }));
// 'Object: { a: 1 }'

console.log(util.format('Big: %O', { nested: { deep: 1 } }));
// Full inspection

// Integer formats
console.log(util.format('Int: %i', 42.5));
// 'Int: 42'

// Percent sign
console.log(util.format('100%% complete'));
// '100% complete'

// Extra arguments appended
console.log(util.format('Hello', 'World', '!'));
// 'Hello World !'

// With options
console.log(
  util.formatWithOptions(
    { colors: true },
    'Data: %O',
    { nested: { value: 42 } }
  )
);

inspect#

const util = require('util');

const complexObject = {
  name: 'Test',
  nested: {
    level1: {
      level2: {
        level3: {
          value: 'deep',
        },
      },
    },
  },
  array: [1, 2, 3, 4, 5],
  fn: function myFunc() {},
  date: new Date(),
};

// Basic inspection
console.log(util.inspect(complexObject));

// With options
console.log(util.inspect(complexObject, {
  depth: null,      // Unlimited depth
  colors: true,     // Colorize output
  showHidden: true, // Show non-enumerable
  maxArrayLength: 10,
  maxStringLength: 100,
  breakLength: 80,
  compact: false,
  sorted: true,
}));

// Custom inspect
class MyClass {
  constructor(value) {
    this.value = value;
    this.secret = 'hidden';
  }

  [util.inspect.custom](depth, options) {
    return `MyClass<${this.value}>`;
  }
}

const instance = new MyClass(42);
console.log(util.inspect(instance));
// 'MyClass<42>'

debuglog#

const util = require('util');

// Create debug logger
const debug = util.debuglog('myapp');

// Only logs when NODE_DEBUG=myapp
debug('Starting application');
debug('Config: %o', { port: 3000 });

// Multiple sections
const dbDebug = util.debuglog('myapp:db');
const apiDebug = util.debuglog('myapp:api');

dbDebug('Connecting to database');
apiDebug('Processing request');

// Run with: NODE_DEBUG=myapp node app.js
// Or: NODE_DEBUG=myapp:* node app.js (all myapp logs)

// Check if enabled
const log = util.debuglog('myapp', (fn) => {
  // Called when logging is enabled
  console.log('Debug logging enabled');
});

types#

const util = require('util');

// Type checking
util.types.isDate(new Date());          // true
util.types.isRegExp(/pattern/);         // true
util.types.isMap(new Map());            // true
util.types.isSet(new Set());            // true
util.types.isPromise(Promise.resolve()); // true

// ArrayBuffer types
util.types.isArrayBuffer(new ArrayBuffer(8)); // true
util.types.isTypedArray(new Uint8Array(8));   // true
util.types.isUint8Array(new Uint8Array(8));   // true

// Error types
util.types.isNativeError(new Error());  // true
util.types.isNativeError({ message: 'fake' }); // false

// Async types
util.types.isAsyncFunction(async () => {}); // true
util.types.isGeneratorFunction(function* () {}); // true

// Proxy
const proxy = new Proxy({}, {});
util.types.isProxy(proxy); // true

// SharedArrayBuffer (if available)
if (typeof SharedArrayBuffer !== 'undefined') {
  util.types.isSharedArrayBuffer(new SharedArrayBuffer(8)); // true
}

deprecate#

const util = require('util');

// Mark function as deprecated
const oldFunction = util.deprecate(
  function oldWay(x) {
    return x * 2;
  },
  'oldWay() is deprecated. Use newWay() instead.',
  'DEP0001'
);

// Warning printed once on first call
oldFunction(5); // Prints deprecation warning
oldFunction(10); // No warning (already shown)

// Mark method
class OldAPI {
  constructor() {
    this.oldMethod = util.deprecate(
      this._oldMethod.bind(this),
      'oldMethod() is deprecated'
    );
  }

  _oldMethod() {
    return 'old';
  }

  newMethod() {
    return 'new';
  }
}

// Suppress warnings
// NODE_OPTIONS=--no-deprecation node app.js
// Or: process.noDeprecation = true;

inherits (Legacy)#

const util = require('util');

// Legacy inheritance (prefer class syntax)
function Animal(name) {
  this.name = name;
}

Animal.prototype.speak = function () {
  console.log(this.name + ' makes a sound.');
};

function Dog(name) {
  Animal.call(this, name);
}

util.inherits(Dog, Animal);

Dog.prototype.speak = function () {
  console.log(this.name + ' barks.');
};

// Modern equivalent
class Animal2 {
  constructor(name) {
    this.name = name;
  }
  speak() {
    console.log(this.name + ' makes a sound.');
  }
}

class Dog2 extends Animal2 {
  speak() {
    console.log(this.name + ' barks.');
  }
}

getSystemErrorName#

const util = require('util');
const fs = require('fs');

// Get system error name from errno
fs.access('/nonexistent', (err) => {
  if (err) {
    console.log('Error code:', err.code);
    console.log('Errno:', err.errno);
    console.log('System name:', util.getSystemErrorName(err.errno));
    // ENOENT
  }
});

// Common error codes
const errors = [-2, -13, -17, -28];
errors.forEach((errno) => {
  console.log(errno, '->', util.getSystemErrorName(errno));
});
// -2 -> ENOENT (No such file)
// -13 -> EACCES (Permission denied)
// -17 -> EEXIST (File exists)
// -28 -> ENOSPC (No space left)

parseArgs#

const { parseArgs } = require('util');

// Parse command line arguments
const options = {
  name: { type: 'string', short: 'n' },
  verbose: { type: 'boolean', short: 'v', default: false },
  count: { type: 'string', short: 'c' },
};

const { values, positionals } = parseArgs({
  options,
  allowPositionals: true,
});

console.log(values);
// { name: 'test', verbose: true, count: '5' }
console.log(positionals);
// ['file1.txt', 'file2.txt']

// Usage: node app.js --name test -v --count 5 file1.txt file2.txt

// With strict mode
try {
  parseArgs({
    options,
    strict: true, // Throw on unknown options
  });
} catch (err) {
  console.error('Invalid arguments:', err.message);
}

TextEncoder/TextDecoder#

const util = require('util');

// Encode string to Uint8Array
const encoder = new util.TextEncoder();
const encoded = encoder.encode('Hello, World!');
console.log(encoded);
// Uint8Array [ 72, 101, 108, 108, 111, ... ]

// Decode Uint8Array to string
const decoder = new util.TextDecoder('utf-8');
const decoded = decoder.decode(encoded);
console.log(decoded);
// 'Hello, World!'

// With different encodings
const utf16Decoder = new util.TextDecoder('utf-16le');

// Stream decoding
const streamDecoder = new util.TextDecoder('utf-8', { stream: true });
// Handles incomplete multi-byte sequences

Best Practices#

Promisify:
✓ Convert callback APIs
✓ Use with async/await
✓ Define custom behavior
✓ Handle multiple values

Debugging:
✓ Use debuglog for dev
✓ Use inspect for logging
✓ Add custom inspect methods
✓ Format with colors

Type Checking:
✓ Use util.types
✓ Check native types
✓ Validate inputs
✓ Handle edge cases

Avoid:
✗ Using inherits (use class)
✗ Ignoring deprecation
✗ Complex format strings
✗ Excessive inspection depth

The util module provides essential utilities for Node.js development. Use promisify for callback-to-promise conversion, debuglog for conditional logging, and inspect for detailed object visualization. The types namespace offers reliable type checking, and parseArgs simplifies CLI argument parsing.