Util

Устойчивость: 2 - Стабильно

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

const util = require('util');

util.debuglog(section)

Добавлен в: v0.11.3

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)

Добавлен в: v0.8.0

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

Добавлен в: v0.5.3

format <строка> Строка формата, похожая на printf.

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

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

%s - Строка.
%d - Число (целое или с плавающей точкой).
%i - Целое число.
%f - Вещественное число.
%j - JSON. Заменяется строкой '[Circular]', если аргумент содержит циклические ссылки.
%% - одиночный знак процента ('%'). Это не потребляет аргумент.

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

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.inherits(constructor, superConstructor)

Добавлен в: v0.3.0

Примечание: использование 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 {
  constructor() {
    super();
  }
  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])

Добавлен в: v0.3.0

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

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

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

const util = require('util');

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

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

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

const util = require('util');

const obj = { foo: 'this will not show up in the inspect() output' };
obj[util.inspect.custom] = function(depth) {
  return { bar: 'baz' };
};

util.inspect(obj);
// Returns: "{ bar: 'baz' }"

Пользовательский метод проверки можно альтернативно предоставить, предоставив метод inspect(depth, opts) в объекте:

const util = require('util');

const obj = { foo: 'this will not show up in the inspect() output' };
obj.inspect = function(depth) {
  return { bar: 'baz' };
};

util.inspect(obj);
// Returns: "{ bar: 'baz' }"

util.inspect.defaultOptions

Добавлен в: v6.4.0

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

const util = require('util');
const arr = Array(101);

console.log(arr); // logs the truncated array
util.inspect.defaultOptions.maxArrayLength = null;
console.log(arr); // logs the full array

util.inspect.custom

Добавлен в: v6.6.0

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

Устаревшие API

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

util.debug(string)

Добавлен в: v0.3.0 Устарел с: v0.11.3

Стабильность: 0 - Устарел: Используйте console.error() вместо этого.

string <строка> Сообщение для вывода в stderr

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

util.error([...strings])

Добавлен в: v0.3.0 Устарел с: v0.11.3

Стабильность: 0 - Устарел: Используйте console.error() вместо этого.

...strings <строка> Сообщение для вывода в stderr

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

util.isArray(object)

Добавлен в: v0.6.0 Устарел с: v4.0.0

Стабильность: 0 - Устарел

object <любой>

Внутренний псевдоним для 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)

Добавлен в: v0.11.5 Устарел с: v4.0.0

Стабильность: 0 - Устарел

object <любой>

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

Добавлен в: v0.11.5 Устарел с: v4.0.0

Стабильность: 0 - Устарел: Используйте Buffer.isBuffer() вместо этого.

object <любой>

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

Добавлен в: v0.6.0 Устарел с: v4.0.0

Стабильность: 0 - Устарел

object <любой>

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

Добавлен в: v0.6.0 Устарел с: v4.0.0

Стабильность: 0 - Устарел

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)

Добавлен в: v0.11.5 Устарел с: v4.0.0

Стабильность: 0 - Устарел

object <любой>

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

Добавлен в: v0.11.5 Устарел с: v4.0.0

Стабильность: 0 - Устарел

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)

Добавлен в: v0.11.5 Устарел с: v4.0.0

Стабильность: 0 - Устарел

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)

Добавлен в: v0.11.5 Устарел с: v4.0.0

Стабильность: 0 - Устарел

object <любой>

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

Добавлен в: v0.11.5 Устарел с: v4.0.0

Стабильность: 0 - Устарел

object <любой>

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

Добавлен в: v0.11.5 Устарел с: v4.0.0

Стабильность: 0 - Устарел

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(function() {});
// Returns: false
util.isPrimitive(/^$/);
// Returns: false
util.isPrimitive(new Date());
// Returns: false

util.isRegExp(object)

Добавлен в: v0.6.0 Устарел начиная с: v4.0.0

Устойчивость: 0 - Устарел

object <any>

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

Добавлен в: v0.11.5 Устарел начиная с: v4.0.0

Устойчивость: 0 - Устарел

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)

Добавлен в: v0.11.5 Устарел начиная с: v4.0.0

Устойчивость: 0 - Устарел

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)

Добавлен в: v0.11.5 Устарел начиная с: v4.0.0

Устойчивость: 0 - Устарел

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)

Добавлен в: v0.3.0 Устарел начиная с: v6.0.0

Устойчивость: 0 - Устарел: Используйте модуль третьей стороны вместо него.

string <string>

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

const util = require('util');

util.log('Timestamped message.');

util.print([...strings])

Добавлен в: v0.3.0 Устарел начиная с: v0.11.3

Устойчивость: 0 - Устарел: Используйте console.log() вместо этого.

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

util.puts([...strings])

Добавлен в: v0.3.0 Устарел начиная с: v0.11.3

Устойчивость: 0 - Устарел: Используйте console.log() вместо этого.

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

util._extend(target, source)

Добавлен в: v0.7.5 Устарел начиная с: v6.0.0

Устойчивость: 0 - Устарел: Используйте Object.assign() вместо этого.

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

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

© Joyent, Inc. and other Node contributors
Licensed under the MIT License.
Node.js is a trademark of Joyent, Inc. and is used with its permission.
We are not endorsed by or affiliated with Joyent.
https://nodejs.org/dist/latest-v6.x/docs/api/util.html

Util

util.debuglog(section)

util.deprecate(function, string)

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

util.inherits(constructor, superConstructor)

util.inspect(object[, options])

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

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

util.inspect.defaultOptions

util.inspect.custom

Устаревшие API

util.debug(string)

util.error([...strings])

util.isArray(object)

util.isBoolean(object)

util.isBuffer(object)

util.isDate(object)

util.isError(object)

util.isFunction(object)

util.isNull(object)

util.isNullOrUndefined(object)

util.isNumber(object)

util.isObject(object)

util.isPrimitive(object)

util.isRegExp(object)

util.isString(object)

util.isSymbol(object)

util.isUndefined(object)

util.log(string)

util.print([...strings])

util.puts([...strings])

util._extend(target, source)

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