util

Отслеживает событие прерывания для переданного signal и возвращает промис, который выполняется, когда операция signal прерывается. Если передан resource, он слабо ссылается на связанный с операцией объект, поэтому, если resource будет удален сборщиком мусора до того, как произойдет прерывание signal, возвращенный промис останется в ожидании. Это предотвращает утечки памяти при длительных или не подлежащих отмене операциях.

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

Принимает функцию async (или функцию, возвращающую Promise) и возвращает функцию, соответствующую стилю обратного вызова с передачей ошибки первым аргументом, то есть принимающую обратный вызов (err, value) => ... в качестве последнего аргумента. В обратном вызове первым аргументом будет причина отклонения (или null, если Promise выполнен успешно), а вторым аргументом — разрешённое значение.

import util from 'node:util';

async function fn() {
  return 'hello world';
}
const callbackFunction = util.callbackify(fn);

callbackFunction((err, ret) => {
  if (err) throw err;
  console.log(ret);
});

Будет выведено:

hello world

Обратный вызов выполняется асинхронно, и его трассировка стека будет ограничена. Если обратный вызов вызывает исключение, процесс сгенерирует событие '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
});

Метод util.debuglog() используется для создания функции, которая условно записывает отладочные сообщения в stderr в зависимости от наличия переменной среды NODE_DEBUG. Если имя section указано в значении этой переменной среды, возвращённая функция работает аналогично console.error(). В противном случае возвращённая функция ничего не делает.

import util from 'node:util';
const debuglog = util.debuglog('foo');

debuglog('hello from foo [%d]', 123);

Если запустить эту программу с NODE_DEBUG=foo в среде, она выведет примерно следующее:

FOO 3245: hello from foo [123]

где 3245 — это идентификатор процесса. Если запустить программу без заданной переменной среды, ничего выведено не будет.

В section также поддерживаются подстановочные знаки:

import util from 'node:util';
const debuglog = util.debuglog('foo-bar');

debuglog('hi there, it\'s foo-bar [%d]', 2333);

если запустить программу с NODE_DEBUG=foo* в среде, она выведет примерно следующее:

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

В переменной среды NODE_DEBUG можно указать несколько имён section, разделённых запятыми: NODE_DEBUG=fs,net,tls.

Необязательный аргумент callback можно использовать, чтобы заменить функцию журналирования другой функцией без инициализации и ненужной обёртки.

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

Метод util.deprecate() оборачивает fn (которым может быть функция или класс) таким образом, чтобы пометить его как устаревший.

import util from 'node:util';

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

При вызове util.deprecate() возвращает функцию, которая генерирует DeprecationWarning с помощью события 'warning'. Предупреждение будет сгенерировано и выведено в stderr при первом вызове возвращённой функции. После этого обёрнутая функция вызывается без предупреждения.

Если при нескольких вызовах util.deprecate() передаётся одно и то же необязательное значение code, предупреждение будет сгенерировано для этого code только один раз.

import util from 'node:util';

const fn1 = util.deprecate(someFunction, someMessage, 'DEP0001');
const fn2 = util.deprecate(someOtherFunction, someOtherMessage, 'DEP0001');
fn1(); // Emits a deprecation warning with code DEP0001
fn2(); // Does not emit a deprecation warning because it has the same code

Если используются флаги командной строки --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.format() возвращает отформатированную строку, используя первый аргумент в качестве строки формата, подобной printf, которая может содержать ноль или более спецификаторов формата. Каждый спецификатор заменяется преобразованным значением из соответствующего аргумента. Поддерживаются следующие спецификаторы:

Если для спецификатора нет соответствующего аргумента, он не заменяется:

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

Значения, не являющиеся частью строки формата, форматируются с помощью util.inspect(), если их тип не string.

Если методу util.format() передано больше аргументов, чем имеется спецификаторов, лишние аргументы объединяются с возвращаемой строкой через пробелы:

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

Если первый аргумент не содержит допустимого спецификатора формата, util.format() возвращает строку, составленную из всех аргументов, разделённых пробелами:

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

Если передан только один аргумент, util.format() возвращает его без изменений, не выполняя форматирование:

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

util.format() — синхронный метод, предназначенный для отладки. Обработка некоторых входных значений может значительно снижать производительность и блокировать цикл событий. Используйте эту функцию с осторожностью и никогда не вызывайте её в критически важном для производительности коде.

Эта функция идентична format, за исключением того, что принимает аргумент inspectOptions, задающий параметры, передаваемые в 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.

Возвращает массив объектов call site, содержащих стек вызывающей функции.

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

function exampleFunction() {
  const callSites = util.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();

Исходные местоположения можно восстановить, установив для параметра sourceMap значение true. Если карта исходного кода недоступна, исходное местоположение будет совпадать с текущим. Если включён флаг --enable-source-maps, например при использовании --experimental-transform-types, значение sourceMap по умолчанию будет равно true.

import util from 'node:util';

interface Foo {
  foo: string;
}

const callSites = util.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

Возвращает Map всех системных кодов ошибок, доступных в API Node.js. Соответствие между кодами и именами ошибок зависит от платформы. См. Common System Errors, где приведены имена распространённых ошибок.

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

Возвращает текстовое сообщение для числового кода ошибки, полученного из API Node.js. Соответствие между кодами ошибок и текстовыми сообщениями зависит от платформы.

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

Возвращает текстовое имя для числового кода ошибки, полученного из API Node.js. Соответствие между кодами и именами ошибок зависит от платформы. См. Common System Errors, где приведены имена распространённых ошибок.

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

Использование util.inherits() не рекомендуется. Для поддержки наследования на уровне языка используйте ключевые слова ES6 class и extends. Также обратите внимание, что эти два подхода семантически несовместимы.

Наследует методы прототипа одного конструктора другим. Прототип constructor будет установлен в новый объект, созданный на основе superConstructor.

В основном эта функция добавляет проверку входных данных поверх Object.setPrototypeOf(constructor.prototype, superConstructor.prototype). Для удобства superConstructor также будет доступен через свойство constructor.super_.

import util from 'node:util';
import EventEmitter from '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!"

Пример ES6 с использованием class и 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');

Метод 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] {}'

Циклические ссылки указывают на свой якорь с помощью индекса ссылки:

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] }
// }

В следующем примере проверяются все свойства объекта util:

import util from 'node:util';

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

В следующем примере показано влияние параметра compact:

import util 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(util.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(util.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.

Параметр 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 } }

Параметр 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 }),
);

Параметр numericSeparator добавляет подчёркивание после каждой группы из трёх цифр во всех числах.

import { inspect } from 'node:util';

const thousand = 1_000;
const million = 1_000_000;
const bigNumber = 123_456_789n;
const bigDecimal = 1_234.123_45;

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_45

util.inspect() — синхронный метод, предназначенный для отладки. Максимальная длина вывода составляет приблизительно 128 МиБ. Результаты для входных данных, дающих более длинный вывод, будут усечены.

Возвращает true, если между val1 и val2 выполняется глубокое строгое равенство. В противном случае возвращает false.

Подробнее о глубоком строгом равенстве см. в assert.deepStrictEqual().

Предоставляет высокоуровневый API для разбора аргументов командной строки, не требуя непосредственного взаимодействия с process.argv. Принимает спецификацию ожидаемых аргументов и возвращает структурированный объект с разобранными параметрами и позиционными аргументами.

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' } []

Стабильность: 1.1 — активная разработка. Пример файла .env:

import { parseEnv } from 'node:util';

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

Принимает функцию, использующую распространённый стиль обратного вызова с ошибкой в первом аргументе, то есть принимающую обратный вызов (err, value) => ... последним аргументом, и возвращает её версию, возвращающую промисы.

import util from 'node:util';
import fs from 'node:fs';

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

Или, что эквивалентно, с использованием async function:

import util from 'node:util';
import fs from 'node:fs';

const stat = util.promisify(fs.stat);

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

callStat();

Если присутствует свойство original[util.promisify.custom], promisify возвращает его значение; см. Custom promisified functions.

promisify() предполагает, что original во всех случаях является функцией, принимающей обратный вызов в качестве последнего аргумента. Если original не является функцией, promisify() выдаст ошибку. Если original является функцией, но её последний аргумент не является обратным вызовом с ошибкой в первом аргументе, ей всё равно будет передан такой обратный вызов в качестве последнего аргумента.

Использование promisify() с методами классов или другими методами, использующими this, может привести к неожиданным результатам, если не обработать их специальным образом:

import util from 'node:util';

class Foo {
  constructor() {
    this.a = 42;
  }

  bar(callback) {
    callback(null, this.a);
  }
}

const foo = new Foo();

const naiveBar = util.promisify(foo.bar);
// TypeError: Cannot read property 'a' of undefined
// 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'

Возвращает str без ANSI-кодов escape-последовательностей.

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

Эта функция возвращает отформатированный текст с учётом переданных format.

import { styleText } from 'node:util';
const errorMessage = styleText('red', 'Error! Error!');
console.log(errorMessage);

util.inspect.colors также предоставляет текстовые форматы, такие как italic и underline; их можно комбинировать:

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

Если передан массив форматов, они применяются слева направо, поэтому следующий стиль может переопределить предыдущий.

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

Полный список форматов можно найти в разделе модификаторы.

Возвращает string, заменяя все суррогатные кодовые точки (или, что эквивалентно, все непарные кодовые единицы суррогатов) символом замены Unicode U+FFFD.

Создаёт и возвращает экземпляр AbortController, чей AbortSignal помечен как передаваемый и может использоваться с structuredClone() или postMessage().

Помечает данный AbortSignal как передаваемый, чтобы его можно было использовать сstructuredClone() и postMessage().

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

Возвращает true, если значение является экземпляром встроенного ArrayBuffer или SharedArrayBuffer.

См. также util.types.isArrayBuffer() и util.types.isSharedArrayBuffer().

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

Возвращает true, если значение является объектом arguments.

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