Node.js v24.0.0 文档

util.callbackify(original)#

• original <Function> 一个 async 函数
• 返回：<Function> 一个回调风格的函数

接受一个 async 函数（或返回 Promise 的函数），并返回一个遵循 error-first 回调风格的函数，即接受一个 (err, value) => ... 回调作为最后一个参数。 在回调中，第一个参数将是拒绝原因（如果 Promise 已解决，则为 null），第二个参数将是已解决的值。

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);
});copy

将打印

hello world copy

该回调以异步方式执行，并将具有有限的堆栈跟踪。 如果回调抛出，则该进程将发出一个 'uncaughtException' 事件，如果未处理，则将退出。

由于 null 作为回调的第一个参数具有特殊含义，如果包装的函数以一个虚值作为原因拒绝 Promise，则该值将被包装在 Error 中，原始值存储在名为 reason 的字段中。

function fn() {
  return Promise.reject(null);
}
const callbackFunction = util.callbackify(fn);

callbackFunction((err, ret) => {
  // When the Promise was rejected with `null` it is wrapped with an Error and
  // the original value is stored in `reason`.
  err && Object.hasOwn(err, 'reason') && err.reason === null;  // true
}); copy

util.debuglog(section[, callback])#

• section <string> 一个字符串，用于标识应用程序中创建 debuglog 函数的部分。
• callback <Function> 首次使用函数参数调用日志记录函数时调用的回调，该函数参数是更优化的日志记录函数。
• 返回：<Function> 日志记录函数

util.debuglog() 方法用于创建一个函数，该函数根据 NODE_DEBUG 环境变量的存在有条件地将调试消息写入 stderr。 如果 section 名称出现在该环境变量的值中，则返回的函数的操作类似于 console.error()。 否则，返回的函数是一个空操作。

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);copy

如果使用环境变量 NODE_DEBUG=foo 运行此程序，则它将输出类似以下内容：

FOO 3245: hello from foo [123] copy

其中 3245 是进程 ID。 如果在没有设置该环境变量的情况下运行它，则它不会打印任何内容。

section 也支持通配符

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);copy

如果使用环境变量 NODE_DEBUG=foo* 运行它，则它将输出类似以下内容：

FOO-BAR 3257: hi there, it's foo-bar [2333] copy

可以在 NODE_DEBUG 环境变量中指定多个逗号分隔的 section 名称：NODE_DEBUG=fs,net,tls。

可选的 callback 参数可用于将日志记录函数替换为没有初始化或不必要的包装的不同函数。

import { debuglog } from 'node:util';
let log = debuglog('internals', (debug) => {
  // Replace with a logging function that optimizes out
  // testing if the section is enabled
  log = debug;
});const { debuglog } = require('node:util');
let log = debuglog('internals', (debug) => {
  // Replace with a logging function that optimizes out
  // testing if the section is enabled
  log = debug;
});copy

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);
}copy

hello from foo [123] copy

util.debug(section)#

util.debuglog 的别名。 使用允许读取，这并不意味着在使用 util.debuglog().enabled 时仅进行日志记录。

util.deprecate(fn, msg[, code])#

• fn <Function> 正在弃用的函数。
• msg <string> 调用已弃用的函数时显示的警告消息。
• code <string> 一个弃用代码。请参阅已弃用 API 列表以获取代码列表。
• 返回: <Function> 包装好的已弃用函数，用于发出警告。

util.deprecate() 方法包装 fn（可以是函数或类），使其标记为已弃用。

import { deprecate } from 'node:util';

export const obsoleteFunction = deprecate(() => {
  // Do something here.
}, 'obsoleteFunction() is deprecated. Use newShinyFunction() instead.');const { deprecate } = require('node:util');

exports.obsoleteFunction = deprecate(() => {
  // Do something here.
}, 'obsoleteFunction() is deprecated. Use newShinyFunction() instead.');copy

调用时，util.deprecate() 将返回一个函数，该函数将使用 'warning' 事件发出 DeprecationWarning。 警告将被发出并打印到 stderr，这是第一次调用返回的函数时。 发出警告后，将在不发出警告的情况下调用包装的函数。

如果在多次调用 util.deprecate() 中提供相同的可选 code，则仅针对该 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(); // Emits a deprecation warning with code DEP0001
fn2(); // Does not emit a deprecation warning because it has the same codeconst { 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(); // Emits a deprecation warning with code DEP0001
fn2(); // Does not emit a deprecation warning because it has the same codecopy

如果使用 --no-deprecation 或 --no-warnings 命令行标志，或者如果 process.noDeprecation 属性在首次弃用警告之前设置为 true，则 util.deprecate() 方法不执行任何操作。

如果设置了 --trace-deprecation 或 --trace-warnings 命令行标志，或者 process.traceDeprecation 属性设置为 true，则在第一次调用已弃用的函数时，警告和堆栈跟踪会打印到 stderr。

如果设置了 --throw-deprecation 命令行标志，或者 process.throwDeprecation 属性设置为 true，则在调用已弃用的函数时将引发异常。

--throw-deprecation 命令行标志和 process.throwDeprecation 属性优先于 --trace-deprecation 和 process.traceDeprecation。

util.diff(actual, expected)#

• actual <Array> | <string> 要比较的第一个值

• expected <Array> | <string> 要比较的第二个值

• 返回: <Array> 差异条目的数组。 每个条目都是一个包含两个元素的数组

  • 索引 0: <number> 操作码：-1 表示删除，0 表示无操作/未更改，1 表示插入
  • 索引 1: <string> 与操作关联的值

• 算法复杂度：O(N*D)，其中

• N 是两个序列组合的总长度（N = actual.length + expected.length）

• D 是编辑距离（将一个序列转换为另一个序列所需的最少操作数）。

util.diff() 比较两个字符串或数组值，并返回一个差异条目的数组。 它使用 Myers diff 算法来计算最小差异，该算法与断言错误消息内部使用的算法相同。

如果值相等，则返回一个空数组。

const { diff } = require('node:util');

// Comparing strings
const actualString = '12345678';
const expectedString = '12!!5!7!';
console.log(diff(actualString, expectedString));
// [
//   [0, '1'],
//   [0, '2'],
//   [1, '3'],
//   [1, '4'],
//   [-1, '!'],
//   [-1, '!'],
//   [0, '5'],
//   [1, '6'],
//   [-1, '!'],
//   [0, '7'],
//   [1, '8'],
//   [-1, '!'],
// ]
// Comparing arrays
const actualArray = ['1', '2', '3'];
const expectedArray = ['1', '3', '4'];
console.log(diff(actualArray, expectedArray));
// [
//   [0, '1'],
//   [1, '2'],
//   [0, '3'],
//   [-1, '4'],
// ]
// Equal values return empty array
console.log(diff('same', 'same'));
// [] copy

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

• format <string> 一个类似 printf 的格式字符串。

util.format() 方法返回一个格式化的字符串，该字符串使用第一个参数作为类似 printf 的格式字符串，该字符串可以包含零个或多个格式说明符。 每个说明符都将替换为来自相应参数的转换值。 支持的说明符是

• %s: String 将用于转换除 BigInt、Object 和 -0 之外的所有值。 BigInt 值将用 n 表示，并且既没有用户定义的 toString 函数也没有 Symbol.toPrimitive 函数的对象将使用 util.inspect() 进行检查，选项为 { depth: 0, colors: false, compact: 3 }。
• %d: Number 将用于转换除 BigInt 和 Symbol 之外的所有值。
• %i: parseInt(value, 10) 用于转换除 BigInt 和 Symbol 之外的所有值。
• %f: parseFloat(value) 用于转换除 Symbol 之外的所有值。
• %j: JSON。 如果参数包含循环引用，则替换为字符串 '[Circular]'。
• %o: Object。 具有通用 JavaScript 对象格式的对象字符串表示形式。 类似于 util.inspect()，选项为 { showHidden: true, showProxy: true }。 这将显示完整对象，包括不可枚举的属性和代理。
• %O: Object。 具有通用 JavaScript 对象格式的对象字符串表示形式。 类似于没有选项的 util.inspect()。 这将显示完整对象，不包括不可枚举的属性和代理。
• %c: CSS。 此说明符将被忽略，并将跳过传入的任何 CSS。
• %%: 单个百分号 ('%')。 这不占用参数。
• 返回: <string> 格式化的字符串

如果说明符没有相应的参数，则不会替换它

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

如果类型不是 string，则不属于格式字符串一部分的值将使用 util.inspect() 格式化。

如果传递给 util.format() 方法的参数多于说明符的数量，则额外的参数将连接到返回的字符串，用空格分隔

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

如果第一个参数不包含有效的格式说明符，则 util.format() 返回一个字符串，该字符串是由所有参数连接而成，用空格分隔

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

如果仅将一个参数传递给 util.format()，则会按原样返回，无需任何格式化

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

util.format() 是一种同步方法，旨在用作调试工具。 某些输入值可能会产生显着的性能开销，从而可能阻止事件循环。 请谨慎使用此函数，切勿在热代码路径中使用。

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

• inspectOptions <Object>
• format <string>

此函数与 util.format() 相同，不同之处在于它采用一个 inspectOptions 参数，该参数指定传递给 util.inspect() 的选项。

util.formatWithOptions({ colors: true }, 'See object %O', { foo: 42 });
// Returns 'See object { foo: 42 }', where `42` is colored as a number
// when printed to a terminal. copy

util.getCallSites([frameCount][, options])#

• frameCount <number> 要捕获为调用站点对象的帧的可选数量。 默认: 10。 允许的范围是 1 到 200 之间。
• options <Object> 可选
  • sourceMap <boolean> 从 source-map 重构堆栈跟踪中的原始位置。 默认情况下，使用标志 --enable-source-maps 启用。
• 返回: <Object[]> 调用站点对象的数组
  • functionName <string> 返回与此调用站点关联的函数的名称。
  • scriptName <string> 返回包含此调用站点函数的脚本的资源的名称。
  • scriptId <string> 返回脚本的唯一 ID，如 Chrome DevTools 协议 Runtime.ScriptId 中所述。
  • lineNumber <number> 返回 JavaScript 脚本行号（从 1 开始）。
  • columnNumber <number> 返回 JavaScript 脚本列号（从 1 开始）。

返回一个调用站点对象数组，其中包含调用函数的堆栈。

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}`);
  });
  // CallSite 1:
  // Function Name: exampleFunction
  // Script Name: /home/example.js
  // Line Number: 5
  // Column Number: 26

  // CallSite 2:
  // Function Name: anotherFunction
  // Script Name: /home/example.js
  // Line Number: 22
  // Column Number: 3

  // ...
}

// A function to simulate another stack layer
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}`);
  });
  // CallSite 1:
  // Function Name: exampleFunction
  // Script Name: /home/example.js
  // Line Number: 5
  // Column Number: 26

  // CallSite 2:
  // Function Name: anotherFunction
  // Script Name: /home/example.js
  // Line Number: 22
  // Column Number: 3

  // ...
}

// A function to simulate another stack layer
function anotherFunction() {
  exampleFunction();
}

anotherFunction();copy

可以通过将选项 sourceMap 设置为 true 来重构原始位置。 如果 source map 不可用，则原始位置将与当前位置相同。 启用 --enable-source-maps 标志后，例如在使用 --experimental-transform-types 时，sourceMap 默认情况下将为 true。

import { getCallSites } from 'node:util';

interface Foo {
  foo: string;
}

const callSites = getCallSites({ sourceMap: true });

// With sourceMap:
// Function Name: ''
// Script Name: example.js
// Line Number: 7
// Column Number: 26

// Without sourceMap:
// Function Name: ''
// Script Name: example.js
// Line Number: 2
// Column Number: 26 copy

const { getCallSites } = require('node:util');

const callSites = getCallSites({ sourceMap: true });

// With sourceMap:
// Function Name: ''
// Script Name: example.js
// Line Number: 7
// Column Number: 26

// Without sourceMap:
// Function Name: ''
// Script Name: example.js
// Line Number: 2
// Column Number: 26 copy

util.getSystemErrorName(err)#

• err <number>
• 返回: <string>

返回来自 Node.js API 的数字错误代码的字符串名称。 错误代码和错误名称之间的映射取决于平台。 有关常见错误的名称，请参见常见系统错误。

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

util.getSystemErrorMap()#

• 返回: <Map>

返回一个 Map，其中包含 Node.js API 提供的所有系统错误代码。错误代码和错误名称之间的映射取决于平台。有关常见错误的名称，请参阅常见系统错误。

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

util.getSystemErrorMessage(err)#

• err <number>
• 返回: <string>

返回来自 Node.js API 的数字错误代码的字符串消息。错误代码和字符串消息之间的映射取决于平台。

fs.access('file/that/does/not/exist', (err) => {
  const message = util.getSystemErrorMessage(err.errno);
  console.error(message);  // No such file or directory
}); copy

util.inherits(constructor, superConstructor)#

• constructor <Function>
• superConstructor <Function>

不鼓励使用 util.inherits()。请使用 ES6 class 和 extends 关键字来获得语言级别的继承支持。另请注意，这两种风格在语义上不兼容。

将一个构造函数的原型方法继承到另一个构造函数中。constructor 的原型将被设置为从 superConstructor 创建的新对象。

这主要是在 Object.setPrototypeOf(constructor.prototype, superConstructor.prototype) 的基础上添加一些输入验证。作为额外的便利，可以通过 constructor.super_ 属性访问 superConstructor。

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); // true
console.log(MyStream.super_ === EventEmitter); // true

stream.on('data', (data) => {
  console.log(`Received data: "${data}"`);
});
stream.write('It works!'); // Received data: "It works!" copy

使用 class 和 extends 的 ES6 示例

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');copy

util.inspect(object[, options])#

util.inspect(object[, showHidden[, depth[, colors]]])#

• object <any> 任何 JavaScript 原始类型或 Object。
• options <Object>
  • showHidden <boolean> 如果为 true，则格式化结果中包含 object 的不可枚举符号和属性。<WeakMap> 和 <WeakSet> 条目以及用户定义的原型属性（不包括方法属性）也包含在内。默认: false。
  • depth <number> 指定格式化 object 时要递归的次数。这对于检查大型对象很有用。要递归到最大调用堆栈大小，请传递 Infinity 或 null。默认: 2。
  • colors <boolean> 如果为 true，则输出将使用 ANSI 颜色代码进行样式化。颜色是可自定义的。请参阅自定义 util.inspect 颜色。默认: false。
  • customInspect <boolean> 如果为 false，则不会调用 [util.inspect.custom](depth, opts, inspect) 函数。默认: true。
  • showProxy <boolean> 如果为 true，则 Proxy 检查包括target 和 handler 对象。默认: false。
  • maxArrayLength <integer> 指定格式化时要包含的 Array、<TypedArray>、<Map>、<WeakMap> 和 <WeakSet> 元素的最大数量。设置为 null 或 Infinity 可显示所有元素。设置为 0 或负数可不显示任何元素。默认: 100。
  • maxStringLength <integer> 指定格式化时要包含的最大字符数。设置为 null 或 Infinity 可显示所有元素。设置为 0 或负数可不显示任何字符。默认: 10000。
  • breakLength <integer> 输入值跨多行拆分的长度。设置为 Infinity 可以将输入格式化为单行（与设置为 true 或任何数字 >= 1 的 compact 结合使用）。默认: 80。
  • compact <boolean> | <integer> 将此设置为 false 会导致每个对象键显示在新行上。它会在长于 breakLength 的文本中换行。如果设置为数字，则只要所有属性都适合 breakLength，最内部的 n 个元素就会在单行上合并。短数组元素也会分组在一起。有关更多信息，请参见下面的示例。默认: 3。
  • sorted <boolean> | <Function> 如果设置为 true 或函数，则对象的所有属性以及 Set 和 Map 条目都会在结果字符串中排序。如果设置为 true，则使用默认排序。如果设置为函数，则将其用作比较函数。
  • getters <boolean> | <string> 如果设置为 true，则检查 getter。如果设置为 'get'，则仅检查没有相应 setter 的 getter。如果设置为 'set'，则仅检查具有相应 setter 的 getter。这可能会导致副作用，具体取决于 getter 函数。默认: false。
  • numericSeparator <boolean> 如果设置为 true，则使用下划线分隔所有 bigint 和数字中每三位数字。默认: false。
• 返回: <string> object 的表示形式。

util.inspect() 方法返回 object 的字符串表示形式，用于调试。 util.inspect 的输出可能随时更改，不应以编程方式依赖它。可以传递其他 options 来更改结果。 util.inspect() 将使用构造函数的名称和/或 @@toStringTag 为检查的值创建一个可识别的标签。

class Foo {
  get [Symbol.toStringTag]() {
    return 'bar';
  }
}

class Bar {}

const baz = Object.create(null, { [Symbol.toStringTag]: { value: 'foo' } });

util.inspect(new Foo()); // 'Foo [bar] {}'
util.inspect(new Bar()); // 'Bar {}'
util.inspect(baz);       // '[foo] {}' copy

循环引用使用引用索引指向其锚点

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));
// <ref *1> {
//   a: [ [Circular *1] ],
//   b: <ref *2> { inner: [Circular *2], obj: [Circular *1] }
// }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));
// <ref *1> {
//   a: [ [Circular *1] ],
//   b: <ref *2> { inner: [Circular *2], obj: [Circular *1] }
// }copy

以下示例检查 util 对象的所有属性

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 }));copy

以下示例重点介绍了 compact 选项的效果

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 }));

// { a:
//   [ 1,
//     2,
//     [ [ 'Lorem ipsum dolor sit amet,\nconsectetur [...]', // A long line
//           'test',
//           'foo' ] ],
//     4 ],
//   b: Map(2) { 'za' => 1, 'zb' => 'test' } }

// Setting `compact` to false or an integer creates more reader friendly output.
console.log(inspect(o, { compact: false, depth: 5, breakLength: 80 }));

// {
//   a: [
//     1,
//     2,
//     [
//       [
//         'Lorem ipsum dolor sit amet,\n' +
//           'consectetur adipiscing elit, sed do eiusmod \n' +
//           'tempor incididunt ut labore et dolore magna aliqua.',
//         'test',
//         'foo'
//       ]
//     ],
//     4
//   ],
//   b: Map(2) {
//     'za' => 1,
//     'zb' => 'test'
//   }
// }

// Setting `breakLength` to e.g. 150 will print the "Lorem ipsum" text in a
// single line.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 }));

// { a:
//   [ 1,
//     2,
//     [ [ 'Lorem ipsum dolor sit amet,\nconsectetur [...]', // A long line
//           'test',
//           'foo' ] ],
//     4 ],
//   b: Map(2) { 'za' => 1, 'zb' => 'test' } }

// Setting `compact` to false or an integer creates more reader friendly output.
console.log(inspect(o, { compact: false, depth: 5, breakLength: 80 }));

// {
//   a: [
//     1,
//     2,
//     [
//       [
//         'Lorem ipsum dolor sit amet,\n' +
//           'consectetur adipiscing elit, sed do eiusmod \n' +
//           'tempor incididunt ut labore et dolore magna aliqua.',
//         'test',
//         'foo'
//       ]
//     ],
//     4
//   ],
//   b: Map(2) {
//     'za' => 1,
//     'zb' => 'test'
//   }
// }

// Setting `breakLength` to e.g. 150 will print the "Lorem ipsum" text in a
// single line.copy

showHidden 选项允许检查<WeakMap> 和 <WeakSet> 条目。如果条目多于 maxArrayLength，则不能保证显示哪些条目。这意味着两次检索相同的 <WeakSet> 条目可能会导致不同的输出。此外，任何时候都可能对没有剩余强引用的条目进行垃圾回收。

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 }));
// WeakSet { { a: 1 }, { b: 2 } }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 }));
// WeakSet { { a: 1 }, { b: 2 } }copy

sorted 选项确保对象的属性插入顺序不会影响 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 }));
// { a: '`a` comes before `b`', b: [ 2, 3, 1 ], c: Set(3) { 1, 2, 3 } }
console.log(inspect(o1, { sorted: (a, b) => b.localeCompare(a) }));
// { c: Set(3) { 3, 2, 1 }, b: [ 2, 3, 1 ], a: '`a` comes before `b`' }

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 }));
// { a: '`a` comes before `b`', b: [ 2, 3, 1 ], c: Set(3) { 1, 2, 3 } }
console.log(inspect(o1, { sorted: (a, b) => b.localeCompare(a) }));
// { c: Set(3) { 3, 2, 1 }, b: [ 2, 3, 1 ], a: '`a` comes before `b`' }

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 }),
);copy

numericSeparator 选项在所有数字中每三位数字添加一个下划线。

import { inspect } from 'node:util';

const thousand = 1000;
const million = 1000000;
const bigNumber = 123456789n;
const bigDecimal = 1234.12345;

console.log(inspect(thousand, { numericSeparator: true }));
// 1_000
console.log(inspect(million, { numericSeparator: true }));
// 1_000_000
console.log(inspect(bigNumber, { numericSeparator: true }));
// 123_456_789n
console.log(inspect(bigDecimal, { numericSeparator: true }));
// 1_234.123_45const { inspect } = require('node:util');

const thousand = 1000;
const million = 1000000;
const bigNumber = 123456789n;
const bigDecimal = 1234.12345;

console.log(inspect(thousand, { numericSeparator: true }));
// 1_000
console.log(inspect(million, { numericSeparator: true }));
// 1_000_000
console.log(inspect(bigNumber, { numericSeparator: true }));
// 123_456_789n
console.log(inspect(bigDecimal, { numericSeparator: true }));
// 1_234.123_45copy

util.inspect() 是一种用于调试的同步方法。其最大输出长度约为 128 MiB。导致输出更长的输入将被截断。

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,
    });

    // Five space padding because that's the size of "Box< ".
    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));
// "Box< true >"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,
    });

    // Five space padding because that's the size of "Box< ".
    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));
// "Box< true >"copy

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));
// "{ bar: 'baz' }"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));
// "{ bar: 'baz' }"copy

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);
// Prints Password <xxxxxxxx> copy

import { inspect } from 'node:util';
const arr = Array(156).fill(0);

console.log(arr); // Logs the truncated array
inspect.defaultOptions.maxArrayLength = null;
console.log(arr); // logs the full arrayconst { inspect } = require('node:util');
const arr = Array(156).fill(0);

console.log(arr); // Logs the truncated array
inspect.defaultOptions.maxArrayLength = null;
console.log(arr); // logs the full arraycopy

util.isDeepStrictEqual(val1, val2)#

• val1 <any>
• val2 <any>
• 返回: <boolean>

如果 val1 和 val2 之间存在深度严格相等，则返回 true。 否则，返回 false。

有关深度严格相等的更多信息，请参阅assert.deepStrictEqual()。

类: util.MIMEType#

MIMEType 类的一个实现。

按照浏览器约定，MIMEType 对象的所有属性都作为类原型上的 getter 和 setter 实现，而不是作为对象本身上的数据属性。

MIME 字符串是一个结构化字符串，包含多个有意义的组成部分。 解析后，将返回一个 MIMEType 对象，其中包含每个这些组成部分的属性。

import { MIMEType } from 'node:util';

const myMIME = new MIMEType('text/plain');const { MIMEType } = require('node:util');

const myMIME = new MIMEType('text/plain');copy

import { MIMEType } from 'node:util';
const myMIME = new MIMEType({ toString: () => 'text/plain' });
console.log(String(myMIME));
// Prints: text/plainconst { MIMEType } = require('node:util');
const myMIME = new MIMEType({ toString: () => 'text/plain' });
console.log(String(myMIME));
// Prints: text/plaincopy

import { MIMEType } from 'node:util';

const myMIME = new MIMEType('text/javascript');
console.log(myMIME.type);
// Prints: text
myMIME.type = 'application';
console.log(myMIME.type);
// Prints: application
console.log(String(myMIME));
// Prints: application/javascriptconst { MIMEType } = require('node:util');

const myMIME = new MIMEType('text/javascript');
console.log(myMIME.type);
// Prints: text
myMIME.type = 'application';
console.log(myMIME.type);
// Prints: application
console.log(String(myMIME));
// Prints: application/javascriptcopy

import { MIMEType } from 'node:util';

const myMIME = new MIMEType('text/ecmascript');
console.log(myMIME.subtype);
// Prints: ecmascript
myMIME.subtype = 'javascript';
console.log(myMIME.subtype);
// Prints: javascript
console.log(String(myMIME));
// Prints: text/javascriptconst { MIMEType } = require('node:util');

const myMIME = new MIMEType('text/ecmascript');
console.log(myMIME.subtype);
// Prints: ecmascript
myMIME.subtype = 'javascript';
console.log(myMIME.subtype);
// Prints: javascript
console.log(String(myMIME));
// Prints: text/javascriptcopy

import { MIMEType } from 'node:util';

const myMIME = new MIMEType('text/javascript;key=value');
console.log(myMIME.essence);
// Prints: text/javascript
myMIME.type = 'application';
console.log(myMIME.essence);
// Prints: application/javascript
console.log(String(myMIME));
// Prints: application/javascript;key=valueconst { MIMEType } = require('node:util');

const myMIME = new MIMEType('text/javascript;key=value');
console.log(myMIME.essence);
// Prints: text/javascript
myMIME.type = 'application';
console.log(myMIME.essence);
// Prints: application/javascript
console.log(String(myMIME));
// Prints: application/javascript;key=valuecopy

import { MIMEType } from 'node:util';

const myMIMES = [
  new MIMEType('image/png'),
  new MIMEType('image/gif'),
];
console.log(JSON.stringify(myMIMES));
// Prints: ["image/png", "image/gif"]const { MIMEType } = require('node:util');

const myMIMES = [
  new MIMEType('image/png'),
  new MIMEType('image/gif'),
];
console.log(JSON.stringify(myMIMES));
// Prints: ["image/png", "image/gif"]copy

类: util.MIMEParams#

MIMEParams API 提供对 MIMEType 参数的读写访问。

import { MIMEParams } from 'node:util';

const myParams = new MIMEParams();const { MIMEParams } = require('node:util');

const myParams = new MIMEParams();copy

import { MIMEType } from 'node:util';

const { params } = new MIMEType('text/plain;foo=0;bar=1');
for (const name of params.keys()) {
  console.log(name);
}
// Prints:
//   foo
//   barconst { MIMEType } = require('node:util');

const { params } = new MIMEType('text/plain;foo=0;bar=1');
for (const name of params.keys()) {
  console.log(name);
}
// Prints:
//   foo
//   barcopy

import { MIMEType } from 'node:util';

const { params } = new MIMEType('text/plain;foo=0;bar=1');
params.set('foo', 'def');
params.set('baz', 'xyz');
console.log(params.toString());
// Prints: foo=def;bar=1;baz=xyzconst { MIMEType } = require('node:util');

const { params } = new MIMEType('text/plain;foo=0;bar=1');
params.set('foo', 'def');
params.set('baz', 'xyz');
console.log(params.toString());
// Prints: foo=def;bar=1;baz=xyzcopy

import { MIMEType } from 'node:util';

const { params } = new MIMEType('text/plain;foo=bar;xyz=baz');
for (const [name, value] of params) {
  console.log(name, value);
}
// Prints:
//   foo bar
//   xyz bazconst { MIMEType } = require('node:util');

const { params } = new MIMEType('text/plain;foo=bar;xyz=baz');
for (const [name, value] of params) {
  console.log(name, value);
}
// Prints:
//   foo bar
//   xyz bazcopy

util.parseArgs([config])#

• config <Object> 用于提供解析的参数并配置解析器。 config 支持以下属性

  • args <string[]> 参数字符串数组。 默认: 删除 execPath 和 filename 的 process.argv。
  • options <Object> 用于描述解析器已知的参数。 options 的键是选项的长名称，值是<Object>，接受以下属性
    • type <string> 参数的类型，必须是 boolean 或 string。
    • multiple <boolean> 是否允许多次提供此选项。如果为 true，所有值将被收集到一个数组中。如果为 false，则选项的值以最后一次为准。默认值: false。
    • short <string> 选项的单字符别名。
    • default <string> | <boolean> | <string[]> | <boolean[]> 如果（且仅当）要解析的参数中没有出现该选项时，使用的默认值。 它必须与 type 属性的类型相同。 当 multiple 为 true 时，它必须是一个数组。
  • strict <boolean> 当遇到未知参数，或者传递的参数与 options 中配置的 type 不匹配时，是否应该抛出错误。默认值: true。
  • allowPositionals <boolean> 此命令是否接受位置参数。 默认值: 如果 strict 为 true，则为 false，否则为 true。
  • allowNegative <boolean> 如果为 true，则允许通过在选项名称前加上 --no- 来显式地将布尔选项设置为 false。默认值: false。
  • tokens <boolean> 返回解析后的 tokens。 这对于扩展内置行为非常有用，从添加额外的检查到以不同的方式重新处理 tokens。默认值: false。

• 返回值: <Object> 解析后的命令行参数

  • values <Object> 已解析的选项名称与其 <string> 或 <boolean> 值的映射。
  • positionals <string[]> 位置参数。
  • tokens <Object[]> | <undefined> 参见 parseArgs tokens 部分。 仅当 config 包含 tokens: true 时才返回。

提供比直接与 process.argv 交互更高层次的命令行参数解析 API。 接受预期参数的规范，并返回一个包含解析后的选项和位置参数的结构化对象。

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);
// Prints: [Object: null prototype] { foo: true, bar: 'b' } []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);
// Prints: [Object: null prototype] { foo: true, bar: 'b' } []copy

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 });

// Reprocess the option tokens and overwrite the returned values.
tokens
  .filter((token) => token.kind === 'option')
  .forEach((token) => {
    if (token.name.startsWith('no-')) {
      // Store foo:false for --no-foo
      const positiveName = token.name.slice(3);
      values[positiveName] = false;
      delete values[token.name];
    } else {
      // Resave value so last one wins if both --foo and --no-foo.
      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 });

// Reprocess the option tokens and overwrite the returned values.
tokens
  .filter((token) => token.kind === 'option')
  .forEach((token) => {
    if (token.name.startsWith('no-')) {
      // Store foo:false for --no-foo
      const positiveName = token.name.slice(3);
      values[positiveName] = false;
      delete values[token.name];
    } else {
      // Resave value so last one wins if both --foo and --no-foo.
      values[token.name] = token.value ?? true;
    }
  });

const color = values.color;
const logfile = values.logfile ?? 'default.log';

console.log({ logfile, color });copy

$ 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 } copy

util.parseEnv(content)#

• content <string>

.env 文件的原始内容。

• 返回值: <Object>

给定一个示例 .env 文件

const { parseEnv } = require('node:util');

parseEnv('HELLO=world\nHELLO=oh my\n');
// Returns: { HELLO: 'oh my' }import { parseEnv } from 'node:util';

parseEnv('HELLO=world\nHELLO=oh my\n');
// Returns: { HELLO: 'oh my' }copy

util.promisify(original)#

• original <Function>
• 返回值: <Function>

接受一个遵循常见错误优先回调风格的函数，即，以一个 (err, value) => ... 回调作为最后一个参数，并返回一个返回 Promise 的版本。

import { promisify } from 'node:util';
import { stat } from 'node:fs';

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

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

或者，等效地使用 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();copy

如果存在 original[util.promisify.custom] 属性，则 promisify 将返回其值，请参阅 自定义 Promise 化函数。

promisify() 假定 original 是一个函数，在所有情况下都将回调作为其最后一个参数。 如果 original 不是函数，promisify() 将抛出错误。 如果 original 是函数，但其最后一个参数不是错误优先回调，它仍然会被传递一个错误优先回调作为其最后一个参数。

除非经过特殊处理，否则在类方法或其他使用 this 的方法上使用 promisify() 可能无法按预期工作

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);
// TypeError: Cannot read properties of undefined (reading 'a')
// naiveBar().then(a => console.log(a));

naiveBar.call(foo).then((a) => console.log(a)); // '42'

const bindBar = naiveBar.bind(foo);
bindBar().then((a) => console.log(a)); // '42'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);
// TypeError: Cannot read properties of undefined (reading 'a')
// naiveBar().then(a => console.log(a));

naiveBar.call(foo).then((a) => console.log(a)); // '42'

const bindBar = naiveBar.bind(foo);
bindBar().then((a) => console.log(a)); // '42'copy

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]);
// prints 'true'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]);
// prints 'true'copy

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

const kCustomPromisifiedSymbol = Symbol.for('nodejs.util.promisify.custom');

doSomething[kCustomPromisifiedSymbol] = (foo) => {
  return new Promise((resolve, reject) => {
    doSomething(foo, resolve, reject);
  });
}; copy

util.stripVTControlCharacters(str)#

• str <string>
• 返回: <string>

返回删除了任何 ANSI 转义码的 str。

console.log(util.stripVTControlCharacters('\u001B[4mvalue\u001B[0m'));
// Prints "value" copy

util.styleText(format, text[, options])#

• format <string> | <Array> 在 util.inspect.colors 中定义的文本格式或文本格式数组。
• text <string> 要格式化的文本。
• options <Object>
  • validateStream <boolean> 当为 true 时，会检查 stream 以查看其是否可以处理颜色。 默认值: true。
  • stream <Stream> 一个流，如果可以着色，将会进行验证。 默认值: process.stdout。

此函数返回一个格式化的文本，考虑了传递的 format 以在终端中打印。 它知道终端的功能，并根据通过 NO_COLOR、NODE_DISABLE_COLORS 和 FORCE_COLOR 环境变量设置的配置进行操作。

import { styleText } from 'node:util';
import { stderr } from 'node:process';

const successMessage = styleText('green', 'Success!');
console.log(successMessage);

const errorMessage = styleText(
  'red',
  'Error! Error!',
  // Validate if process.stderr has TTY
  { 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!',
  // Validate if process.stderr has TTY
  { stream: stderr },
);
console.error(errorMessage);copy

util.inspect.colors 还提供了文本格式，例如 italic 和 underline，您可以将两者结合起来

console.log(
  util.styleText(['underline', 'italic'], 'My italic underlined message'),
); copy

当传递格式数组时，应用的格式的顺序是从左到右，因此以下样式可能会覆盖前一个样式。

console.log(
  util.styleText(['red', 'green'], 'text'), // green
); copy

完整的格式列表可以在 修饰符 中找到。

类: util.TextDecoder#

WHATWG 编码标准 TextDecoder API 的实现。

const decoder = new TextDecoder();
const u8arr = new Uint8Array([72, 101, 108, 108, 111]);
console.log(decoder.decode(u8arr)); // Hello copy

类: util.TextEncoder#

WHATWG 编码标准 TextEncoder API 的实现。 TextEncoder 的所有实例仅支持 UTF-8 编码。

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

TextEncoder 类也可在全局对象上使用。

const encoder = new TextEncoder();
const src = 'this is some data';
const dest = new Uint8Array(10);
const { read, written } = encoder.encodeInto(src, dest); copy

util.toUSVString(string)#

• string <string>

返回 string，在将任何代理代码点（或等效地，任何未配对的代理代码单元）替换为 Unicode“替换字符”U+FFFD 之后。

util.transferableAbortController()#

创建并返回一个 <AbortController> 实例，该实例的 <AbortSignal> 被标记为可传递，并且可以与 structuredClone() 或 postMessage() 一起使用。

util.transferableAbortSignal(signal)#

• signal <AbortSignal>
• 返回: <AbortSignal>

将给定的 <AbortSignal> 标记为可传递，以便它可以与 structuredClone() 和 postMessage() 一起使用。

const signal = transferableAbortSignal(AbortSignal.timeout(100));
const channel = new MessageChannel();
channel.port2.postMessage(signal, [signal]); copy

util.aborted(signal, resource)#

• signal <AbortSignal>
• resource <Object> 任何与可中止操作相关联并被弱引用的非空对象。 如果在 signal 中止之前垃圾回收了 resource，则 promise 将保持挂起状态，从而允许 Node.js 停止跟踪它。 这有助于防止长时间运行或不可取消操作中的内存泄漏。
• 返回: <Promise>

侦听提供的 signal 上的 abort 事件，并返回一个 promise，该 promise 在 signal 中止时解析。 如果提供了 resource，它会弱引用操作的关联对象，因此如果在 signal 中止之前垃圾回收了 resource，则返回的 promise 应保持挂起状态。 这可以防止长时间运行或不可取消操作中的内存泄漏。

const { aborted } = require('node:util');

// Obtain an object with an abortable signal, like a custom resource or operation.
const dependent = obtainSomethingAbortable();

// Pass `dependent` as the resource, indicating the promise should only resolve
// if `dependent` is still in memory when the signal is aborted.
aborted(dependent.signal, dependent).then(() => {

  // This code runs when `dependent` is aborted.
  console.log('Dependent resource was aborted.');
});

// Simulate an event that triggers the abort.
dependent.on('event', () => {
  dependent.abort(); // This will cause the `aborted` promise to resolve.
});import { aborted } from 'node:util';

// Obtain an object with an abortable signal, like a custom resource or operation.
const dependent = obtainSomethingAbortable();

// Pass `dependent` as the resource, indicating the promise should only resolve
// if `dependent` is still in memory when the signal is aborted.
aborted(dependent.signal, dependent).then(() => {

  // This code runs when `dependent` is aborted.
  console.log('Dependent resource was aborted.');
});

// Simulate an event that triggers the abort.
dependent.on('event', () => {
  dependent.abort(); // This will cause the `aborted` promise to resolve.
});copy

util.types#

util.types 为不同种类的内置对象提供类型检查。 与 instanceof 或 Object.prototype.toString.call(value) 不同，这些检查不会检查可以从 JavaScript 访问的对象的属性（例如它们的 prototype），并且通常具有调用 C++ 的开销。

通常，结果不会对值在 JavaScript 中公开的属性或行为类型做出任何保证。 它们主要供希望在 JavaScript 中进行类型检查的插件开发者使用。

该 API 可通过 require('node:util').types 或 require('node:util/types') 访问。

util.types.isAnyArrayBuffer(new ArrayBuffer());  // Returns true
util.types.isAnyArrayBuffer(new SharedArrayBuffer());  // Returns true copy

util.types.isArrayBufferView(new Int8Array());  // true
util.types.isArrayBufferView(Buffer.from('hello world')); // true
util.types.isArrayBufferView(new DataView(new ArrayBuffer(16)));  // true
util.types.isArrayBufferView(new ArrayBuffer());  // false copy

function foo() {
  util.types.isArgumentsObject(arguments);  // Returns true
} copy

util.types.isArrayBuffer(new ArrayBuffer());  // Returns true
util.types.isArrayBuffer(new SharedArrayBuffer());  // Returns false copy

util.types.isAsyncFunction(function foo() {});  // Returns false
util.types.isAsyncFunction(async function foo() {});  // Returns true copy

util.types.isBigInt64Array(new BigInt64Array());   // Returns true
util.types.isBigInt64Array(new BigUint64Array());  // Returns false copy

util.types.isBigIntObject(Object(BigInt(123)));   // Returns true
util.types.isBigIntObject(BigInt(123));   // Returns false
util.types.isBigIntObject(123);  // Returns false copy

util.types.isBigUint64Array(new BigInt64Array());   // Returns false
util.types.isBigUint64Array(new BigUint64Array());  // Returns true copy

util.types.isBooleanObject(false);  // Returns false
util.types.isBooleanObject(true);   // Returns false
util.types.isBooleanObject(new Boolean(false)); // Returns true
util.types.isBooleanObject(new Boolean(true));  // Returns true
util.types.isBooleanObject(Boolean(false)); // Returns false
util.types.isBooleanObject(Boolean(true));  // Returns false copy

util.types.isBoxedPrimitive(false); // Returns false
util.types.isBoxedPrimitive(new Boolean(false)); // Returns true
util.types.isBoxedPrimitive(Symbol('foo')); // Returns false
util.types.isBoxedPrimitive(Object(Symbol('foo'))); // Returns true
util.types.isBoxedPrimitive(Object(BigInt(5))); // Returns true copy

const ab = new ArrayBuffer(20);
util.types.isDataView(new DataView(ab));  // Returns true
util.types.isDataView(new Float64Array());  // Returns false copy

util.types.isDate(new Date());  // Returns true copy

#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)
... copy

import native from 'napi_addon.node';
import { types } from 'node:util';

const data = native.myNapi();
types.isExternal(data); // returns true
types.isExternal(0); // returns false
types.isExternal(new String('foo')); // returns falseconst native = require('napi_addon.node');
const { types } = require('node:util');

const data = native.myNapi();
types.isExternal(data); // returns true
types.isExternal(0); // returns false
types.isExternal(new String('foo')); // returns falsecopy

util.types.isFloat16Array(new ArrayBuffer());  // Returns false
util.types.isFloat16Array(new Float16Array());  // Returns true
util.types.isFloat16Array(new Float32Array());  // Returns false copy

util.types.isFloat32Array(new ArrayBuffer());  // Returns false
util.types.isFloat32Array(new Float32Array());  // Returns true
util.types.isFloat32Array(new Float64Array());  // Returns false copy

util.types.isFloat64Array(new ArrayBuffer());  // Returns false
util.types.isFloat64Array(new Uint8Array());  // Returns false
util.types.isFloat64Array(new Float64Array());  // Returns true copy

util.types.isGeneratorFunction(function foo() {});  // Returns false
util.types.isGeneratorFunction(function* foo() {});  // Returns true copy

function* foo() {}
const generator = foo();
util.types.isGeneratorObject(generator);  // Returns true copy

util.types.isInt8Array(new ArrayBuffer());  // Returns false
util.types.isInt8Array(new Int8Array());  // Returns true
util.types.isInt8Array(new Float64Array());  // Returns false copy

util.types.isInt16Array(new ArrayBuffer());  // Returns false
util.types.isInt16Array(new Int16Array());  // Returns true
util.types.isInt16Array(new Float64Array());  // Returns false copy

util.types.isInt32Array(new ArrayBuffer());  // Returns false
util.types.isInt32Array(new Int32Array());  // Returns true
util.types.isInt32Array(new Float64Array());  // Returns false copy

util.types.isMap(new Map());  // Returns true copy

const map = new Map();
util.types.isMapIterator(map.keys());  // Returns true
util.types.isMapIterator(map.values());  // Returns true
util.types.isMapIterator(map.entries());  // Returns true
util.types.isMapIterator(map[Symbol.iterator]());  // Returns true copy

import * as ns from './a.js';

util.types.isModuleNamespaceObject(ns);  // Returns true copy

console.log(util.types.isNativeError(new Error()));  // true
console.log(util.types.isNativeError(new TypeError()));  // true
console.log(util.types.isNativeError(new RangeError()));  // true copy

class MyError extends Error {}
console.log(util.types.isNativeError(new MyError()));  // true copy

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)); // true
console.log(myError instanceof Error); // falseconst { createContext, runInContext } = require('node:vm');
const { types } = require('node:util');

const context = createContext({});
const myError = runInContext('new Error()', context);
console.log(types.isNativeError(myError)); // true
console.log(myError instanceof Error); // falsecopy

const myError = { __proto__: Error.prototype };
console.log(util.types.isNativeError(myError)); // false
console.log(myError instanceof Error); // true copy

util.types.isNumberObject(0);  // Returns false
util.types.isNumberObject(new Number(0));   // Returns true copy

util.types.isPromise(Promise.resolve(42));  // Returns true copy

const target = {};
const proxy = new Proxy(target, {});
util.types.isProxy(target);  // Returns false
util.types.isProxy(proxy);  // Returns true copy

util.types.isRegExp(/abc/);  // Returns true
util.types.isRegExp(new RegExp('abc'));  // Returns true copy

util.types.isSet(new Set());  // Returns true copy

const set = new Set();
util.types.isSetIterator(set.keys());  // Returns true
util.types.isSetIterator(set.values());  // Returns true
util.types.isSetIterator(set.entries());  // Returns true
util.types.isSetIterator(set[Symbol.iterator]());  // Returns true copy

util.types.isSharedArrayBuffer(new ArrayBuffer());  // Returns false
util.types.isSharedArrayBuffer(new SharedArrayBuffer());  // Returns true copy

util.types.isStringObject('foo');  // Returns false
util.types.isStringObject(new String('foo'));   // Returns true copy

const symbol = Symbol('foo');
util.types.isSymbolObject(symbol);  // Returns false
util.types.isSymbolObject(Object(symbol));   // Returns true copy

util.types.isTypedArray(new ArrayBuffer());  // Returns false
util.types.isTypedArray(new Uint8Array());  // Returns true
util.types.isTypedArray(new Float64Array());  // Returns true copy

util.types.isUint8Array(new ArrayBuffer());  // Returns false
util.types.isUint8Array(new Uint8Array());  // Returns true
util.types.isUint8Array(new Float64Array());  // Returns false copy

util.types.isUint8ClampedArray(new ArrayBuffer());  // Returns false
util.types.isUint8ClampedArray(new Uint8ClampedArray());  // Returns true
util.types.isUint8ClampedArray(new Float64Array());  // Returns false copy

util.types.isUint16Array(new ArrayBuffer());  // Returns false
util.types.isUint16Array(new Uint16Array());  // Returns true
util.types.isUint16Array(new Float64Array());  // Returns false copy

util.types.isUint32Array(new ArrayBuffer());  // Returns false
util.types.isUint32Array(new Uint32Array());  // Returns true
util.types.isUint32Array(new Float64Array());  // Returns false copy

util.types.isWeakMap(new WeakMap());  // Returns true copy

util.types.isWeakSet(new WeakSet());  // Returns true copy

已弃用的 API#

以下 API 已弃用，不应再使用。 应更新现有的应用程序和模块以找到替代方法。

const util = require('node:util');

util.isArray([]);
// Returns: true
util.isArray(new Array());
// Returns: true
util.isArray({});
// Returns: false copy