util.callbackify(original)

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

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

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

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

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

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

hello world copy

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

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

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

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

util.debuglog(section[, callback])

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

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

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

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

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

FOO 3245: hello from foo [123] copy

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

Для section также поддерживаются подстановочные символы:

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

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

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

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

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

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

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

debuglog().enabled

• <boolean>

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

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

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

hello from foo [123] copy

util.debug(section)

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

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

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

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

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

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

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

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

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

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

Если используются флаги командной строки --no-deprecation или --no-warnings либо свойству process.noDeprecation присвоено значение true до первого предупреждения об устаревании, метод util.deprecate() ничего не делает.

Если заданы флаги командной строки --trace-deprecation или --trace-warnings либо свойству process.traceDeprecation присвоено значение true, при первом вызове устаревшей функции в stderr выводятся предупреждение и трассировка стека.

Если задан флаг командной строки --throw-deprecation либо свойству process.throwDeprecation присвоено значение true, при вызове устаревшей функции будет выброшено исключение.

Флаг командной строки --throw-deprecation и свойство process.throwDeprecation имеют приоритет над --trace-deprecation и process.traceDeprecation.

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

• format <string> Форматная строка в стиле printf.

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

• %s: String используется для преобразования всех значений, кроме BigInt, Object и -0. Значения BigInt представляются в виде n, а объекты, у которых нет пользовательской функции toString или Symbol.toPrimitive, проверяются с помощью util.inspect() с параметрами { depth: 0, colors: false, compact: 3 }.
• %d: Number используется для преобразования всех значений, кроме BigInt и Symbol.
• %i: parseInt(value, 10) используется для всех значений, кроме BigInt и Symbol.
• %f: parseFloat(value) используется для всех значений, кроме Symbol.
• %j: JSON. Заменяется строкой '[Circular]', если аргумент содержит циклические ссылки.
• %o: Object. Строковое представление объекта с обычным форматированием объектов JavaScript. Аналогично util.inspect() с параметрами { showHidden: true, showProxy: true }. Отображает весь объект, включая неперечисляемые свойства и прокси.
• %O: Object. Строковое представление объекта с обычным форматированием объектов JavaScript. Аналогично util.inspect() без параметров. Отображает весь объект, за исключением неперечисляемых свойств и прокси.
• %c: CSS. Этот спецификатор игнорируется, а переданный CSS пропускается.
• %%: знак процента ('%'). Не использует аргумент.
• Возвращает: <string> Отформатированную строку

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

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

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

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

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

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

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

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

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

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

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

• inspectOptions <Object>
• format <string>

Эта функция идентична util.format(), за исключением того, что принимает аргумент inspectOptions, задающий параметры, которые передаются в util.inspect().

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

util.getSystemErrorName(err)

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

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

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

util.getSystemErrorMap()

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

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

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

util.inherits(constructor, superConstructor)

• constructor <Function>
• superConstructor <Function>

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

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

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

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

function MyStream() {
  EventEmitter.call(this);
}

util.inherits(MyStream, EventEmitter);

MyStream.prototype.write = function(data) {
  this.emit('data', data);
};

const stream = new MyStream();

console.log(stream instanceof EventEmitter); // true
console.log(MyStream.super_ === EventEmitter); // true

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

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

const EventEmitter = require('node:events');

class MyStream extends EventEmitter {
  write(data) {
    this.emit('data', data);
  }
}

const stream = new MyStream();

stream.on('data', (data) => {
  console.log(`Received data: "${data}"`);
});
stream.write('With ES6'); copy

util.inspect(object[, options])

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

• object <any> Любой примитив JavaScript или Object.
• options <Object>
  • showHidden <boolean> Если true, в форматированный результат включаются ненумеруемые символы и свойства object. Также включаются записи WeakMap и WeakSet, а также свойства прототипа, определённые пользователем (за исключением свойств-методов). По умолчанию: false.
  • depth <number> Задаёт количество рекурсивных вызовов при форматировании object. Это полезно для проверки больших объектов. Чтобы выполнять рекурсию вплоть до максимального размера стека вызовов, передайте Infinity или null. По умолчанию: 2.
  • colors <boolean> Если true, вывод оформляется с помощью цветовых кодов ANSI. Цвета можно настроить. См. раздел Настройка цветов util.inspect. По умолчанию: false.
  • customInspect <boolean> Если false, функции [util.inspect.custom](depth, opts, inspect) не вызываются. По умолчанию: true.
  • showProxy <boolean> Если true, проверка Proxy включает объекты target и handler. По умолчанию: false.
  • maxArrayLength <integer> Задаёт максимальное количество элементов Array, TypedArray, Map, Set, 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, для разделения каждой группы из трёх цифр во всех значениях BigInt и числах используется символ подчёркивания. По умолчанию: false.
• Возвращает: <string> Представление object.

Метод util.inspect() возвращает строковое представление object, предназначенное для отладки. Вывод util.inspect может измениться в любой момент, поэтому не следует программно полагаться на него. Можно передать дополнительные параметры options, изменяющие результат. util.inspect() использует имя конструктора и/или @@toStringTag для создания распознаваемой метки проверяемого значения.

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

class Bar {}

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

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

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

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

const obj = {};
obj.a = [obj];
obj.b = {};
obj.b.inner = obj.b;
obj.b.obj = obj;

console.log(inspect(obj));
// <ref *1> {
//   a: [ [Circular *1] ],
//   b: <ref *2> { inner: [Circular *2], obj: [Circular *1] }
// } copy

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

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

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

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

const util = 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(util.inspect(o, { compact: true, depth: 5, breakLength: 80 }));

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

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

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

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

Параметр showHidden позволяет проверять записи WeakMap и WeakSet. Если записей больше, чем maxArrayLength, нельзя гарантировать, какие именно записи будут отображены. Это означает, что при повторном получении тех же записей WeakSet результат может отличаться. Кроме того, записи, на которые больше не осталось сильных ссылок, могут быть удалены сборщиком мусора в любой момент.

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

const obj = { a: 1 };
const obj2 = { b: 2 };
const weakSet = new WeakSet([obj, obj2]);

console.log(inspect(weakSet, { showHidden: true }));
// WeakSet { { a: 1 }, { b: 2 } } copy

Параметр sorted гарантирует, что порядок вставки свойств объекта не влияет на результат util.inspect().

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

const o1 = {
  b: [2, 3, 1],
  a: '`a` comes before `b`',
  c: new Set([2, 3, 1]),
};
console.log(inspect(o1, { sorted: true }));
// { a: '`a` comes before `b`', b: [ 2, 3, 1 ], c: Set(3) { 1, 2, 3 } }
console.log(inspect(o1, { sorted: (a, b) => b.localeCompare(a) }));
// { c: Set(3) { 3, 2, 1 }, b: [ 2, 3, 1 ], a: '`a` comes before `b`' }

const o2 = {
  c: new Set([2, 1, 3]),
  a: '`a` comes before `b`',
  b: [2, 3, 1],
};
assert.strict.equal(
  inspect(o1, { sorted: true }),
  inspect(o2, { sorted: true }),
); copy

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

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

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

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

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: red
• special: cyan (например, Proxies)
• string: green
• symbol: green
• undefined: grey

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

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

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

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

• 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

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

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

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

class Box {
  constructor(value) {
    this.value = value;
  }

  [util.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);

util.inspect(box);
// Returns: "Box< true >" copy

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

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

const obj = { foo: 'this will not show up in the inspect() output' };
obj[util.inspect.custom] = (depth) => {
  return { bar: 'baz' };
};

util.inspect(obj);
// Returns: "{ bar: 'baz' }" copy

util.inspect.custom

• <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> copy

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

util.inspect.defaultOptions

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

const util = require('node:util');
const arr = Array(101).fill(0);

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

util.isDeepStrictEqual(val1, val2)

• val1 <any>
• val2 <any>
• Возвращает: <boolean>

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

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

Класс: util.MIMEType

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

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

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

Конструктор: new MIMEType(input)

• input <string> Входная строка MIME для разбора

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

import { MIMEType } from 'node:util';

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

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

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

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

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

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

mime.type

• <string>

Получает и задаёт тип MIME.

import { MIMEType } from 'node:util';

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

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

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

mime.subtype

• <string>

Получает и задаёт подтип MIME.

import { MIMEType } from 'node:util';

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

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

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

mime.essence

• <string>

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

import { MIMEType } from 'node:util';

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

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

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

mime.params

• <MIMEParams>

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

mime.toString()

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

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

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

mime.toJSON()

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

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

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

import { MIMEType } from 'node:util';

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

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

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

Класс: util.MIMEParams

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

Конструктор: new MIMEParams()

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

import { MIMEParams } from 'node:util';

const myParams = new MIMEParams();

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>

Возвращает итератор по именам всех пар «имя-значение».

import { MIMEType } from 'node:util';

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

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

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

mimeParams.set(name, value)

• name <string>
• value <string>

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

import { MIMEType } from 'node:util';

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

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

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

mimeParams.values()

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

Возвращает итератор по значениям всех пар «имя-значение».

mimeParams[@@iterator]()

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

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

import { MIMEType } from 'node:util';

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

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

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

util.parseArgs([config])

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

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

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

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

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

import { parseArgs } from 'node:util';
const args = ['-f', '--bar', 'b'];
const options = {
  foo: {
    type: 'boolean',
    short: 'f',
  },
  bar: {
    type: 'string',
  },
};
const {
  values,
  positionals,
} = parseArgs({ args, options });
console.log(values, positionals);
// Prints: [Object: null prototype] { foo: true, bar: 'b' } []

const { parseArgs } = require('node:util');
const args = ['-f', '--bar', 'b'];
const options = {
  foo: {
    type: 'boolean',
    short: 'f',
  },
  bar: {
    type: 'string',
  },
};
const {
  values,
  positionals,
} = parseArgs({ args, options });
console.log(values, positionals);
// Prints: [Object: null prototype] { foo: true, bar: 'b' } []

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> Значение параметра, заданное в аргументах. Для логических параметров значение равно undefined.
  • inlineValue <boolean> | <undefined> Указывает, задано ли значение параметра непосредственно в строке, например --foo=bar.
• позиционные токены
  • value <string> Значение позиционного аргумента в аргументах (то есть args[index]).
• токен завершения параметров

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

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

import { parseArgs } from 'node:util';

const options = {
  'color': { type: 'boolean' },
  'no-color': { type: 'boolean' },
  'logfile': { type: 'string' },
  'no-logfile': { type: 'boolean' },
};
const { values, tokens } = parseArgs({ options, tokens: true });

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

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

console.log({ logfile, color });

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

const options = {
  'color': { type: 'boolean' },
  'no-color': { type: 'boolean' },
  'logfile': { type: 'string' },
  'no-logfile': { type: 'boolean' },
};
const { values, tokens } = parseArgs({ options, tokens: true });

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

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

console.log({ logfile, color });

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

$ node negate.js
{ logfile: 'default.log', color: undefined }
$ node negate.js --no-logfile --no-color
{ logfile: false, color: false }
$ node negate.js --logfile=test.log --color
{ logfile: 'test.log', color: true }
$ node negate.js --no-logfile --logfile=test.log --color --no-color
{ logfile: 'test.log', color: false } copy

util.parseEnv(content)

• content <string>

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

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

Для примера файла .env:

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

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

import { parseEnv } from 'node:util';

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

util.promisify(original)

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

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

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

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

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

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

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

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

callStat(); copy

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

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

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

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

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

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

const foo = new Foo();

const naiveBar = util.promisify(foo.bar);
// TypeError: Cannot read property 'a' of undefined
// naiveBar().then(a => console.log(a));

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

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

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

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

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

function doSomething(foo, callback) {
  // ...
}

doSomething[util.promisify.custom] = (foo) => {
  return getPromiseSomehow();
};

const promisified = util.promisify(doSomething);
console.log(promisified === doSomething[util.promisify.custom]);
// prints 'true' copy

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

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

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

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

util.promisify.custom

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

util.stripVTControlCharacters(str)

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

Возвращает str с удалёнными ANSI-кодами управления.

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

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

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

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

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

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

const errorMessage = styleText(
  'red',
  'Error! Error!',
  // Validate if process.stderr has TTY
  { stream: stderr },
);
console.error(errorMessage);

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

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

const errorMessage = styleText(
  'red',
  'Error! Error!',
  // Validate if process.stderr has TTY
  { stream: stderr },
);
console.error(successMessage);

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

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

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

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

Класс: util.TextDecoder

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

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

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

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

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

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

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

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

Кодировка '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

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

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

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

textEncoder.encode([input])

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

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

textEncoder.encodeInto(src, dest)

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

Кодирует строку src в UTF-8 в массив dest Uint8Array и возвращает объект, содержащий количество прочитанных кодовых единиц 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); copy

textEncoder.encoding

• <string>

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

util.toUSVString(string)

• string <string>

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

util.transferableAbortController()

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

util.transferableAbortSignal(signal)

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

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

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

util.aborted(signal, resource)

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

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

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

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

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

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

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

import { aborted } from 'node:util';

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

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

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

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

util.types

util.types выполняет проверку типов для различных видов встроенных объектов. В отличие от instanceof или Object.prototype.toString.call(value), эти проверки не анализируют свойства объекта, доступные из JavaScript (например, его прототип), и обычно требуют вызова C++.

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

Доступ к API осуществляется через require('node:util').types или require('node:util/types').

util.types.isAnyArrayBuffer(value)

• 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 copy

util.types.isArrayBufferView(value)

• 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 copy

util.types.isArgumentsObject(value)

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

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

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

util.types.isArrayBuffer(value)

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

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

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

util.types.isAsyncFunction(value)

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

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

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

util.types.isBigInt64Array(value)

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

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

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

util.types.isBigIntObject(value)

• 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 copy

util.types.isBigUint64Array(value)

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

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

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

util.types.isBooleanObject(value)

• 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 copy

util.types.isBoxedPrimitive(value)

• 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 copy

util.types.isCryptoKey(value)

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

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

util.types.isDataView(value)

• 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 copy

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

util.types.isDate(value)

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

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

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

util.types.isExternal(value)

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

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

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

#include <js_native_api.h>
#include <stdlib.h>
napi_value result;
static napi_value MyNapi(napi_env env, napi_callback_info info) {
  int* raw = (int*) malloc(1024);
  napi_status status = napi_create_external(env, (void*) raw, NULL, NULL, &result);
  if (status != napi_ok) {
    napi_throw_error(env, NULL, "napi_create_external failed");
    return NULL;
  }
  return result;
}
...
DECLARE_NAPI_PROPERTY("myNapi", MyNapi)
... copy

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

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

util.types.isFloat32Array(value)

• 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 copy

util.types.isFloat64Array(value)

• 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 copy

util.types.isGeneratorFunction(value)

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

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

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

util.types.isGeneratorObject(value)

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

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

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

util.types.isInt8Array(value)

• 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 copy

util.types.isInt16Array(value)

• 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 copy

util.types.isInt32Array(value)

• 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 copy

util.types.isKeyObject(value)

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

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

util.types.isMap(value)

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

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

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

util.types.isMapIterator(value)

• 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 copy

util.types.isModuleNamespaceObject(value)

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

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

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

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

util.types.isNativeError(value)

• 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 copy

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

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

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

const vm = require('node:vm');
const context = vm.createContext({});
const myError = vm.runInContext('new Error()', context);
console.log(util.types.isNativeError(myError)); // true
console.log(myError instanceof Error); // false copy

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

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

util.types.isNumberObject(value)

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

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

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

util.types.isPromise(value)

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

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

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

util.types.isProxy(value)

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

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

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

util.types.isRegExp(value)

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

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

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

util.types.isSet(value)

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

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

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

util.types.isSetIterator(value)

• 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 copy

util.types.isSharedArrayBuffer(value)

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

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

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

util.types.isStringObject(value)

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

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

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

util.types.isSymbolObject(value)

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

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

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

util.types.isTypedArray(value)

• 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 copy

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

util.types.isUint8Array(value)

• 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 copy

util.types.isUint8ClampedArray(value)

• 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 copy

util.types.isUint16Array(value)

• 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 copy

util.types.isUint32Array(value)

• 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 copy

util.types.isWeakMap(value)

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

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

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

util.types.isWeakSet(value)

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

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

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

Устаревшие API

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

util._extend(target, source)

• target <Object>
• source <Object>

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

Метод устарел, и его не следует использовать в новом коде. В JavaScript есть очень похожая встроенная функциональность: Object.assign().

util.isArray(object)

• 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 copy

util.isBoolean(object)

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

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

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

util.isBoolean(1);
// Returns: false
util.isBoolean(0);
// Returns: false
util.isBoolean(false);
// Returns: true copy

util.isBuffer(object)

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

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

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

util.isBuffer({ length: 0 });
// Returns: false
util.isBuffer([]);
// Returns: false
util.isBuffer(Buffer.from('hello world'));
// Returns: true copy

util.isDate(object)

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

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

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

util.isDate(new Date());
// Returns: true
util.isDate(Date());
// false (without 'new' returns a String)
util.isDate({});
// Returns: false copy

util.isError(object)

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

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

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

util.isError(new Error());
// Returns: true
util.isError(new TypeError());
// Returns: true
util.isError({ name: 'Error', message: 'an error occurred' });
// Returns: false copy

Этот метод основан на поведении Object.prototype.toString(). Если аргумент object изменяет @@toStringTag, результат может быть неверным.

const util = require('node:util');
const obj = { name: 'Error', message: 'an error occurred' };

util.isError(obj);
// Returns: false
obj[Symbol.toStringTag] = 'Error';
util.isError(obj);
// Returns: true copy

util.isFunction(object)

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

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

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

function Foo() {}
const Bar = () => {};

util.isFunction({});
// Returns: false
util.isFunction(Foo);
// Returns: true
util.isFunction(Bar);
// Returns: true copy

util.isNull(object)

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

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

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

util.isNull(0);
// Returns: false
util.isNull(undefined);
// Returns: false
util.isNull(null);
// Returns: true copy

util.isNullOrUndefined(object)

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

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

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

util.isNullOrUndefined(0);
// Returns: false
util.isNullOrUndefined(undefined);
// Returns: true
util.isNullOrUndefined(null);
// Returns: true copy

util.isNumber(object)

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

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

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

util.isNumber(false);
// Returns: false
util.isNumber(Infinity);
// Returns: true
util.isNumber(0);
// Returns: true
util.isNumber(NaN);
// Returns: true copy

util.isObject(object)

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

Возвращает true, если заданное object строго является Object и не является Function (хотя в JavaScript функции являются объектами). В противном случае возвращает false.

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

util.isObject(5);
// Returns: false
util.isObject(null);
// Returns: false
util.isObject({});
// Returns: true
util.isObject(() => {});
// Returns: false copy

util.isPrimitive(object)

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

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

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

util.isPrimitive(5);
// Returns: true
util.isPrimitive('foo');
// Returns: true
util.isPrimitive(false);
// Returns: true
util.isPrimitive(null);
// Returns: true
util.isPrimitive(undefined);
// Returns: true
util.isPrimitive({});
// Returns: false
util.isPrimitive(() => {});
// Returns: false
util.isPrimitive(/^$/);
// Returns: false
util.isPrimitive(new Date());
// Returns: false copy

util.isRegExp(object)

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

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

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

util.isRegExp(/some regexp/);
// Returns: true
util.isRegExp(new RegExp('another regexp'));
// Returns: true
util.isRegExp({});
// Returns: false copy

util.isString(object)

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

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

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

util.isString('');
// Returns: true
util.isString('foo');
// Returns: true
util.isString(String('foo'));
// Returns: true
util.isString(5);
// Returns: false copy

util.isSymbol(object)

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

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

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

util.isSymbol(5);
// Returns: false
util.isSymbol('foo');
// Returns: false
util.isSymbol(Symbol('foo'));
// Returns: true copy

util.isUndefined(object)

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

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

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

const foo = undefined;
util.isUndefined(5);
// Returns: false
util.isUndefined(foo);
// Returns: true
util.isUndefined(null);
// Returns: false copy

util.log(string)

• string <string>

Метод util.log() выводит заданное string в stdout с добавленной временной меткой.

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

util.log('Timestamped message.'); copy