Util

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

const util = require('util');

util.callbackify(original)

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

• 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 — идентификатор процесса. Если программа запускается без этой переменной среды, то ничего не будет выведено.

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

util.deprecate(function, string)

Метод util.deprecate() оборачивает заданную function или класс таким образом, что он помечается как устаревший.

const util = require('util');

exports.puts = util.deprecate(function() {
  for (let i = 0, len = arguments.length; i < len; ++i) {
    process.stdout.write(arguments[i] + '\n');
  }
}, 'util.puts: Use console.log instead');

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

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

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

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

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

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

• format <строка> строка в формате printf

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

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

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

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

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

Если аргументов, переданных методу util.format(), больше, чем число заполнителей, лишние аргументы преобразуются в строки и конкатенируются к возвращаемой строке, каждый раз разделённый пробелом. Аргументы, чьи типы являются typeof или 'object' (кроме 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.getSystemErrorName(err)

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

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

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

Наследует методы прототипа от одного конструктора в другой. Прототип 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])

• object <any> Любой примитив JavaScript или объект.
• options <Object>
  • showHidden <boolean> Если true, неперечисляемые символы и свойства объекта object будут включены в отформатированный результат. По умолчанию: false.
  • depth <number> Указывает количество рекурсий при форматировании object. Это полезно для проверки больших сложных объектов. По умолчанию 2. Чтобы сделать рекурсию бесконечной, передайте null.
  • colors <boolean> Если true, вывод будет стилизован с помощью ANSI-кодов цвета. Цвета настраиваются, см. Настройка цветов util.inspect. По умолчанию: false.
  • customInspect <boolean> Если false, то пользовательские функции inspect(depth, opts) экспортированные в object объекта, который проверяется, не будут вызваны. По умолчанию: true.
  • showProxy <boolean> Если true, то объекты и функции, являющиеся Proxy объектами, будут проинспектированы для отображения их target и handler объектов. По умолчанию: false.
  • maxArrayLength <number> Указывает максимальное количество элементов массивов и TypedArray для включения при форматировании. Установите в null для отображения всех элементов массива. Установите в 0 или отрицательное значение, чтобы не отображать элементы массива. По умолчанию: 100.
  • breakLength <number> Длина, после которой ключи объекта разделяются на несколько строк. Установите в Infinity для форматирования объекта в одну строку. По умолчанию: 60 для совместимости со старыми версиями.

Метод util.inspect() возвращает строковое представление object, что преимущественно полезно для отладки. Можно передать дополнительные options, которые изменят определенные аспекты отформатированной строки.

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

const util = require('util');

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

Значения могут предоставить свои собственные пользовательские функции inspect(depth, opts), при вызове они получат текущий depth в рекурсивной инспекции, а также объект параметров, переданный в 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)), которую util.inspect() вызовет и использует результат при инспектировании объекта:

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.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.promisify(original)

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

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

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

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

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

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

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

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

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

new TextDecoder([кодировка[, параметры]])

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

textDecoder.decode([вход[, параметры]])

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

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

textDecoder.кодировка

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

textDecoder.fatal

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

textDecoder.ignoreBOM

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

Класс: util.TextEncoder

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

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

textEncoder.encode([вход])

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

textEncoder.encoding

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

Устаревшие API

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

util._extend(target, source)

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

Внутренний псевдоним для Array.isArray.

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

const util = require('util');

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

util.isBoolean(object)

• object <any>

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

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

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

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

• object <any>

Возвращает true, если заданный object является функцией. В противном случае возвращает 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)

• object <any>

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

• object <any>

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

• object <any>

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

• object <any>

Возвращает true, если заданный object строго является объектом (и не является массивом). В противном случае возвращает false.

const util = require('util');

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

util.isPrimitive(object)

• object <any>

Возвращает 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(function() {});
// Returns: false
util.isPrimitive(/^$/);
// Returns: false
util.isPrimitive(new Date());
// Returns: false

util.isRegExp(object)

• object <any>

Возвращает true, если заданный object является регулярным выражением. В противном случае возвращает 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)

• object <any>

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

• object <any>

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

• object <any>

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

• string <string>

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

const util = require('util');

util.log('Timestamped message.');

util.print([...strings])

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

util.puts([...strings])

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