Util

Исходный код: lib/util.js

Модуль node:util поддерживает потребности внутренних API Node.js. Многие утилиты также полезны разработчикам приложений и модулей. Чтобы получить к нему доступ:

Модули JavaScript

import util from 'node:util';

CommonJS

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

`util.callbackify(original)`

Добавлено в: v8.2.0

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

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

Модули JavaScript

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

CommonJS

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
textcopy

Обратный вызов выполняется асинхронно и имеет ограниченную трассировку стека. Если обратный вызов выдаёт исключение, процесс сгенерирует событие 'uncaughtException' и завершится, если это событие не будет обработано.

Поскольку null имеет особое значение в качестве первого аргумента обратного вызова, если обёрнутая функция отклоняет Promise с ложным значением в качестве причины, это значение оборачивается в Error, а исходное значение сохраняется в поле с именем reason.

Модули JavaScript

import util from 'node:util';

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

CommonJS

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

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

Добавлено в: v25.4.0, v24.14.0

signal <string> Имя сигнала (например, 'SIGTERM')
Возвращает: <number> Код завершения, соответствующий signal

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

Если signal не является допустимым именем сигнала, будет выдана ошибка. Список допустимых сигналов см. в разделе signal(7).

Модули JavaScript

import { convertProcessSignalToExitCode } from 'node:util';

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

CommonJS

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

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

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

`util.debuglog(section[, callback])`

Добавлено в: v0.11.3

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

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

Модули JavaScript

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

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

CommonJS

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

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

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

FOO 3245: hello from foo [123]
consolecopy

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

Функция section также поддерживает подстановочные знаки:

Модули JavaScript

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

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

CommonJS

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

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

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

Модули JavaScript

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

CommonJS

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

`debuglog().enabled`

Добавлено в: v14.9.0

Тип: <boolean>

Геттер util.debuglog().enabled используется для создания проверки, применяемой в условных выражениях в зависимости от наличия переменной среды NODE_DEBUG. Если имя section присутствует в значении этой переменной среды, возвращаемое значение будет true. В противном случае возвращаемое значение будет false.

Модули JavaScript

import { debuglog } from 'node:util';
const enabled = debuglog('foo').enabled;
if (enabled) {
  console.log('hello from foo [%d]', 123);
}

CommonJS

const { debuglog } = require('node:util');
const enabled = debuglog('foo').enabled;
if (enabled) {
  console.log('hello from foo [%d]', 123);
}

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

hello from foo [123]
consolecopy

`util.debug(section)`

Добавлено в: v14.9.0

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

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

Добавлено в: v0.8.0

История

Версия	Изменения
v25.2.0, v24.12.0	Добавлен объект options с параметром modifyPrototype для условного изменения прототипа устаревшего объекта.
v10.0.0

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

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

Модули JavaScript

import { deprecate } from 'node:util';

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

CommonJS

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.

Модули JavaScript

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

CommonJS

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

Добавлено в: v23.11.0, v22.15.0

Стабильность: 1 — Экспериментальный

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'));
// []
jscopy

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

Добавлено в: v0.5.3

История

Версия	Изменения
v12.11.0	Спецификатор `%c` теперь игнорируется.
v12.0.0	Аргумент `format` теперь рассматривается как таковой, только если он действительно содержит спецификаторы формата.
v12.0.0	Если аргумент `format` не является строкой формата, форматирование выходной строки больше не зависит от типа первого аргумента. Это изменение удаляет ранее добавлявшиеся кавычки вокруг строк, выводившихся, когда первый аргумент не был строкой.
v11.4.0	Спецификаторы `%d`, `%f` и `%i` теперь корректно поддерживают Symbols.
v11.4.0	Для параметра `depth` спецификатора `%o` снова задана глубина по умолчанию 4.
v11.0.0	Параметр `depth` спецификатора `%o` теперь использует глубину по умолчанию, если значение не указано.
v10.12.0	Спецификаторы `%d` и `%i` теперь поддерживают BigInt.
v8.4.0	Теперь поддерживаются спецификаторы `%o` и `%O`.

format <string> Строка формата в стиле printf.

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

%s: для преобразования всех значений, кроме BigInt, Object и -0, будет использоваться String. Значения BigInt будут представлены как n, а объекты, у которых нет пользовательской функции toString и функции Symbol.toPrimitive, проверяются с помощью util.inspect() с параметрами { depth: 0, colors: false, compact: 3 }.
%d: для преобразования всех значений, кроме BigInt и Symbol, будет использоваться Number.
%i: для всех значений, кроме BigInt и Symbol, используется parseInt(value, 10).
%f: для всех значений, кроме Symbol, используется parseFloat(value).
%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'
jscopy

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

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

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

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

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

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

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

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

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

Добавлено в: v10.0.0

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.
jscopy

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

Добавлено в: v22.9.0

История

Версия	Изменения
v23.7.0, v22.14.0	Свойство `column` объявлено устаревшим в пользу `columnNumber`.
v23.7.0, v22.14.0	Добавлено свойство `CallSite.scriptId`.
v23.3.0, v22.12.0	API переименован из `util.getCallSite` в `util.getCallSites()`.

Стабильность: 1.1 — Активная разработка

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

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

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

Модули JavaScript

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

CommonJS

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, значение 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
tscopy

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
cjscopy

`util.getSystemErrorName(err)`

Добавлено в: v9.7.0

err <number>
Возвращает: <string>

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

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

`util.getSystemErrorMap()`

Добавлено в: v16.0.0, v14.17.0

Возвращает: <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
});
jscopy

`util.getSystemErrorMessage(err)`

Добавлено в: v23.1.0, v22.12.0

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

`util.setTraceSigInt(enable)`

Добавлено в: v24.6.0, v22.19.0

enable <boolean>

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

`util.inherits(constructor, superConstructor)`

Добавлено в: v0.3.0

История

Версия	Изменения
v5.0.0	Теперь параметр `constructor` может ссылаться на класс ES6.

Стабильность: 3 — Устаревший интерфейс: используйте синтаксис классов ES2015 и ключевое слово extends.

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

Пример ES6 с использованием class и extends:

Модули JavaScript

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

CommonJS

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]]])`

Добавлено в: v0.3.0

История

Версия	Изменения
v25.0.0	Стиль util.inspect.styles.regexp теперь является методом, который вызывается для раскрашивания преобразованного в строку регулярного выражения.
v17.3.0, v16.14.0	Теперь поддерживается параметр `numericSeparator`.
v16.18.0	добавлена поддержка `maxArrayLength` при проверке `Set` и `Map`.
v14.6.0, v12.19.0	Если `object` теперь относится к другому `vm.Context`, пользовательская функция проверки для него больше не будет получать аргументы, зависящие от контекста.
v13.13.0, v12.17.0	Теперь поддерживается параметр `maxStringLength`.
v13.5.0, v12.16.0	Свойства прототипа, определённые пользователем, проверяются, если `showHidden` равен `true`.
v13.0.0	Циклические ссылки теперь включают маркер, указывающий на ссылку.
v12.0.0	Значение параметра `compact` по умолчанию изменено на `3`, а значение параметра `breakLength` по умолчанию изменено на `80`.
v12.0.0	Внутренние свойства больше не отображаются в аргументе контекста пользовательской функции проверки.
v11.11.0	Параметр `compact` принимает числа для нового режима вывода.
v11.7.0	Теперь объекты ArrayBuffer также отображают своё двоичное содержимое.
v11.5.0	Теперь поддерживается параметр `getters`.
v11.4.0	Значение `depth` по умолчанию снова изменено на `2`.
v11.0.0	Значение `depth` по умолчанию изменено на `20`.
v11.0.0	Теперь размер вывода проверки ограничен примерно 128 МиБ. Данные, превышающие этот размер, не будут проверены полностью.
v10.12.0	Теперь поддерживается параметр `sorted`.
v10.6.0	Теперь можно проверять связанные списки и подобные объекты вплоть до максимального размера стека вызовов.
v10.0.0	Теперь можно проверять также записи `WeakMap` и `WeakSet`.
v9.9.0	Теперь поддерживается параметр `compact`.
v6.6.0	Пользовательские функции проверки теперь могут возвращать `this`.
v6.3.0	Теперь поддерживается параметр `breakLength`.
v6.1.0	Теперь поддерживается параметр `maxArrayLength`; в частности, длинные массивы по умолчанию усекаются.
v6.1.0	Теперь поддерживается параметр `showProxy`.

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] {}'
jscopy

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

Модули JavaScript

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

CommonJS

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:

Модули JavaScript

import util from 'node:util';

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

CommonJS

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

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

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

Модули JavaScript

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.

CommonJS

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> результат может отличаться. Кроме того, записи, на которые больше не осталось сильных ссылок, могут быть удалены сборщиком мусора в любой момент.

Модули JavaScript

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

CommonJS

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

Модули JavaScript

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

CommonJS

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 добавляет знак подчёркивания после каждых трёх цифр во всех числах.

Модули JavaScript

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

CommonJS

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 МиБ. Входные данные, для которых результат превышает эту длину, будут усечены.

Настройка цветов `util.inspect`

Цвета вывода util.inspect (если они включены) можно настраивать глобально с помощью свойств util.inspect.styles и util.inspect.colors.

util.inspect.styles — это карта, сопоставляющая имя стиля с цветом из util.inspect.colors.

Стили по умолчанию и соответствующие им цвета:

bigint: yellow
boolean: yellow
date: magenta
module: underline
name: (без оформления)
null: bold
number: yellow
regexp: Метод, который раскрашивает классы символов, группы, проверки и другие части для повышения удобочитаемости. Чтобы настроить раскраску, измените свойство colors. По умолчанию оно имеет значение ['red', 'green', 'yellow', 'cyan', 'magenta'], но его можно изменить при необходимости. В зависимости от «глубины» массив обходится повторно.
special: cyan (например, Proxies)
string: green
symbol: green
undefined: grey

Для цветового оформления используются управляющие коды ANSI, которые могут поддерживаться не всеми терминалами. Чтобы проверить поддержку цветов, используйте tty.hasColors().

Предопределённые управляющие коды перечислены ниже (в группах «Модификаторы», «Цвета переднего плана» и «Цвета фона»).

Сложная пользовательская раскраска

В качестве стиля можно определить метод. Он получает строковое представление входного значения. Метод вызывается, если активна раскраска и проверяется соответствующий тип.

Пример: util.inspect.styles.regexp(value)

value <string> Строковое представление входного типа.
Возвращает: <string> Изменённое представление object.

Модификаторы

Поддержка модификаторов зависит от терминала. Если модификатор не поддерживается, он обычно игнорируется.

reset — сбрасывает все модификаторы (цвета) к значениям по умолчанию
жирный — делает текст жирным
курсив — делает текст курсивным
подчёркнутый — подчёркивает текст
~~зачёркнутый~~ — проводит горизонтальную линию через середину текста (псевдонимы: strikeThrough, crossedout, crossedOut)
hidden — выводит текст, но делает его невидимым (псевдоним: conceal)
приглушённый — снижает интенсивность цвета (псевдоним: faint)
надчёркнутый — проводит линию над текстом
мигание — периодически скрывает и показывает текст
инвертированный — меняет местами цвета переднего плана и фона (псевдонимы: swapcolors, swapColors)
с двойным подчёркиванием — подчёркивает текст двойной линией (псевдоним: doubleUnderline)
в рамке — обводит текст рамкой

Цвета переднего плана

black
red
green
yellow
blue
magenta
cyan
white
gray (псевдоним: grey, blackBright)
redBright
greenBright
yellowBright
blueBright
magentaBright
cyanBright
whiteBright

Цвета фона

bgBlack
bgRed
bgGreen
bgYellow
bgBlue
bgMagenta
bgCyan
bgWhite
bgGray (псевдоним: bgGrey, bgBlackBright)
bgRedBright
bgGreenBright
bgYellowBright
bgBlueBright
bgMagentaBright
bgCyanBright
bgWhiteBright

Пользовательские функции проверки объектов

Добавлено в: v0.1.97

История

Версия	Изменения
v17.3.0, v16.14.0	Для повышения совместимости добавлен аргумент inspect.

Объекты также могут определять собственную функцию [util.inspect.custom](depth, opts, inspect), которую util.inspect() вызывает при проверке объекта и использует её результат.

Модули JavaScript

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

CommonJS

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

Пользовательские функции [util.inspect.custom](depth, opts, inspect) обычно возвращают строку, но могут возвращать значение любого типа, которое util.inspect() отформатирует соответствующим образом.

Модули JavaScript

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

CommonJS

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

`util.inspect.custom`

Добавлено в: v6.6.0

История

Версия	Изменения
v10.12.0	Теперь этот символ определён как общий.

Тип: <symbol>, который можно использовать для объявления пользовательских функций проверки.

Помимо доступности через util.inspect.custom, этот символ зарегистрирован глобально и доступен в любой среде как Symbol.for('nodejs.util.inspect.custom').

Это позволяет писать переносимый код: пользовательская функция проверки будет использоваться в среде Node.js и игнорироваться в браузере. Сама функция util.inspect() передаётся пользовательской функции проверки третьим аргументом, что обеспечивает дополнительную переносимость.

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

Дополнительные сведения см. в разделе Пользовательские функции проверки объектов.

`util.inspect.defaultOptions`

Добавлено в: v6.4.0

Значение defaultOptions позволяет настраивать параметры по умолчанию, используемые util.inspect. Это полезно для таких функций, как console.log или util.format, которые неявно вызывают util.inspect. Ему следует присвоить объект, содержащий один или несколько допустимых параметров util.inspect(). Также поддерживается непосредственное задание свойств параметров.

Модули JavaScript

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

CommonJS

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])`

Добавлено в: v9.0.0

История

Версия	Изменения
v24.9.0	Добавлен параметр `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
jscopy

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

Класс: `util.MIMEType`

Добавлено в: v19.1.0, v18.13.0

История

Версия	Изменения
v23.11.0, v22.15.0	API объявлен стабильным.

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

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

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

`new MIMEType(input)`

input <string> Входные данные MIME для разбора

Создаёт новый объект MIMEType, разбирая input.

Модули JavaScript

import { MIMEType } from 'node:util';

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

CommonJS

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

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

Если input не является допустимым MIME, будет выброшено исключение TypeError. Обратите внимание, что предпринимается попытка преобразовать переданные значения в строки. Например:

Модули JavaScript

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

CommonJS

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

`mime.type`

Тип: <string>

Получает и задаёт часть MIME, содержащую тип.

Модули JavaScript

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

CommonJS

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

`mime.subtype`

Тип: <string>

Получает и задаёт часть MIME, содержащую подтип.

Модули 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

CommonJS

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

`mime.essence`

Тип: <string>

Получает основу MIME. Это свойство доступно только для чтения. Чтобы изменить MIME, используйте mime.type или mime.subtype.

Модули 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

CommonJS

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

`mime.params`

Тип: <MIMEParams>

Получает объект MIMEParams, представляющий параметры MIME. Это свойство доступно только для чтения. Подробности см. в документации MIMEParams.

`mime.toString()`

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

Метод toString() объекта MIMEType возвращает сериализованный MIME.

Для обеспечения соответствия стандартам этот метод не позволяет пользователям настраивать процесс сериализации MIME.

`mime.toJSON()`

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

Псевдоним для mime.toString().

Этот метод вызывается автоматически, когда объект MIMEType сериализуется с помощью JSON.stringify().

Модули JavaScript

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

CommonJS

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`

Добавлено в: v19.1.0, v18.13.0

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

`new MIMEParams()`

Создаёт новый объект MIMEParams с пустыми параметрами

Модули JavaScript

import { MIMEParams } from 'node:util';

const myParams = new MIMEParams();

CommonJS

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

const myParams = new MIMEParams();

`mimeParams.delete(name)`

name <string>

Удаляет все пары «имя — значение», имя которых равно name.

`mimeParams.entries()`

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

Возвращает итератор по всем парам «имя — значение» в параметрах. Каждый элемент итератора — это массив JavaScript Array. Первый элемент массива — это name, второй — value.

`mimeParams.get(name)`

name <string>
Возвращает: <string> | <null> Строку или null, если пары «имя — значение» с указанным name нет.

Возвращает значение первой пары «имя — значение», имя которой равно name. Если таких пар нет, возвращается null.

`mimeParams.has(name)`

name <string>
Возвращает: <boolean>

Возвращает true, если существует хотя бы одна пара «имя — значение», имя которой равно name.

`mimeParams.keys()`

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

Возвращает итератор по именам каждой пары «имя — значение».

Модули JavaScript

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

CommonJS

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

`mimeParams.set(name, value)`

name <string>
value <string>

Задаёт значение в объекте MIMEParams, связанном с name, равным value. Если уже существуют пары «имя — значение» с именами name, задаёт значение первой такой пары равным value.

Модули JavaScript

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

CommonJS

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

`mimeParams.values()`

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

Возвращает итератор по значениям каждой пары «имя — значение».

`mimeParams[Symbol.iterator]()`

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

Псевдоним для mimeParams.entries().

Модули JavaScript

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

CommonJS

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])`

Добавлено в: v18.3.0, v16.17.0

История

Версия	Изменения
v22.4.0, v20.16.0	Добавлена поддержка разрешения отрицательных параметров во входных данных `config`.
v20.0.0	API больше не является экспериментальным.
v18.11.0, v16.19.0	Добавлена поддержка значений по умолчанию во входных данных `config`.
v18.7.0, v16.17.0	Добавлена поддержка возврата подробной информации о разборе с помощью `tokens` во входных данных `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. Принимает спецификацию ожидаемых аргументов и возвращает структурированный объект с разобранными параметрами и позиционными аргументами.

Модули JavaScript

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

CommonJS

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

`parseArgs` `tokens`

Подробная информация о разборе доступна для добавления пользовательского поведения: для этого в конфигурации нужно указать tokens: true. Возвращаемые токены имеют свойства, описывающие:

все токены
- kind <string> Одно из значений: 'option', 'positional' или 'option-terminator'.
- index <number> Индекс элемента в args, содержащего токен. Таким образом, исходный аргумент для токена — args[token.index].
токены параметров
- name <string> Длинное имя параметра.
- rawName <string> Способ использования параметра в аргументах, например -f из --foo.
- value <string> | <undefined> Значение параметра, указанное в аргументах. Для логических параметров не определено.
- inlineValue <boolean> | <undefined> Указано ли значение параметра непосредственно, например --foo=bar.
позиционные токены
- value <string> Значение позиционного аргумента в аргументах (то есть args[index]).
токен завершения параметров

Возвращаемые токены расположены в том порядке, в котором они встречаются во входных аргументах. Для каждого параметра, встречающегося в аргументах несколько раз, создаётся отдельный токен. Группы коротких параметров, например -xy, разворачиваются в отдельный токен для каждого параметра. Поэтому -xxx создаёт три токена.

Например, чтобы добавить поддержку параметра с отрицанием, такого как --no-color (поддерживаемого allowNegative для параметров типа boolean), возвращаемые токены можно обработать повторно, чтобы изменить значение, сохранённое для параметра с отрицанием.

Модули JavaScript

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

CommonJS

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 }
consolecopy

`util.parseEnv(content)`

Добавлено в: v21.7.0, v20.12.0

История

Версия	Изменения
v24.10.0, v22.21.0	Этот API больше не является экспериментальным.

content <string>

Необработанное содержимое файла .env.

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

Пример файла .env:

CommonJS

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

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

Модули JavaScript

import { parseEnv } from 'node:util';

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

`util.promisify(original)`

Добавлено в: v8.0.0

История

Версия	Изменения
v20.8.0	Вызов `promisify` для функции, возвращающей `Promise`, считается устаревшим.

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

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

Модули JavaScript

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

CommonJS

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:

Модули JavaScript

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

CommonJS

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, может привести к неожиданному результату, если не обработать их особым образом:

Модули JavaScript

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'

CommonJS

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'

Пользовательские функции с поддержкой промисов

С помощью символа util.promisify.custom можно переопределить возвращаемое значение util.promisify():

Модули JavaScript

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'

CommonJS

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'

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

Например, для функции, принимающей (foo, onSuccessCallback, onErrorCallback):

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

Если promisify.custom определено, но не является функцией, promisify() выдаст ошибку.

`util.promisify.custom`

Добавлено в: v8.0.0

История

Версия	Изменения
v13.12.0, v12.16.2	Теперь определён как общий символ.

Тип: <symbol>, который можно использовать для объявления пользовательских вариантов функций с поддержкой промисов; см. раздел Пользовательские функции с поддержкой промисов.

Помимо доступности через util.promisify.custom, этот символ зарегистрирован глобально и доступен в любой среде как Symbol.for('nodejs.util.promisify.custom').

Например, для функции, принимающей (foo, onSuccessCallback, onErrorCallback):

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

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

`util.stripVTControlCharacters(str)`

Добавлено в: v16.11.0

str <string>
Возвращает: <string>

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

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

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

Добавлено в: v21.7.0, v20.12.0

История

Версия	Изменения
v26.1.0	Добавлена поддержка шестнадцатеричных цветов.
v24.2.0, v22.17.0	Добавлен формат `'none'`, не выполняющий никаких операций.
v23.5.0, v22.13.0	styleText теперь имеет стабильный статус.
v22.8.0, v20.18.0	Учитывает isTTY и переменные среды, такие как NO_COLOR, NODE_DISABLE_COLORS и FORCE_COLOR.

format <string> | <Array> Формат текста или массив форматов текста, определённых в util.inspect.colors, либо шестнадцатеричный цвет в формате #RGB или #RRGGBB.
text <string> Текст для форматирования.
options <Object>
- validateStream <boolean> Если значение равно true, проверяется, может ли stream работать с цветами. По умолчанию: true.
- stream <Stream> Поток, для которого будет проверена возможность раскрашивания. По умолчанию: process.stdout.

Эта функция возвращает отформатированный текст, учитывая переданные format для вывода в терминал. Она учитывает возможности терминала и действует в соответствии с настройками, заданными переменными среды NO_COLOR, NODE_DISABLE_COLORS и FORCE_COLOR.

Модули JavaScript

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

CommonJS

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'),
);
cjscopy

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

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

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

Помимо предопределённых названий цветов, util.styleText() поддерживает шестнадцатеричные цветовые строки с использованием ANSI escape-последовательностей TrueColor (24 бита). Шестнадцатеричные цвета можно задавать в формате из 3 (#RGB) или 6 (#RRGGBB) цифр:

Модули JavaScript

import { styleText } from 'node:util';

// 6-digit hex color
console.log(styleText('#ff5733', 'Orange text'));

// 3-digit hex color (shorthand)
console.log(styleText('#f00', 'Red text'));

CommonJS

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

// 6-digit hex color
console.log(styleText('#ff5733', 'Orange text'));

// 3-digit hex color (shorthand)
console.log(styleText('#f00', 'Red text'));

модификаторы.

Класс: `util.TextDecoder`

Добавлено в: v8.3.0

История

Версия	Изменения
v11.0.0	Класс теперь доступен в глобальном объекте.

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

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

Поддерживаемые кодировки WHATWG

Согласно стандарту кодирования WHATWG, кодировки, поддерживаемые API TextDecoder, перечислены в таблицах ниже. Для каждой кодировки можно использовать один или несколько псевдонимов.

Различные конфигурации сборки Node.js поддерживают разные наборы кодировок (см. раздел Интернационализация).

Кодировки, поддерживаемые по умолчанию (при полном наборе данных ICU)

Кодировка	Псевдонимы
`'ibm866'`	`'866'`, `'cp866'`, `'csibm866'`
`'iso-8859-2'`	`'csisolatin2'`, `'iso-ir-101'`, `'iso8859-2'`, `'iso88592'`, `'iso_8859-2'`, `'iso_8859-2:1987'`, `'l2'`, `'latin2'`
`'iso-8859-3'`	`'csisolatin3'`, `'iso-ir-109'`, `'iso8859-3'`, `'iso88593'`, `'iso_8859-3'`, `'iso_8859-3:1988'`, `'l3'`, `'latin3'`
`'iso-8859-4'`	`'csisolatin4'`, `'iso-ir-110'`, `'iso8859-4'`, `'iso88594'`, `'iso_8859-4'`, `'iso_8859-4:1988'`, `'l4'`, `'latin4'`
`'iso-8859-5'`	`'csisolatincyrillic'`, `'cyrillic'`, `'iso-ir-144'`, `'iso8859-5'`, `'iso88595'`, `'iso_8859-5'`, `'iso_8859-5:1988'`
`'iso-8859-6'`	`'arabic'`, `'asmo-708'`, `'csiso88596e'`, `'csiso88596i'`, `'csisolatinarabic'`, `'ecma-114'`, `'iso-8859-6-e'`, `'iso-8859-6-i'`, `'iso-ir-127'`, `'iso8859-6'`, `'iso88596'`, `'iso_8859-6'`, `'iso_8859-6:1987'`
`'iso-8859-7'`	`'csisolatingreek'`, `'ecma-118'`, `'elot_928'`, `'greek'`, `'greek8'`, `'iso-ir-126'`, `'iso8859-7'`, `'iso88597'`, `'iso_8859-7'`, `'iso_8859-7:1987'`, `'sun_eu_greek'`
`'iso-8859-8'`	`'csiso88598e'`, `'csisolatinhebrew'`, `'hebrew'`, `'iso-8859-8-e'`, `'iso-ir-138'`, `'iso8859-8'`, `'iso88598'`, `'iso_8859-8'`, `'iso_8859-8:1988'`, `'visual'`
`'iso-8859-8-i'`	`'csiso88598i'`, `'logical'`
`'iso-8859-10'`	`'csisolatin6'`, `'iso-ir-157'`, `'iso8859-10'`, `'iso885910'`, `'l6'`, `'latin6'`
`'iso-8859-13'`	`'iso8859-13'`, `'iso885913'`
`'iso-8859-14'`	`'iso8859-14'`, `'iso885914'`
`'iso-8859-15'`	`'csisolatin9'`, `'iso8859-15'`, `'iso885915'`, `'iso_8859-15'`, `'l9'`
`'koi8-r'`	`'cskoi8r'`, `'koi'`, `'koi8'`, `'koi8_r'`
`'koi8-u'`	`'koi8-ru'`
`'macintosh'`	`'csmacintosh'`, `'mac'`, `'x-mac-roman'`
`'windows-874'`	`'dos-874'`, `'iso-8859-11'`, `'iso8859-11'`, `'iso885911'`, `'tis-620'`
`'windows-1250'`	`'cp1250'`, `'x-cp1250'`
`'windows-1251'`	`'cp1251'`, `'x-cp1251'`
`'windows-1252'`	`'ansi_x3.4-1968'`, `'ascii'`, `'cp1252'`, `'cp819'`, `'csisolatin1'`, `'ibm819'`, `'iso-8859-1'`, `'iso-ir-100'`, `'iso8859-1'`, `'iso88591'`, `'iso_8859-1'`, `'iso_8859-1:1987'`, `'l1'`, `'latin1'`, `'us-ascii'`, `'x-cp1252'`
`'windows-1253'`	`'cp1253'`, `'x-cp1253'`
`'windows-1254'`	`'cp1254'`, `'csisolatin5'`, `'iso-8859-9'`, `'iso-ir-148'`, `'iso8859-9'`, `'iso88599'`, `'iso_8859-9'`, `'iso_8859-9:1989'`, `'l5'`, `'latin5'`, `'x-cp1254'`
`'windows-1255'`	`'cp1255'`, `'x-cp1255'`
`'windows-1256'`	`'cp1256'`, `'x-cp1256'`
`'windows-1257'`	`'cp1257'`, `'x-cp1257'`
`'windows-1258'`	`'cp1258'`, `'x-cp1258'`
`'x-mac-cyrillic'`	`'x-mac-ukrainian'`
`'gbk'`	`'chinese'`, `'csgb2312'`, `'csiso58gb231280'`, `'gb2312'`, `'gb_2312'`, `'gb_2312-80'`, `'iso-ir-58'`, `'x-gbk'`
`'gb18030'`
`'big5'`	`'big5-hkscs'`, `'cn-big5'`, `'csbig5'`, `'x-x-big5'`
`'euc-jp'`	`'cseucpkdfmtjapanese'`, `'x-euc-jp'`
`'iso-2022-jp'`	`'csiso2022jp'`
`'shift_jis'`	`'csshiftjis'`, `'ms932'`, `'ms_kanji'`, `'shift-jis'`, `'sjis'`, `'windows-31j'`, `'x-sjis'`
`'euc-kr'`	`'cseuckr'`, `'csksc56011987'`, `'iso-ir-149'`, `'korean'`, `'ks_c_5601-1987'`, `'ks_c_5601-1989'`, `'ksc5601'`, `'ksc_5601'`, `'windows-949'`

Кодировки, поддерживаемые при сборке Node.js с параметром `small-icu`

Кодировка	Псевдонимы
`'utf-8'`	`'unicode-1-1-utf-8'`, `'utf8'`
`'utf-16le'`	`'utf-16'`
`'utf-16be'`

Кодировки, поддерживаемые при отключённом ICU

Кодировка	Псевдонимы
`'utf-8'`	`'unicode-1-1-utf-8'`, `'utf8'`
`'utf-16le'`	`'utf-16'`

Кодировка 'iso-8859-16', перечисленная в стандарте кодирования WHATWG, не поддерживается.

`new TextDecoder([encoding[, options]])`

encoding <string> Определяет encoding, который поддерживает этот экземпляр TextDecoder. По умолчанию: 'utf-8'.
options <Object>
- fatal <boolean> true, если ошибки декодирования являются фатальными. Этот параметр не поддерживается, если ICU отключен (см. Интернационализация). По умолчанию: false.
- ignoreBOM <boolean> Если true, TextDecoder будет включать метку порядка байтов в результат декодирования. Если false, метка порядка байтов будет удалена из выходных данных. Этот параметр используется только если encoding равно 'utf-8', 'utf-16be' или 'utf-16le'. По умолчанию: false.

Создает новый экземпляр TextDecoder. encoding может указывать одну из поддерживаемых кодировок или ее псевдоним.

Класс TextDecoder также доступен в глобальном объекте.

`textDecoder.decode([input[, options]])`

input <ArrayBuffer> | <DataView> | <TypedArray> Экземпляр ArrayBuffer, DataView или TypedArray, содержащий закодированные данные.
options <Object>
- stream <boolean> true, если ожидаются дополнительные фрагменты данных. По умолчанию: false.
Возвращает: <string>

Декодирует input и возвращает строку. Если options.stream равно true, любые неполные последовательности байтов в конце input сохраняются во внутреннем буфере и передаются после следующего вызова textDecoder.decode().

Если textDecoder.fatal равно true, возникающие ошибки декодирования приводят к выбросу TypeError.

`textDecoder.encoding`

Тип: <string>

Кодировка, поддерживаемая экземпляром TextDecoder.

`textDecoder.fatal`

Тип: <boolean>

Значение будет true, если ошибки декодирования приводят к выбросу TypeError.

`textDecoder.ignoreBOM`

Тип: <boolean>

Значение будет true, если результат декодирования будет включать метку порядка байтов.

Класс: `util.TextEncoder`

Добавлено в: v8.3.0

История

Версия	Изменения
v11.0.0	Теперь класс доступен в глобальном объекте.

Реализация API TextEncoder стандарта кодирования WHATWG. Все экземпляры TextEncoder поддерживают только кодировку UTF-8.

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

Класс TextEncoder также доступен в глобальном объекте.

`textEncoder.encode([input])`

input <string> Текст для кодирования. По умолчанию: пустая строка.
Возвращает: <Uint8Array>

Кодирует строку input в UTF-8 и возвращает Uint8Array, содержащий закодированные байты.

`textEncoder.encodeInto(src, dest)`

Добавлено в: v12.11.0

src <string> Текст для кодирования.
dest <Uint8Array> Массив для хранения результата кодирования.
Возвращает: <Object>
- read <number> Прочитанные кодовые единицы Unicode из src.
- written <number> Записанные байты UTF-8 в dest.

Кодирует строку src в UTF-8 и записывает результат в Uint8Array dest, а затем возвращает объект, содержащий прочитанные кодовые единицы Unicode и записанные байты UTF-8.

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

`textEncoder.encoding`

Тип: <string>

Кодировка, поддерживаемая экземпляром TextEncoder. Всегда имеет значение 'utf-8'.

`util.toUSVString(string)`

Добавлено в: v16.8.0, v14.18.0

string <string>

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

`util.transferableAbortController()`

Добавлено в: v18.11.0

История

Версия	Изменения
v23.11.0, v22.15.0	API признан стабильным.

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

`util.transferableAbortSignal(signal)`

Добавлено в: v18.11.0

История

Версия	Изменения
v23.11.0, v22.15.0	API признан стабильным.

signal <AbortSignal>
Возвращает: <AbortSignal>

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

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

`util.aborted(signal, resource)`

Добавлено в: v19.7.0, v18.16.0

История

Версия	Изменения
v24.0.0, v22.16.0	Уровень стабильности этой функции изменен с экспериментального на стабильный.

signal <AbortSignal>
resource <Object> Любой объект, отличный от null, связанный с отменяемой операцией и слабо удерживаемый. Если resource будет удален сборщиком мусора до отмены signal, промис останется ожидающим, позволяя Node.js прекратить отслеживание объекта. Это помогает предотвратить утечки памяти при длительных или не подлежащих отмене операциях.
Возвращает: <Promise>

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

CommonJS

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

Модули JavaScript

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`

Добавлено в: v10.0.0

История

Версия	Изменения
v15.3.0	Предоставлено как `require('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(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

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

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

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

`util.types.isArrayBufferView(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является экземпляром одного из представлений <ArrayBuffer>, например типизированного массива или <DataView>. Эквивалентно ArrayBuffer.isView().

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
jscopy

`util.types.isArgumentsObject(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

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

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

`util.types.isArrayBuffer(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является встроенным экземпляром <ArrayBuffer>. Сюда не входят экземпляры <SharedArrayBuffer>. Обычно рекомендуется проверять оба типа; для этого см. util.types.isAnyArrayBuffer().

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

`util.types.isAsyncFunction(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является асинхронной функцией. Результат отражает только то, что видит движок JavaScript; в частности, возвращаемое значение может не соответствовать исходному коду, если использовался инструмент транспиляции.

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

`util.types.isBigInt64Array(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

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

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

`util.types.isBigIntObject(value)`

Добавлено в: v10.4.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является объектом BigInt, например созданным с помощью Object(BigInt(123)).

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

`util.types.isBigUint64Array(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

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

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

`util.types.isBooleanObject(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является логическим объектом, например созданным с помощью new Boolean().

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
jscopy

`util.types.isBoxedPrimitive(value)`

Добавлено в: v10.11.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является любым примитивным объектом-оберткой, например созданным с помощью new Boolean(), new String() или Object(Symbol()).

Например:

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
jscopy

`util.types.isCryptoKey(value)`

Добавлено в: v16.2.0

value <Object>
Возвращает: <boolean>

Возвращает true, если value является <CryptoKey>, иначе возвращает false.

`util.types.isDataView(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является встроенным экземпляром <DataView>.

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

См. также ArrayBuffer.isView().

`util.types.isDate(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является встроенным экземпляром <Date>.

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

`util.types.isExternal(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является нативным значением External.

Нативное значение External — это особый тип объекта, содержащий необработанный указатель C++ (void*) для доступа из нативного кода и не имеющий других свойств. Такие объекты создаются внутренними компонентами Node.js или нативными аддонами. В JavaScript это замороженные объекты с прототипом null.

Модули JavaScript

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

CommonJS

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

Дополнительные сведения о napi_create_external см. в разделе napi_create_external().

`util.types.isFloat16Array(value)`

Добавлено в: v24.0.0, v22.16.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является встроенным экземпляром <Float16Array>.

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

`util.types.isFloat32Array(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является встроенным экземпляром <Float32Array>.

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

`util.types.isFloat64Array(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является встроенным экземпляром <Float64Array>.

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

`util.types.isGeneratorFunction(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является функцией-генератором. Результат отражает только то, что видит движок JavaScript; в частности, возвращаемое значение может не соответствовать исходному коду, если использовался инструмент транспиляции.

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

`util.types.isGeneratorObject(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является объектом-генератором, возвращаемым встроенной функцией-генератором. Результат отражает только то, что видит движок JavaScript; в частности, возвращаемое значение может не соответствовать исходному коду, если использовался инструмент транспиляции.

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

`util.types.isInt8Array(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является встроенным экземпляром <Int8Array>.

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

`util.types.isInt16Array(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является встроенным экземпляром <Int16Array>.

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

`util.types.isInt32Array(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является встроенным экземпляром <Int32Array>.

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

`util.types.isKeyObject(value)`

Добавлено в: v16.2.0

value <Object>
Возвращает: <boolean>

Возвращает true, если value является <KeyObject>, иначе возвращает false.

`util.types.isMap(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является встроенным экземпляром <Map>.

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

`util.types.isMapIterator(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является итератором, возвращенным для встроенного экземпляра <Map>.

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
jscopy

`util.types.isModuleNamespaceObject(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

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

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

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

`util.types.isNativeError(value)`

Добавлено в: v10.0.0Устарело в: v24.2.0

Стабильность: 0 — Устарело: вместо этого используйте Error.isError.

Примечание: В Node.js 24 Error.isError() сейчас работает медленнее, чем util.types.isNativeError(). Если производительность критична, рассмотрите возможность сравнить их производительность в своей среде.

value <any>
Возвращает: <boolean>

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

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

Подклассы встроенных типов ошибок также являются встроенными ошибками:

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

Принадлежность значения instanceof к встроенному классу ошибок не эквивалентна тому, что isNativeError() возвращает true для этого значения. isNativeError() возвращает true для ошибок из другой области, тогда как instanceof Error возвращает false для таких ошибок:

Модули JavaScript

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

CommonJS

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

И наоборот, isNativeError() возвращает false для всех объектов, которые не были возвращены конструктором встроенной ошибки. К ним относятся значения, которые instanceof являются встроенными ошибками:

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

`util.types.isNumberObject(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является объектом числа, например созданным с помощью new Number().

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

`util.types.isPromise(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является встроенным <Promise>.

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

`util.types.isProxy(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является экземпляром <Proxy>.

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

`util.types.isRegExp(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

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

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

`util.types.isSet(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

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

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

`util.types.isSetIterator(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является итератором, возвращённым для экземпляра встроенного <Set>.

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
jscopy

`util.types.isSharedArrayBuffer(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является экземпляром встроенного <SharedArrayBuffer>. Сюда не входят экземпляры <ArrayBuffer>. Обычно желательно проверять оба типа; см. util.types.isAnyArrayBuffer().

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

`util.types.isStringObject(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является строковым объектом, например созданным с помощью new String().

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

`util.types.isSymbolObject(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

Возвращает true, если значение является объектом символа, созданным вызовом Object() для примитивного значения Symbol.

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

`util.types.isTypedArray(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

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

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

См. также ArrayBuffer.isView().

`util.types.isUint8Array(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

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

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

`util.types.isUint8ClampedArray(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

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

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

`util.types.isUint16Array(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

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

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

`util.types.isUint32Array(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

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

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

`util.types.isWeakMap(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

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

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

`util.types.isWeakSet(value)`

Добавлено в: v10.0.0

value <any>
Возвращает: <boolean>

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

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

Устаревшие API

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

`util._extend(target, source)`

Добавлено в: v0.7.5Устарело в: v6.0.0

Стабильность: 0 — Устарело: вместо этого используйте Object.assign().

target <Object>
source <Object>

Метод util._extend() никогда не предназначался для использования вне внутренних модулей Node.js. Тем не менее сообщество обнаружило и стало его использовать.

Этот метод устарел и не должен использоваться в новом коде. В JavaScript есть очень похожие встроенные возможности — Object.assign().

Доступна автоматическая миграция (исходный код):

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

`util.isArray(object)`

Добавлено в: v0.6.0Устарело в: v4.0.0

Стабильность: 0 — Устарело: вместо этого используйте Array.isArray().

object <any>
Возвращает: <boolean>

Псевдоним для Array.isArray().

Возвращает true, если заданное значение object является Array. В противном случае возвращает false.

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

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

Доступна автоматическая миграция (исходный код):

npx codemod@latest @nodejs/util-is
bashcopy

© Joyent, Inc. and other Node contributors
Licensed under the MIT License.
Node.js is a trademark of Joyent, Inc. and is used with its permission.
We are not endorsed by or affiliated with Joyent.
https://nodejs.org/api/util.html

Util

util.callbackify(original)

util.convertProcessSignalToExitCode(signal)

util.debuglog(section[, callback])

debuglog().enabled

util.debug(section)

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

util.diff(actual, expected)

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

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

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

util.getSystemErrorName(err)

util.getSystemErrorMap()

util.getSystemErrorMessage(err)

util.setTraceSigInt(enable)

util.inherits(constructor, superConstructor)

util.inspect(object[, options])

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

Настройка цветов util.inspect

Сложная пользовательская раскраска

Модификаторы

Цвета переднего плана

Цвета фона

Пользовательские функции проверки объектов

util.inspect.custom

util.inspect.defaultOptions

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

Класс: util.MIMEType

new MIMEType(input)

mime.type

mime.subtype

mime.essence

mime.params

mime.toString()

mime.toJSON()

Класс: util.MIMEParams

new MIMEParams()

mimeParams.delete(name)

mimeParams.entries()

mimeParams.get(name)

mimeParams.has(name)

mimeParams.keys()

mimeParams.set(name, value)

mimeParams.values()

mimeParams[Symbol.iterator]()

util.parseArgs([config])

parseArgs tokens

util.parseEnv(content)

util.promisify(original)

Пользовательские функции с поддержкой промисов

util.promisify.custom

util.stripVTControlCharacters(str)

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

Класс: util.TextDecoder

Поддерживаемые кодировки WHATWG

Кодировки, поддерживаемые по умолчанию (при полном наборе данных ICU)

Кодировки, поддерживаемые при сборке Node.js с параметром small-icu

Кодировки, поддерживаемые при отключённом ICU

new TextDecoder([encoding[, options]])

textDecoder.decode([input[, options]])

textDecoder.encoding

textDecoder.fatal

textDecoder.ignoreBOM

Класс: util.TextEncoder

textEncoder.encode([input])

textEncoder.encodeInto(src, dest)

textEncoder.encoding

util.toUSVString(string)

util.transferableAbortController()

util.transferableAbortSignal(signal)

util.aborted(signal, resource)

util.types

util.types.isAnyArrayBuffer(value)

util.types.isArrayBufferView(value)

util.types.isArgumentsObject(value)

util.types.isArrayBuffer(value)

util.types.isAsyncFunction(value)

util.types.isBigInt64Array(value)

util.types.isBigIntObject(value)

util.types.isBigUint64Array(value)

`util.callbackify(original)`

`util.convertProcessSignalToExitCode(signal)`

`util.debuglog(section[, callback])`

`debuglog().enabled`

`util.debug(section)`

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

`util.diff(actual, expected)`

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

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

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

`util.getSystemErrorName(err)`

`util.getSystemErrorMap()`

`util.getSystemErrorMessage(err)`

`util.setTraceSigInt(enable)`

`util.inherits(constructor, superConstructor)`

`util.inspect(object[, options])`

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

Настройка цветов `util.inspect`

`util.inspect.custom`

`util.inspect.defaultOptions`

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

Класс: `util.MIMEType`

`new MIMEType(input)`

`mime.type`

`mime.subtype`

`mime.essence`

`mime.params`

`mime.toString()`

`mime.toJSON()`

Класс: `util.MIMEParams`

`new MIMEParams()`

`mimeParams.delete(name)`

`mimeParams.entries()`

`mimeParams.get(name)`

`mimeParams.has(name)`

`mimeParams.keys()`

`mimeParams.set(name, value)`

`mimeParams.values()`

`mimeParams[Symbol.iterator]()`

`util.parseArgs([config])`

`parseArgs` `tokens`

`util.parseEnv(content)`

`util.promisify(original)`

`util.promisify.custom`

`util.stripVTControlCharacters(str)`

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

Класс: `util.TextDecoder`

Кодировки, поддерживаемые при сборке Node.js с параметром `small-icu`

`new TextDecoder([encoding[, options]])`

`textDecoder.decode([input[, options]])`

`textDecoder.encoding`

`textDecoder.fatal`

`textDecoder.ignoreBOM`

Класс: `util.TextEncoder`

`textEncoder.encode([input])`

`textEncoder.encodeInto(src, dest)`

`textEncoder.encoding`

`util.toUSVString(string)`

`util.transferableAbortController()`

`util.transferableAbortSignal(signal)`

`util.aborted(signal, resource)`

`util.types`

`util.types.isAnyArrayBuffer(value)`

`util.types.isArrayBufferView(value)`

`util.types.isArgumentsObject(value)`

`util.types.isArrayBuffer(value)`

`util.types.isAsyncFunction(value)`

`util.types.isBigInt64Array(value)`

`util.types.isBigIntObject(value)`

`util.types.isBigUint64Array(value)`

`util.types.isBooleanObject(value)`

`util.types.isBoxedPrimitive(value)`

`util.types.isCryptoKey(value)`

`util.types.isDataView(value)`

`util.types.isDate(value)`

`util.types.isExternal(value)`

`util.types.isFloat16Array(value)`

`util.types.isFloat32Array(value)`

`util.types.isFloat64Array(value)`

`util.types.isGeneratorFunction(value)`