Util

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

const util = require('util');

util.callbackify(original)[src]

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

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

const util = require('util');

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

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

Вывод:

hello world

Обратный вызов выполняется асинхронно и будет иметь ограниченный стек отслеживания. Если обратный вызов выбросит исключение, процесс выведет событие '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 && err.hasOwnProperty('reason') && err.reason === null;  // true
});

util.debuglog(section)[src]

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

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

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

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

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

FOO 3245: hello from foo [123]

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

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

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

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

если она запущена с NODE_DEBUG=foo* в среде, то она выведет что-то вроде:

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

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

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

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

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

const util = require('util');

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

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

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

const util = require('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

Если используются флаги командной строки --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])[src]

• format <строка> Строка форматирования, подобная printf.

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

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

• %s - String.
• %d - Number (целое или с плавающей точкой) или BigInt.
• %i - Целое число или BigInt.
• %f - Значение с плавающей точкой.
• %j - JSON. Заменяется строкой '[Circular]' если аргумент содержит циклические ссылки.
• %o - Object. Строковое представление объекта с общим форматированием JavaScript-объектов. Аналогично util.inspect() с параметрами { showHidden: true, showProxy: true }. Это покажет весь объект, включая неперечисляемые свойства и прокси.
• %O - Object. Строковое представление объекта с общим форматированием JavaScript-объектов. Аналогично util.inspect() без параметров. Покажет весь объект, не включая неперечисляемые свойства и прокси.
• %% - один знак процента ('%'). Не потребляет аргумент.
• Возвращает: <строка> Отформатированная строка

Если маркера заменителя не соответствует соответствующий аргумент, маркер заменителя не заменяется.

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

Если аргументов, переданных методу util.format(), больше, чем количество маркеров заменителя, дополнительные аргументы преобразуются в строки и затем конкатенируются в возвращаемую строку, каждый раз отделяемые пробелом. Излишние аргументы, чьё typeof - 'object' или 'symbol' (кроме null ), будут преобразованы util.inspect().

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

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

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

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

util.format('%% %s'); // '%% %s'

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

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

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

util.getSystemErrorName(err)[src]

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

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

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

util.inherits(constructor, superConstructor)[src]

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

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

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

Для дополнительного удобства superConstructor будет доступен через свойство constructor.super_.

const util = require('util');
const EventEmitter = require('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!"

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

const EventEmitter = require('events');

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

const stream = new MyStream();

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

util.inspect(object[, options])

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

• object <любое> Любой примитивный JavaScript или Object.

• options <Объект>

  • showHidden <логическое> Если true, неперечисляемые символы и свойства object также будут включены в отформатированный результат, а также записи WeakMap и WeakSet. По умолчанию: false.
  • depth <число> Указывает количество рекурсивных вызовов при форматировании object. Это полезно для инспектирования крупных сложных объектов. Чтобы сделать рекурсию до максимального размера стека вызовов, передайте Infinity или null. По умолчанию: 2.
  • colors <логическое> Если true, вывод будет стилизован с помощью кодов ANSI-цветов. Цвета настраиваются, см. Настройка цветов util.inspect. По умолчанию: false.
  • customInspect <логическое> Если false, тогда пользовательские функции inspect(depth, opts) не будут вызываться. По умолчанию: true.
  • showProxy <логическое> Если true, объекты и функции, которые являются Proxy объектами, будут инспектированы для отображения их target и handler объектов. По умолчанию: false.
  • maxArrayLength <число> Указывает максимальное количество Array, TypedArray, WeakMap и WeakSet элементов, которые нужно включить при форматировании. Установите в null или Infinity для отображения всех элементов. Установите в 0 или отрицательное значение для отображения никаких элементов. По умолчанию: 100.
  • breakLength <число> Длина, при которой ключи объекта разделяются на несколько строк. Установите в Infinity для форматирования объекта как одной строки. По умолчанию: 60 для обратной совместимости.
  • compact <логическое> Установка в false изменяет отступ по умолчанию на использование переноса строки для каждого ключа объекта вместо выравнивания нескольких свойств в одной строке. Также будет разбить текст, который находится выше breakLength размера, на более короткие и читаемые фрагменты и отступы объектов так же, как массивы. Обратите внимание, что ни один текст не будет уменьшен ниже 16 символов, независимо от размера breakLength. Для получения дополнительной информации см. пример ниже. По умолчанию: true.
  • sorted <логическое> | <Функция> Если установлено в true или функцию, все свойства объекта и записи Set и Map будут отсортированы в возвращаемой строке. Если установлено в true, будет использоваться стандартная сортировка. Если установлено в функцию, она используется в качестве функции сравнения.
• Возвращает: <строка> Представление переданного объекта

Метод 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] {}'

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

const util = require('util');

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

Значения могут предоставить свои собственные пользовательские функции inspect(depth, opts), когда они вызываются, эти функции получают текущее значение depth в рекурсивной инспекции, а также объект параметров, переданный в util.inspect().

Следующий пример демонстрирует разницу с параметром compact:

const util = require('util');

const o = {
  a: [1, 2, [[
    'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do ' +
      'eiusmod tempor 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 }));

// This will print

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

// Setting `compact` to false changes the output to be more reader friendly.
console.log(util.inspect(o, { compact: false, depth: 5, breakLength: 80 }));

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

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

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

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

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

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

Опция sorted гарантирует, что вывод будет идентичным независимо от порядка вставки свойств:

const { inspect } = require('util');
const assert = require('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 { 1, 2, 3 } }
console.log(inspect(o1, { sorted: (a, b) => b.localeCompare(a) }));
// { c: Set { 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 })
);

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

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

Вывод цвета (если включен) util.inspect настраивается глобально через свойства util.inspect.styles и util.inspect.colors.

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

Значения по умолчанию для стилей и соответствующих цветов:

• number - yellow
• boolean - yellow
• string - green
• date - magenta
• regexp - red
• null - bold
• undefined - grey
• special - cyan (применяется только к функциям в данный момент)
• name - (нет стилей)

Предопределённые цветовые коды: white, grey, black, blue, cyan, green, magenta, red и yellow. Также существуют коды bold, italic, underline и inverse.

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

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

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

const util = require('util');

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

  [util.inspect.custom](depth, options) {
    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 = util.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 >"

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

const util = require('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' }"

util.inspect.custom

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

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

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

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

  toString() {
    return 'xxxxxxxx';
  }

  [inspect]() {
    return `Password <${this.toString()}>`;
  }
}

const password = new Password('r0sebud');
console.log(password);
// Prints Password <xxxxxxxx>

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

util.inspect.defaultOptions

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

const util = require('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

util.isDeepStrictEqual(val1, val2)

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

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

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

util.promisify(original)

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

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

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

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

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

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

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

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

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

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

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

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

const util = require('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'

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

Например, с функцией, которая принимает (foo, onSuccessCallback, onErrorCallback):

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

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

util.promisify.custom

• <символ>

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

Класс: util.TextDecoder

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

const decoder = new TextDecoder('shift_jis');
let string = '';
let buffer;
while (buffer = getNextChunkSomehow()) {
  string += decoder.decode(buffer, { stream: true });
}
string += decoder.decode(); // end-of-stream

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

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

Различные конфигурации Node.js поддерживают разные наборы кодировок. Хотя очень базовый набор кодировок поддерживается даже в конфигурациях Node.js без включённого ICU, поддержка некоторых кодировок предоставляется только когда Node.js скомпилирован с ICU и используется полный набор данных ICU (см. Локализация).

Кодировки, поддерживаемые без ICU

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

Кодировки, требующие полных данных ICU

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

new TextDecoder([encoding[, options]])

• encoding <строка> Указывает кодировку, которую поддерживает этот экземпляр TextDecoder. По умолчанию: 'utf-8'.

• options <Объект>

  • fatal <логическое значение> true при возникновении ошибки декодирования. Этот параметр поддерживается только при включенном ICU (см. Международные настройки). По умолчанию: false.
  • ignoreBOM <логическое значение> Если true, в результат декодирования TextDecoder будет включен байтовый порядок. Если false, байтовый порядок из результата будет удален. Этот параметр используется только когда encoding равен 'utf-8', 'utf-16be' или 'utf-16le'. По умолчанию: false.

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

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

• input <ArrayBuffer> | <DataView> | <TypedArray> Данные в формате ArrayBuffer, DataView или Typed Array.

• options <Объект>

  • stream <логическое значение> true если ожидаются дополнительные части данных. По умолчанию: false.
• Возвращает: <строка>

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

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

textDecoder.encoding

• <строка>

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

textDecoder.fatal

• <логическое значение>

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

textDecoder.ignoreBOM

• <логическое значение>

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

Класс: util.TextEncoder

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

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

textEncoder.encode([input])

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

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

textEncoder.encoding

• <string>

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

util.types

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

Результат, как правило, не гарантирует каких-либо свойств или поведения значения в JavaScript. Они в первую очередь полезны для разработчиков дополнений, которые предпочитают выполнять проверки типов в JavaScript.

util.types.isAnyArrayBuffer(value)

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

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

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

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

util.types.isArgumentsObject(value)

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

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

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

util.types.isArrayBuffer(value)

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

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

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

util.types.isAsyncFunction(value)

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

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

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

util.types.isBigInt64Array(value)

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

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

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

util.types.isBigUint64Array(value)

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

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

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

util.types.isBooleanObject(value)

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

Возвращает 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

util.types.isBoxedPrimitive(value)

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

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

Например:

util.types.isBoxedPrimitive(false); // Returns false
util.types.isBoxedPrimitive(new Boolean(false)); // Returns true
util.types.isBoxedPrimitive(Symbol('foo')); // Returns false
util.types.isBoxedPrimitive(Object(Symbol('foo'))); // Returns true
util.types.isBoxedPrimitive(Object(BigInt(5))); // Returns true

util.types.isDataView(value)

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

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

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

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

util.types.isDate(value)

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

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

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

util.types.isExternal(value)

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

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

util.types.isFloat32Array(value)

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

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

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

util.types.isFloat64Array(value)

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

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

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

util.types.isGeneratorFunction(value)

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

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

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

util.types.isGeneratorObject(value)

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

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

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

util.types.isInt8Array(value)

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

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

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

util.types.isInt16Array(value)

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

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

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

util.types.isInt32Array(value)

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

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

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

util.types.isMap(value)

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

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

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

util.types.isMapIterator(value)

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

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

const map = new Map();
util.types.isMapIterator(map.keys());  // Returns true
util.types.isMapIterator(map.values());  // Returns true
util.types.isMapIterator(map.entries());  // Returns true
util.types.isMapIterator(map[Symbol.iterator]());  // Returns true

util.types.isModuleNamespaceObject(value)

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

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

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

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

util.types.isNativeError(value)

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

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

util.types.isNativeError(new Error());  // Returns true
util.types.isNativeError(new TypeError());  // Returns true
util.types.isNativeError(new RangeError());  // Returns true

util.types.isNumberObject(value)

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

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

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

util.types.isPromise(value)

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

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

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

util.types.isProxy(value)

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

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

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

util.types.isRegExp(value)

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

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

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

util.types.isSet(value)

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

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

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

util.types.isSetIterator(value)

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

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

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

util.types.isSharedArrayBuffer(value)

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

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

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

util.types.isStringObject(value)

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

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

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

util.types.isSymbolObject(value)

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

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

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

util.types.isTypedArray(value)

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

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

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

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

util.types.isUint8Array(value)

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

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

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

util.types.isUint8ClampedArray(value)

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

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

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

util.types.isUint16Array(value)

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

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

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

util.types.isUint32Array(value)

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

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

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

util.types.isWeakMap(value)

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

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

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

util.types.isWeakSet(value)

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

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

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

util.types.isWebAssemblyCompiledModule(value)

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

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

const module = new WebAssembly.Module(wasmBuffer);
util.types.isWebAssemblyCompiledModule(module);  // Returns true

Устаревшие API

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

util._extend(target, source)

• target <Object>
• source <Object>

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

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

util.debug(string)

• string <string> Сообщение для вывода в stderr

Устаревшая предшественница console.error.

util.error([...strings])

• ...strings <string> Сообщение для вывода в stderr

Устаревшая предшественница console.error.

util.isArray(object)

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

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

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

const util = require('util');

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

util.isBoolean(object)[src]

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

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

const util = require('util');

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

util.isBuffer(object)

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

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

const util = require('util');

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

util.isDate(object)

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

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

const util = require('util');

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

util.isError(object)

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

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

const util = require('util');

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

Обратите внимание, что этот метод опирается на поведение Object.prototype.toString(). Возможен неверный результат, когда аргумент object изменяет @@toStringTag.

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

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

util.isFunction(object)[src]

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

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

const util = require('util');

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

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

util.isNull(object)[src]

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

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

const util = require('util');

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

util.isNullOrUndefined(object)[src]

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

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

const util = require('util');

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

util.isNumber(object)[src]

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

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

const util = require('util');

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

util.isObject(object)[src]

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

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

const util = require('util');

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

util.isPrimitive(object)[src]

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

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

const util = require('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

util.isRegExp(object)

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

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

const util = require('util');

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

util.isString(object)[src]

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

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

const util = require('util');

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

util.isSymbol(object)[src]

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

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

const util = require('util');

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

util.isUndefined(object)[src]

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

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

const util = require('util');

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

util.log(string)[src]

• string <string>

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

const util = require('util');

util.log('Timestamped message.');

util.print([...strings])

Устаревший предшественник console.log.

util.puts([...strings])

Устаревший предшественник console.log.