Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท util, assert and the Test Runner

Node.js util.inspect.custom symbol

Reference for util.inspect.custom in Node.js: define how a class prints in console.log and util.inspect, with the depth, options and inspect arguments.

util.inspect.custom is a well-known symbol. If an object has a method stored under that symbol, util.inspect() calls it to decide how the object looks, and so does console.log(), the REPL and error messages. It lets you hide internals, shorten big structures and show what a human wants to see.

The symbol is registered globally as Symbol.for("nodejs.util.inspect.custom"), so a library can implement it without importing node:util at all. The method may return a string, which is printed as is, or any other value, which is then inspected in its place.

NODE
import { inspect } from "node:util";

class Money {
  constructor(amount) { this.amount = amount; }
  [inspect.custom]() { return `Money<${this.amount}>`; }
}
console.log(new Money(5)); // Money<5>

Try it

Node.js Hiding secrets and showing a summary

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Arguments and returning an object

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
[util.inspect.custom](depth: number, options: object, inspect: Function): any
Name Description
depth How many more levels may be expanded. It counts down as inspection goes deeper and is negative when the depth limit was passed.
options The effective util.inspect() options (colors, compact, breakLength, stylize() and so on).
inspect The util.inspect function itself, so you can inspect parts without importing it.

Returns: a string (used verbatim) or any value (inspected with the same options in place of the object).

Errors: if the method throws, the error propagates out of console.log() or util.inspect().

Usage notes

  • Pass { customInspect: false } to util.inspect() to bypass the method and see the raw structure.
  • When you inspect a part of your object, pass options along (changing depth as needed), otherwise colors and line width are lost.
  • options.stylize(text, "special") colors text the way built-ins do when colors is on. Styles include "string", "number", "special", "name" and "undefined".
  • Check depth < 0 to print a short placeholder such as [Tree] instead of expanding a deep or cyclic structure.
  • A custom string is not wrapped or indented for you. For multi-line output, indent nested lines yourself.
  • Only the output of util.inspect() changes. JSON.stringify() and String(obj) are not affected; use toJSON() and toString() for those.
  • Use Symbol.for("nodejs.util.inspect.custom") in libraries that should not depend on a particular Node version of node:util.