Util

Эти функции находятся в модуле 'util'. Используйте require('util') для доступа к ним.

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

util.debug(string)

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

util.debuglog(section)

• section <Строка> Раздел программы, который необходимо отладить
• Возвращает: <Функция> Функция регистрации

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

Например:

var debuglog = util.debuglog('foo');

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

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

FOO 3245: hello from foo [123]

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

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

util.deprecate(function, string)

Помечает метод, который больше не следует использовать.

const util = require('util');

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

Возвращает изменённую функцию, которая предупреждает один раз по умолчанию.

Если --no-deprecation установлена, эта функция является NO-OP. Настраивается во время выполнения с помощью булевого значения process.noDeprecation (действует только если установлено перед загрузкой модуля).

Если --trace-deprecation установлена, предупреждение и стек вызовов записываются в консоль при первом использовании устаревшего API. Настраивается во время выполнения с помощью булевого значения process.traceDeprecation.

Если --throw-deprecation установлена, приложение выбрасывает исключение при использовании устаревшего API. Настраивается во время выполнения с помощью булевого значения process.throwDeprecation.

process.throwDeprecation имеет приоритет над process.traceDeprecation.

util.error([...])

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

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

Возвращает отформатированную строку, используя первый аргумент как шаблон форматирования printf.

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

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

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

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

Если аргументов больше, чем placeholders, дополнительные аргументы преобразуются в строки (для объектов и символов используется 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.inherits(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);
}

var 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!"

util.inspect(object[, options])

Возвращает строковое представление object, что полезно для отладки.

В качестве необязательного аргумента может быть передан объект options, который изменяет некоторые аспекты отформатированной строки:

• showHidden - если true то неперечисляемые и символьные свойства объекта также будут показаны. По умолчанию false.

• depth - сообщает inspect сколько раз рекурсировать при форматировании объекта. Это полезно для проверки больших сложных объектов. По умолчанию 2. Чтобы сделать рекурсию бесконечной, передайте null.

• colors - если true, то вывод будет стилизован с кодами ANSI. По умолчанию false. Цвета настраиваются, см. Настройка цветов util.inspect.

• customInspect - если false, тогда пользовательские функции inspect(depth, opts) определенные на проверяемых объектах не будут вызываться. По умолчанию true.

Пример проверки всех свойств объекта util:

const util = require('util');

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

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

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

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

util.inspect.styles — это отображение, которое присваивает каждому стилю цвет из util.inspect.colors. Выделенные стили и их значения по умолчанию:

• number (жёлтый)
• boolean (жёлтый)
• string (зелёный)
• date (пурпурный)
• regexp (красный)
• null (полужирный)
• undefined (серый)
• special - только функция в данный момент (голубой)
• name (без стилизации)

Предопределённые цветовые коды: white, grey, black, blue, cyan, green, magenta, red и yellow.

Также есть коды bold, italic, underline и inverse.

Пользовательская функция inspect() для объектов

Объекты также могут определить свою собственную функцию inspect(depth), которую util.inspect() вызовет и использует результат при проверке объекта:

const util = require('util');

var obj = { name: 'nate' };
obj.inspect = function(depth) {
  return `{${this.name}}`;
};

util.inspect(obj);
  // "{nate}"

Вы также можете вернуть совершенно другой объект, и возвращаемая строка будет отформатирована в соответствии с возвращённым объектом. Это похоже на то, как работает JSON.stringify():

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

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

util.isArray(object)

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

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

const util = require('util');

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

util.isBoolean(object)

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

const util = require('util');

util.isBoolean(1)
  // false
util.isBoolean(0)
  // false
util.isBoolean(false)
  // true

util.isBuffer(object)

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

const util = require('util');

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

util.isDate(object)

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

const util = require('util');

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

util.isError(object)

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

const util = require('util');

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

util.isFunction(object)

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

const util = require('util');

function Foo() {}
var Bar = function() {};

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

util.isNull(object)

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

const util = require('util');

util.isNull(0)
  // false
util.isNull(undefined)
  // false
util.isNull(null)
  // true

util.isNullOrUndefined(object)

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

const util = require('util');

util.isNullOrUndefined(0)
  // false
util.isNullOrUndefined(undefined)
  // true
util.isNullOrUndefined(null)
  // true

util.isNumber(object)

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

const util = require('util');

util.isNumber(false)
  // false
util.isNumber(Infinity)
  // true
util.isNumber(0)
  // true
util.isNumber(NaN)
  // true

util.isObject(object)

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

const util = require('util');

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

util.isPrimitive(object)

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

const util = require('util');

util.isPrimitive(5)
  // true
util.isPrimitive('foo')
  // true
util.isPrimitive(false)
  // true
util.isPrimitive(null)
  // true
util.isPrimitive(undefined)
  // true
util.isPrimitive({})
  // false
util.isPrimitive(function() {})
  // false
util.isPrimitive(/^$/)
  // false
util.isPrimitive(new Date())
  // false

util.isRegExp(object)

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

const util = require('util');

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

util.isString(object)

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

const util = require('util');

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

util.isSymbol(object)

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

const util = require('util');

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

util.isUndefined(object)

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

const util = require('util');

var foo;
util.isUndefined(5)
  // false
util.isUndefined(foo)
  // true
util.isUndefined(null)
  // false

util.log(string)

Вывод со временем на stdout.

require('util').log('Timestamped message.');

util.print([...])

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

util.pump(readableStream, writableStream[, callback])

Устаревший предшественник stream.pipe().

util.puts([...])

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