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.
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
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.
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
[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 }toutil.inspect()to bypass the method and see the raw structure. - When you inspect a part of your object, pass
optionsalong (changingdepthas needed), otherwise colors and line width are lost. options.stylize(text, "special")colors text the way built-ins do whencolorsis on. Styles include"string","number","special","name"and"undefined".- Check
depth < 0to 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()andString(obj)are not affected; usetoJSON()andtoString()for those. - Use
Symbol.for("nodejs.util.inspect.custom")in libraries that should not depend on a particular Node version ofnode:util.