util.callbackify(original)

• original <Function> Функция async
• Возвращает: <Function> функция в стиле обратного вызова

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

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

Выведет:

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.convertProcessSignalToExitCode(signalCode)

• signalCode <string> Имя сигнала (например, 'SIGTERM', 'SIGKILL').
• Возвращает: <number> | <null> Код завершения или null, если сигнал недопустим.

Метод util.convertProcessSignalToExitCode() преобразует имя сигнала в соответствующий код завершения POSIX. Согласно стандарту POSIX, код завершения процесса, завершённого сигналом, вычисляется как 128 + signal number.

import { convertProcessSignalToExitCode } from 'node:util';

console.log(convertProcessSignalToExitCode('SIGTERM')); // 143 (128 + 15)
console.log(convertProcessSignalToExitCode('SIGKILL')); // 137 (128 + 9)
console.log(convertProcessSignalToExitCode('INVALID')); // null

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

console.log(convertProcessSignalToExitCode('SIGTERM')); // 143 (128 + 15)
console.log(convertProcessSignalToExitCode('SIGKILL')); // 137 (128 + 9)
console.log(convertProcessSignalToExitCode('INVALID')); // null

Это особенно полезно при работе с процессами, чтобы определить код завершения на основе сигнала, завершившего процесс.

util.debuglog(section[, callback])

• section <string> Строка, указывающая часть приложения, для которой создаётся функция debuglog.
• callback <Function> Функция обратного вызова, вызываемая при первом вызове функции журналирования с аргументом-функцией, представляющим собой более оптимизированную функцию журналирования.
• Возвращает: <Function> Функция журналирования

Метод util.debuglog() используется для создания функции, которая условно записывает отладочные сообщения в stderr в зависимости от наличия переменной окружения NODE_DEBUG. Если имя 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);

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

FOO 3245: hello from foo [123] copy

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

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

import { debuglog } from 'node:util';
const log = debuglog('foo-bar');

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

const { debuglog } = require('node:util');
const log = debuglog('foo-bar');

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

если программа запущена с 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;
});

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

hello from foo [123] copy

util.debug(section)

Псевдоним для util.debuglog. Использование повышает читаемость и не подразумевает журналирование, если применяется только util.debuglog().enabled.

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

• fn <Function> Функция, объявляемая устаревшей.
• msg <string> Предупреждение, которое будет выведено при вызове устаревшей функции.
• code <string> Код устаревания. Список кодов см. в списке устаревших API.
• options <Object>
  • modifyPrototype <boolean> Если значение равно false, не изменять прототип объекта при выводе предупреждения об устаревании. По умолчанию: true.
• Возвращает: <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.');

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

Если один и тот же необязательный code передаётся в нескольких вызовах util.deprecate(), предупреждение будет выведено только один раз для этого 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 code

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(); // 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.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() сравнивает два строковых значения или два массива и возвращает массив записей различий. Для вычисления минимальных различий используется алгоритм 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

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

Если методу 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> Необязательное число кадров для захвата в виде объектов call site. По умолчанию: 10. Допустимый диапазон — от 1 до 200.
• options <Object> Необязательный параметр
  • sourceMap <boolean> Восстановить исходное расположение в трассировке стека на основе source map. По умолчанию включено с флагом --enable-source-maps.
• Возвращает: <Object[]> Массив объектов call site
  • functionName <string> Возвращает имя функции, связанной с этим call site.
  • scriptName <string> Возвращает имя ресурса, содержащего скрипт функции для этого call site.
  • scriptId <string> Возвращает уникальный идентификатор скрипта, используемый, например, в протоколе Chrome DevTools Runtime.ScriptId.
  • lineNumber <number> Возвращает номер строки скрипта JavaScript (начиная с 1).
  • columnNumber <number> Возвращает номер столбца скрипта JavaScript (начиная с 1).

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

В отличие от доступа к error.stack, результат, возвращаемый этим API, не изменяется под воздействием Error.prepareStackTrace.

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.columnNumber}`);
  });
  // 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.columnNumber}`);
  });
  // 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. Если 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>

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

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

util.getSystemErrorMap()

• Возвращает: <Map>

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

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>

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

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

util.setTraceSigInt(enable)

• enable <boolean>

Включает или отключает вывод трассировки стека при SIGINT. API доступен только в основном потоке.

util.inherits(constructor, superConstructor)

• constructor <Function>
• superConstructor <Function>

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

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

Этот метод в основном добавляет проверку входных данных поверх Object.setPrototypeOf(constructor.prototype, superConstructor.prototype). Кроме того, superConstructor будет доступен через свойство constructor.super_.

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

Пример 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');

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> Любое примитивное значение 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, чтобы форматировать входные данные в одну строку (в сочетании с compact, установленным в true или любое число >= 1). По умолчанию: 80.
  • compact <boolean> | <integer> Если установить значение false, каждый ключ объекта будет отображаться на новой строке. Текст, длина которого превышает breakLength, будет переноситься на новые строки. Если задано число, самые внутренние элементы уровня n объединяются в одну строку, если все свойства помещаются в breakLength. Короткие элементы массива также группируются. Дополнительные сведения см. в примере ниже. По умолчанию: 3.
  • sorted <boolean> | <Function> Если задано значение true или функция, все свойства объекта, а также элементы Set и Map сортируются в результирующей строке. Если задано значение true, используется сортировка по умолчанию. Если задана функция, она используется как функция сравнения.
  • getters <boolean> | <string> Если задано значение true, проверяются геттеры. Если задано значение 'get', проверяются только геттеры без соответствующего сеттера. Если задано значение 'set', проверяются только геттеры с соответствующим сеттером. В зависимости от функции геттера это может привести к побочным эффектам. По умолчанию: false.
  • numericSeparator <boolean> Если задано значение true, в больших целых числах и числах между каждыми тремя цифрами ставится подчёркивание. По умолчанию: false.
• Возвращает: <string> Представление object.

Метод util.inspect() возвращает строковое представление object, предназначенное для отладки. Вывод util.inspect может измениться в любой момент, поэтому не следует программно полагаться на него. Можно передать дополнительные options, которые изменят результат. util.inspect() использует имя конструктора и/или свойство Symbol.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] }
// }

В следующем примере проверяются все свойства объекта 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 }));

В следующем примере показано влияние параметра 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.

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

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

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

const { 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_45

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

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 >"

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' }"

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 array

const { 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 array

util.isDeepStrictEqual(val1, val2[, options])

• val1 <any>
• val2 <any>
• skipPrototype <boolean> Если значение равно true, сравнение прототипов и конструкторов при проверке глубокой строгой эквивалентности пропускается. По умолчанию: false.
• Возвращает: <boolean>

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

По умолчанию глубокая строгая эквивалентность включает сравнение прототипов и конструкторов объектов. Если skipPrototype имеет значение true, объекты с разными прототипами или конструкторами всё равно могут считаться равными, если их перечисляемые свойства глубоко строго эквивалентны.

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

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

class Bar {
  constructor(a) {
    this.a = a;
  }
}

const foo = new Foo(1);
const bar = new Bar(1);

// Different constructors, same properties
console.log(util.isDeepStrictEqual(foo, bar));
// false

console.log(util.isDeepStrictEqual(foo, bar, true));
// true copy

Дополнительные сведения о глубокой строгой эквивалентности см. в разделе assert.deepStrictEqual().

Класс: util.MIMEType

Реализация класса MIMEType.

В соответствии с соглашениями браузеров все свойства объектов MIMEType реализованы как геттеры и сеттеры в прототипе класса, а не как свойства данных самого объекта.

Строка MIME — это структурированная строка, содержащая несколько значимых компонентов. При её разборе возвращается объект MIMEType со свойствами для каждого из этих компонентов.

import { MIMEType } from 'node:util';

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

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

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

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

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

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/javascript

const { 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/javascript

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/javascript

const { 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/javascript

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=value

const { 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=value

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"]

Класс: util.MIMEParams

API MIMEParams предоставляет доступ на чтение и запись параметров MIMEType.

import { MIMEParams } from 'node:util';

const myParams = new MIMEParams();

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

const myParams = new MIMEParams();

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
//   bar

const { 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
//   bar

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=xyz

const { 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=xyz

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 baz

const { 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 baz

util.parseArgs([config])

• config <Object> Используется для передачи аргументов для разбора и настройки анализатора. config поддерживает следующие свойства:

  • args <string[]> массив строк аргументов. По умолчанию: process.argv без execPath и filename.
  • 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> Следует ли вызывать ошибку при обнаружении неизвестных аргументов или при передаче аргументов, не соответствующих type, настроенным в options. По умолчанию: true.
  • allowPositionals <boolean> Принимает ли эта команда позиционные аргументы. По умолчанию: false, если strict имеет значение true, в противном случае — true.
  • allowNegative <boolean> Если true, позволяет явно задавать для логических параметров значение false, добавляя перед именем параметра --no-. По умолчанию: false.
  • tokens <boolean> Возвращать разобранные токены. Это полезно для расширения встроенного поведения: от добавления дополнительных проверок до повторной обработки токенов различными способами. По умолчанию: false.

• Возвращает: <Object> Разобранные аргументы командной строки:

  • values <Object> Сопоставление разобранных имен параметров с их значениями типа <string> или <boolean>.
  • positionals <string[]> Позиционные аргументы.
  • tokens <Object[]> | <undefined> См. раздел Токены parseArgs. Возвращается только в том случае, если config включает tokens: true.

Предоставляет 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' } []

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

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

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

util.promisify(original)

• original <Function>
• Возвращает: <Function>

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

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

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

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

Если присутствует свойство original[util.promisify.custom], promisify вернет его значение. См. раздел Пользовательские функции с поддержкой промисов.

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

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

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'

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'

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>

Возвращает str без кодов ANSI escape.

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

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

Специальное значение формата none не добавляет к тексту никаких дополнительных стилей.

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

Класс: util.TextDecoder

Реализация API TextDecoder стандарта кодирования WHATWG.

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

Класс: util.TextEncoder

Реализация API TextEncoder стандарта кодирования WHATWG. Все экземпляры 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> Любой объект, отличный от null, связанный с прерываемой операцией и слабо удерживаемый в памяти. Если resource будет удалён сборщиком мусора до прерывания signal, промис останется ожидающим, что позволит Node.js перестать отслеживать его. Это помогает предотвратить утечки памяти при длительных или неотменяемых операциях.
• Возвращает: <Promise>

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

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

util.types

util.types предоставляет проверки типов для различных видов встроенных объектов. В отличие от instanceof или Object.prototype.toString.call(value), эти проверки не анализируют свойства объекта, доступные из JavaScript (например, его прототип), и обычно требуют накладных расходов на вызов 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 false

const 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 false

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); // false

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)); // true
console.log(myError instanceof Error); // false

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

Устаревшие API

Следующие API устарели и больше не должны использоваться. Существующие приложения и модули следует обновить, чтобы найти альтернативные подходы.

npx codemod@latest @nodejs/util-extend-to-object-assign copy

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

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

npx codemod@latest @nodejs/util-is copy