Table of Contents

• Util
  • util.callbackify(original)
  • util.debuglog(section)
  • util.deprecate(function, string)
  • util.format(format[, ...args])
  • util.getSystemErrorName(err)
  • util.inherits(constructor, superConstructor)
  • util.inspect(object[, options])
    • Customizingutil.inspect colors
    • Custom inspection functions on Objects
    • util.inspect.custom
    • util.inspect.defaultOptions
  • util.promisify(original)
    • Custom promisified functions
    • util.promisify.custom
  • Class: util.TextDecoder
    • WHATWG Supported Encodings
      • Encodings Supported Without ICU
      • Encodings Supported by Default (With ICU)
      • Encodings Requiring Full ICU Data
    • new TextDecoder([encoding[, options]])
    • textDecoder.decode([input[, options]])
    • textDecoder.encoding
    • textDecoder.fatal
    • textDecoder.ignoreBOM
  • Class: util.TextEncoder
    • textEncoder.encode([input])
    • textEncoder.encoding
  • Deprecated APIs
    • util._extend(target, source)
    • util.debug(string)
    • util.error([...strings])
    • util.isArray(object)
    • util.isBoolean(object)
    • util.isBuffer(object)
    • util.isDate(object)
    • util.isError(object)
    • util.isFunction(object)
    • util.isNull(object)
    • util.isNullOrUndefined(object)
    • util.isNumber(object)
    • util.isObject(object)
    • util.isPrimitive(object)
    • util.isRegExp(object)
    • util.isString(object)
    • util.isSymbol(object)
    • util.isUndefined(object)
    • util.log(string)
    • util.print([...strings])
    • util.puts([...strings])

Util#

Theutil module is primarily designed to support the needs of Node.js' owninternal APIs. However, many of the utilities are useful for application andmodule developers as well. It can be accessed using:

const util = require('util');

util.callbackify(original)#

• original<Function> Anasync function
• Returns:<Function> a callback style function

Takes anasync function (or a function that returns a Promise) and returns afunction following the error-first callback style, i.e. takinga(err, value) => ... callback as the last argument. In the callback, thefirst argument will be the rejection reason (ornull if the Promiseresolved), and the second argument will be the resolved value.

For example:

const util = require('util');async function fn() {  return 'hello world';}const callbackFunction = util.callbackify(fn);callbackFunction((err, ret) => {  if (err) throw err;  console.log(ret);});

Will print:

hello world

Note:

• The callback is executed asynchronously, and will have a limited stack trace.If the callback throws, the process will emit an'uncaughtException'event, and if not handled will exit.

• Sincenull has a special meaning as the first argument to a callback, if awrapped function rejects aPromise with a falsy value as a reason, the valueis wrapped in anError with the original value stored in a field namedreason.

  function fn() {  return Promise.reject(null);}const callbackFunction = util.callbackify(fn);callbackFunction((err, ret) => {  // When the Promise was rejected with `null` it is wrapped with an Error and  // the original value is stored in `reason`.  err && err.hasOwnProperty('reason') && err.reason === null;  // true});

util.debuglog(section)#

• section<string> A string identifying the portion of the application forwhich thedebuglog function is being created.
• Returns:<Function> The logging function

Theutil.debuglog() method is used to create a function that conditionallywrites debug messages tostderr based on the existence of theNODE_DEBUGenvironment variable. If thesection name appears within the value of thatenvironment variable, then the returned function operates similar toconsole.error(). If not, then the returned function is a no-op.

For example:

const util = require('util');const debuglog = util.debuglog('foo');debuglog('hello from foo [%d]', 123);

If this program is run withNODE_DEBUG=foo in the environment, thenit will output something like:

FOO 3245: hello from foo [123]

where3245 is the process id. If it is not run with thatenvironment variable set, then it will not print anything.

Multiple comma-separatedsection names may be specified in theNODE_DEBUGenvironment variable. For example:NODE_DEBUG=fs,net,tls.

util.deprecate(function, string)#

Theutil.deprecate() method wraps the givenfunction or class in such a way thatit is marked as deprecated.

const util = require('util');exports.puts = util.deprecate(function() {  for (let i = 0, len = arguments.length; i < len; ++i) {    process.stdout.write(arguments[i] + '\n');  }}, 'util.puts: Use console.log instead');

When called,util.deprecate() will return a function that will emit aDeprecationWarning using theprocess.on('warning') event. By default,this warning will be emitted and printed tostderr exactly once, the firsttime it is called. After the warning is emitted, the wrappedfunctionis called.

If either the--no-deprecation or--no-warnings command line flags areused, or if theprocess.noDeprecation property is set totrueprior tothe first deprecation warning, theutil.deprecate() method does nothing.

If the--trace-deprecation or--trace-warnings command line flags are set,or theprocess.traceDeprecation property is set totrue, a warning and astack trace are printed tostderr the first time the deprecated function iscalled.

If the--throw-deprecation command line flag is set, or theprocess.throwDeprecation property is set totrue, then an exception will bethrown when the deprecated function is called.

The--throw-deprecation command line flag andprocess.throwDeprecationproperty take precedence over--trace-deprecation andprocess.traceDeprecation.

util.format(format[, ...args])#

• format<string> Aprintf-like format string.

Theutil.format() method returns a formatted string using the first argumentas aprintf-like format.

The first argument is a string containing zero or moreplaceholder tokens.Each placeholder token is replaced with the converted value from thecorresponding argument. Supported placeholders are:

• %s - String.
• %d - Number (integer or floating point value).
• %i - Integer.
• %f - Floating point value.
• %j - JSON. Replaced with the string'[Circular]' if the argumentcontains circular references.
• %o - Object. A string representation of an objectwith generic JavaScript object formatting.Similar toutil.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 objectwith generic JavaScript object formatting.Similar toutil.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.

If the placeholder does not have a corresponding argument, the placeholder isnot replaced.

util.format('%s:%s', 'foo');// Returns: 'foo:%s'

If there are more arguments passed to theutil.format() method than the numberof placeholders, the extra arguments are coerced into strings then concatenatedto the returned string, each delimited by a space. Excessive arguments whosetypeof is'object' or'symbol' (exceptnull) will be transformed byutil.inspect().

util.format('%s:%s', 'foo', 'bar', 'baz'); // 'foo:bar baz'

If the first argument is not a string thenutil.format() returnsa string that is the concatenation of all arguments separated by spaces.Each argument is converted to a string usingutil.inspect().

util.format(1, 2, 3); // '1 2 3'

If only one argument is passed toutil.format(), it is returned as it iswithout any formatting.

util.format('%% %s'); // '%% %s'

util.getSystemErrorName(err)#

• err<number>
• Returns:<string>

Returns the string name for a numeric error code that comes from a Node.js API.The mapping between error codes and error names is platform-dependent.SeeCommon System Errors for the names of common errors.

fs.access('file/that/does/not/exist', (err) => {  const name = util.getSystemErrorName(err.errno);  console.error(name);  // ENOENT});

util.inherits(constructor, superConstructor)#

Note: Usage ofutil.inherits() is discouraged. Please use the ES6classandextends keywords to get language level inheritance support. Also notethat the two styles aresemantically incompatible.

• constructor<Function>
• superConstructor<Function>

Inherit the prototype methods from oneconstructor into another. Theprototype ofconstructor will be set to a new object created fromsuperConstructor.

As an additional convenience,superConstructor will be accessiblethrough theconstructor.super_ property.

const util = require('util');const EventEmitter = require('events');function MyStream() {  EventEmitter.call(this);}util.inherits(MyStream, EventEmitter);MyStream.prototype.write = function(data) {  this.emit('data', data);};const stream = new MyStream();console.log(stream instanceof EventEmitter); // trueconsole.log(MyStream.super_ === EventEmitter); // truestream.on('data', (data) => {  console.log(`Received data: "${data}"`);});stream.write('It works!'); // Received data: "It works!"

ES6 example usingclass andextends

const EventEmitter = require('events');class MyStream extends EventEmitter {  write(data) {    this.emit('data', data);  }}const stream = new MyStream();stream.on('data', (data) => {  console.log(`Received data: "${data}"`);});stream.write('With ES6');

util.inspect(object[, options])#

• object<any> Any JavaScript primitive or Object.
• options<Object>
  • showHidden<boolean> Iftrue, theobject's non-enumerable symbols andproperties will be included in the formatted result.Default:false.
  • depth<number> Specifies the number of times to recurse while formattingtheobject. This is useful for inspecting large complicated objects.Defaults to2. To make it recurse indefinitely passnull.
  • colors<boolean> Iftrue, the output will be styled with ANSI colorcodes. Colors are customizable, seeCustomizingutil.inspect colors.Default:false.
  • customInspect<boolean> Iffalse, then custominspect(depth, opts)functions exported on theobject being inspected will not be called.Default:true.
  • showProxy<boolean> Iftrue, then objects and functions that areProxy objects will be introspected to show theirtarget andhandlerobjects.Default:false.
  • maxArrayLength<number> Specifies the maximum number of array andTypedArray elements to include when formatting. Set tonull to show allarray elements. Set to0 or negative to show no array elements.Default:100.
  • breakLength<number> The length at which an object's keys are splitacross multiple lines. Set toInfinity to format an object as a singleline.Default:60 for legacy compatibility.

Theutil.inspect() method returns a string representation ofobject that isprimarily useful for debugging. Additionaloptions may be passed that altercertain aspects of the formatted string.

The following example inspects all properties of theutil object:

const util = require('util');console.log(util.inspect(util, { showHidden: true, depth: null }));

Values may supply their own custominspect(depth, opts) functions, whencalled these receive the currentdepth in the recursive inspection, as well asthe options object passed toutil.inspect().

Customizingutil.inspect colors#

Color output (if enabled) ofutil.inspect is customizable globallyvia theutil.inspect.styles andutil.inspect.colors properties.

util.inspect.styles is a map associating a style name to a color fromutil.inspect.colors.

The default styles and associated colors are:

• number -yellow
• boolean -yellow
• string -green
• date -magenta
• regexp -red
• null -bold
• undefined -grey
• special -cyan (only applied to functions at this time)
• name - (no styling)

The predefined color codes are:white,grey,black,blue,cyan,green,magenta,red andyellow. There are alsobold,italic,underline andinverse codes.

Color styling uses ANSI control codes that may not be supported on allterminals.

Custom inspection functions on Objects#

Objects may also define their own[util.inspect.custom](depth, opts)(or the equivalent but deprecatedinspect(depth, opts)) function thatutil.inspect() will invoke and use the result of when inspecting the object:

const util = require('util');class Box {  constructor(value) {    this.value = value;  }  [util.inspect.custom](depth, options) {    if (depth < 0) {      return options.stylize('[Box]', 'special');    }    const newOptions = Object.assign({}, options, {      depth: options.depth === null ? null : options.depth - 1    });    // Five space padding because that's the size of "Box< ".    const padding = ' '.repeat(5);    const inner = util.inspect(this.value, newOptions)                      .replace(/\n/g, `\n${padding}`);    return `${options.stylize('Box', 'special')}< ${inner} >`;  }}const box = new Box(true);util.inspect(box);// Returns: "Box< true >"

Custom[util.inspect.custom](depth, opts) functions typically return a stringbut may return a value of any type that will be formatted accordingly byutil.inspect().

const util = require('util');const obj = { foo: 'this will not show up in the inspect() output' };obj[util.inspect.custom] = (depth) => {  return { bar: 'baz' };};util.inspect(obj);// Returns: "{ bar: 'baz' }"

util.inspect.custom#

A Symbol that can be used to declare custom inspect functions, seeCustom inspection functions on Objects.

util.inspect.defaultOptions#

ThedefaultOptions value allows customization of the default options used byutil.inspect. This is useful for functions likeconsole.log orutil.format which implicitly call intoutil.inspect. It shall be set to anobject containing one or more validutil.inspect() options. Settingoption properties directly is also supported.

const util = require('util');const arr = Array(101).fill(0);console.log(arr); // logs the truncated arrayutil.inspect.defaultOptions.maxArrayLength = null;console.log(arr); // logs the full array

util.promisify(original)#

• original<Function>
• Returns:<Function>

Takes a function following the common error-first callback style, i.e. takinga(err, value) => ... callback as the last argument, and returns a versionthat returns promises.

For example:

const util = require('util');const fs = require('fs');const stat = util.promisify(fs.stat);stat('.').then((stats) => {  // Do something with `stats`}).catch((error) => {  // Handle the error.});

Or, equivalently usingasync functions:

const util = require('util');const fs = require('fs');const stat = util.promisify(fs.stat);async function callStat() {  const stats = await stat('.');  console.log(`This directory is owned by ${stats.uid}`);}

If there is anoriginal[util.promisify.custom] property present,promisifywill return its value, seeCustom promisified functions.

promisify() assumes thatoriginal is a function taking a callback as itsfinal argument in all cases. Iforiginal is not a function,promisify()will throw an error. Iforiginal is a function but its last argument is notan error-first callback, it will still be passed an error-firstcallback as its last argument.

Custom promisified functions#

Using theutil.promisify.custom symbol one can override the return value ofutil.promisify():

const util = require('util');function doSomething(foo, callback) {  // ...}doSomething[util.promisify.custom] = (foo) => {  return getPromiseSomehow();};const promisified = util.promisify(doSomething);console.log(promisified === doSomething[util.promisify.custom]);// prints 'true'

This can be useful for cases where the original function does not follow thestandard format of taking an error-first callback as the last argument.

For example, with a function that takes in(foo, onSuccessCallback, onErrorCallback):

doSomething[util.promisify.custom] = (foo) => {  return new Promise((resolve, reject) => {    doSomething(foo, resolve, reject);  });};

Ifpromisify.custom is defined but is not a function,promisify() willthrow an error.

util.promisify.custom#

• <symbol>

A Symbol that can be used to declare custom promisified variants of functions,seeCustom promisified functions.

Class: util.TextDecoder#

An implementation of theWHATWG Encoding StandardTextDecoder API.

const decoder = new TextDecoder('shift_jis');let string = '';let buffer;while (buffer = getNextChunkSomehow()) {  string += decoder.decode(buffer, { stream: true });}string += decoder.decode(); // end-of-stream

WHATWG Supported Encodings#

Per theWHATWG Encoding Standard, the encodings supported by theTextDecoder API are outlined in the tables below. For each encoding,one or more aliases may be used.

Different Node.js build configurations support different sets of encodings.While a very basic set of encodings is supported even on Node.js builds withoutICU enabled, support for some encodings is provided only when Node.js is builtwith ICU and using the full ICU data (seeInternationalization).

Encodings Supported Without ICU#

Encodings Supported by Default (With ICU)#

Encodings Requiring Full ICU Data#

Note: The'iso-8859-16' encoding listed in theWHATWG Encoding Standardis not supported.

new TextDecoder([encoding[, options]])#

Creates an newTextDecoder instance. Theencoding may specify one of thesupported encodings or an alias.

textDecoder.decode([input[, options]])#

Decodes theinput and returns a string. Ifoptions.stream istrue, anyincomplete byte sequences occurring at the end of theinput are bufferedinternally and emitted after the next call totextDecoder.decode().

IftextDecoder.fatal istrue, decoding errors that occur will result in aTypeError being thrown.

textDecoder.encoding#

The encoding supported by theTextDecoder instance.

textDecoder.fatal#

The value will betrue if decoding errors result in aTypeError beingthrown.

textDecoder.ignoreBOM#

The value will betrue if the decoding result will include the byte ordermark.

Class: util.TextEncoder#

An implementation of theWHATWG Encoding StandardTextEncoder API. Allinstances ofTextEncoder only support UTF-8 encoding.

const encoder = new TextEncoder();const uint8array = encoder.encode('this is some data');

textEncoder.encode([input])#

UTF-8 encodes theinput string and returns aUint8Array containing theencoded bytes.

textEncoder.encoding#

The encoding supported by theTextEncoder instance. Always set to'utf-8'.

Deprecated APIs#

The following APIs have been deprecated and should no longer be used. Existingapplications and modules should be updated to find alternative approaches.

util._extend(target, source)#

Theutil._extend() method was never intended to be used outside of internalNode.js modules. The community found and used it anyway.

It is deprecated and should not be used in new code. JavaScript comes with verysimilar built-in functionality throughObject.assign().

util.debug(string)#

• string<string> The message to print tostderr

Deprecated predecessor ofconsole.error.

util.error([...strings])#

• ...strings<string> The message to print tostderr

Deprecated predecessor ofconsole.error.

util.isArray(object)#

• object<any>

Internal alias forArray.isArray.

Returnstrue if the givenobject is anArray. Otherwise, returnsfalse.

const util = require('util');util.isArray([]);// Returns: trueutil.isArray(new Array());// Returns: trueutil.isArray({});// Returns: false

util.isBoolean(object)#

• object<any>

Returnstrue if the givenobject is aBoolean. Otherwise, returnsfalse.

const util = require('util');util.isBoolean(1);// Returns: falseutil.isBoolean(0);// Returns: falseutil.isBoolean(false);// Returns: true

util.isBuffer(object)#

• object<any>

Returnstrue if the givenobject is aBuffer. Otherwise, returnsfalse.

const util = require('util');util.isBuffer({ length: 0 });// Returns: falseutil.isBuffer([]);// Returns: falseutil.isBuffer(Buffer.from('hello world'));// Returns: true

util.isDate(object)#

• object<any>

Returnstrue if the givenobject is aDate. Otherwise, returnsfalse.

const util = require('util');util.isDate(new Date());// Returns: trueutil.isDate(Date());// false (without 'new' returns a String)util.isDate({});// Returns: false

util.isError(object)#

• object<any>

Returnstrue if the givenobject is anError. Otherwise, returnsfalse.

const util = require('util');util.isError(new Error());// Returns: trueutil.isError(new TypeError());// Returns: trueutil.isError({ name: 'Error', message: 'an error occurred' });// Returns: false

Note that this method relies onObject.prototype.toString() behavior. It ispossible to obtain an incorrect result when theobject argument manipulates@@toStringTag.

const util = require('util');const obj = { name: 'Error', message: 'an error occurred' };util.isError(obj);// Returns: falseobj[Symbol.toStringTag] = 'Error';util.isError(obj);// Returns: true

util.isFunction(object)#

• object<any>

Returnstrue if the givenobject is aFunction. Otherwise, returnsfalse.

const util = require('util');function Foo() {}const Bar = () => {};util.isFunction({});// Returns: falseutil.isFunction(Foo);// Returns: trueutil.isFunction(Bar);// Returns: true

util.isNull(object)#

• object<any>

Returnstrue if the givenobject is strictlynull. Otherwise, returnsfalse.

const util = require('util');util.isNull(0);// Returns: falseutil.isNull(undefined);// Returns: falseutil.isNull(null);// Returns: true

util.isNullOrUndefined(object)#

• object<any>

Returnstrue if the givenobject isnull orundefined. Otherwise,returnsfalse.

const util = require('util');util.isNullOrUndefined(0);// Returns: falseutil.isNullOrUndefined(undefined);// Returns: trueutil.isNullOrUndefined(null);// Returns: true

util.isNumber(object)#

• object<any>

Returnstrue if the givenobject is aNumber. Otherwise, returnsfalse.

const util = require('util');util.isNumber(false);// Returns: falseutil.isNumber(Infinity);// Returns: trueutil.isNumber(0);// Returns: trueutil.isNumber(NaN);// Returns: true

util.isObject(object)#

• object<any>

Returnstrue if the givenobject is strictly anObjectand not aFunction. Otherwise, returnsfalse.

const util = require('util');util.isObject(5);// Returns: falseutil.isObject(null);// Returns: falseutil.isObject({});// Returns: trueutil.isObject(function() {});// Returns: false

util.isPrimitive(object)#

• object<any>

Returnstrue if the givenobject is a primitive type. Otherwise, returnsfalse.

const util = require('util');util.isPrimitive(5);// Returns: trueutil.isPrimitive('foo');// Returns: trueutil.isPrimitive(false);// Returns: trueutil.isPrimitive(null);// Returns: trueutil.isPrimitive(undefined);// Returns: trueutil.isPrimitive({});// Returns: falseutil.isPrimitive(function() {});// Returns: falseutil.isPrimitive(/^$/);// Returns: falseutil.isPrimitive(new Date());// Returns: false

util.isRegExp(object)#

• object<any>

Returnstrue if the givenobject is aRegExp. Otherwise, returnsfalse.

const util = require('util');util.isRegExp(/some regexp/);// Returns: trueutil.isRegExp(new RegExp('another regexp'));// Returns: trueutil.isRegExp({});// Returns: false

util.isString(object)#

• object<any>

Returnstrue if the givenobject is astring. Otherwise, returnsfalse.

const util = require('util');util.isString('');// Returns: trueutil.isString('foo');// Returns: trueutil.isString(String('foo'));// Returns: trueutil.isString(5);// Returns: false

util.isSymbol(object)#

• object<any>

Returnstrue if the givenobject is aSymbol. Otherwise, returnsfalse.

const util = require('util');util.isSymbol(5);// Returns: falseutil.isSymbol('foo');// Returns: falseutil.isSymbol(Symbol('foo'));// Returns: true

util.isUndefined(object)#

• object<any>

Returnstrue if the givenobject isundefined. Otherwise, returnsfalse.

const util = require('util');const foo = undefined;util.isUndefined(5);// Returns: falseutil.isUndefined(foo);// Returns: trueutil.isUndefined(null);// Returns: false

util.log(string)#

• string<string>

Theutil.log() method prints the givenstring tostdout with an includedtimestamp.

const util = require('util');util.log('Timestamped message.');

util.print([...strings])#

Deprecated predecessor ofconsole.log.

util.puts([...strings])#

Deprecated predecessor ofconsole.log.