Util

Node.js utility module for promisify, inspect, types, and debugging

The node:util module provides utility functions that support the needs of Node.js internal APIs. Many of these utilities are useful for application and module developers as well.

Installation

import util from 'node:util';
// or
const util = require('node:util');

Key Functions

util.promisify(original)

Converts a callback-based function to a Promise-based function.

Parameters:

• original - A function following the error-first callback style

Returns: - A Promise-based version of the function

Example:

import { promisify } from 'node:util';
import { readFile } from 'node:fs';

const readFileAsync = promisify(readFile);

try {
  const data = await readFileAsync('file.txt', 'utf8');
  console.log(data);
} catch (err) {
  console.error(err);
}

util.callbackify(original)

Converts an async function or Promise-returning function to a callback style function.

Parameters:

• original - An async function or function that returns a Promise

Returns: - A callback style function

Example:

import { callbackify } from 'node:util';

async function fetchData() {
  return 'hello world';
}

const callbackFunction = callbackify(fetchData);

callbackFunction((err, result) => {
  if (err) throw err;
  console.log(result); // 'hello world'
});

util.inspect(object[, options])

Returns a string representation of an object for debugging purposes.

Parameters:

• object - The object to inspect
• options - Optional formatting options
  • showHidden - Show non-enumerable properties (default: false)
  • depth - Recursion depth (default: 2)
  • colors - Colorize output (default: false)
  • compact - Compact output format
  • maxArrayLength - Maximum array elements to show
  • breakLength - Length at which to break output

Returns: - String representation of the object

Example:

import { inspect } from 'node:util';

const obj = {
  name: 'John',
  details: { age: 30, city: 'NYC' }
};

console.log(inspect(obj, { depth: null, colors: true }));

util.format(format[, …args])

Returns a formatted string using printf-like format specifiers.

Format specifiers:

• %s - String
• %d - Number
• %i - Integer
• %f - Floating point
• %j - JSON
• %o - Object
• %% - Literal percent sign

Example:

import { format } from 'node:util';

const formatted = format('Hello %s, you are %d years old', 'John', 30);
console.log(formatted); // 'Hello John, you are 30 years old'

util.types

Provides type checking utilities for various JavaScript and Node.js types.

Common Type Checks

import { types } from 'node:util';

// Check if value is a Promise
types.isPromise(Promise.resolve()); // true

// Check if value is async function
types.isAsyncFunction(async () => {}); // true

// Check if value is a Map
types.isMap(new Map()); // true

// Check if value is a Set
types.isSet(new Set()); // true

// Check if value is a Date
types.isDate(new Date()); // true

// Check if value is a RegExp
types.isRegExp(/abc/); // true

// Check typed arrays
types.isUint8Array(new Uint8Array()); // true
types.isArrayBuffer(new ArrayBuffer(8)); // true

Available Type Checks

• isAnyArrayBuffer(value)
• isArgumentsObject(value)
• isArrayBuffer(value)
• isArrayBufferView(value)
• isAsyncFunction(value)
• isBigInt64Array(value)
• isBigUint64Array(value)
• isBooleanObject(value)
• isBoxedPrimitive(value)
• isDataView(value)
• isDate(value)
• isExternal(value)
• isFloat32Array(value)
• isFloat64Array(value)
• isGeneratorFunction(value)
• isGeneratorObject(value)
• isInt8Array(value)
• isInt16Array(value)
• isInt32Array(value)
• isMap(value)
• isMapIterator(value)
• isModuleNamespaceObject(value)
• isNativeError(value)
• isNumberObject(value)
• isPromise(value)
• isProxy(value)
• isRegExp(value)
• isSet(value)
• isSetIterator(value)
• isSharedArrayBuffer(value)
• isStringObject(value)
• isSymbolObject(value)
• isTypedArray(value)
• isUint8Array(value)
• isUint8ClampedArray(value)
• isUint16Array(value)
• isUint32Array(value)
• isWeakMap(value)
• isWeakSet(value)

Debugging Utilities

util.debuglog(section[, callback])

Creates a function that conditionally writes debug messages based on the NODE_DEBUG environment variable.

Example:

import { debuglog } from 'node:util';

const log = debuglog('myapp');

log('Starting application [%d]', process.pid);
// Only outputs if NODE_DEBUG=myapp is set

Usage:

NODE_DEBUG=myapp node app.js
# Output: MYAPP 12345: Starting application [12345]

util.deprecate(fn, msg[, code])

Marks a function as deprecated and emits a deprecation warning when called.

Example:

import { deprecate } from 'node:util';

export const oldFunction = deprecate(
  () => {
    // Function implementation
  },
  'oldFunction() is deprecated. Use newFunction() instead.',
  'DEP0001'
);

Additional Utilities

util.parseArgs([config])

Parses command-line arguments (Node.js v18.3.0+).

Example:

import { parseArgs } from 'node:util';

const options = {
  name: { type: 'string' },
  verbose: { type: 'boolean', short: 'v' }
};

const { values, positionals } = parseArgs({ options });
console.log(values.name);
console.log(values.verbose);

util.stripVTControlCharacters(str)

Removes ANSI escape codes from a string.

Example:

import { stripVTControlCharacters } from 'node:util';

const str = '\x1b[31mRed text\x1b[0m';
const plain = stripVTControlCharacters(str);
console.log(plain); // 'Red text'

Common Use Cases

Converting Callback APIs to Promises

import { promisify } from 'node:util';
import { exec } from 'node:child_process';

const execAsync = promisify(exec);

try {
  const { stdout, stderr } = await execAsync('ls -la');
  console.log(stdout);
} catch (error) {
  console.error(error);
}

Deep Object Inspection

import { inspect } from 'node:util';

const complexObject = {
  nested: {
    deep: {
      value: [1, 2, 3],
      map: new Map([['key', 'value']])
    }
  }
};

console.log(inspect(complexObject, {
  depth: Infinity,
  colors: true,
  compact: false
}));

Type Validation

import { types } from 'node:util';

function processData(data) {
  if (types.isPromise(data)) {
    return data.then(processData);
  }
  
  if (types.isTypedArray(data)) {
    // Handle typed array
    return Array.from(data);
  }
  
  return data;
}

Related Modules

• assert - Testing assertions
• Buffer - Binary data handling
• console - Console output