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

Возвращает строковое имя для числового кода ошибки, который поступает из 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 <Функция>
• 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 Array. Первый элемент массива — name, второй — value.

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]).
• токен завершения опций

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

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 TextEncoder стандарта WHATWG Encoding. Все экземпляры TextEncoder поддерживают только кодировку UTF-8.

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

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

textEncoder.encode([input])

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

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

textEncoder.encodeInto(src, dest)

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

UTF-8 кодирует строку src в массив 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 является 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 <любой>
• Возвращает: <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 <любой>
• Возвращает: <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 <любой>
• Возвращает: <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