util.callbackify(original)

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

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

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

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

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

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

util.debuglog(section[, callback])

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

Метод 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

• <булево>

Геттер 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 <Функция> Функция, которая устаревает.
• msg <строка> Сообщение об предупреждении, которое должно отображаться при вызове устаревшей функции.
• code <строка> Код устаревания. См. список устаревших API для получения списка кодов.
• Возвращает: <Функция> Обернутая устаревшая функция для вывода предупреждения.

Метод 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 <строка> Строка формата, похожая на printf.

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

• %s: String будет использоваться для преобразования всех значений, кроме BigInt, Object и -0. Значения BigInt будут представлены с помощью n, а объекты, у которых нет пользовательской функции toString, будут проверены с помощью 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.
• %%: одиночный знак процента ('%'). Не потребляет аргумент.
• Возвращает: <строка> Отформатированная строка

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

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 <Объект>
• format <строка>

Эта функция идентична 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 <число>
• Возвращает: <строка>

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

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

util.getSystemErrorMap()

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

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

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

util.inherits(constructor, superConstructor)

• constructor <Функция>
• superConstructor <Функция>

Использование 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 <любой> Любая примитивная JavaScript-структура или Object.
• options <Объект>
  • showHidden <логическое> Если true, неперечисляемые символы и свойства object включены в отформатированный результат. WeakMap и WeakSet записи также включены, а также пользовательские свойства прототипа (исключая свойства методов). По умолчанию: false.
  • depth <число> Указывает количество рекурсий при форматировании object. Это полезно для инспектирования больших объектов. Чтобы рекурсировать до максимального размера стека вызовов, передайте Infinity или null. По умолчанию: 2.
  • colors <логическое> Если true, вывод стилизуется с помощью кодов ANSI-цветов. Цвета настраиваются. См. Настройка цветов util.inspect. По умолчанию: false.
  • customInspect <логическое> Если false, функции [util.inspect.custom](depth, opts, inspect) не вызываются. По умолчанию: true.
  • showProxy <логическое> Если true, инспектирование Proxy включает объекты target и handler. По умолчанию: false.
  • maxArrayLength <целое> Указывает максимальное количество Array, TypedArray, Map, Set, WeakMap и WeakSet элементов для включения при форматировании. Установите значение null или Infinity для отображения всех элементов. Установите значение 0 или отрицательное значение для отображения без элементов. По умолчанию: 100.
  • maxStringLength <целое> Указывает максимальное количество символов для включения при форматировании. Установите значение null или Infinity для отображения всех элементов. Установите значение 0 или отрицательное значение для отображения без символов. По умолчанию: 10000.
  • breakLength <целое> Длина, при которой входные значения разделяются на несколько строк. Установите значение Infinity для форматирования входных данных как одной строки (в сочетании с compact установленным на true или любое число >= 1). По умолчанию: 80.
  • compact <логическое> | <целое> Установка этого значения на false приводит к отображению каждого ключа объекта на новой строке. Разбиение на новые строки произойдёт, если текст длиннее breakLength. Если установлено число, то самые n вложенные элементы объединяются на одной строке, если все свойства умещаются в breakLength. Короткие элементы массивов также группируются вместе. Для получения дополнительной информации см. пример ниже. По умолчанию: 3.
  • sorted <логическое> | <Функция> Если установлено значение true или функция, все свойства объекта, а также Set и Map записи сортируются в результирующей строке. Если установлено значение true , используется сортировка по умолчанию. Если установлено значение в виде функции, используется функция сравнения.
  • getters <логическое> | <строка> Если установлено значение true, инспектируются геттеры. Если установлено значение 'get', инспектируются только геттеры без соответствующего сеттера. Если установлено значение 'set', инспектируются только геттеры с соответствующим сеттером. Это может вызвать побочные эффекты, зависящие от функции геттера. По умолчанию: false.
  • numericSeparator <логическое> Если установлено значение true, используется нижнее подчёркивание для разделения каждых трёх цифр во всех больших целых числах и числах. По умолчанию: false.
• Возвращает: <строка> Представление 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 — Выводит текст, но делает его невидимым (Псевдоним: скрыть)
• приглушённый — Уменьшение интенсивности цвета (Псевдоним: 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

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

Помимо доступности через 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 <любой>
• val2 <любой>
• Возвращает: <логическое>

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

См. assert.deepStrictEqual() для получения дополнительной информации о глубоком строгом равенстве.

Класс: util.MIMEType

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

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

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

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

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

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

MJS модули

import { MIMEType } from 'node:util';

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

CJS модули

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

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

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

MJS модули

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

CJS модули

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

mime.type

• <строка>

Получает и устанавливает часть типа MIME.

MJS модули

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

CJS модули

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

• <строка>

Получает и устанавливает часть подтипа MIME.

MJS модули

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

CJS модули

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

• <строка>

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

MJS модули

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

CJS модули

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

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

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

Из-за необходимости соблюдения стандартов, этот метод не позволяет пользователям настраивать процесс сериализации MIME.

mime.toJSON()

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

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

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

MJS модули

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

CJS модули

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 с пустыми параметрами.

MJS модули

import { MIMEParams } from 'node:util';

const myParams = new MIMEParams();

CJS модули

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

const myParams = new MIMEParams();

mimeParams.delete(name)

• name <строка>

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

mimeParams.entries()

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

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

mimeParams.get(name)

• name <строка>
• Возвращает: <строка> | <null> Строка или null, если нет пары имя-значение с заданным именем name.

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

mimeParams.has(name)

• name <строка>
• Возвращает: <логическое значение>

Возвращает true, если хотя бы одна пара имя-значение имеет имя name.

mimeParams.keys()

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

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

MJS модули

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

CJS модули

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 <строка>
• value <строка>

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

MJS модули

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

CJS модули

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

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

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

mimeParams[@@iterator]()

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

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

MJS модули

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

CJS модули

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 <Объект> Используется для предоставления аргументов для разбора и настройки парсера. config поддерживает следующие свойства:

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

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

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

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

Модули MJS

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

Модули CJS

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

Возвращаемые токены упорядочены в порядке их появления во входных args. Опции, которые появляются более одного раза в args, производят токен для каждого использования. Группы коротких опций, например -xy , расширяются до токена для каждой опции. Таким образом, -xxx производит три токена.

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

Модули MJS

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

Модули CJS

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 <строка>

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

• Возвращает: <Объект>

Рассмотрим пример файла .env:

Модули CJS

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

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

Модули MJS

import { parseEnv } from 'node:util';

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

util.promisify(original)

• original <Функция>
• Возвращает: <Функция>

Принимает функцию, следующую общему стилю обратного вызова с ошибкой, то есть принимающую обратный вызов (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

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

Помимо доступности через 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 <строка>
• Возвращает: <строка>

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

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

util.styleText(format, text)

• format <строка> | <массив> Формат текста или массив форматов текста, определённых в util.inspect.colors.
• text <строка> Текст, который нужно отформатировать.

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

Модули MJS

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

Модули CJS

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

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

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

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

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

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

Класс: util.TextDecoder

Реализация спецификации WHATWG Encoding Standard TextDecoder API.

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

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

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

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

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

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

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

Кодировка 'iso-8859-16', указанная в WHATWG Encoding Standard, не поддерживается.

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 WHATWG Encoding Standard. Все экземпляры 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> Прочитанные Юникод-кодовые единицы src.
  • written <number> Записанные UTF-8 байты dest.

Кодирует строку src в UTF-8 в массив dest Uint8Array и возвращает объект, содержащий прочитанные Юникод-кодовые единицы и записанные 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 после замены всех суррогатных кодовых точек (или, что эквивалентно, любых неспаренных суррогатных кодовых единиц) замещающим символом Юникода 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> Любой не-нулевой объект, ссылка на который хранится слабо.
• Возвращает: <Promise>

Прослушивает событие прерывания для заданного signal и возвращает обещание, которое выполняется, когда signal прервано. Если переданный resource собран сборщиком мусора до того, как signal будет прерван, возвращённое обещание останется в состоянии ожидания неопределённо долго.

Модули CJS

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

const dependent = obtainSomethingAbortable();

aborted(dependent.signal, dependent).then(() => {
  // Do something when dependent is aborted.
});

dependent.on('event', () => {
  dependent.abort();
});

Модули MJS

import { aborted } from 'node:util';

const dependent = obtainSomethingAbortable();

aborted(dependent.signal, dependent).then(() => {
  // Do something when dependent is aborted.
});

dependent.on('event', () => {
  dependent.abort();
});

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 <любое>
• Возвращает: <логическое>

Возвращает 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 <любое>
• Возвращает: <логическое>

Возвращает 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 <любое>
• Возвращает: <логическое>

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

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

util.types.isArrayBuffer(value)

• value <любое>
• Возвращает: <логическое>

Возвращает 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 <любое>
• Возвращает: <логическое>

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

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

util.types.isBigInt64Array(value)

• value <любое>
• Возвращает: <логическое>

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

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

util.types.isBigUint64Array(value)

• value <любое>
• Возвращает: <логическое>

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

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

util.types.isBooleanObject(value)

• value <любое>
• Возвращает: <логическое>

Возвращает true, если значение является объектом типа boolean, например, созданным 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 <любое>
• Возвращает: <логическое>

Возвращает 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 <Объект>
• Возвращает: <логическое>

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

util.types.isDataView(value)

• value <любое>
• Возвращает: <логическое>

Возвращает 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 <любое>
• Возвращает: <логическое>

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

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

util.types.isExternal(value)

• value <любое>
• Возвращает: <логическое>

Возвращает 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 <любое>
• Возвращает: <логическое>

Возвращает 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 <любое>
• Возвращает: <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 <любое>
• Возвращает: <boolean>

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

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

util.types.isGeneratorObject(value)

• value <любое>
• Возвращает: <boolean>

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

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

util.types.isInt8Array(value)

• value <любое>
• Возвращает: <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 <любое>
• Возвращает: <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 <любое>
• Возвращает: <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 <Объект>
• Возвращает: <boolean>

Возвращает true если value является <Ключевой объект>, false в противном случае.

util.types.isMap(value)

• value <любое>
• Возвращает: <boolean>

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

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

util.types.isMapIterator(value)

• value <любое>
• Возвращает: <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 <любое>
• Возвращает: <boolean>

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

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

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

util.types.isNativeError(value)

• value <любое>
• Возвращает: <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

То, что значение является экземпляром класса встроенной ошибки, не эквивалентно тому, что isNativeError() возвращает true для этого значения. isNativeError() возвращает true для ошибок, которые происходят из другого облака, в то время как 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 <любое>
• Возвращает: <boolean>

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

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

util.types.isPromise(value)

• value <любое>
• Возвращает: <boolean>

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

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

util.types.isProxy(value)

• value <любое>
• Возвращает: <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 <любое>
• Возвращает: <boolean>

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

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

util.types.isSet(value)

• value <любое>
• Возвращает: <boolean>

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

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

util.types.isSetIterator(value)

• value <любой>
• Returns: <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 <любой>
• Returns: <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 <любой>
• Returns: <boolean>

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

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

util.types.isSymbolObject(value)

• value <любой>
• Returns: <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 <любой>
• Returns: <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 <любой>
• Returns: <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 <любой>
• Returns: <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 <любой>
• Returns: <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 <любой>
• Returns: <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 <любой>
• Returns: <boolean>

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

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

util.types.isWeakSet(value)

• value <любой>
• Returns: <boolean>

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

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

Устаревшие API

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

util._extend(target, source)

• target <Объект>
• source <Объект>

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

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

util.isArray(object)

• object <любой>
• Возвращает: <логическое>

Псевдоним для 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 <любой>
• Возвращает: <логическое>

Возвращает 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 <любой>
• Возвращает: <логическое>

Возвращает 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 <любой>
• Возвращает: <логическое>

Возвращает 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 <любой>
• Возвращает: <логическое>

Возвращает 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 <любой>
• Возвращает: <логическое>

Возвращает 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 <любой>
• Возвращает: <логическое>

Возвращает 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 <любой>
• Возвращает: <логическое>

Возвращает 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 <любой>
• Возвращает: <логическое>

Возвращает 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 <любой>
• Возвращает: <логическое>

Возвращает 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 <любой>
• Возвращает: <логическое>

Возвращает 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 <любой>
• Возвращает: <boolean>

Возвращает true если заданный object является строкой. В противном случае возвращает 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 <любой>
• Возвращает: <boolean>

Возвращает true если заданный object является символом. В противном случае возвращает 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 <любой>
• Возвращает: <boolean>

Возвращает true если заданный object является undefined. В противном случае возвращает 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 <любой>
• Возвращает: <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 <строка>

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

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

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