File an issue

node:util

Node.js util module, resolvable via both ESM import and CommonJS require.

Status: util.types (the type-checking predicate family), util.inspect, util.promisify, util.getCallSites, TextEncoder, and TextDecoder are implemented. format, callbackify, isDeepStrictEqual, deprecate, debuglog, getSystemError*, toUSVString, stripVTControlCharacters, styleText, parseEnv, and log will land in follow-up commits.

util.inspect / promisify / getCallSites

  • util.inspect(value[, options]) — formats a value the way Node does: primitives, quoted strings (single/double/backtick selection like Node), { key: value } objects, [ 1, 2 ] arrays, Map(n) { … } / Set(n) { … }, functions ([Function: name] / [class X]), Date / RegExp, and circular references (1> / [Circular 1]). Multi-line wrapping is faithful to Node's layout engine — breakLength (default 80), compact (default 3) and indentation are honoured, and long numeric arrays are grouped into aligned columns. depth (default 2 → [Object] / [Array] past it; null for no limit) and maxArrayLength (default 100 → … N more items, applied to arrays, Map and Set) are supported. Typed arrays (Uint8Array(3) [ 1, 2, 3 ]), Buffer (), ArrayBuffer / DataView, boxed primitives ([Number: 5]), and function kinds ([AsyncFunction: x] / [GeneratorFunction: x]) all match Node. util.inspect.custom is the standard symbol and an object's [util.inspect.custom]() method is invoked when present. The formatting mirrors Node's lib/internal/util/inspect.js layout algorithm. One deliberate limitation: a Promise's resolved/pending state cannot be introspected from pure JS, so promises print as Promise {} rather than Node's Promise { }.
  • util.promisify(fn) — wraps an error-first-callback function into one that returns a Promise. Honors fn[util.promisify.custom] (a.k.a. Symbol.for('nodejs.util.promisify.custom')); throws ERR_INVALID_ARG_TYPE for a non-function argument.
  • util.getCallSites([frameCount][, options]) — returns an array of call-site objects with functionName, scriptName, lineNumber, columnNumber, and scriptId.
  • TextEncoder / TextDecoder — exported from node:util; both resolve to the realm's WHATWG constructors, so require('node:util').TextEncoder === globalThis.TextEncoder.

util.types — implemented predicates (13)

PredicateReturns true for
isArrayBuffer(value)Any ArrayBuffer (heap, direct, or interop-wrapped)
isArrayBufferView(value)Any typed array or DataView
isDataView(value)DataView only
isDate(value)Date instances
isMap(value)Map instances
isNativeError(value)Any built-in Error subtype (TypeError, RangeError, …)
isPromise(value)Native Promise instances
isProxy(value)Values created via new Proxy(...)
isRegExp(value)RegExp instances
isSet(value)Set instances
isTypedArray(value)Typed arrays (Uint8Array, Int32Array, etc.) — excludes DataView
isWeakMap(value)WeakMap instances
isWeakSet(value)WeakSet instances
All predicates accept any JS value and return true/false — they never throw. Plain objects, primitives (number, string, boolean, null, undefined), and duck-typed look-alikes ({ then: () => {} } is not a Promise) return false.

Identity note: util.types is cached per realm — util.types === util.types always holds. This makes it safe to hold a reference across calls.

util.types — deferred predicates

The long tail of util.types predicates (isAsyncFunction, isGeneratorFunction, isBigIntObject, isNumberObject, isStringObject, isBooleanObject, isSymbolObject, isBoxedPrimitive, isCryptoKey, isKeyObject, isExternal, isMapIterator, isSetIterator, isModuleNamespaceObject, isSharedArrayBuffer, isInt8Array, isUint8Array, isUint8ClampedArray, isInt16Array, isUint16Array, isInt32Array, isUint32Array, isFloat32Array, isFloat64Array, isBigInt64Array, isBigUint64Array) is not yet wired. These are less commonly used and will land on demand.

Example

javascript
const util = require("node:util");

util.types.isDate(new Date());                     // → true
util.types.isDate("2024-01-01");                   // → false
util.types.isPromise(Promise.resolve());           // → true
util.types.isPromise({ then: () => {} });          // → false (duck-typing excluded)
util.types.isMap(new Map());                       // → true
util.types.isTypedArray(new Uint8Array(4));        // → true
util.types.isTypedArray(new DataView(new ArrayBuffer(4))); // → false
util.types.isNativeError(new TypeError("x"));      // → true

See also

  • Node.js upstream:
  • util.types section: