Util#
Source Code: lib/util.js
The node:util module supports the needs of Node.js internal APIs. Many of the
utilities are useful for application and module developers as well. To access
it:
import util from 'node:util';const util = require('node:util');
util.callbackify(original)#
Added in: v8.2.0
Takes an async function (or a function that returns a Promise) and returns a
function following the error-first callback style, i.e. taking
an (err, value) => ... callback as the last argument. In the callback, the
first argument will be the rejection reason (or null if the Promise
resolved), and the second argument will be the resolved value.
import { callbackify } from 'node:util';
async function fn() {
return 'hello world';
}
const callbackFunction = callbackify(fn);
callbackFunction((err, ret) => {
if (err) throw err;
console.log(ret);
});const { callbackify } = require('node:util');
async function fn() {
return 'hello world';
}
const callbackFunction = callbackify(fn);
callbackFunction((err, ret) => {
if (err) throw err;
console.log(ret);
});
Will print:
hello world
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.
Since null has a special meaning as the first argument to a callback, if a
wrapped function rejects a Promise with a falsy value as a reason, the value
is wrapped in an Error with the original value stored in a field named
reason.
function fn() {
return Promise.reject(null);
}
const callbackFunction = util.callbackify(fn);
callbackFunction((err, ret) => {
err && Object.hasOwn(err, 'reason') && err.reason === null;
});
util.debuglog(section[, callback])#
Added in: v0.11.3
section <string> A string identifying the portion of the application for
which the debuglog function is being created.
callback <Function> A callback invoked the first time the logging function
is called with a function argument that is a more optimized logging function.
- Returns: <Function> The logging function
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 similar to
console.error(). If not, then the returned function is a no-op.
import { debuglog } from 'node:util';
const log = debuglog('foo');
log('hello from foo [%d]', 123);const { debuglog } = require('node:util');
const log = debuglog('foo');
log('hello from foo [%d]', 123);
If this program is run with NODE_DEBUG=foo in the environment, then
it will output something like:
FOO 3245: hello from foo [123]
where 3245 is the process id. If it is not run with that
environment variable set, then it will not print anything.
The section supports wildcard also:
import { debuglog } from 'node:util';
const log = debuglog('foo');
log('hi there, it\'s foo-bar [%d]', 2333);const { debuglog } = require('node:util');
const log = debuglog('foo');
log('hi there, it\'s foo-bar [%d]', 2333);
if it is run with NODE_DEBUG=foo* in the environment, then it will output
something like:
FOO-BAR 3257: hi there, it's foo-bar [2333]
Multiple comma-separated section names may be specified in the NODE_DEBUG
environment variable: NODE_DEBUG=fs,net,tls.
The optional callback argument can be used to replace the logging function
with a different function that doesn't have any initialization or
unnecessary wrapping.
import { debuglog } from 'node:util';
let log = debuglog('internals', (debug) => {
log = debug;
});const { debuglog } = require('node:util');
let log = debuglog('internals', (debug) => {
log = debug;
});
debuglog().enabled#
Added in: v14.9.0
The util.debuglog().enabled getter is used to create a test that can be used
in conditionals 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 value will be true. If not, then the returned value will be
false.
import { debuglog } from 'node:util';
const enabled = debuglog('foo').enabled;
if (enabled) {
console.log('hello from foo [%d]', 123);
}const { debuglog } = require('node:util');
const enabled = debuglog('foo').enabled;
if (enabled) {
console.log('hello from foo [%d]', 123);
}
If this program is run with NODE_DEBUG=foo in the environment, then it will
output something like:
hello from foo [123]
util.debug(section)#
Added in: v14.9.0
Alias for util.debuglog. Usage allows for readability of that doesn't imply
logging when only using util.debuglog().enabled.
util.deprecate(fn, msg[, code])#
The util.deprecate() method wraps fn (which may be a function or class) in
such a way that it is marked as deprecated.
import { deprecate } from 'node:util';
export const obsoleteFunction = deprecate(() => {
}, 'obsoleteFunction() is deprecated. Use newShinyFunction() instead.');const { deprecate } = require('node:util');
exports.obsoleteFunction = deprecate(() => {
}, 'obsoleteFunction() is deprecated. Use newShinyFunction() instead.');
When called, util.deprecate() will return a function that will emit a
DeprecationWarning using the 'warning' event. The warning will
be emitted and printed to stderr the first time the returned function is
called. After the warning is emitted, the wrapped function is called without
emitting a warning.
If the same optional code is supplied in multiple calls to util.deprecate(),
the warning will be emitted only once for that code.
import { deprecate } from 'node:util';
const fn1 = deprecate(
() => 'a value',
'deprecation message',
'DEP0001',
);
const fn2 = deprecate(
() => 'a different value',
'other dep message',
'DEP0001',
);
fn1();
fn2(); const { deprecate } = require('node:util');
const fn1 = deprecate(
function() {
return 'a value';
},
'deprecation message',
'DEP0001',
);
const fn2 = deprecate(
function() {
return 'a different value';
},
'other dep message',
'DEP0001',
);
fn1();
fn2();
If either the --no-deprecation or --no-warnings command-line flags are
used, or if the process.noDeprecation property is set to true prior to
the first deprecation warning, the util.deprecate() method does nothing.
If the --trace-deprecation or --trace-warnings command-line flags are set,
or the process.traceDeprecation property is set to true, a warning and a
stack trace are printed to stderr the first time the deprecated function is
called.
If the --throw-deprecation command-line flag is set, or the
process.throwDeprecation property is set to true, then an exception will be
thrown when the deprecated function is called.
The --throw-deprecation command-line flag and process.throwDeprecation
property take precedence over --trace-deprecation and
process.traceDeprecation.
util.diff(actual, expected)#
Added in: v22.15.0
-
actual <Array> | <string> The first value to compare
-
expected <Array> | <string> The second value to compare
-
Returns: <Array> An array of difference entries. Each entry is an array with two elements:
0 <number> Operation code: -1 for delete, 0 for no-op/unchanged, 1 for insert
1 <string> The value associated with the operation
-
Algorithm complexity: O(N*D), where:
-
N is the total length of the two sequences combined (N = actual.length + expected.length)
-
D is the edit distance (the minimum number of operations required to transform one sequence into the other).
util.diff() compares two string or array values and returns an array of difference entries.
It uses the Myers diff algorithm to compute minimal differences, which is the same algorithm
used internally by assertion error messages.
If the values are equal, an empty array is returned.
const { diff } = require('node:util');
const actualString = '12345678';
const expectedString = '12!!5!7!';
console.log(diff(actualString, expectedString));
const actualArray = ['1', '2', '3'];
const expectedArray = ['1', '3', '4'];
console.log(diff(actualArray, expectedArray));
console.log(diff('same', 'same'));
util.format(format[, ...args])#
format <string> A printf-like format string.
The util.format() method returns a formatted string using the first argument
as a printf-like format string which can contain zero or more format
specifiers. Each specifier is replaced with the converted value from the
corresponding argument. Supported specifiers are:
%s: String will be used to convert all values except BigInt, Object
and -0. BigInt values will be represented with an n and Objects that
have neither a user defined toString function nor Symbol.toPrimitive function are inspected using util.inspect()
with options { depth: 0, colors: false, compact: 3 }.
%d: Number will be used to convert all values except BigInt and
Symbol.
%i: parseInt(value, 10) is used for all values except BigInt and
Symbol.
%f: parseFloat(value) is used for all values expect Symbol.
%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, showProxy: true }. This will show the full object
including non-enumerable properties and proxies.
%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 properties and proxies.
%c: CSS. This specifier is ignored and will skip any CSS passed in.
%%: single percent sign ('%'). This does not consume an argument.
- Returns: <string> The formatted string
If a specifier does not have a corresponding argument, it is not replaced:
util.format('%s:%s', 'foo');
Values that are not part of the format string are formatted using
util.inspect() if their type is not string.
If there are more arguments passed to the util.format() method than the
number of specifiers, the extra arguments are concatenated to the returned
string, separated by spaces:
util.format('%s:%s', 'foo', 'bar', 'baz');
If the first argument does not contain a valid format specifier, util.format()
returns a string that is the concatenation of all arguments separated by spaces:
util.format(1, 2, 3);
If only one argument is passed to util.format(), it is returned as it is
without any formatting:
util.format('%% %s');
util.format() is a synchronous method that is intended as a debugging tool.
Some input values can have a significant performance overhead that can block the
event loop. Use this function with care and never in a hot code path.
util.formatWithOptions(inspectOptions, format[, ...args])#
Added in: v10.0.0
This function is identical to util.format(), except in that it takes
an inspectOptions argument which specifies options that are passed along to
util.inspect().
util.formatWithOptions({ colors: true }, 'See object %O', { foo: 42 });
util.getCallSites([frameCount][, options])#
frameCount <number> Optional number of frames to capture as call site objects.
Default: 10. Allowable range is between 1 and 200.
options <Object> Optional
sourceMap <boolean> Reconstruct the original location in the stacktrace from the source-map.
Enabled by default with the flag --enable-source-maps.
- Returns: <Object[]> An array of call site objects
functionName <string> Returns the name of the function associated with this call site.
scriptName <string> Returns the name of the resource that contains the script for the
function for this call site.
scriptId <string> Returns the unique id of the script, as in Chrome DevTools protocol Runtime.ScriptId.
lineNumber <number> Returns the JavaScript script line number (1-based).
columnNumber <number> Returns the JavaScript script column number (1-based).
Returns an array of call site objects containing the stack of
the caller function.
import { getCallSites } from 'node:util';
function exampleFunction() {
const callSites = getCallSites();
console.log('Call Sites:');
callSites.forEach((callSite, index) => {
console.log(`CallSite ${index + 1}:`);
console.log(`Function Name: ${callSite.functionName}`);
console.log(`Script Name: ${callSite.scriptName}`);
console.log(`Line Number: ${callSite.lineNumber}`);
console.log(`Column Number: ${callSite.column}`);
});
}
function anotherFunction() {
exampleFunction();
}
anotherFunction();const { getCallSites } = require('node:util');
function exampleFunction() {
const callSites = getCallSites();
console.log('Call Sites:');
callSites.forEach((callSite, index) => {
console.log(`CallSite ${index + 1}:`);
console.log(`Function Name: ${callSite.functionName}`);
console.log(`Script Name: ${callSite.scriptName}`);
console.log(`Line Number: ${callSite.lineNumber}`);
console.log(`Column Number: ${callSite.column}`);
});
}
function anotherFunction() {
exampleFunction();
}
anotherFunction();
It is possible to reconstruct the original locations by setting the option sourceMap to true.
If the source map is not available, the original location will be the same as the current location.
When the --enable-source-maps flag is enabled, for example when using --experimental-transform-types,
sourceMap will be true by default.
import { getCallSites } from 'node:util';
interface Foo {
foo: string;
}
const callSites = getCallSites({ sourceMap: true });
const { getCallSites } = require('node:util');
const callSites = getCallSites({ sourceMap: true });
util.getSystemErrorName(err)#
Added in: v9.7.0
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.
See Common 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);
});
util.getSystemErrorMap()#
Added in: v16.0.0, v14.17.0
Returns a Map of all system error codes available from the Node.js API.
The mapping between error codes and error names is platform-dependent.
See Common System Errors for the names of common errors.
fs.access('file/that/does/not/exist', (err) => {
const errorMap = util.getSystemErrorMap();
const name = errorMap.get(err.errno);
console.error(name);
});
util.getSystemErrorMessage(err)#
Added in: v22.12.0
Returns the string message for a numeric error code that comes from a Node.js
API.
The mapping between error codes and string messages is platform-dependent.
fs.access('file/that/does/not/exist', (err) => {
const message = util.getSystemErrorMessage(err.errno);
console.error(message);
});
util.setTraceSigInt(enable)#
Added in: v22.19.0
Enable or disable printing a stack trace on SIGINT. The API is only available on the main thread.
util.inherits(constructor, superConstructor)#
Stability: 3 - Legacy: Use ES2015 class syntax and
extends keyword instead.
Usage of util.inherits() is discouraged. Please use the ES6 class and
extends keywords to get language level inheritance support. Also note
that the two styles are semantically incompatible.
Inherit the prototype methods from one constructor into another. The
prototype of constructor will be set to a new object created from
superConstructor.
This mainly adds some input validation on top of
Object.setPrototypeOf(constructor.prototype, superConstructor.prototype).
As an additional convenience, superConstructor will be accessible
through the constructor.super_ property.
const util = require('node:util');
const EventEmitter = require('node: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);
console.log(MyStream.super_ === EventEmitter);
stream.on('data', (data) => {
console.log(`Received data: "${data}"`);
});
stream.write('It works!');
ES6 example using class and extends:
import EventEmitter from 'node: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');const EventEmitter = require('node: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])#
util.inspect(object[, showHidden[, depth[, colors]]])#
object <any> Any JavaScript primitive or Object.
options <Object>
showHidden <boolean> If true, object's non-enumerable symbols and
properties are included in the formatted result. <WeakMap> and
<WeakSet> entries are also included as well as user defined prototype
properties (excluding method properties). Default: false.
depth <number> Specifies the number of times to recurse while formatting
object. This is useful for inspecting large objects. To recurse up to
the maximum call stack size pass Infinity or null.
Default: 2.
colors <boolean> If true, the output is styled with ANSI color
codes. Colors are customizable. See Customizing util.inspect colors.
Default: false.
customInspect <boolean> If false,
[util.inspect.custom](depth, opts, inspect) functions are not invoked.
Default: true.
showProxy <boolean> If true, Proxy inspection includes
the target and handler objects. Default: false.
maxArrayLength <integer> Specifies the maximum number of Array,
<TypedArray>, <Map>, <WeakMap>, and <WeakSet> elements to include when formatting.
Set to null or Infinity to show all elements. Set to 0 or
negative to show no elements. Default: 100.
maxStringLength <integer> Specifies the maximum number of characters to
include when formatting. Set to null or Infinity to show all elements.
Set to 0 or negative to show no characters. Default: 10000.
breakLength <integer> The length at which input values are split across
multiple lines. Set to Infinity to format the input as a single line
(in combination with compact set to true or any number >= 1).
Default: 80.
compact <boolean> | <integer> Setting this to false causes each object key
to be displayed on a new line. It will break on new lines in text that is
longer than breakLength. If set to a number, the most n inner elements
are united on a single line as long as all properties fit into
breakLength. Short array elements are also grouped together. For more
information, see the example below. Default: 3.
sorted <boolean> | <Function> If set to true or a function, all properties
of an object, and Set and Map entries are sorted in the resulting
string. If set to true the default sort is used. If set to a function,
it is used as a compare function.
getters <boolean> | <string> If set to true, getters are inspected. If set
to 'get', only getters without a corresponding setter are inspected. If
set to 'set', only getters with a corresponding setter are inspected.
This might cause side effects depending on the getter function.
Default: false.
numericSeparator <boolean> If set to true, an underscore is used to
separate every three digits in all bigints and numbers.
Default: false.
- Returns: <string> The representation of
object.
The util.inspect() method returns a string representation of object that is
intended for debugging. The output of util.inspect may change at any time
and should not be depended upon programmatically. Additional options may be
passed that alter the result.
util.inspect() will use the constructor's name and/or Symbol.toStringTag
property to make an identifiable tag for an inspected value.
class Foo {
get [Symbol.toStringTag]() {
return 'bar';
}
}
class Bar {}
const baz = Object.create(null, { [Symbol.toStringTag]: { value: 'foo' } });
util.inspect(new Foo());
util.inspect(new Bar());
util.inspect(baz);
Circular references point to their anchor by using a reference index:
import { inspect } from 'node:util';
const obj = {};
obj.a = [obj];
obj.b = {};
obj.b.inner = obj.b;
obj.b.obj = obj;
console.log(inspect(obj));
const { inspect } = require('node:util');
const obj = {};
obj.a = [obj];
obj.b = {};
obj.b.inner = obj.b;
obj.b.obj = obj;
console.log(inspect(obj));
The following example inspects all properties of the util object:
import util from 'node:util';
console.log(util.inspect(util, { showHidden: true, depth: null }));const util = require('node:util');
console.log(util.inspect(util, { showHidden: true, depth: null }));
The following example highlights the effect of the compact option:
import { inspect } from 'node:util';
const o = {
a: [1, 2, [[
'Lorem ipsum dolor sit amet,\nconsectetur adipiscing elit, sed do ' +
'eiusmod \ntempor incididunt ut labore et dolore magna aliqua.',
'test',
'foo']], 4],
b: new Map([['za', 1], ['zb', 'test']]),
};
console.log(inspect(o, { compact: true, depth: 5, breakLength: 80 }));
console.log(inspect(o, { compact: false, depth: 5, breakLength: 80 }));
const { inspect } = require('node:util');
const o = {
a: [1, 2, [[
'Lorem ipsum dolor sit amet,\nconsectetur adipiscing elit, sed do ' +
'eiusmod \ntempor incididunt ut labore et dolore magna aliqua.',
'test',
'foo']], 4],
b: new Map([['za', 1], ['zb', 'test']]),
};
console.log(inspect(o, { compact: true, depth: 5, breakLength: 80 }));
console.log(inspect(o, { compact: false, depth: 5, breakLength: 80 }));
The showHidden option allows <WeakMap> and <WeakSet> entries to be
inspected. If there are more entries than maxArrayLength, there is no
guarantee which entries are displayed. That means retrieving the same
<WeakSet> entries twice may result in different output. Furthermore, entries
with no remaining strong references may be garbage collected at any time.
import { inspect } from 'node:util';
const obj = { a: 1 };
const obj2 = { b: 2 };
const weakSet = new WeakSet([obj, obj2]);
console.log(inspect(weakSet, { showHidden: true }));
const { inspect } = require('node:util');
const obj = { a: 1 };
const obj2 = { b: 2 };
const weakSet = new WeakSet([obj, obj2]);
console.log(inspect(weakSet, { showHidden: true }));
The sorted option ensures that an object's property insertion order does not
impact the result of util.inspect().
import { inspect } from 'node:util';
import assert from 'node:assert';
const o1 = {
b: [2, 3, 1],
a: '`a` comes before `b`',
c: new Set([2, 3, 1]),
};
console.log(inspect(o1, { sorted: true }));
console.log(inspect(o1, { sorted: (a, b) => b.localeCompare(a) }));
const o2 = {
c: new Set([2, 1, 3]),
a: '`a` comes before `b`',
b: [2, 3, 1],
};
assert.strict.equal(
inspect(o1, { sorted: true }),
inspect(o2, { sorted: true }),
);const { inspect } = require('node:util');
const assert = require('node:assert');
const o1 = {
b: [2, 3, 1],
a: '`a` comes before `b`',
c: new Set([2, 3, 1]),
};
console.log(inspect(o1, { sorted: true }));
console.log(inspect(o1, { sorted: (a, b) => b.localeCompare(a) }));
const o2 = {
c: new Set([2, 1, 3]),
a: '`a` comes before `b`',
b: [2, 3, 1],
};
assert.strict.equal(
inspect(o1, { sorted: true }),
inspect(o2, { sorted: true }),
);
The numericSeparator option adds an underscore every three digits to all
numbers.
import { inspect } from 'node:util';
const thousand = 1000;
const million = 1000000;
const bigNumber = 123456789n;
const bigDecimal = 1234.12345;
console.log(inspect(thousand, { numericSeparator: true }));
console.log(inspect(million, { numericSeparator: true }));
console.log(inspect(bigNumber, { numericSeparator: true }));
console.log(inspect(bigDecimal, { numericSeparator: true }));
const { inspect } = require('node:util');
const thousand = 1000;
const million = 1000000;
const bigNumber = 123456789n;
const bigDecimal = 1234.12345;
console.log(inspect(thousand, { numericSeparator: true }));
console.log(inspect(million, { numericSeparator: true }));
console.log(inspect(bigNumber, { numericSeparator: true }));
console.log(inspect(bigDecimal, { numericSeparator: true }));
util.inspect() is a synchronous method intended for debugging. Its maximum
output length is approximately 128 MiB. Inputs that result in longer output will
be truncated.
Customizing util.inspect colors#
Color output (if enabled) of util.inspect is customizable globally
via the util.inspect.styles and util.inspect.colors properties.
util.inspect.styles is a map associating a style name to a color from
util.inspect.colors.
The default styles and associated colors are:
bigint: yellow
boolean: yellow
date: magenta
module: underline
name: (no styling)
null: bold
number: yellow
regexp: red
special: cyan (e.g., Proxies)
string: green
symbol: green
undefined: grey
Color styling uses ANSI control codes that may not be supported on all
terminals. To verify color support use tty.hasColors().
Predefined control codes are listed below (grouped as "Modifiers", "Foreground
colors", and "Background colors").
Modifiers#
Modifier support varies throughout different terminals. They will mostly be
ignored, if not supported.
reset - Resets all (color) modifiers to their defaults
- bold - Make text bold
- italic - Make text italic
- underline - Make text underlined
strikethrough - Puts a horizontal line through the center of the text
(Alias: strikeThrough, crossedout, crossedOut)
hidden - Prints the text, but makes it invisible (Alias: conceal)
- dim - Decreased color intensity (Alias:
faint)
- overlined - Make text overlined
- blink - Hides and shows the text in an interval
- inverse - Swap foreground and
background colors (Alias:
swapcolors, swapColors)
- doubleunderline - Make text
double underlined (Alias:
doubleUnderline)
- framed - Draw a frame around the text
Foreground colors#
black
red
green
yellow
blue
magenta
cyan
white
gray (alias: grey, blackBright)
redBright
greenBright
yellowBright
blueBright
magentaBright
cyanBright
whiteBright
Background colors#
bgBlack
bgRed
bgGreen
bgYellow
bgBlue
bgMagenta
bgCyan
bgWhite
bgGray (alias: bgGrey, bgBlackBright)
bgRedBright
bgGreenBright
bgYellowBright
bgBlueBright
bgMagentaBright
bgCyanBright
bgWhiteBright
Custom inspection functions on objects#
Objects may also define their own
[util.inspect.custom](depth, opts, inspect) function,
which util.inspect() will invoke and use the result of when inspecting
the object.
import { inspect } from 'node:util';
class Box {
constructor(value) {
this.value = value;
}
[inspect.custom](depth, options, inspect) {
if (depth < 0) {
return options.stylize('[Box]', 'special');
}
const newOptions = Object.assign({}, options, {
depth: options.depth === null ? null : options.depth - 1,
});
const padding = ' '.repeat(5);
const inner = inspect(this.value, newOptions)
.replace(/\n/g, `\n${padding}`);
return `${options.stylize('Box', 'special')}< ${inner} >`;
}
}
const box = new Box(true);
console.log(inspect(box));
const { inspect } = require('node:util');
class Box {
constructor(value) {
this.value = value;
}
[inspect.custom](depth, options, inspect) {
if (depth < 0) {
return options.stylize('[Box]', 'special');
}
const newOptions = Object.assign({}, options, {
depth: options.depth === null ? null : options.depth - 1,
});
const padding = ' '.repeat(5);
const inner = inspect(this.value, newOptions)
.replace(/\n/g, `\n${padding}`);
return `${options.stylize('Box', 'special')}< ${inner} >`;
}
}
const box = new Box(true);
console.log(inspect(box));
Custom [util.inspect.custom](depth, opts, inspect) functions typically return
a string but may return a value of any type that will be formatted accordingly
by util.inspect().
import { inspect } from 'node:util';
const obj = { foo: 'this will not show up in the inspect() output' };
obj[inspect.custom] = (depth) => {
return { bar: 'baz' };
};
console.log(inspect(obj));
const { inspect } = require('node:util');
const obj = { foo: 'this will not show up in the inspect() output' };
obj[inspect.custom] = (depth) => {
return { bar: 'baz' };
};
console.log(inspect(obj));
util.inspect.custom#
- Type: <symbol> that can be used to declare custom inspect functions.
In addition to being accessible through util.inspect.custom, this
symbol is registered globally and can be
accessed in any environment as Symbol.for('nodejs.util.inspect.custom').
Using this allows code to be written in a portable fashion, so that the custom
inspect function is used in an Node.js environment and ignored in the browser.
The util.inspect() function itself is passed as third argument to the custom
inspect function to allow further portability.
const customInspectSymbol = Symbol.for('nodejs.util.inspect.custom');
class Password {
constructor(value) {
this.value = value;
}
toString() {
return 'xxxxxxxx';
}
[customInspectSymbol](depth, inspectOptions, inspect) {
return `Password <${this.toString()}>`;
}
}
const password = new Password('r0sebud');
console.log(password);
See Custom inspection functions on Objects for more details.
util.isDeepStrictEqual(val1, val2)#
Added in: v9.0.0
Returns true if there is deep strict equality between val1 and val2.
Otherwise, returns false.
See assert.deepStrictEqual() for more information about deep strict
equality.
Class: util.MIMEType#
An implementation of the MIMEType class.
In accordance with browser conventions, all properties of MIMEType objects
are implemented as getters and setters on the class prototype, rather than as
data properties on the object itself.
A MIME string is a structured string containing multiple meaningful
components. When parsed, a MIMEType object is returned containing
properties for each of these components.
mime.params#
Gets the MIMEParams object representing the
parameters of the MIME. This property is read-only. See
MIMEParams documentation for details.
mime.toString()#
The toString() method on the MIMEType object returns the serialized MIME.
Because of the need for standard compliance, this method does not allow users
to customize the serialization process of the MIME.
Class: util.MIMEParams#
Added in: v19.1.0, v18.13.0
The MIMEParams API provides read and write access to the parameters of a
MIMEType.
mimeParams.delete(name)#
Remove all name-value pairs whose name is name.
mimeParams.entries()#
Returns an iterator over each of the name-value pairs in the parameters.
Each item of the iterator is a JavaScript Array. The first item of the array
is the name, the second item of the array is the value.
mimeParams.get(name)#
Returns the value of the first name-value pair whose name is name. If there
are no such pairs, null is returned.
mimeParams.has(name)#
Returns true if there is at least one name-value pair whose name is name.
mimeParams.values()#
Returns an iterator over the values of each name-value pair.
util.parseArgs([config])#
Provides a higher level API for command-line argument parsing than interacting
with process.argv directly. Takes a specification for the expected arguments
and returns a structured object with the parsed options and positionals.
import { parseArgs } from 'node:util';
const args = ['-f', '--bar', 'b'];
const options = {
foo: {
type: 'boolean',
short: 'f',
},
bar: {
type: 'string',
},
};
const {
values,
positionals,
} = parseArgs({ args, options });
console.log(values, positionals);
const { parseArgs } = require('node:util');
const args = ['-f', '--bar', 'b'];
const options = {
foo: {
type: 'boolean',
short: 'f',
},
bar: {
type: 'string',
},
};
const {
values,
positionals,
} = parseArgs({ args, options });
console.log(values, positionals);
parseArgs tokens#
Detailed parse information is available for adding custom behaviors by
specifying tokens: true in the configuration.
The returned tokens have properties describing:
- all tokens
kind <string> One of 'option', 'positional', or 'option-terminator'.
index <number> Index of element in args containing token. So the
source argument for a token is args[token.index].
- option tokens
name <string> Long name of option.
rawName <string> How option used in args, like -f of --foo.
value <string> | <undefined> Option value specified in args.
Undefined for boolean options.
inlineValue <boolean> | <undefined> Whether option value specified inline,
like --foo=bar.
- positional tokens
value <string> The value of the positional argument in args (i.e. args[index]).
- option-terminator token
The returned tokens are in the order encountered in the input args. Options
that appear more than once in args produce a token for each use. Short option
groups like -xy expand to a token for each option. So -xxx produces
three tokens.
For example, to add support for a negated option like --no-color (which
allowNegative supports when the option is of boolean type), the returned
tokens can be reprocessed to change the value stored for the negated option.
import { parseArgs } from 'node:util';
const options = {
'color': { type: 'boolean' },
'no-color': { type: 'boolean' },
'logfile': { type: 'string' },
'no-logfile': { type: 'boolean' },
};
const { values, tokens } = parseArgs({ options, tokens: true });
tokens
.filter((token) => token.kind === 'option')
.forEach((token) => {
if (token.name.startsWith('no-')) {
const positiveName = token.name.slice(3);
values[positiveName] = false;
delete values[token.name];
} else {
values[token.name] = token.value ?? true;
}
});
const color = values.color;
const logfile = values.logfile ?? 'default.log';
console.log({ logfile, color });const { parseArgs } = require('node:util');
const options = {
'color': { type: 'boolean' },
'no-color': { type: 'boolean' },
'logfile': { type: 'string' },
'no-logfile': { type: 'boolean' },
};
const { values, tokens } = parseArgs({ options, tokens: true });
tokens
.filter((token) => token.kind === 'option')
.forEach((token) => {
if (token.name.startsWith('no-')) {
const positiveName = token.name.slice(3);
values[positiveName] = false;
delete values[token.name];
} else {
values[token.name] = token.value ?? true;
}
});
const color = values.color;
const logfile = values.logfile ?? 'default.log';
console.log({ logfile, color });
Example usage showing negated options, and when an option is used
multiple ways then last one wins.
$ node negate.js
{ logfile: 'default.log', color: undefined }
$ node negate.js --no-logfile --no-color
{ logfile: false, color: false }
$ node negate.js --logfile=test.log --color
{ logfile: 'test.log', color: true }
$ node negate.js --no-logfile --logfile=test.log --color --no-color
{ logfile: 'test.log', color: false }
util.promisify(original)#
Takes a function following the common error-first callback style, i.e. taking
an (err, value) => ... callback as the last argument, and returns a version
that returns promises.
import { promisify } from 'node:util';
import { stat } from 'node:fs';
const promisifiedStat = promisify(stat);
promisifiedStat('.').then((stats) => {
}).catch((error) => {
});const { promisify } = require('node:util');
const { stat } = require('node:fs');
const promisifiedStat = promisify(stat);
promisifiedStat('.').then((stats) => {
}).catch((error) => {
});
Or, equivalently using async functions:
import { promisify } from 'node:util';
import { stat } from 'node:fs';
const promisifiedStat = promisify(stat);
async function callStat() {
const stats = await promisifiedStat('.');
console.log(`This directory is owned by ${stats.uid}`);
}
callStat();const { promisify } = require('node:util');
const { stat } = require('node:fs');
const promisifiedStat = promisify(stat);
async function callStat() {
const stats = await promisifiedStat('.');
console.log(`This directory is owned by ${stats.uid}`);
}
callStat();
If there is an original[util.promisify.custom] property present, promisify
will return its value, see Custom promisified functions.
promisify() assumes that original is a function taking a callback as its
final argument in all cases. If original is not a function, promisify()
will throw an error. If original is a function but its last argument is not
an error-first callback, it will still be passed an error-first
callback as its last argument.
Using promisify() on class methods or other methods that use this may not
work as expected unless handled specially:
import { promisify } from 'node:util';
class Foo {
constructor() {
this.a = 42;
}
bar(callback) {
callback(null, this.a);
}
}
const foo = new Foo();
const naiveBar = promisify(foo.bar);
naiveBar.call(foo).then((a) => console.log(a));
const bindBar = naiveBar.bind(foo);
bindBar().then((a) => console.log(a)); const { promisify } = require('node:util');
class Foo {
constructor() {
this.a = 42;
}
bar(callback) {
callback(null, this.a);
}
}
const foo = new Foo();
const naiveBar = promisify(foo.bar);
naiveBar.call(foo).then((a) => console.log(a));
const bindBar = naiveBar.bind(foo);
bindBar().then((a) => console.log(a));
Custom promisified functions#
Using the util.promisify.custom symbol one can override the return value of
util.promisify():
import { promisify } from 'node:util';
function doSomething(foo, callback) {
}
doSomething[promisify.custom] = (foo) => {
return getPromiseSomehow();
};
const promisified = promisify(doSomething);
console.log(promisified === doSomething[promisify.custom]);
const { promisify } = require('node:util');
function doSomething(foo, callback) {
}
doSomething[promisify.custom] = (foo) => {
return getPromiseSomehow();
};
const promisified = promisify(doSomething);
console.log(promisified === doSomething[promisify.custom]);
This can be useful for cases where the original function does not follow the
standard 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);
});
};
If promisify.custom is defined but is not a function, promisify() will
throw an error.
util.promisify.custom#
In addition to being accessible through util.promisify.custom, this
symbol is registered globally and can be
accessed in any environment as Symbol.for('nodejs.util.promisify.custom').
For example, with a function that takes in
(foo, onSuccessCallback, onErrorCallback):
const kCustomPromisifiedSymbol = Symbol.for('nodejs.util.promisify.custom');
doSomething[kCustomPromisifiedSymbol] = (foo) => {
return new Promise((resolve, reject) => {
doSomething(foo, resolve, reject);
});
};
util.stripVTControlCharacters(str)
Added in: v16.11.0
Returns str with any ANSI escape codes removed.
console.log(util.stripVTControlCharacters('\u001B[4mvalue\u001B[0m'));
util.styleText(format, text[, options])#
format <string> | <Array> A text format or an Array
of text formats defined in util.inspect.colors.
text <string> The text to to be formatted.
options <Object>
validateStream <boolean> When true, stream is checked to see if it can handle colors. Default: true.
stream <Stream> A stream that will be validated if it can be colored. Default: process.stdout.
This function returns a formatted text considering the format passed
for printing in a terminal. It is aware of the terminal's capabilities
and acts according to the configuration set via NO_COLOR,
NODE_DISABLE_COLORS and FORCE_COLOR environment variables.
import { styleText } from 'node:util';
import { stderr } from 'node:process';
const successMessage = styleText('green', 'Success!');
console.log(successMessage);
const errorMessage = styleText(
'red',
'Error! Error!',
{ stream: stderr },
);
console.error(errorMessage);const { styleText } = require('node:util');
const { stderr } = require('node:process');
const successMessage = styleText('green', 'Success!');
console.log(successMessage);
const errorMessage = styleText(
'red',
'Error! Error!',
{ stream: stderr },
);
console.error(errorMessage);
util.inspect.colors also provides text formats such as italic, and
underline and you can combine both:
console.log(
util.styleText(['underline', 'italic'], 'My italic underlined message'),
);
When passing an array of formats, the order of the format applied
is left to right so the following style might overwrite the previous one.
console.log(
util.styleText(['red', 'green'], 'text'),
);
The special format value none applies no additional styling to the text.
The full list of formats can be found in modifiers.
Class: util.TextDecoder#
An implementation of the WHATWG Encoding Standard TextDecoder API.
const decoder = new TextDecoder();
const u8arr = new Uint8Array([72, 101, 108, 108, 111]);
console.log(decoder.decode(u8arr));
WHATWG supported encodings#
Per the WHATWG Encoding Standard, the encodings supported by the
TextDecoder 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.
(see Internationalization)
Encodings supported by default (with full ICU data)#
| Encoding | Aliases |
|---|
'ibm866' | '866', 'cp866', 'csibm866' |
'iso-8859-2' | 'csisolatin2', 'iso-ir-101', 'iso8859-2', 'iso88592', 'iso_8859-2', 'iso_8859-2:1987', 'l2', 'latin2' |
'iso-8859-3' | 'csisolatin3', 'iso-ir-109', 'iso8859-3', 'iso88593', 'iso_8859-3', 'iso_8859-3:1988', 'l3', 'latin3' |
'iso-8859-4' | 'csisolatin4', 'iso-ir-110', 'iso8859-4', 'iso88594', 'iso_8859-4', 'iso_8859-4:1988', 'l4', 'latin4' |
'iso-8859-5' | 'csisolatincyrillic', 'cyrillic', 'iso-ir-144', 'iso8859-5', 'iso88595', 'iso_8859-5', 'iso_8859-5:1988' |
'iso-8859-6' | 'arabic', 'asmo-708', 'csiso88596e', 'csiso88596i', 'csisolatinarabic', 'ecma-114', 'iso-8859-6-e', 'iso-8859-6-i', 'iso-ir-127', 'iso8859-6', 'iso88596', 'iso_8859-6', 'iso_8859-6:1987' |
'iso-8859-7' | 'csisolatingreek', 'ecma-118', 'elot_928', 'greek', 'greek8', 'iso-ir-126', 'iso8859-7', 'iso88597', 'iso_8859-7', 'iso_8859-7:1987', 'sun_eu_greek' |
'iso-8859-8' | 'csiso88598e', 'csisolatinhebrew', 'hebrew', 'iso-8859-8-e', 'iso-ir-138', 'iso8859-8', 'iso88598', 'iso_8859-8', 'iso_8859-8:1988', 'visual' |
'iso-8859-8-i' | 'csiso88598i', 'logical' |
'iso-8859-10' | 'csisolatin6', 'iso-ir-157', 'iso8859-10', 'iso885910', 'l6', 'latin6' |
'iso-8859-13' | 'iso8859-13', 'iso885913' |
'iso-8859-14' | 'iso8859-14', 'iso885914' |
'iso-8859-15' | 'csisolatin9', 'iso8859-15', 'iso885915', 'iso_8859-15', 'l9' |
'koi8-r' | 'cskoi8r', 'koi', 'koi8', 'koi8_r' |
'koi8-u' | 'koi8-ru' |
'macintosh' | 'csmacintosh', 'mac', 'x-mac-roman' |
'windows-874' | 'dos-874', 'iso-8859-11', 'iso8859-11', 'iso885911', 'tis-620' |
'windows-1250' | 'cp1250', 'x-cp1250' |
'windows-1251' | 'cp1251', 'x-cp1251' |
'windows-1252' | 'ansi_x3.4-1968', 'ascii', 'cp1252', 'cp819', 'csisolatin1', 'ibm819', 'iso-8859-1', 'iso-ir-100', 'iso8859-1', 'iso88591', 'iso_8859-1', 'iso_8859-1:1987', 'l1', 'latin1', 'us-ascii', 'x-cp1252' |
'windows-1253' | 'cp1253', 'x-cp1253' |
'windows-1254' | 'cp1254', 'csisolatin5', 'iso-8859-9', 'iso-ir-148', 'iso8859-9', 'iso88599', 'iso_8859-9', 'iso_8859-9:1989', 'l5', 'latin5', 'x-cp1254' |
'windows-1255' | 'cp1255', 'x-cp1255' |
'windows-1256' | 'cp1256', 'x-cp1256' |
'windows-1257' | 'cp1257', 'x-cp1257' |
'windows-1258' | 'cp1258', 'x-cp1258' |
'x-mac-cyrillic' | 'x-mac-ukrainian' |
'gbk' | 'chinese', 'csgb2312', 'csiso58gb231280', 'gb2312', 'gb_2312', 'gb_2312-80', 'iso-ir-58', 'x-gbk' |
'gb18030' | |
'big5' | 'big5-hkscs', 'cn-big5', 'csbig5', 'x-x-big5' |
'euc-jp' | 'cseucpkdfmtjapanese', 'x-euc-jp' |
'iso-2022-jp' | 'csiso2022jp' |
'shift_jis' | 'csshiftjis', 'ms932', 'ms_kanji', 'shift-jis', 'sjis', 'windows-31j', 'x-sjis' |
'euc-kr' | 'cseuckr', 'csksc56011987', 'iso-ir-149', 'korean', 'ks_c_5601-1987', 'ks_c_5601-1989', 'ksc5601', 'ksc_5601', 'windows-949' |
Encodings supported when Node.js is built with the small-icu option#
| Encoding | Aliases |
|---|
'utf-8' | 'unicode-1-1-utf-8', 'utf8' |
'utf-16le' | 'utf-16' |
'utf-16be' | |
Encodings supported when ICU is disabled#
| Encoding | Aliases |
|---|
'utf-8' | 'unicode-1-1-utf-8', 'utf8' |
'utf-16le' | 'utf-16' |
The 'iso-8859-16' encoding listed in the WHATWG Encoding Standard
is not supported.
new TextDecoder([encoding[, options]])#
encoding <string> Identifies the encoding that this TextDecoder instance
supports. Default: 'utf-8'.
options <Object>
fatal <boolean> true if decoding failures are fatal.
This option is not supported when ICU is disabled
(see Internationalization). Default: false.
ignoreBOM <boolean> When true, the TextDecoder will include the byte
order mark in the decoded result. When false, the byte order mark will
be removed from the output. This option is only used when encoding is
'utf-8', 'utf-16be', or 'utf-16le'. Default: false.
Creates a new TextDecoder instance. The encoding may specify one of the
supported encodings or an alias.
The TextDecoder class is also available on the global object.
textDecoder.decode([input[, options]])#
Decodes the input and returns a string. If options.stream is true, any
incomplete byte sequences occurring at the end of the input are buffered
internally and emitted after the next call to textDecoder.decode().
If textDecoder.fatal is true, decoding errors that occur will result in a
TypeError being thrown.
textDecoder.encoding#
The encoding supported by the TextDecoder instance.
textDecoder.fatal#
The value will be true if decoding errors result in a TypeError being
thrown.
textDecoder.ignoreBOM#
The value will be true if the decoding result will include the byte order
mark.
Class: util.TextEncoder#
An implementation of the WHATWG Encoding Standard TextEncoder API. All
instances of TextEncoder only support UTF-8 encoding.
const encoder = new TextEncoder();
const uint8array = encoder.encode('this is some data');
The TextEncoder class is also available on the global object.
textEncoder.encode([input])#
UTF-8 encodes the input string and returns a Uint8Array containing the
encoded bytes.
textEncoder.encodeInto(src, dest)#
Added in: v12.11.0
UTF-8 encodes the src string to the dest Uint8Array and returns an object
containing the read Unicode code units and written UTF-8 bytes.
const encoder = new TextEncoder();
const src = 'this is some data';
const dest = new Uint8Array(10);
const { read, written } = encoder.encodeInto(src, dest);
textEncoder.encoding#
The encoding supported by the TextEncoder instance. Always set to 'utf-8'.
util.toUSVString(string)#
Added in: v16.8.0, v14.18.0
Returns the string after replacing any surrogate code points
(or equivalently, any unpaired surrogate code units) with the
Unicode "replacement character" U+FFFD.
util.transferableAbortController()#
Creates and returns an <AbortController> instance whose <AbortSignal> is marked
as transferable and can be used with structuredClone() or postMessage().
util.transferableAbortSignal(signal)#
Marks the given <AbortSignal> as transferable so that it can be used with
structuredClone() and postMessage().
const signal = transferableAbortSignal(AbortSignal.timeout(100));
const channel = new MessageChannel();
channel.port2.postMessage(signal, [signal]);
util.aborted(signal, resource)#
signal <AbortSignal>
resource <Object> Any non-null object tied to the abortable operation and held weakly.
If resource is garbage collected before the signal aborts, the promise remains pending,
allowing Node.js to stop tracking it.
This helps prevent memory leaks in long-running or non-cancelable operations.
- Returns: <Promise>
Listens to abort event on the provided signal and returns a promise that resolves when the signal is aborted.
If resource is provided, it weakly references the operation's associated object,
so if resource is garbage collected before the signal aborts,
then returned promise shall remain pending.
This prevents memory leaks in long-running or non-cancelable operations.
const { aborted } = require('node:util');
const dependent = obtainSomethingAbortable();
aborted(dependent.signal, dependent).then(() => {
console.log('Dependent resource was aborted.');
});
dependent.on('event', () => {
dependent.abort();
});import { aborted } from 'node:util';
const dependent = obtainSomethingAbortable();
aborted(dependent.signal, dependent).then(() => {
console.log('Dependent resource was aborted.');
});
dependent.on('event', () => {
dependent.abort();
});
util.types#
util.types provides type checks for different kinds of built-in objects.
Unlike instanceof or Object.prototype.toString.call(value), these checks do
not inspect properties of the object that are accessible from JavaScript (like
their prototype), and usually have the overhead of calling into C++.
The result generally does not make any guarantees about what kinds of
properties or behavior a value exposes in JavaScript. They are primarily
useful for addon developers who prefer to do type checking in JavaScript.
The API is accessible via require('node:util').types or require('node:util/types').
util.types.isArrayBufferView(value)#
Added in: v10.0.0
Returns true if the value is an instance of one of the <ArrayBuffer>
views, such as typed array objects or <DataView>. Equivalent to
ArrayBuffer.isView().
util.types.isArrayBufferView(new Int8Array());
util.types.isArrayBufferView(Buffer.from('hello world'));
util.types.isArrayBufferView(new DataView(new ArrayBuffer(16)));
util.types.isArrayBufferView(new ArrayBuffer());
util.types.isArgumentsObject(value)#
Added in: v10.0.0
Returns true if the value is an arguments object.
function foo() {
util.types.isArgumentsObject(arguments);
}
util.types.isArrayBuffer(value)#
Added in: v10.0.0
Returns true if the value is a built-in <ArrayBuffer> instance.
This does not include <SharedArrayBuffer> instances. Usually, it is
desirable to test for both; See util.types.isAnyArrayBuffer() for that.
util.types.isArrayBuffer(new ArrayBuffer());
util.types.isArrayBuffer(new SharedArrayBuffer());
util.types.isAsyncFunction(value)#
Added in: v10.0.0
Returns true if the value is an async function.
This only reports back what the JavaScript engine is seeing;
in particular, the return value may not match the original source code if
a transpilation tool was used.
util.types.isAsyncFunction(function foo() {});
util.types.isAsyncFunction(async function foo() {});
util.types.isBigInt64Array(value)#
Added in: v10.0.0
Returns true if the value is a BigInt64Array instance.
util.types.isBigInt64Array(new BigInt64Array());
util.types.isBigInt64Array(new BigUint64Array());
util.types.isBigIntObject(value)#
Added in: v10.4.0
Returns true if the value is a BigInt object, e.g. created
by Object(BigInt(123)).
util.types.isBigIntObject(Object(BigInt(123)));
util.types.isBigIntObject(BigInt(123));
util.types.isBigIntObject(123);
util.types.isBigUint64Array(value)#
Added in: v10.0.0
Returns true if the value is a BigUint64Array instance.
util.types.isBigUint64Array(new BigInt64Array());
util.types.isBigUint64Array(new BigUint64Array());
util.types.isBooleanObject(value)#
Added in: v10.0.0
Returns true if the value is a boolean object, e.g. created
by new Boolean().
util.types.isBooleanObject(false);
util.types.isBooleanObject(true);
util.types.isBooleanObject(new Boolean(false));
util.types.isBooleanObject(new Boolean(true));
util.types.isBooleanObject(Boolean(false));
util.types.isBooleanObject(Boolean(true));
util.types.isBoxedPrimitive(value)#
Added in: v10.11.0
Returns true if the value is any boxed primitive object, e.g. created
by new Boolean(), new String() or Object(Symbol()).
For example:
util.types.isBoxedPrimitive(false);
util.types.isBoxedPrimitive(new Boolean(false));
util.types.isBoxedPrimitive(Symbol('foo'));
util.types.isBoxedPrimitive(Object(Symbol('foo')));
util.types.isBoxedPrimitive(Object(BigInt(5)));
util.types.isCryptoKey(value)#
Added in: v16.2.0
Returns true if value is a <CryptoKey>, false otherwise.
util.types.isDataView(value)#
Added in: v10.0.0
Returns true if the value is a built-in <DataView> instance.
const ab = new ArrayBuffer(20);
util.types.isDataView(new DataView(ab));
util.types.isDataView(new Float64Array());
See also ArrayBuffer.isView().
util.types.isDate(value)#
Added in: v10.0.0
Returns true if the value is a built-in <Date> instance.
util.types.isDate(new Date());
util.types.isExternal(value)#
Added in: v10.0.0
Returns true if the value is a native External value.
A native External value is a special type of object that contains a
raw C++ pointer (void*) for access from native code, and has no other
properties. Such objects are created either by Node.js internals or native
addons. In JavaScript, they are frozen objects with a
null prototype.
#include <js_native_api.h>
#include <stdlib.h>
napi_value result;
static napi_value MyNapi(napi_env env, napi_callback_info info) {
int* raw = (int*) malloc(1024);
napi_status status = napi_create_external(env, (void*) raw, NULL, NULL, &result);
if (status != napi_ok) {
napi_throw_error(env, NULL, "napi_create_external failed");
return NULL;
}
return result;
}
...
DECLARE_NAPI_PROPERTY("myNapi", MyNapi)
...
import native from 'napi_addon.node';
import { types } from 'node:util';
const data = native.myNapi();
types.isExternal(data);
types.isExternal(0);
types.isExternal(new String('foo')); const native = require('napi_addon.node');
const { types } = require('node:util');
const data = native.myNapi();
types.isExternal(data);
types.isExternal(0);
types.isExternal(new String('foo'));
For further information on napi_create_external, refer to
napi_create_external().
util.types.isFloat16Array(value)#
Added in: v22.16.0
Returns true if the value is a built-in <Float16Array> instance.
util.types.isFloat16Array(new ArrayBuffer());
util.types.isFloat16Array(new Float16Array());
util.types.isFloat16Array(new Float32Array());
util.types.isFloat32Array(value)#
Added in: v10.0.0
Returns true if the value is a built-in <Float32Array> instance.
util.types.isFloat32Array(new ArrayBuffer());
util.types.isFloat32Array(new Float32Array());
util.types.isFloat32Array(new Float64Array());
util.types.isFloat64Array(value)#
Added in: v10.0.0
Returns true if the value is a built-in <Float64Array> instance.
util.types.isFloat64Array(new ArrayBuffer());
util.types.isFloat64Array(new Uint8Array());
util.types.isFloat64Array(new Float64Array());
util.types.isGeneratorFunction(value)#
Added in: v10.0.0
Returns true if the value is a generator function.
This only reports back what the JavaScript engine is seeing;
in particular, the return value may not match the original source code if
a transpilation tool was used.
util.types.isGeneratorFunction(function foo() {});
util.types.isGeneratorFunction(function* foo() {});
util.types.isGeneratorObject(value)#
Added in: v10.0.0
Returns true if the value is a generator object as returned from a
built-in generator function.
This only reports back what the JavaScript engine is seeing;
in particular, the return value may not match the original source code if
a transpilation tool was used.
function* foo() {}
const generator = foo();
util.types.isGeneratorObject(generator);
util.types.isInt8Array(value)#
Added in: v10.0.0
Returns true if the value is a built-in <Int8Array> instance.
util.types.isInt8Array(new ArrayBuffer());
util.types.isInt8Array(new Int8Array());
util.types.isInt8Array(new Float64Array());
util.types.isInt16Array(value)#
Added in: v10.0.0
Returns true if the value is a built-in <Int16Array> instance.
util.types.isInt16Array(new ArrayBuffer());
util.types.isInt16Array(new Int16Array());
util.types.isInt16Array(new Float64Array());
util.types.isInt32Array(value)#
Added in: v10.0.0
Returns true if the value is a built-in <Int32Array> instance.
util.types.isInt32Array(new ArrayBuffer());
util.types.isInt32Array(new Int32Array());
util.types.isInt32Array(new Float64Array());
util.types.isKeyObject(value)#
Added in: v16.2.0
Returns true if value is a <KeyObject>, false otherwise.
util.types.isMap(value)#
Added in: v10.0.0
Returns true if the value is a built-in <Map> instance.
util.types.isMap(new Map());
util.types.isMapIterator(value)#
Added in: v10.0.0
Returns true if the value is an iterator returned for a built-in
<Map> instance.
const map = new Map();
util.types.isMapIterator(map.keys());
util.types.isMapIterator(map.values());
util.types.isMapIterator(map.entries());
util.types.isMapIterator(map[Symbol.iterator]());
util.types.isModuleNamespaceObject(value)#
Added in: v10.0.0
Returns true if the value is an instance of a Module Namespace Object.
import * as ns from './a.js';
util.types.isModuleNamespaceObject(ns);
util.types.isNativeError(value)#
Added in: v10.0.0
Returns true if the value was returned by the constructor of a
built-in Error type.
console.log(util.types.isNativeError(new Error()));
console.log(util.types.isNativeError(new TypeError()));
console.log(util.types.isNativeError(new RangeError()));
Subclasses of the native error types are also native errors:
class MyError extends Error {}
console.log(util.types.isNativeError(new MyError()));
A value being instanceof a native error class is not equivalent to isNativeError()
returning true for that value. isNativeError() returns true for errors
which come from a different realm while instanceof Error returns false
for these errors:
import { createContext, runInContext } from 'node:vm';
import { types } from 'node:util';
const context = createContext({});
const myError = runInContext('new Error()', context);
console.log(types.isNativeError(myError));
console.log(myError instanceof Error); const { createContext, runInContext } = require('node:vm');
const { types } = require('node:util');
const context = createContext({});
const myError = runInContext('new Error()', context);
console.log(types.isNativeError(myError));
console.log(myError instanceof Error);
Conversely, isNativeError() returns false for all objects which were not
returned by the constructor of a native error. That includes values
which are instanceof native errors:
const myError = { __proto__: Error.prototype };
console.log(util.types.isNativeError(myError));
console.log(myError instanceof Error);
util.types.isNumberObject(value)#
Added in: v10.0.0
Returns true if the value is a number object, e.g. created
by new Number().
util.types.isNumberObject(0);
util.types.isNumberObject(new Number(0));
util.types.isPromise(value)#
Added in: v10.0.0
Returns true if the value is a built-in <Promise>.
util.types.isPromise(Promise.resolve(42));
util.types.isProxy(value)#
Added in: v10.0.0
Returns true if the value is a <Proxy> instance.
const target = {};
const proxy = new Proxy(target, {});
util.types.isProxy(target);
util.types.isProxy(proxy);
util.types.isRegExp(value)#
Added in: v10.0.0
Returns true if the value is a regular expression object.
util.types.isRegExp(/abc/);
util.types.isRegExp(new RegExp('abc'));
util.types.isSet(value)#
Added in: v10.0.0
Returns true if the value is a built-in <Set> instance.
util.types.isSet(new Set());
util.types.isSetIterator(value)#
Added in: v10.0.0
Returns true if the value is an iterator returned for a built-in
<Set> instance.
const set = new Set();
util.types.isSetIterator(set.keys());
util.types.isSetIterator(set.values());
util.types.isSetIterator(set.entries());
util.types.isSetIterator(set[Symbol.iterator]());
util.types.isSharedArrayBuffer(value)#
Added in: v10.0.0
Returns true if the value is a built-in <SharedArrayBuffer> instance.
This does not include <ArrayBuffer> instances. Usually, it is
desirable to test for both; See util.types.isAnyArrayBuffer() for that.
util.types.isSharedArrayBuffer(new ArrayBuffer());
util.types.isSharedArrayBuffer(new SharedArrayBuffer());
util.types.isStringObject(value)#
Added in: v10.0.0
Returns true if the value is a string object, e.g. created
by new String().
util.types.isStringObject('foo');
util.types.isStringObject(new String('foo'));
util.types.isSymbolObject(value)#
Added in: v10.0.0
Returns true if the value is a symbol object, created
by calling Object() on a Symbol primitive.
const symbol = Symbol('foo');
util.types.isSymbolObject(symbol);
util.types.isSymbolObject(Object(symbol));
util.types.isTypedArray(value)#
Added in: v10.0.0
Returns true if the value is a built-in <TypedArray> instance.
util.types.isTypedArray(new ArrayBuffer());
util.types.isTypedArray(new Uint8Array());
util.types.isTypedArray(new Float64Array());
See also ArrayBuffer.isView().
util.types.isUint8Array(value)#
Added in: v10.0.0
Returns true if the value is a built-in <Uint8Array> instance.
util.types.isUint8Array(new ArrayBuffer());
util.types.isUint8Array(new Uint8Array());
util.types.isUint8Array(new Float64Array());
util.types.isUint8ClampedArray(value)#
Added in: v10.0.0
Returns true if the value is a built-in <Uint8ClampedArray> instance.
util.types.isUint8ClampedArray(new ArrayBuffer());
util.types.isUint8ClampedArray(new Uint8ClampedArray());
util.types.isUint8ClampedArray(new Float64Array());
util.types.isUint16Array(value)#
Added in: v10.0.0
Returns true if the value is a built-in <Uint16Array> instance.
util.types.isUint16Array(new ArrayBuffer());
util.types.isUint16Array(new Uint16Array());
util.types.isUint16Array(new Float64Array());
util.types.isUint32Array(value)#
Added in: v10.0.0
Returns true if the value is a built-in <Uint32Array> instance.
util.types.isUint32Array(new ArrayBuffer());
util.types.isUint32Array(new Uint32Array());
util.types.isUint32Array(new Float64Array());
util.types.isWeakMap(value)#
Added in: v10.0.0
Returns true if the value is a built-in <WeakMap> instance.
util.types.isWeakMap(new WeakMap());
util.types.isWeakSet(value)#
Added in: v10.0.0
Returns true if the value is a built-in <WeakSet> instance.
util.types.isWeakSet(new WeakSet());
Deprecated APIs#
The following APIs are deprecated and should no longer be used. Existing
applications and modules should be updated to find alternative approaches.
util._extend(target, source)#
Added in: v0.7.5Deprecated since: v6.0.0
The util._extend() method was never intended to be used outside of internal
Node.js modules. The community found and used it anyway.
It is deprecated and should not be used in new code. JavaScript comes with very
similar built-in functionality through Object.assign().
util.isArray(object)#
Added in: v0.6.0Deprecated since: v4.0.0
Alias for Array.isArray().
Returns true if the given object is an Array. Otherwise, returns false.
const util = require('node:util');
util.isArray([]);
util.isArray(new Array());
util.isArray({});
util.isBoolean(object)#
Added in: v0.11.5Deprecated since: v4.0.0
Stability: 0 - Deprecated: Use
typeof value === 'boolean' instead.
Returns true if the given object is a Boolean. Otherwise, returns false.
const util = require('node:util');
util.isBoolean(1);
util.isBoolean(0);
util.isBoolean(false);
util.isBuffer(object)#
Added in: v0.11.5Deprecated since: v4.0.0
Returns true if the given object is a Buffer. Otherwise, returns false.
const util = require('node:util');
util.isBuffer({ length: 0 });
util.isBuffer([]);
util.isBuffer(Buffer.from('hello world'));
util.isDate(object)#
Added in: v0.6.0Deprecated since: v4.0.0
Returns true if the given object is a Date. Otherwise, returns false.
const util = require('node:util');
util.isDate(new Date());
util.isDate(Date());
util.isDate({});
util.isError(object)#
Added in: v0.6.0Deprecated since: v4.0.0
Returns true if the given object is an <Error>. Otherwise, returns
false.
const util = require('node:util');
util.isError(new Error());
util.isError(new TypeError());
util.isError({ name: 'Error', message: 'an error occurred' });
This method relies on Object.prototype.toString() behavior. It is
possible to obtain an incorrect result when the object argument manipulates
@@toStringTag.
const util = require('node:util');
const obj = { name: 'Error', message: 'an error occurred' };
util.isError(obj);
obj[Symbol.toStringTag] = 'Error';
util.isError(obj);
util.isFunction(object)#
Added in: v0.11.5Deprecated since: v4.0.0
Stability: 0 - Deprecated: Use
typeof value === 'function' instead.
Returns true if the given object is a Function. Otherwise, returns
false.
const util = require('node:util');
function Foo() {}
const Bar = () => {};
util.isFunction({});
util.isFunction(Foo);
util.isFunction(Bar);
util.isNull(object)#
Added in: v0.11.5Deprecated since: v4.0.0
Returns true if the given object is strictly null. Otherwise, returns
false.
const util = require('node:util');
util.isNull(0);
util.isNull(undefined);
util.isNull(null);
util.isNullOrUndefined(object)#
Added in: v0.11.5Deprecated since: v4.0.0
Stability: 0 - Deprecated: Use
value === undefined || value === null instead.
Returns true if the given object is null or undefined. Otherwise,
returns false.
const util = require('node:util');
util.isNullOrUndefined(0);
util.isNullOrUndefined(undefined);
util.isNullOrUndefined(null);
util.isNumber(object)#
Added in: v0.11.5Deprecated since: v4.0.0
Stability: 0 - Deprecated: Use
typeof value === 'number' instead.
Returns true if the given object is a Number. Otherwise, returns false.
const util = require('node:util');
util.isNumber(false);
util.isNumber(Infinity);
util.isNumber(0);
util.isNumber(NaN);
util.isObject(object)#
Added in: v0.11.5Deprecated since: v4.0.0
Stability: 0 - Deprecated:
Use
value !== null && typeof value === 'object' instead.
Returns true if the given object is strictly an Object and not a
Function (even though functions are objects in JavaScript).
Otherwise, returns false.
const util = require('node:util');
util.isObject(5);
util.isObject(null);
util.isObject({});
util.isObject(() => {});
util.isPrimitive(object)#
Added in: v0.11.5Deprecated since: v4.0.0
Stability: 0 - Deprecated: Use
(typeof value !== 'object' && typeof value !== 'function') || value === null
instead.
Returns true if the given object is a primitive type. Otherwise, returns
false.
const util = require('node:util');
util.isPrimitive(5);
util.isPrimitive('foo');
util.isPrimitive(false);
util.isPrimitive(null);
util.isPrimitive(undefined);
util.isPrimitive({});
util.isPrimitive(() => {});
util.isPrimitive(/^$/);
util.isPrimitive(new Date());
util.isRegExp(object)#
Added in: v0.6.0Deprecated since: v4.0.0
Returns true if the given object is a RegExp. Otherwise, returns false.
const util = require('node:util');
util.isRegExp(/some regexp/);
util.isRegExp(new RegExp('another regexp'));
util.isRegExp({});
util.isString(object)#
Added in: v0.11.5Deprecated since: v4.0.0
Stability: 0 - Deprecated: Use
typeof value === 'string' instead.
Returns true if the given object is a string. Otherwise, returns false.
const util = require('node:util');
util.isString('');
util.isString('foo');
util.isString(String('foo'));
util.isString(5);
util.isSymbol(object)#
Added in: v0.11.5Deprecated since: v4.0.0
Stability: 0 - Deprecated: Use
typeof value === 'symbol' instead.
Returns true if the given object is a Symbol. Otherwise, returns false.
const util = require('node:util');
util.isSymbol(5);
util.isSymbol('foo');
util.isSymbol(Symbol('foo'));
util.isUndefined(object)#
Added in: v0.11.5Deprecated since: v4.0.0
Returns true if the given object is undefined. Otherwise, returns false.
const util = require('node:util');
const foo = undefined;
util.isUndefined(5);
util.isUndefined(foo);
util.isUndefined(null);
util.log(string)#
Added in: v0.3.0Deprecated since: v6.0.0
Stability: 0 - Deprecated: Use a third party module instead.
The util.log() method prints the given string to stdout with an included
timestamp.
const util = require('node:util');
util.log('Timestamped message.');