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 имеют приоритет над --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()

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

Возвращает карту всех системных кодов ошибок, доступных из 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, WeakMap и WeakSet элементов для включения при форматировании. Установите в null или Infinity для отображения всех элементов. Установите в 0 или отрицательное значение, чтобы не отображать элементов. По умолчанию: 100.
  • maxStringLength <целое> Указывает максимальное количество символов для включения при форматировании. Установите в null или Infinity для отображения всех элементов. Установите в 0 или отрицательное значение, чтобы не отображать символов. По умолчанию: 10000.
  • breakLength <целое> Длина, при которой входные значения разбиваются на несколько строк. Установите в Infinity для форматирования ввода в одну строку (в сочетании с compact установленным на true или любое число >= 1). По умолчанию: 80.
  • compact <булево> | <целое> Установка в false приводит к отображению каждого ключа объекта на новой строке. Разбиение на новые строки произойдет в тексте, длина которого превышает n. Если задано число, то самое n вложенных элементов объединяются на одной строке, если все свойства помещаются в breakLength. Короткие элементы массива также группируются вместе. Подробнее см. пример ниже. По умолчанию: 3.
  • sorted <булево> | <Функция> Если установлено в true или функцию, все свойства объекта и Set и Map записи сортируются в результирующей строке. Если установлено в true используется стандартная сортировка. Если установлена функция, она используется как функция сравнения.
  • getters <булево> | <строка> Если установлено в true, проверяются геттеры. Если установлено в 'get', проверяются только геттеры без соответствующего сеттера. Если установлено в 'set', проверяются только геттеры с соответствующим сеттером. Это может вызвать побочные эффекты в зависимости от функции геттера. По умолчанию: false.
  • numericSeparator <булево> Если установлено в true, подчёркивание используется для разделения каждой группы из трёх цифр во всех bigint и числах. По умолчанию: 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(thousand, million, bigNumber, bigDecimal);
// 1_000 1_000_000 123_456_789n 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 , если пары имя-значение с заданным именем 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' } []

util.parseArgs — экспериментальная функция, и поведение может измениться. Присоединяйтесь к обсуждению на pkgjs/parseargs, чтобы внести свой вклад в проектирование.

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.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}`);
} 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.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, кодировки, поддерживаемые TextDecoder API, перечислены в таблицах ниже. Для каждой кодировки может быть использовано одно или несколько псевдонимов.

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

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

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

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

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

new TextDecoder([encoding[, options]])

• encoding <строка> Определяет encoding, которые поддерживает этот экземпляр TextDecoder. По умолчанию: 'utf-8'.
• options <Объект>
  • fatal <логическое значение> true при ошибках декодирования являются фатальными. Этот параметр не поддерживается, когда ICU отключен (см. Международные настройки). По умолчанию: false.
  • ignoreBOM <логическое значение> Когда 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 Encoding Standard https://encoding.spec.whatwg.org/. Все экземпляры 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 если значение является объектом булевого типа, например, созданным 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 они являются замороженными объектами frozen с 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 является <KeyObject>, в противном случае 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 <any>
• Returns: <boolean>

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

const set = new Set();
util.types.isSetIterator(set.keys());  // Returns true
util.types.isSetIterator(set.values());  // Returns true
util.types.isSetIterator(set.entries());  // Returns true
util.types.isSetIterator(set[Symbol.iterator]());  // Returns true copy

util.types.isSharedArrayBuffer(value)

• value <any>
• 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 <any>
• 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 <any>
• 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 <any>
• 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 <any>
• 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 <any>
• 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 <any>
• 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 <any>
• 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 <any>
• Returns: <boolean>

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

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

util.types.isWeakSet(value)

• value <any>
• Returns: <boolean>

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

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

util.types.isWebAssemblyCompiledModule(value)

• value <any>
• Returns: <boolean>

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

const module = new WebAssembly.Module(wasmBuffer);
util.types.isWebAssemblyCompiledModule(module);  // 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