Definition

The util module is one of the modules that have been defined to be used internally in Node.js APIs. Nonetheless, it encompasses loads of handy and pragmatic functionalities that could be employed in the user code.

The best way to see the functions/methods that this module utilizes is to use one of its own methods; the inspect. From there, we can explore some of those functionalities.

The inspect Method

The util.inspect() method returns a string representation of any JavaScript primitive or object that is passed to it. Therefore, if we used that method on the util module itself, we can get the details of the module. We can open the Node.js REPL, and execute the following there.

const util = require('util');

console.log(util.inspect(util));

Relatively straightforward, we would have a list of all the available APIs that the util module provides.

util inspect on util

The util.inspect() method takes another parameter as an object. That parameter is an options object. For instance, the colors is a boolean option that if sat to true, the output will be styled with ANSI color codes.

const util = require('util');

console.log(util.inspect(util, {colors: true}));

util inspect on util with options colors

The format Method

This is a substitution formatter which returns a formatted string just like the printf in most of the C-like languages. And just like printf, the first argument is a string containing placeholders where each is replaced with the converted value from the corresponding argument. The following is a list of the available placeholders.

  • %s - String.
  • %d - Number (integer or floating point value).
  • %i - Integer.
  • %f - Floating point value.
  • %j - JSON. Replaced with the string [Circular] if the argument contains circular references.
  • %o - Object. A string representation of an object with generic JavaScript object formatting. Similar to util.inspect() with options { showHidden: true, depth: 4, showProxy: true }. This will show the full object including non-enumerable symbols and properties.
  • %O - Object. A string representation of an object with generic JavaScript object formatting. Similar to util.inspect() without options. This will show the full object, not including non-enumerable symbols and properties.
  • %% - single percent sign ('%'). This does not consume an argument.

Let's take an example.

const util = require('util');

console.log(util.format('%s: %j', 'This is a JSON', {foo: 'bar'}));

the debuglog method

The util.debuglog() method is used to create a function that conditionally writes debug messages to stderr based on the existence of the NODE_DEBUG environment variable. If the section name appears within the value of that environment variable, then the returned function operates similarly to console.error(). If not, then the returned function is a no-op. Let's see it in an example.

const util = require('util');

const appDebug = util.debuglog('appDebug');

appDebug('This is a debug message from appDebug');

Now if we placed that in, let's say, app.js for example, and run it node app.js, there will be no output. However, if we run it like with the NODE_DEBUG like so: NODE_DEBUG=appDebug node app.js, we will have the message in the output.

util debuglog

The number 5090 next to APPDEBUG represents the node process id.

We can have multiple debuglogs instances, and to be activated, we can select the required by separating them with commas when running the application with NODE_DEBUG.

const util = require('util');

const appDebug = util.debuglog('appDebug');
const anotherDebug = util.debuglog('anotherDebug');

appDebug('This is a debug message from appDebug');
anotherDebug('This is another debug message from anotherDebug');

And we run the app like this: NODE_DEBUG=appDebug,anotherDebug node app.js.

util debuglog with two messages