{ "source": "doc/api/util.md", "modules": [ { "textRaw": "util", "name": "util", "stability": 2, "stabilityText": "Stable", "desc": "

The util module is primarily designed to support the needs of Node.js' own\ninternal APIs. However, many of the utilities are useful for application and\nmodule developers as well. It can be accessed using:

\n
const util = require('util');\n
\n", "methods": [ { "textRaw": "util.debuglog(section)", "type": "method", "name": "debuglog", "signatures": [ { "return": { "textRaw": "Returns: {Function} The logging function ", "name": "return", "type": "Function", "desc": "The logging function" }, "params": [ { "textRaw": "`section` {String} A string identifying the portion of the application for which the `debuglog` function is being created. ", "name": "section", "type": "String", "desc": "A string identifying the portion of the application for which the `debuglog` function is being created." } ] }, { "params": [ { "name": "section" } ] } ], "desc": "

The util.debuglog() method is used to create a function that conditionally\nwrites debug messages to stderr based on the existence of the NODE_DEBUG\nenvironment variable. If the section name appears within the value of that\nenvironment variable, then the returned function operates similar to\nconsole.error(). If not, then the returned function is a no-op.

\n

For example:

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

If this program is run with NODE_DEBUG=foo in the environment, then\nit will output something like:

\n
FOO 3245: hello from foo [123]\n

where 3245 is the process id. If it is not run with that\nenvironment variable set, then it will not print anything.

\n

Multiple comma-separated section names may be specified in the NODE_DEBUG\nenvironment variable. For example: NODE_DEBUG=fs,net,tls.

\n" }, { "textRaw": "util.deprecate(function, string)", "type": "method", "name": "deprecate", "desc": "

The util.deprecate() method wraps the given function in such a way that\nit is marked as deprecated.

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

When called, util.deprecate() will return a function that will emit a\nDeprecationWarning using the process.on('warning') event. By default,\nthis warning will be emitted and printed to stderr exactly once, the first\ntime it is called. After the warning is emitted, the wrapped function\nis called.

\n

If either the --no-deprecation or --no-warnings command line flags are\nused, or if the process.noDeprecation property is set to true prior to\nthe first deprecation warning, the util.deprecate() method does nothing.

\n

If the --trace-deprecation or --trace-warnings command line flags are set,\nor the process.traceDeprecation property is set to true, a warning and a\nstack trace are printed to stderr the first time the deprecated function is\ncalled.

\n

If the --throw-deprecation command line flag is set, or the\nprocess.throwDeprecation property is set to true, then an exception will be\nthrown when the deprecated function is called.

\n

The --throw-deprecation command line flag and process.throwDeprecation\nproperty take precedence over --trace-deprecation and\nprocess.traceDeprecation.

\n", "signatures": [ { "params": [ { "name": "function" }, { "name": "string" } ] } ] }, { "textRaw": "util.format(format[, ...])", "type": "method", "name": "format", "signatures": [ { "params": [ { "textRaw": "`format` {string} A `printf`-like format string. ", "name": "format", "type": "string", "desc": "A `printf`-like format string." }, { "name": "...", "optional": true } ] }, { "params": [ { "name": "format" }, { "name": "...", "optional": true } ] } ], "desc": "

The util.format() method returns a formatted string using the first argument\nas a printf-like format.

\n

The first argument is a string containing zero or more placeholder tokens.\nEach placeholder token is replaced with the converted value from the\ncorresponding argument. Supported placeholders are:

\n\n

If the placeholder does not have a corresponding argument, the placeholder is\nnot replaced.

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

If there are more arguments passed to the util.format() method than the\nnumber of placeholders, the extra arguments are coerced into strings (for\nobjects and symbols, util.inspect() is used) then concatenated to the\nreturned string, each delimited by a space.

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

If the first argument is not a format string then util.format() returns\na string that is the concatenation of all arguments separated by spaces.\nEach argument is converted to a string using util.inspect().

\n
util.format(1, 2, 3); // '1 2 3'\n
\n" }, { "textRaw": "util.inherits(constructor, superConstructor)", "type": "method", "name": "inherits", "desc": "

Note: usage of util.inherits() is discouraged. Please use the ES6 class and\nextends keywords to get language level inheritance support. Also note that\nthe two styles are [semantically incompatible][].

\n\n

Inherit the prototype methods from one [constructor][] into another. The\nprototype of constructor will be set to a new object created from\nsuperConstructor.

\n

As an additional convenience, superConstructor will be accessible\nthrough the constructor.super_ property.

\n
const util = require('util');\nconst EventEmitter = require('events');\n\nfunction MyStream() {\n  EventEmitter.call(this);\n}\n\nutil.inherits(MyStream, EventEmitter);\n\nMyStream.prototype.write = function(data) {\n  this.emit('data', data);\n};\n\nconst stream = new MyStream();\n\nconsole.log(stream instanceof EventEmitter); // true\nconsole.log(MyStream.super_ === EventEmitter); // true\n\nstream.on('data', (data) => {\n  console.log(`Received data: "${data}"`);\n});\nstream.write('It works!'); // Received data: "It works!"\n
\n", "signatures": [ { "params": [ { "name": "constructor" }, { "name": "superConstructor" } ] } ] }, { "textRaw": "util.inspect(object[, options])", "type": "method", "name": "inspect", "signatures": [ { "params": [ { "textRaw": "`object` {any} Any JavaScript primitive or Object. ", "name": "object", "type": "any", "desc": "Any JavaScript primitive or Object." }, { "textRaw": "`options` {Object} ", "options": [ { "textRaw": "`showHidden` {boolean} If `true`, the `object`'s non-enumerable symbols and properties will be included in the formatted result. Defaults to `false`. ", "name": "showHidden", "type": "boolean", "desc": "If `true`, the `object`'s non-enumerable symbols and properties will be included in the formatted result. Defaults to `false`." }, { "textRaw": "`depth` {number} Specifies the number of times to recurse while formatting the `object`. This is useful for inspecting large complicated objects. Defaults to `2`. To make it recurse indefinitely pass `null`. ", "name": "depth", "type": "number", "desc": "Specifies the number of times to recurse while formatting the `object`. This is useful for inspecting large complicated objects. Defaults to `2`. To make it recurse indefinitely pass `null`." }, { "textRaw": "`colors` {boolean} If `true`, the output will be styled with ANSI color codes. Defaults to `false`. Colors are customizable, see [Customizing `util.inspect` colors][]. ", "name": "colors", "type": "boolean", "desc": "If `true`, the output will be styled with ANSI color codes. Defaults to `false`. Colors are customizable, see [Customizing `util.inspect` colors][]." }, { "textRaw": "`customInspect` {boolean} If `false`, then custom `inspect(depth, opts)` functions exported on the `object` being inspected will not be called. Defaults to `true`. ", "name": "customInspect", "type": "boolean", "desc": "If `false`, then custom `inspect(depth, opts)` functions exported on the `object` being inspected will not be called. Defaults to `true`." }, { "textRaw": "`showProxy` {boolean} If `true`, then objects and functions that are `Proxy` objects will be introspected to show their `target` and `handler` objects. Defaults to `false`. ", "name": "showProxy", "type": "boolean", "desc": "If `true`, then objects and functions that are `Proxy` objects will be introspected to show their `target` and `handler` objects. Defaults to `false`." }, { "textRaw": "`maxArrayLength` {number} Specifies the maximum number of array and `TypedArray` elements to include when formatting. Defaults to `100`. Set to `null` to show all array elements. Set to `0` or negative to show no array elements. ", "name": "maxArrayLength", "type": "number", "desc": "Specifies the maximum number of array and `TypedArray` elements to include when formatting. Defaults to `100`. Set to `null` to show all array elements. Set to `0` or negative to show no array elements." }, { "textRaw": "`breakLength` {number} The length at which an object's keys are split across multiple lines. Set to `Infinity` to format an object as a single line. Defaults to 60 for legacy compatibility. ", "name": "breakLength", "type": "number", "desc": "The length at which an object's keys are split across multiple lines. Set to `Infinity` to format an object as a single line. Defaults to 60 for legacy compatibility." } ], "name": "options", "type": "Object", "optional": true } ] }, { "params": [ { "name": "object" }, { "name": "options", "optional": true } ] } ], "desc": "

The util.inspect() method returns a string representation of object that is\nprimarily useful for debugging. Additional options may be passed that alter\ncertain aspects of the formatted string.

\n

The following example inspects all properties of the util object:

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

Values may supply their own custom inspect(depth, opts) functions, when\ncalled these receive the current depth in the recursive inspection, as well as\nthe options object passed to util.inspect().

\n", "miscs": [ { "textRaw": "Customizing `util.inspect` colors", "name": "Customizing `util.inspect` colors", "type": "misc", "desc": "

Color output (if enabled) of util.inspect is customizable globally\nvia the util.inspect.styles and util.inspect.colors properties.

\n

util.inspect.styles is a map associating a style name to a color from\nutil.inspect.colors.

\n

The default styles and associated colors are:

\n\n

The predefined color codes are: white, grey, black, blue, cyan,\ngreen, magenta, red and yellow. There are also bold, italic,\nunderline and inverse codes.

\n

Color styling uses ANSI control codes that may not be supported on all\nterminals.

\n" }, { "textRaw": "Custom `inspect()` function on Objects", "name": "Custom `inspect()` function on Objects", "type": "misc", "desc": "

Objects may also define their own inspect(depth, opts) function that\nutil.inspect() will invoke and use the result of when inspecting the object:

\n
const util = require('util');\n\nconst obj = { name: 'nate' };\nobj.inspect = function(depth) {\n  return `{${this.name}}`;\n};\n\nutil.inspect(obj);\n  // "{nate}"\n
\n

Custom inspect(depth, opts) functions typically return a string but may\nreturn a value of any type that will be formatted accordingly by\nutil.inspect().

\n
const util = require('util');\n\nconst obj = { foo: 'this will not show up in the inspect() output' };\nobj.inspect = function(depth) {\n  return { bar: 'baz' };\n};\n\nutil.inspect(obj);\n  // "{ bar: 'baz' }"\n
\n" } ] } ], "modules": [ { "textRaw": "Deprecated APIs", "name": "deprecated_apis", "desc": "

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

\n", "methods": [ { "textRaw": "util.debug(string)", "type": "method", "name": "debug", "stability": 0, "stabilityText": "Deprecated: Use [`console.error()`][] instead.", "signatures": [ { "params": [ { "textRaw": "`string` {string} The message to print to `stderr` ", "name": "string", "type": "string", "desc": "The message to print to `stderr`" } ] }, { "params": [ { "name": "string" } ] } ], "desc": "

Deprecated predecessor of console.error.

\n" }, { "textRaw": "util.error([...])", "type": "method", "name": "error", "stability": 0, "stabilityText": "Deprecated: Use [`console.error()`][] instead.", "signatures": [ { "params": [ { "textRaw": "`string` {string} The message to print to `stderr` ", "name": "string", "type": "string", "desc": "The message to print to `stderr`", "optional": true } ] }, { "params": [ { "name": "...", "optional": true } ] } ], "desc": "

Deprecated predecessor of console.error.

\n" }, { "textRaw": "util.isArray(object)", "type": "method", "name": "isArray", "stability": 0, "stabilityText": "Deprecated", "signatures": [ { "params": [ { "textRaw": "`object` {any} ", "name": "object", "type": "any" } ] }, { "params": [ { "name": "object" } ] } ], "desc": "

Internal alias for [Array.isArray][].

\n

Returns true if the given object is an Array. Otherwise, returns false.

\n
const util = require('util');\n\nutil.isArray([]);\n  // true\nutil.isArray(new Array);\n  // true\nutil.isArray({});\n  // false\n
\n" }, { "textRaw": "util.isBoolean(object)", "type": "method", "name": "isBoolean", "stability": 0, "stabilityText": "Deprecated", "signatures": [ { "params": [ { "textRaw": "`object` {any} ", "name": "object", "type": "any" } ] }, { "params": [ { "name": "object" } ] } ], "desc": "

Returns true if the given object is a Boolean. Otherwise, returns false.

\n
const util = require('util');\n\nutil.isBoolean(1);\n  // false\nutil.isBoolean(0);\n  // false\nutil.isBoolean(false);\n  // true\n
\n" }, { "textRaw": "util.isBuffer(object)", "type": "method", "name": "isBuffer", "stability": 0, "stabilityText": "Deprecated: Use [`Buffer.isBuffer()`][] instead.", "signatures": [ { "params": [ { "textRaw": "`object` {any} ", "name": "object", "type": "any" } ] }, { "params": [ { "name": "object" } ] } ], "desc": "

Returns true if the given object is a Buffer. Otherwise, returns false.

\n
const util = require('util');\n\nutil.isBuffer({ length: 0 });\n  // false\nutil.isBuffer([]);\n  // false\nutil.isBuffer(Buffer.from('hello world'));\n  // true\n
\n" }, { "textRaw": "util.isDate(object)", "type": "method", "name": "isDate", "stability": 0, "stabilityText": "Deprecated", "signatures": [ { "params": [ { "textRaw": "`object` {any} ", "name": "object", "type": "any" } ] }, { "params": [ { "name": "object" } ] } ], "desc": "

Returns true if the given object is a Date. Otherwise, returns false.

\n
const util = require('util');\n\nutil.isDate(new Date());\n  // true\nutil.isDate(Date());\n  // false (without 'new' returns a String)\nutil.isDate({});\n  // false\n
\n" }, { "textRaw": "util.isError(object)", "type": "method", "name": "isError", "stability": 0, "stabilityText": "Deprecated", "signatures": [ { "params": [ { "textRaw": "`object` {any} ", "name": "object", "type": "any" } ] }, { "params": [ { "name": "object" } ] } ], "desc": "

Returns true if the given object is an [Error][]. Otherwise, returns\nfalse.

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

Note that this method relies on Object.prototype.toString() behavior. It is\npossible to obtain an incorrect result when the object argument manipulates\n@@toStringTag.

\n
const util = require('util');\nconst obj = { name: 'Error', message: 'an error occurred' };\n\nutil.isError(obj);\n  // false\nobj[Symbol.toStringTag] = 'Error';\nutil.isError(obj);\n  // true\n
\n" }, { "textRaw": "util.isFunction(object)", "type": "method", "name": "isFunction", "stability": 0, "stabilityText": "Deprecated", "signatures": [ { "params": [ { "textRaw": "`object` {any} ", "name": "object", "type": "any" } ] }, { "params": [ { "name": "object" } ] } ], "desc": "

Returns true if the given object is a Function. Otherwise, returns\nfalse.

\n
const util = require('util');\n\nfunction Foo() {}\nconst Bar = function() {};\n\nutil.isFunction({});\n  // false\nutil.isFunction(Foo);\n  // true\nutil.isFunction(Bar);\n  // true\n
\n" }, { "textRaw": "util.isNull(object)", "type": "method", "name": "isNull", "stability": 0, "stabilityText": "Deprecated", "signatures": [ { "params": [ { "textRaw": "`object` {any} ", "name": "object", "type": "any" } ] }, { "params": [ { "name": "object" } ] } ], "desc": "

Returns true if the given object is strictly null. Otherwise, returns\nfalse.

\n
const util = require('util');\n\nutil.isNull(0);\n  // false\nutil.isNull(undefined);\n  // false\nutil.isNull(null);\n  // true\n
\n" }, { "textRaw": "util.isNullOrUndefined(object)", "type": "method", "name": "isNullOrUndefined", "stability": 0, "stabilityText": "Deprecated", "signatures": [ { "params": [ { "textRaw": "`object` {any} ", "name": "object", "type": "any" } ] }, { "params": [ { "name": "object" } ] } ], "desc": "

Returns true if the given object is null or undefined. Otherwise,\nreturns false.

\n
const util = require('util');\n\nutil.isNullOrUndefined(0);\n  // false\nutil.isNullOrUndefined(undefined);\n  // true\nutil.isNullOrUndefined(null);\n  // true\n
\n" }, { "textRaw": "util.isNumber(object)", "type": "method", "name": "isNumber", "stability": 0, "stabilityText": "Deprecated", "signatures": [ { "params": [ { "textRaw": "`object` {any} ", "name": "object", "type": "any" } ] }, { "params": [ { "name": "object" } ] } ], "desc": "

Returns true if the given object is a Number. Otherwise, returns false.

\n
const util = require('util');\n\nutil.isNumber(false);\n  // false\nutil.isNumber(Infinity);\n  // true\nutil.isNumber(0);\n  // true\nutil.isNumber(NaN);\n  // true\n
\n" }, { "textRaw": "util.isObject(object)", "type": "method", "name": "isObject", "stability": 0, "stabilityText": "Deprecated", "signatures": [ { "params": [ { "textRaw": "`object` {any} ", "name": "object", "type": "any" } ] }, { "params": [ { "name": "object" } ] } ], "desc": "

Returns true if the given object is strictly an Object and not a\nFunction. Otherwise, returns false.

\n
const util = require('util');\n\nutil.isObject(5);\n  // false\nutil.isObject(null);\n  // false\nutil.isObject({});\n  // true\nutil.isObject(function(){});\n  // false\n
\n" }, { "textRaw": "util.isPrimitive(object)", "type": "method", "name": "isPrimitive", "stability": 0, "stabilityText": "Deprecated", "signatures": [ { "params": [ { "textRaw": "`object` {any} ", "name": "object", "type": "any" } ] }, { "params": [ { "name": "object" } ] } ], "desc": "

Returns true if the given object is a primitive type. Otherwise, returns\nfalse.

\n
const util = require('util');\n\nutil.isPrimitive(5);\n  // true\nutil.isPrimitive('foo');\n  // true\nutil.isPrimitive(false);\n  // true\nutil.isPrimitive(null);\n  // true\nutil.isPrimitive(undefined);\n  // true\nutil.isPrimitive({});\n  // false\nutil.isPrimitive(function() {});\n  // false\nutil.isPrimitive(/^$/);\n  // false\nutil.isPrimitive(new Date());\n  // false\n
\n" }, { "textRaw": "util.isRegExp(object)", "type": "method", "name": "isRegExp", "stability": 0, "stabilityText": "Deprecated", "signatures": [ { "params": [ { "textRaw": "`object` {any} ", "name": "object", "type": "any" } ] }, { "params": [ { "name": "object" } ] } ], "desc": "

Returns true if the given object is a RegExp. Otherwise, returns false.

\n
const util = require('util');\n\nutil.isRegExp(/some regexp/);\n  // true\nutil.isRegExp(new RegExp('another regexp'));\n  // true\nutil.isRegExp({});\n  // false\n
\n" }, { "textRaw": "util.isString(object)", "type": "method", "name": "isString", "stability": 0, "stabilityText": "Deprecated", "signatures": [ { "params": [ { "textRaw": "`object` {any} ", "name": "object", "type": "any" } ] }, { "params": [ { "name": "object" } ] } ], "desc": "

Returns true if the given object is a string. Otherwise, returns false.

\n
const util = require('util');\n\nutil.isString('');\n  // true\nutil.isString('foo');\n  // true\nutil.isString(String('foo'));\n  // true\nutil.isString(5);\n  // false\n
\n" }, { "textRaw": "util.isSymbol(object)", "type": "method", "name": "isSymbol", "stability": 0, "stabilityText": "Deprecated", "signatures": [ { "params": [ { "textRaw": "`object` {any} ", "name": "object", "type": "any" } ] }, { "params": [ { "name": "object" } ] } ], "desc": "

Returns true if the given object is a Symbol. Otherwise, returns false.

\n
const util = require('util');\n\nutil.isSymbol(5);\n  // false\nutil.isSymbol('foo');\n  // false\nutil.isSymbol(Symbol('foo'));\n  // true\n
\n" }, { "textRaw": "util.isUndefined(object)", "type": "method", "name": "isUndefined", "stability": 0, "stabilityText": "Deprecated", "signatures": [ { "params": [ { "textRaw": "`object` {any} ", "name": "object", "type": "any" } ] }, { "params": [ { "name": "object" } ] } ], "desc": "

Returns true if the given object is undefined. Otherwise, returns false.

\n
const util = require('util');\n\nconst foo = undefined;\nutil.isUndefined(5);\n  // false\nutil.isUndefined(foo);\n  // true\nutil.isUndefined(null);\n  // false\n
\n" }, { "textRaw": "util.log(string)", "type": "method", "name": "log", "stability": 0, "stabilityText": "Deprecated: Use a third party module instead.", "signatures": [ { "params": [ { "textRaw": "`string` {string} ", "name": "string", "type": "string" } ] }, { "params": [ { "name": "string" } ] } ], "desc": "

The util.log() method prints the given string to stdout with an included\ntimestamp.

\n
const util = require('util');\n\nutil.log('Timestamped message.');\n
\n" }, { "textRaw": "util.print([...])", "type": "method", "name": "print", "stability": 0, "stabilityText": "Deprecated: Use [`console.log()`][] instead.", "desc": "

Deprecated predecessor of console.log.

\n", "signatures": [ { "params": [ { "name": "...", "optional": true } ] } ] }, { "textRaw": "util.puts([...])", "type": "method", "name": "puts", "stability": 0, "stabilityText": "Deprecated: Use [`console.log()`][] instead.", "desc": "

Deprecated predecessor of console.log.

\n", "signatures": [ { "params": [ { "name": "...", "optional": true } ] } ] }, { "textRaw": "util._extend(obj)", "type": "method", "name": "_extend", "stability": 0, "stabilityText": "Deprecated: Use [`Object.assign()`] instead.", "desc": "

The util._extend() method was never intended to be used outside of internal\nNode.js modules. The community found and used it anyway.

\n

It is deprecated and should not be used in new code. JavaScript comes with very\nsimilar built-in functionality through [Object.assign()].

\n", "signatures": [ { "params": [ { "name": "obj" } ] } ] } ], "type": "module", "displayName": "Deprecated APIs" } ], "type": "module", "displayName": "util" } ] }