iDoc.dev

Русский

English
简体中文
Español
Français
Português
Deutsch
Italiano
日本語
한국어
العربية

Русский

English
简体中文
Español
Français
Português
Deutsch
Italiano
日本語
한국어
العربية

Тема

Util ​

[Стабильно: 2 - Стабильно]

Стабильно: 2 Стабильность: 2 - Стабильно

Исходный код: lib/util.js

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

js
const util = require('node:util')

util.callbackify(original) ​

Добавлено в: v8.2.0

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

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

js
const util = require('node:util')

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

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

Будет выведено:

text
hello world

Обратный вызов выполняется асинхронно и будет иметь ограниченный стек трассировки. Если обратный вызов вызывает исключение, процесс отправит событие 'uncaughtException', и если оно не обработано, завершится.

Поскольку null имеет специальное значение в качестве первого аргумента обратного вызова, если обернутая функция отклоняет Promise со значением, равным false, в качестве причины, значение оборачивается в Error с исходным значением, хранящимся в поле с именем reason.

js
function fn() {
  return Promise.reject(null)
}
const callbackFunction = util.callbackify(fn)

callbackFunction((err, ret) => {
  // Когда Promise был отклонен с `null`, он оборачивается в Error, и
  // исходное значение хранится в `reason`.
  err && Object.hasOwn(err, 'reason') && err.reason === null // true
})

util.debuglog(section[, callback]) ​

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

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

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

js
const util = require('node:util')
const debuglog = util.debuglog('foo')

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

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

bash
FOO 3245: hello from foo [123]

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

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

js
const util = require('node:util')
const debuglog = util.debuglog('foo-bar')

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

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

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

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

Необязательный аргумент callback можно использовать для замены функции ведения журнала на другую функцию, которая не имеет никакой инициализации или ненужного обертывания.

js
const util = require('node:util')
let debuglog = util.debuglog('internals', debug => {
  // Заменить на функцию ведения журнала, которая оптимизирует
  // проверку включен ли раздел
  debuglog = debug
})

debuglog().enabled ​

Добавлен в: v14.9.0

Геттер util.debuglog().enabled используется для создания теста, который можно использовать в условных операторах на основе существования переменной окружения NODE_DEBUG. Если имя section присутствует в значении этой переменной окружения, возвращаемое значение будет true. В противном случае возвращаемое значение будет false.

js
const util = require('node:util')
const enabled = util.debuglog('foo').enabled
if (enabled) {
  console.log('hello from foo [%d]', 123)
}

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

bash
hello from foo [123]

util.debug(section) ​

Добавлен в: v14.9.0

Псевдоним для util.debuglog. Использование обеспечивает читаемость, которая не подразумевает ведение журнала, если используется только util.debuglog().enabled.

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

[История]

ВерсияИзменения
v10.0.0Предупреждения о снятии с поддержки выводятся только один раз для каждого кода.
v0.8.0Добавлено в: v0.8.0
  • fn <Function> Функция, которая снимается с поддержки.
  • msg <string> Предупреждающее сообщение, которое отображается при вызове устаревшей функции.
  • code <string> Код снятия с поддержки. См. список устаревших API для списка кодов.
  • Возвращает: <Function> Устаревшая функция, обернутая для вывода предупреждения.

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

js
const util = require('node:util')

exports.obsoleteFunction = util.deprecate(() => {
  // Сделайте что-нибудь здесь.
}, 'obsoleteFunction() устарела. Используйте newShinyFunction() вместо этого.')

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

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

js
const util = require('node:util')

const fn1 = util.deprecate(someFunction, someMessage, 'DEP0001')
const fn2 = util.deprecate(someOtherFunction, someOtherMessage, 'DEP0001')
fn1() // Выводит предупреждение о снятии с поддержки с кодом DEP0001
fn2() // Не выводит предупреждение о снятии с поддержки, потому что имеет тот же код

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

[История]

ВерсияИзменения
v12.11.0Спецификатор %c теперь игнорируется.
v12.0.0Аргумент format теперь принимается как таковой, только если он действительно содержит спецификаторы формата.
v12.0.0Если аргумент format не является строкой формата, форматирование выходной строки больше не зависит от типа первого аргумента. Это изменение удаляет ранее присутствующие кавычки из строк, которые выводились, когда первый аргумент не был строкой.
v11.4.0Спецификаторы %d, %f и %i теперь корректно поддерживают Symbols.
v11.4.0Спецификатор %o снова имеет значение глубины по умолчанию 4.
v11.0.0Опция depth спецификатора %o теперь будет возвращаться к глубине по умолчанию.
v10.12.0Спецификаторы %d и %i теперь поддерживают BigInt.
v8.4.0Теперь поддерживаются спецификаторы %o и %O.
v0.5.3Добавлено в: v0.5.3
  • format <строка> Строка формата в стиле printf.

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

  • %s: String будет использоваться для преобразования всех значений, кроме BigInt, Object и -0. Значения BigInt будут представлены с n, а объекты, не имеющие пользовательской функции toString, проверяются с помощью util.inspect() с опциями { depth: 0, colors: false, compact: 3 }.
  • %d: Number будет использоваться для преобразования всех значений, кроме BigInt и Symbol.
  • %i: parseInt(value, 10) используется для всех значений, кроме BigInt и Symbol.
  • %f: parseFloat(value) используется для всех значений, кроме Symbol.
  • %j: JSON. Заменяется строкой '[Circular]', если аргумент содержит циклические ссылки.
  • %o: Object. Строковое представление объекта с общим форматированием объектов JavaScript. Аналогично util.inspect() с опциями { showHidden: true, showProxy: true }. Это покажет весь объект, включая неперечисляемые свойства и прокси.
  • %O: Object. Строковое представление объекта с общим форматированием объектов JavaScript. Аналогично util.inspect() без опций. Это покажет весь объект, не включая неперечисляемые свойства и прокси.
  • %c: CSS. Этот спецификатор игнорируется и пропускает любой переданный CSS.
  • %%: одиночный знак процента ('%'). Он не потребляет аргумент.
  • Возвращает: <строка> Отформатированная строка

Если у спецификатора нет соответствующего аргумента, он не заменяется:

js
util.format('%s:%s', 'foo')
// Возвращает: 'foo:%s'

Значения, которые не являются частью строки формата, форматируются с помощью util.inspect(), если их тип не string.

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

js
util.format('%s:%s', 'foo', 'bar', 'baz')
// Возвращает: 'foo:bar baz'

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

js
util.format(1, 2, 3)
// Возвращает: '1 2 3'

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

js
util.format('%% %s')
// Возвращает: '%% %s'

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

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

Добавлено в: v10.0.0

Эта функция идентична util.format(), за исключением того, что она принимает аргумент inspectOptions, который указывает параметры, передаваемые в util.inspect().

js
util.formatWithOptions({ colors: true }, 'See object %O', { foo: 42 })
// Возвращает 'See object { foo: 42 }', где `42` окрашивается как число
// при выводе в терминал.

util.getCallSites(frameCountOrOptions, [options]) ​

[Стабильно: 1 - Экспериментально]

Стабильно: 1 Стабильность: 1.1 - Активная разработка

[История]

ВерсияИзменения
v23.3.0API переименован из util.getCallSite в util.getCallSites().
v22.9.0Добавлено в: v22.9.0

  • frameCount <number> Необязательное количество кадров для захвата в виде объектов вызова сайта. По умолчанию: 10. Допустимый диапазон от 1 до 200.

  • options <Object> Необязательно

    • sourceMap <boolean> Восстановить исходное местоположение в трассировке стека из source-map. Включено по умолчанию с флагом --enable-source-maps.

  • Возвращает: <Object[]> Массив объектов вызова сайта

    • functionName <string> Возвращает имя функции, связанной с этим сайтом вызова.
    • scriptName <string> Возвращает имя ресурса, содержащего скрипт для функции для этого сайта вызова.
    • lineNumber <number> Возвращает номер строки (с учётом 1) для связанного вызова функции.
    • column <number> Возвращает смещение столбца (с учётом 1) на строке для связанного вызова функции.

Возвращает массив объектов вызова сайта, содержащих стек вызывающей функции.

js
const util = require('node:util')

function exampleFunction() {
  const callSites = util.getCallSites()

  console.log('Call Sites:')
  callSites.forEach((callSite, index) => {
    console.log(`CallSite ${index + 1}:`)
    console.log(`Function Name: ${callSite.functionName}`)
    console.log(`Script Name: ${callSite.scriptName}`)
    console.log(`Line Number: ${callSite.lineNumber}`)
    console.log(`Column Number: ${callSite.column}`)
  })
  // CallSite 1:
  // Function Name: exampleFunction
  // Script Name: /home/example.js
  // Line Number: 5
  // Column Number: 26

  // CallSite 2:
  // Function Name: anotherFunction
  // Script Name: /home/example.js
  // Line Number: 22
  // Column Number: 3

  // ...
}

// Функция для симуляции другого уровня стека
function anotherFunction() {
  exampleFunction()
}

anotherFunction()

Можно восстановить исходные местоположения, установив параметр sourceMap в true. Если source map недоступен, исходное местоположение будет таким же, как текущее. Когда включен флаг --enable-source-maps, например, при использовании --experimental-transform-types, sourceMap будет истинным по умолчанию.

ts
import util from 'node:util'

interface Foo {
  foo: string
}

const callSites = util.getCallSites({ sourceMap: true })

// С sourceMap:
// Function Name: ''
// Script Name: example.js
// Line Number: 7
// Column Number: 26

// Без sourceMap:
// Function Name: ''
// Script Name: example.js
// Line Number: 2
// Column Number: 26

util.getSystemErrorName(err) ​

Добавлено в: v9.7.0

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

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

util.getSystemErrorMap() ​

Добавлено в: v16.0.0, v14.17.0

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

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

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

util.getSystemErrorMessage(err) ​

Добавлено в: v23.1.0

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

js
fs.access('file/that/does/not/exist', err => {
  const name = util.getSystemErrorMessage(err.errno)
  console.error(name) // No such file or directory
})

util.inherits(constructor, superConstructor) ​

[История]

ВерсияИзменения
v5.0.0Параметр constructor теперь может ссылаться на класс ES6.
v0.3.0Добавлено в: v0.3.0

[Стабильно: 3 - Устарело]

Стабильно: 3 Стабильность: 3 - Устарело: используйте синтаксис класса ES2015 и ключевое слово extends вместо этого.

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

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

Это в основном добавляет некоторую проверку ввода поверх Object.setPrototypeOf(constructor.prototype, superConstructor.prototype). В качестве дополнительного удобства superConstructor будет доступен через свойство constructor.super_.

js
const util = require('node:util')
const EventEmitter = require('node:events')

function MyStream() {
  EventEmitter.call(this)
}

util.inherits(MyStream, EventEmitter)

MyStream.prototype.write = function (data) {
  this.emit('data', data)
}

const stream = new MyStream()

console.log(stream instanceof EventEmitter) // true
console.log(MyStream.super_ === EventEmitter) // true

stream.on('data', data => {
  console.log(`Получены данные: "${data}"`)
})
stream.write('Работает!') // Получены данные: "Работает!"

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

js
const EventEmitter = require('node:events')

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

const stream = new MyStream()

stream.on('data', data => {
  console.log(`Получены данные: "${data}"`)
})
stream.write('С ES6')

util.inspect(object[, options]) ​

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

[История]

ВерсияИзменения
v16.18.0Добавлена поддержка maxArrayLength при инспектировании Set и Map.
v17.3.0, v16.14.0Теперь поддерживается опция numericSeparator.
v13.0.0Циклические ссылки теперь включают маркер ссылки.
v14.6.0, v12.19.0Если object принадлежит другому vm.Context, пользовательская функция инспекции больше не будет получать контекстно-зависимые аргументы.
v13.13.0, v12.17.0Теперь поддерживается опция maxStringLength.
v13.5.0, v12.16.0Свойства прототипа, определенные пользователем, инспектируются, если showHidden имеет значение true.
v12.0.0Значение по умолчанию для опции compact изменено на 3, а значение по умолчанию для опции breakLength изменено на 80.
v12.0.0Внутренние свойства больше не отображаются в аргументе контекста пользовательской функции инспекции.
v11.11.0Опция compact принимает числа для нового режима вывода.
v11.7.0ArrayBuffers теперь также показывают свое двоичное содержимое.
v11.5.0Теперь поддерживается опция getters.
v11.4.0Значение по умолчанию для depth возвращено к 2.
v11.0.0Значение по умолчанию для depth изменено на 20.
v11.0.0Вывод инспекции теперь ограничен приблизительно 128 МБ. Данные большего размера не будут полностью проверены.
v10.12.0Теперь поддерживается опция sorted.
v10.6.0Теперь возможно инспектирование связанных списков и подобных объектов до максимального размера стека вызовов.
v10.0.0Теперь также можно инспектировать записи WeakMap и WeakSet.
v9.9.0Теперь поддерживается опция compact.
v6.6.0Пользовательские функции инспекции теперь могут возвращать this.
v6.3.0Теперь поддерживается опция breakLength.
v6.1.0Теперь поддерживается опция maxArrayLength; в частности, длинные массивы усекаются по умолчанию.
v6.1.0Теперь поддерживается опция showProxy.
v0.3.0Добавлено в: v0.3.0

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

  • options <Object>

    • showHidden <boolean> Если true, неперечисляемые символы и свойства object включаются в отформатированный результат. Записи WeakMap и WeakSet также включаются, а также свойства прототипа, определенные пользователем (за исключением свойств метода). По умолчанию: false.
    • depth <number> Указывает количество рекурсий при форматировании object. Это полезно для инспектирования больших объектов. Чтобы выполнить рекурсию до максимального размера стека вызовов, передайте Infinity или null. По умолчанию: 2.
    • colors <boolean> Если true, вывод стилизуется с помощью кодов ANSI-цветов. Цвета можно настраивать. См. Настройка цветов util.inspect. По умолчанию: false.
    • customInspect <boolean> Если false, функции [util.inspect.custom](depth, opts, inspect) не вызываются. По умолчанию: true.
    • showProxy <boolean> Если true, инспекция Proxy включает объекты target и handler. По умолчанию: false.
    • maxArrayLength <integer> Указывает максимальное количество элементов Array, TypedArray, Map, Set, WeakMap и WeakSet для включения при форматировании. Установите null или Infinity, чтобы показать все элементы. Установите 0 или отрицательное значение, чтобы не показывать элементы. По умолчанию: 100.
    • maxStringLength <integer> Указывает максимальное количество символов для включения при форматировании. Установите null или Infinity, чтобы показать все элементы. Установите 0 или отрицательное значение, чтобы не показывать символы. По умолчанию: 10000.
    • breakLength <integer> Длина, при которой входные значения разбиваются на несколько строк. Установите Infinity, чтобы отформатировать входные данные в одну строку (в сочетании с compact, установленным в true или любое число >= 1). По умолчанию: 80.
    • compact <boolean> | <integer> Установка этого параметра в false приводит к отображению каждого ключа объекта на новой строке. Он будет разрываться на новых строках в тексте, который длиннее breakLength. Если установлено число, то самые внутренние n элементов объединяются в одной строке, если все свойства помещаются в breakLength. Короткие элементы массива также группируются вместе. Для получения дополнительной информации см. пример ниже. По умолчанию: 3.
    • sorted <boolean> | <Function> Если установлено значение true или функция, все свойства объекта и записи Set и Map сортируются в результирующей строке. Если установлено значение true, используется стандартная сортировка. Если установлено значение функции, она используется в качестве функции сравнения.
    • getters <boolean> | <string> Если установлено значение true, геттеры инспектируются. Если установлено значение 'get', инспектируются только геттеры без соответствующего сеттера. Если установлено значение 'set', инспектируются только геттеры с соответствующим сеттером. Это может вызвать побочные эффекты в зависимости от функции геттера. По умолчанию: false.
    • numericSeparator <boolean> Если установлено значение true, для разделения каждых трех цифр во всех больших целых числах и числах используется подчеркивание. По умолчанию: false.

  • Возвращает: <string> Представление object.

Метод util.inspect() возвращает строковое представление object, предназначенное для отладки. Вывод util.inspect может изменяться в любое время и не должен использоваться программно. Можно передать дополнительные параметры options, которые изменяют результат. util.inspect() будет использовать имя конструктора и/или @@toStringTag для создания идентифицирующего тега для проверяемого значения.

js
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] {}'

Циклические ссылки указывают на свой якорь с помощью индекса ссылки:

js
const { inspect } = require('node:util')

const obj = {}
obj.a = [obj]
obj.b = {}
obj.b.inner = obj.b
obj.b.obj = obj

console.log(inspect(obj))
// <ref *1> {
//   a: [ [Circular *1] ],
//   b: <ref *2> { inner: [Circular *2], obj: [Circular *1] }
// }

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

js
const util = require('node:util')

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

В следующем примере показано влияние опции compact:

js
const util = require('node:util')

const o = {
  a: [
    1,
    2,
    [
      [
        'Lorem ipsum dolor sit amet,\nconsectetur adipiscing elit, sed do ' +
          'eiusmod \ntempor incididunt ut labore et dolore magna aliqua.',
        'test',
        'foo',
      ],
    ],
    4,
  ],
  b: new Map([
    ['za', 1],
    ['zb', 'test'],
  ]),
}
console.log(util.inspect(o, { compact: true, depth: 5, breakLength: 80 }))

// { a:
//   [ 1,
//     2,
//     [ [ 'Lorem ipsum dolor sit amet,\nconsectetur [...]', // Длинная строка
//           'test',
//           'foo' ] ],
//     4 ],
//   b: Map(2) { 'za' => 1, 'zb' => 'test' } }

// Установка `compact` в false или целое число создает более удобный для чтения вывод.
console.log(util.inspect(o, { compact: false, depth: 5, breakLength: 80 }))

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

// Установка `breakLength` например, в 150 позволит напечатать текст "Lorem ipsum" в одной строке.

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

js
const { inspect } = require('node:util')

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

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

Опция sorted гарантирует, что порядок вставки свойств объекта не влияет на результат util.inspect().

js
const { inspect } = require('node:util')
const assert = require('node:assert')

const o1 = {
  b: [2, 3, 1],
  a: '`a` comes before `b`',
  c: new Set([2, 3, 1]),
}
console.log(inspect(o1, { sorted: true }))
// { a: '`a` comes before `b`', b: [ 2, 3, 1 ], c: Set(3) { 1, 2, 3 } }
console.log(inspect(o1, { sorted: (a, b) => b.localeCompare(a) }))
// { c: Set(3) { 3, 2, 1 }, b: [ 2, 3, 1 ], a: '`a` comes before `b`' }

const o2 = {
  c: new Set([2, 1, 3]),
  a: '`a` comes before `b`',
  b: [2, 3, 1],
}
assert.strict.equal(inspect(o1, { sorted: true }), inspect(o2, { sorted: true }))

Опция numericSeparator добавляет подчеркивание каждые три цифры ко всем числам.

js
const { inspect } = require('node:util')

const thousand = 1_000
const million = 1_000_000
const bigNumber = 123_456_789n
const bigDecimal = 1_234.123_45

console.log(inspect(thousand, { numericSeparator: true }))
// 1_000
console.log(inspect(million, { numericSeparator: true }))
// 1_000_000
console.log(inspect(bigNumber, { numericSeparator: true }))
// 123_456_789n
console.log(inspect(bigDecimal, { numericSeparator: true }))
// 1_234.123_45

util.inspect() - это синхронный метод, предназначенный для отладки. Его максимальная длина вывода составляет приблизительно 128 МБ. Входные данные, которые приводят к более длинному выводу, будут усекаться.

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

Цветовое оформление вывода (если включено) util.inspect можно настроить глобально с помощью свойств util.inspect.styles и util.inspect.colors.

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

Стиль и цвета по умолчанию:

  • bigint: yellow
  • boolean: yellow
  • date: magenta
  • module: underline
  • name: (без стиля)
  • null: bold
  • number: yellow
  • regexp: red
  • special: cyan (например, Proxies)
  • string: green
  • symbol: green
  • undefined: grey

Для цветового оформления используются ANSI-коды управления, которые могут не поддерживаться всеми терминалами. Чтобы проверить поддержку цвета, используйте tty.hasColors().

Предварительно определённые управляющие коды перечислены ниже (сгруппированы как "Модификаторы", "Цвета переднего плана" и "Цвета заднего плана").

Модификаторы ​

Поддержка модификаторов варьируется в разных терминалах. В основном они будут игнорироваться, если не поддерживаются.

  • reset - Сбрасывает все (цветовые) модификаторы до значений по умолчанию
  • bold - Делает текст жирным
  • italic - Делает текст курсивом
  • underline - Подчёркивает текст
  • strikethrough - Проводит горизонтальную линию через центр текста (Псевдоним: strikeThrough, crossedout, crossedOut)
  • hidden - Выводит текст, но делает его невидимым (Псевдоним: conceal)
  • dim - Уменьшенная интенсивность цвета (Псевдоним: faint)
  • overlined - Зачёркивает текст сверху
  • blink - Скрывает и показывает текст с интервалом
  • inverse - Меняет цвета переднего и заднего плана (Псевдоним: swapcolors, swapColors)
  • doubleunderline - Подчеркивает текст двойной линией (Псевдоним: doubleUnderline)
  • framed - Рисует рамку вокруг текста

Цвета переднего плана ​

  • black
  • red
  • green
  • yellow
  • blue
  • magenta
  • cyan
  • white
  • gray (псевдоним: grey, blackBright)
  • redBright
  • greenBright
  • yellowBright
  • blueBright
  • magentaBright
  • cyanBright
  • whiteBright

Цвета заднего плана ​

  • bgBlack
  • bgRed
  • bgGreen
  • bgYellow
  • bgBlue
  • bgMagenta
  • bgCyan
  • bgWhite
  • bgGray (псевдоним: bgGrey, bgBlackBright)
  • bgRedBright
  • bgGreenBright
  • bgYellowBright
  • bgBlueBright
  • bgMagentaBright
  • bgCyanBright
  • bgWhiteBright

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

[История]

ВерсияИзменения
v17.3.0, v16.14.0Добавлен аргумент inspect для лучшей совместимости.
v0.1.97Добавлено в: v0.1.97

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

js
const util = require('node:util')

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

  [util.inspect.custom](depth, options, inspect) {
    if (depth < 0) {
      return options.stylize('[Box]', 'special')
    }

    const newOptions = Object.assign({}, options, {
      depth: options.depth === null ? null : options.depth - 1,
    })

    // Отступ в пять пробелов, так как это размер "Box< ".
    const padding = ' '.repeat(5)
    const inner = inspect(this.value, newOptions).replace(/\n/g, `\n${padding}`)
    return `${options.stylize('Box', 'special')}< ${inner} >`
  }
}

const box = new Box(true)

util.inspect(box)
// Возвращает: "Box< true >"

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

js
const util = require('node:util')

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

util.inspect(obj)
// Возвращает: "{ bar: 'baz' }"

util.inspect.custom ​

[История]

ВерсияИзменения
v10.12.0Теперь это определено как общий символ.
v6.6.0Добавлено в: v6.6.0
  • <symbol>, который может использоваться для объявления пользовательских функций инспекции.

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

Это позволяет писать переносимый код, так что пользовательская функция инспекции используется в среде Node.js и игнорируется в браузере. Сама функция util.inspect() передается в качестве третьего аргумента пользовательской функции инспекции для обеспечения большей переносимости.

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

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

  toString() {
    return 'xxxxxxxx'
  }

  [customInspectSymbol](depth, inspectOptions, inspect) {
    return `Password <${this.toString()}>`
  }
}

const password = new Password('r0sebud')
console.log(password)
// Выводит Password <xxxxxxxx>

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

util.inspect.defaultOptions ​

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

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

js
const util = require('node:util')
const arr = Array(101).fill(0)

console.log(arr) // Выводит усеченный массив
util.inspect.defaultOptions.maxArrayLength = null
console.log(arr) // Выводит полный массив

util.isDeepStrictEqual(val1, val2) ​

Добавлено в: v9.0.0

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

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

Класс: util.MIMEType ​

Добавлено в: v19.1.0, v18.13.0

[Стабильность: 1 - Экспериментальный]

Стабильность: 1 Стабильность: 1 - Экспериментальный

Реализация класса MIMEType.

В соответствии с соглашениями браузера все свойства объектов MIMEType реализованы как геттеры и сеттеры в прототипе класса, а не как свойства данных самого объекта.

Строка MIME — это структурированная строка, содержащая несколько значимых компонентов. При анализе возвращается объект MIMEType, содержащий свойства для каждого из этих компонентов.

Конструктор: new MIMEType(input) ​

  • input <string> MIME-строка для анализа

Создает новый объект MIMEType, анализируя input.

js
import { MIMEType } from 'node:util'

const myMIME = new MIMEType('text/plain')
js
const { MIMEType } = require('node:util')

const myMIME = new MIMEType('text/plain')

Если input не является допустимым MIME, будет выброшено исключение TypeError. Обратите внимание, что будет предпринята попытка приведения заданных значений к строкам. Например:

js
import { MIMEType } from 'node:util'
const myMIME = new MIMEType({ toString: () => 'text/plain' })
console.log(String(myMIME))
// Выводит: text/plain
js
const { MIMEType } = require('node:util')
const myMIME = new MIMEType({ toString: () => 'text/plain' })
console.log(String(myMIME))
// Выводит: text/plain

mime.type ​

Получает и устанавливает часть типа MIME.

js
import { MIMEType } from 'node:util'

const myMIME = new MIMEType('text/javascript')
console.log(myMIME.type)
// Выводит: text
myMIME.type = 'application'
console.log(myMIME.type)
// Выводит: application
console.log(String(myMIME))
// Выводит: application/javascript
js
const { MIMEType } = require('node:util')

const myMIME = new MIMEType('text/javascript')
console.log(myMIME.type)
// Выводит: text
myMIME.type = 'application'
console.log(myMIME.type)
// Выводит: application
console.log(String(myMIME))
// Выводит: application/javascript

mime.subtype ​

Получает и устанавливает подтип MIME.

js
import { MIMEType } from 'node:util'

const myMIME = new MIMEType('text/ecmascript')
console.log(myMIME.subtype)
// Выводит: ecmascript
myMIME.subtype = 'javascript'
console.log(myMIME.subtype)
// Выводит: javascript
console.log(String(myMIME))
// Выводит: text/javascript
js
const { MIMEType } = require('node:util')

const myMIME = new MIMEType('text/ecmascript')
console.log(myMIME.subtype)
// Выводит: ecmascript
myMIME.subtype = 'javascript'
console.log(myMIME.subtype)
// Выводит: javascript
console.log(String(myMIME))
// Выводит: text/javascript

mime.essence ​

Получает сущность MIME. Это свойство только для чтения. Используйте mime.type или mime.subtype для изменения MIME.

js
import { MIMEType } from 'node:util'

const myMIME = new MIMEType('text/javascript;key=value')
console.log(myMIME.essence)
// Выводит: text/javascript
myMIME.type = 'application'
console.log(myMIME.essence)
// Выводит: application/javascript
console.log(String(myMIME))
// Выводит: application/javascript;key=value
js
const { MIMEType } = require('node:util')

const myMIME = new MIMEType('text/javascript;key=value')
console.log(myMIME.essence)
// Выводит: text/javascript
myMIME.type = 'application'
console.log(myMIME.essence)
// Выводит: application/javascript
console.log(String(myMIME))
// Выводит: application/javascript;key=value

mime.params ​

Возвращает объект MIMEParams, представляющий параметры MIME. Это свойство доступно только для чтения. Подробности см. в документации по MIMEParams.

mime.toString() ​

Метод toString() объекта MIMEType возвращает сериализованный MIME.

Из-за необходимости соответствия стандартам этот метод не позволяет пользователям настраивать процесс сериализации MIME.

mime.toJSON() ​

Псевдоним для mime.toString().

Этот метод вызывается автоматически при сериализации объекта MIMEType с помощью JSON.stringify().

js
import { MIMEType } from 'node:util'

const myMIMES = [new MIMEType('image/png'), new MIMEType('image/gif')]
console.log(JSON.stringify(myMIMES))
// Выводит: ["image/png", "image/gif"]
js
const { MIMEType } = require('node:util')

const myMIMES = [new MIMEType('image/png'), new MIMEType('image/gif')]
console.log(JSON.stringify(myMIMES))
// Выводит: ["image/png", "image/gif"]

Класс: util.MIMEParams ​

Добавлено в: v19.1.0, v18.13.0

API MIMEParams обеспечивает доступ для чтения и записи к параметрам MIMEType.

Конструктор: new MIMEParams() ​

Создает новый объект MIMEParams с пустыми параметрами

js
import { MIMEParams } from 'node:util'

const myParams = new MIMEParams()
js
const { MIMEParams } = require('node:util')

const myParams = new MIMEParams()

mimeParams.delete(name) ​

Удаляет все пары «имя-значение», имя которых равно name.

mimeParams.entries() ​

Возвращает итератор для каждой пары «имя-значение» в параметрах. Каждый элемент итератора — это массив JavaScript. Первый элемент массива — это имя, второй элемент массива — это значение.

mimeParams.get(name) ​

  • name <string>
  • Возвращает: <string> | <null> Строка или null, если нет пары «имя-значение» с заданным name.

Возвращает значение первой пары «имя-значение», имя которой — name. Если таких пар нет, возвращается null.

mimeParams.has(name) ​

Возвращает true, если существует хотя бы одна пара «имя-значение», имя которой — name.

mimeParams.keys() ​

Возвращает итератор для имен каждой пары «имя-значение».

js
import { MIMEType } from 'node:util'

const { params } = new MIMEType('text/plain;foo=0;bar=1')
for (const name of params.keys()) {
  console.log(name)
}
// Выводит:
//   foo
//   bar
js
const { MIMEType } = require('node:util')

const { params } = new MIMEType('text/plain;foo=0;bar=1')
for (const name of params.keys()) {
  console.log(name)
}
// Выводит:
//   foo
//   bar

mimeParams.set(name, value) ​

Устанавливает значение в объекте MIMEParams, связанном с name, равным value. Если существуют какие-либо предварительно существующие пары «имя-значение», имена которых — name, устанавливает значение первой такой пары равным value.

js
import { MIMEType } from 'node:util'

const { params } = new MIMEType('text/plain;foo=0;bar=1')
params.set('foo', 'def')
params.set('baz', 'xyz')
console.log(params.toString())
// Выводит: foo=def;bar=1;baz=xyz
js
const { MIMEType } = require('node:util')

const { params } = new MIMEType('text/plain;foo=0;bar=1')
params.set('foo', 'def')
params.set('baz', 'xyz')
console.log(params.toString())
// Выводит: foo=def;bar=1;baz=xyz

mimeParams.values() ​

Возвращает итератор по значениям каждой пары «имя-значение».

mimeParams[@@iterator]() ​

Псевдоним для mimeParams.entries().

js
import { MIMEType } from 'node:util'

const { params } = new MIMEType('text/plain;foo=bar;xyz=baz')
for (const [name, value] of params) {
  console.log(name, value)
}
// Выводит:
//   foo bar
//   xyz baz
js
const { MIMEType } = require('node:util')

const { params } = new MIMEType('text/plain;foo=bar;xyz=baz')
for (const [name, value] of params) {
  console.log(name, value)
}
// Выводит:
//   foo bar
//   xyz baz

util.parseArgs([config]) ​

[История]

ВерсияИзменения
v22.4.0, v20.16.0Добавлена поддержка отрицательных опций во входном config.
v20.0.0API больше не является экспериментальным.
v18.11.0, v16.19.0Добавлена поддержка значений по умолчанию во входном config.
v18.7.0, v16.17.0Добавлена поддержка возврата подробной информации о разборе с помощью tokens во входном config и возвращаемых свойствах.
v18.3.0, v16.17.0Добавлено в: v18.3.0, v16.17.0

  • config <Объект> Используется для предоставления аргументов для анализа и настройки анализатора. config поддерживает следующие свойства:

    • args <string[]> Массив строковых аргументов. По умолчанию: process.argv без execPath и filename.

    • options <Объект> Используется для описания аргументов, известных анализатору. Ключи options — это длинные имена опций, а значения — <Объект>, принимающий следующие свойства:

    • type <string> Тип аргумента, который должен быть либо boolean, либо string.

    • multiple <boolean> Может ли эта опция указываться несколько раз. Если true, все значения будут собраны в массив. Если false, значения для опции — «последнее побеждает». По умолчанию: false.

    • short <string> Односимвольный псевдоним для опции.

    • default <string> | <boolean> | <string[]> | <boolean[]> Значение опции по умолчанию, если оно не задано в args. Оно должно быть того же типа, что и свойство type. Когда multiple равно true, оно должно быть массивом.

    • strict <boolean> Должно ли генерироваться исключение, когда встречаются неизвестные аргументы или когда передаются аргументы, не соответствующие type, настроенному в options. По умолчанию: true.

    • allowPositionals <boolean> Принимает ли эта команда позиционные аргументы. По умолчанию: false, если strict равно true, иначе true.

    • allowNegative <boolean> Если true, позволяет явно устанавливать логические опции в false, добавляя префикс --no- к имени опции. По умолчанию: false.

    • tokens <boolean> Возвращает разобранные токены. Это полезно для расширения встроенного поведения, от добавления дополнительных проверок до переработки токенов различными способами. По умолчанию: false.

  • Возвращает: <Объект> Разобранные аргументы командной строки:

Предоставляет API более высокого уровня для анализа аргументов командной строки, чем прямое взаимодействие с process.argv. Принимает спецификацию ожидаемых аргументов и возвращает структурированный объект с разобранными опциями и позиционными аргументами.

js
import { parseArgs } from 'node:util'
const args = ['-f', '--bar', 'b']
const options = {
  foo: {
    type: 'boolean',
    short: 'f',
  },
  bar: {
    type: 'string',
  },
}
const { values, positionals } = parseArgs({ args, options })
console.log(values, positionals)
// Выводит: [Object: null prototype] { foo: true, bar: 'b' } []
js
const { parseArgs } = require('node:util')
const args = ['-f', '--bar', 'b']
const options = {
  foo: {
    type: 'boolean',
    short: 'f',
  },
  bar: {
    type: 'string',
  },
}
const { values, positionals } = parseArgs({ args, options })
console.log(values, positionals)
// Выводит: [Object: null prototype] { foo: true, bar: 'b' } []

parseArgs tokens ​

Подробная информация о разборе доступна для добавления пользовательских поведений путем указания tokens: true в конфигурации. Возвращаемые токены имеют свойства, описывающие:

  • все токены

    • kind <string> Один из 'option', 'positional' или 'option-terminator'.
    • index <number> Индекс элемента в args, содержащего токен. Таким образом, исходный аргумент для токена — это args[token.index].

  • токены опций

    • name <string> Длинное имя опции.
    • rawName <string> Как опция используется в args, например, -f из --foo.
    • value <string> | <undefined> Значение опции, указанное в args. Неопределено для булевых опций.
    • inlineValue <boolean> | <undefined> Указывает ли значение опции внутри строки, например, --foo=bar.

  • позиционные токены

    • value <string> Значение позиционного аргумента в args (т.е. args[index]).

  • токен-разделитель опций

Возвращаемые токены упорядочены в порядке их появления во входных args. Опции, которые появляются более одного раза в args, создают токен для каждого использования. Краткогруппированные опции, такие как -xy, расширяются до токена для каждой опции. Таким образом, -xxx создает три токена.

Например, для добавления поддержки отрицательной опции, такой как --no-color (которую allowNegative поддерживает, когда опция имеет тип boolean), возвращаемые токены могут быть переобработаны для изменения значения, хранящегося для отрицательной опции.

js
import { parseArgs } from 'node:util'

const options = {
  color: { type: 'boolean' },
  'no-color': { type: 'boolean' },
  logfile: { type: 'string' },
  'no-logfile': { type: 'boolean' },
}
const { values, tokens } = parseArgs({ options, tokens: true })

// Переобработка токенов опций и перезапись возвращаемых значений.
tokens
  .filter(token => token.kind === 'option')
  .forEach(token => {
    if (token.name.startsWith('no-')) {
      // Сохранение foo:false для --no-foo
      const positiveName = token.name.slice(3)
      values[positiveName] = false
      delete values[token.name]
    } else {
      // Повторное сохранение значения, чтобы последнее выигрывало, если есть и --foo, и --no-foo.
      values[token.name] = token.value ?? true
    }
  })

const color = values.color
const logfile = values.logfile ?? 'default.log'

console.log({ logfile, color })
js
const { parseArgs } = require('node:util')

const options = {
  color: { type: 'boolean' },
  'no-color': { type: 'boolean' },
  logfile: { type: 'string' },
  'no-logfile': { type: 'boolean' },
}
const { values, tokens } = parseArgs({ options, tokens: true })

// Переобработка токенов опций и перезапись возвращаемых значений.
tokens
  .filter(token => token.kind === 'option')
  .forEach(token => {
    if (token.name.startsWith('no-')) {
      // Сохранение foo:false для --no-foo
      const positiveName = token.name.slice(3)
      values[positiveName] = false
      delete values[token.name]
    } else {
      // Повторное сохранение значения, чтобы последнее выигрывало, если есть и --foo, и --no-foo.
      values[token.name] = token.value ?? true
    }
  })

const color = values.color
const logfile = values.logfile ?? 'default.log'

console.log({ logfile, color })

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

bash
$ node negate.js
{ logfile: 'default.log', color: undefined }
$ node negate.js --no-logfile --no-color
{ logfile: false, color: false }
$ node negate.js --logfile=test.log --color
{ logfile: 'test.log', color: true }
$ node negate.js --no-logfile --logfile=test.log --color --no-color
{ logfile: 'test.log', color: false }

util.parseEnv(content) ​

[Стабильно: 1 - Экспериментально]

Стабильно: 1 Стабильность: 1.1 - Активная разработка

Добавлено в: v21.7.0, v20.12.0

Необработанное содержимое файла .env.

Пример файла .env:

js
const { parseEnv } = require('node:util')

parseEnv('HELLO=world\nHELLO=oh my\n')
// Возвращает: { HELLO: 'oh my' }
js
import { parseEnv } from 'node:util'

parseEnv('HELLO=world\nHELLO=oh my\n')
// Возвращает: { HELLO: 'oh my' }

util.promisify(original) ​

[История]

ВерсияИзменения
v20.8.0Вызов promisify для функции, возвращающей Promise, устарел.
v8.0.0Добавлено в: v8.0.0

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

js
const util = require('node:util')
const fs = require('node:fs')

const stat = util.promisify(fs.stat)
stat('.')
  .then(stats => {
    // Выполните какое-либо действие со значением `stats`
  })
  .catch(error => {
    // Обработайте ошибку.
  })

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

js
const util = require('node:util')
const fs = require('node:fs')

const stat = util.promisify(fs.stat)

async function callStat() {
  const stats = await stat('.')
  console.log(`Эта директория принадлежит пользователю ${stats.uid}`)
}

callStat()

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

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

Использование promisify() для методов класса или других методов, использующих this, может работать не так, как ожидалось, если не обрабатывается специальным образом:

js
const util = require('node:util')

class Foo {
  constructor() {
    this.a = 42
  }

  bar(callback) {
    callback(null, this.a)
  }
}

const foo = new Foo()

const naiveBar = util.promisify(foo.bar)
// TypeError: Cannot read property 'a' of undefined
// naiveBar().then(a => console.log(a));

naiveBar.call(foo).then(a => console.log(a)) // '42'

const bindBar = naiveBar.bind(foo)
bindBar().then(a => console.log(a)) // '42'

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

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

js
const util = require('node:util')

function doSomething(foo, callback) {
  // ...
}

doSomething[util.promisify.custom] = foo => {
  return getPromiseSomehow()
}

const promisified = util.promisify(doSomething)
console.log(promisified === doSomething[util.promisify.custom])
// выводит 'true'

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

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

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

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

util.promisify.custom ​

[История]

ВерсияИзменения
v13.12.0, v12.16.2Теперь это определено как общий символ.
v8.0.0Добавлено в: v8.0.0

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

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

js
const kCustomPromisifiedSymbol = Symbol.for('nodejs.util.promisify.custom')

doSomething[kCustomPromisifiedSymbol] = foo => {
  return new Promise((resolve, reject) => {
    doSomething(foo, resolve, reject)
  })
}

util.stripVTControlCharacters(str) ​

Добавлено в: v16.11.0

Возвращает str без кодов ANSI-последовательностей.

js
console.log(util.stripVTControlCharacters('\u001B[4mvalue\u001B[0m'))
// Выводит "value"

util.styleText(format, text[, options]) ​

[Стабильно: 2 - Стабильно]

Стабильно: 2 Стабильность: 2 - Стабильно.

[История]

ВерсияИзменения
v23.5.0styleText теперь стабилен.
v22.8.0, v20.18.0Учитывает isTTY и переменные среды, такие как NO_COLORS, NODE_DISABLE_COLORS и FORCE_COLOR.
v21.7.0, v20.12.0Добавлено в: v21.7.0, v20.12.0
  • format <string> | <Array> Текстовый формат или массив текстовых форматов, определённых в util.inspect.colors.
  • text <string> Текст для форматирования.
  • options <Object>
    • validateStream <boolean> Если true, stream проверяется на возможность обработки цветов. По умолчанию: true.
    • stream <Stream> Поток, который будет проверен на возможность вывода цветов. По умолчанию: process.stdout.

Эта функция возвращает отформатированный текст, учитывая переданный format для вывода в терминал. Она учитывает возможности терминала и действует в соответствии с конфигурацией, заданной через переменные среды NO_COLORS, NODE_DISABLE_COLORS и FORCE_COLOR.

js
import { styleText } from 'node:util'
import { stderr } from 'node:process'

const successMessage = styleText('green', 'Success!')
console.log(successMessage)

const errorMessage = styleText(
  'red',
  'Error! Error!',
  // Проверить, имеет ли process.stderr TTY
  { stream: stderr }
)
console.error(successMessage)
js
const { styleText } = require('node:util')
const { stderr } = require('node:process')

const successMessage = styleText('green', 'Success!')
console.log(successMessage)

const errorMessage = styleText(
  'red',
  'Error! Error!',
  // Проверить, имеет ли process.stderr TTY
  { stream: stderr }
)
console.error(successMessage)

util.inspect.colors также предоставляет текстовые форматы, такие как italic и underline, и вы можете комбинировать их:

js
console.log(util.styleText(['underline', 'italic'], 'Моё курсивное подчёркнутое сообщение'))

При передаче массива форматов порядок применения форматов слева направо, поэтому последующий стиль может перекрывать предыдущий.

js
console.log(
  util.styleText(['red', 'green'], 'text') // green
)

Полный список форматов можно найти в модификаторах.

Класс: util.TextDecoder ​

[История]

ВерсияИзменения
v11.0.0Класс теперь доступен в глобальном объекте.
v8.3.0Добавлен в: v8.3.0

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

js
const decoder = new TextDecoder()
const u8arr = new Uint8Array([72, 101, 108, 108, 111])
console.log(decoder.decode(u8arr)) // Hello

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

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

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

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

КодировкаПсевдонимы
'ibm866''866' , 'cp866' , 'csibm866'
'iso-8859-2''csisolatin2' , 'iso-ir-101' , 'iso8859-2' , 'iso88592' , 'iso_8859-2' , 'iso_8859-2:1987' , 'l2' , 'latin2'
'iso-8859-3''csisolatin3' , 'iso-ir-109' , 'iso8859-3' , 'iso88593' , 'iso_8859-3' , 'iso_8859-3:1988' , 'l3' , 'latin3'
'iso-8859-4''csisolatin4' , 'iso-ir-110' , 'iso8859-4' , 'iso88594' , 'iso_8859-4' , 'iso_8859-4:1988' , 'l4' , 'latin4'
'iso-8859-5''csisolatincyrillic' , 'cyrillic' , 'iso-ir-144' , 'iso8859-5' , 'iso88595' , 'iso_8859-5' , 'iso_8859-5:1988'
'iso-8859-6''arabic' , 'asmo-708' , 'csiso88596e' , 'csiso88596i' , 'csisolatinarabic' , 'ecma-114' , 'iso-8859-6-e' , 'iso-8859-6-i' , 'iso-ir-127' , 'iso8859-6' , 'iso88596' , 'iso_8859-6' , 'iso_8859-6:1987'
'iso-8859-7''csisolatingreek' , 'ecma-118' , 'elot_928' , 'greek' , 'greek8' , 'iso-ir-126' , 'iso8859-7' , 'iso88597' , 'iso_8859-7' , 'iso_8859-7:1987' , 'sun_eu_greek'
'iso-8859-8''csiso88598e' , 'csisolatinhebrew' , 'hebrew' , 'iso-8859-8-e' , 'iso-ir-138' , 'iso8859-8' , 'iso88598' , 'iso_8859-8' , 'iso_8859-8:1988' , 'visual'
'iso-8859-8-i''csiso88598i' , 'logical'
'iso-8859-10''csisolatin6' , 'iso-ir-157' , 'iso8859-10' , 'iso885910' , 'l6' , 'latin6'
'iso-8859-13''iso8859-13' , 'iso885913'
'iso-8859-14''iso8859-14' , 'iso885914'
'iso-8859-15''csisolatin9' , 'iso8859-15' , 'iso885915' , 'iso_8859-15' , 'l9'
'koi8-r''cskoi8r' , 'koi' , 'koi8' , 'koi8_r'
'koi8-u''koi8-ru'
'macintosh''csmacintosh' , 'mac' , 'x-mac-roman'
'windows-874''dos-874' , 'iso-8859-11' , 'iso8859-11' , 'iso885911' , 'tis-620'
'windows-1250''cp1250' , 'x-cp1250'
'windows-1251''cp1251' , 'x-cp1251'
'windows-1252''ansi_x3.4-1968' , 'ascii' , 'cp1252' , 'cp819' , 'csisolatin1' , 'ibm819' , 'iso-8859-1' , 'iso-ir-100' , 'iso8859-1' , 'iso88591' , 'iso_8859-1' , 'iso_8859-1:1987' , 'l1' , 'latin1' , 'us-ascii' , 'x-cp1252'
'windows-1253''cp1253' , 'x-cp1253'
'windows-1254''cp1254' , 'csisolatin5' , 'iso-8859-9' , 'iso-ir-148' , 'iso8859-9' , 'iso88599' , 'iso_8859-9' , 'iso_8859-9:1989' , 'l5' , 'latin5' , 'x-cp1254'
'windows-1255''cp1255' , 'x-cp1255'
'windows-1256''cp1256' , 'x-cp1256'
'windows-1257''cp1257' , 'x-cp1257'
'windows-1258''cp1258' , 'x-cp1258'
'x-mac-cyrillic''x-mac-ukrainian'
'gbk''chinese' , 'csgb2312' , 'csiso58gb231280' , 'gb2312' , 'gb_2312' , 'gb_2312-80' , 'iso-ir-58' , 'x-gbk'
'gb18030'
'big5''big5-hkscs' , 'cn-big5' , 'csbig5' , 'x-x-big5'
'euc-jp''cseucpkdfmtjapanese' , 'x-euc-jp'
'iso-2022-jp''csiso2022jp'
'shift_jis''csshiftjis' , 'ms932' , 'ms_kanji' , 'shift-jis' , 'sjis' , 'windows-31j' , 'x-sjis'
'euc-kr''cseuckr' , 'csksc56011987' , 'iso-ir-149' , 'korean' , 'ks_c_5601-1987' , 'ks_c_5601-1989' , 'ksc5601' , 'ksc_5601' , 'windows-949'

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

КодировкаПсевдонимы
'utf-8''unicode-1-1-utf-8', 'utf8'
'utf-16le''utf-16'
'utf-16be'

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

КодировкаПсевдонимы
'utf-8''unicode-1-1-utf-8', 'utf8'
'utf-16le''utf-16'

Кодировка '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 также доступен в глобальном объекте.

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

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

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

textDecoder.encoding ​

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

textDecoder.fatal ​

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

textDecoder.ignoreBOM ​

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

Класс: util.TextEncoder ​

[История]

ВерсияИзменения
v11.0.0Класс теперь доступен в глобальном объекте.
v8.3.0Добавлено в: v8.3.0

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

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

Класс TextEncoder также доступен в глобальном объекте.

textEncoder.encode([input]) ​

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

Выполняет кодировку UTF-8 входной строки и возвращает Uint8Array, содержащий закодированные байты.

textEncoder.encodeInto(src, dest) ​

Добавлена в: v12.11.0

  • src <строка> Текст для кодирования.
  • dest <Uint8Array> Массив для хранения результата кодирования.
  • Возвращает: <объект>
    • read <число> Прочитанные юникодные кодовые единицы src.
    • written <число> Записанные байты UTF-8 dest.

Выполняет кодировку UTF-8 строки src в dest Uint8Array и возвращает объект, содержащий прочитанные юникодные кодовые единицы и записанные байты UTF-8.

js
const encoder = new TextEncoder()
const src = 'this is some data'
const dest = new Uint8Array(10)
const { read, written } = encoder.encodeInto(src, dest)

textEncoder.encoding ​

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

util.toUSVString(string) ​

Добавлено в: v16.8.0, v14.18.0

Возвращает строку string после замены любых суррогатных кодовых точек (или, что эквивалентно, любых непарных суррогатных кодовых единиц) на символ Unicode "замены" U+FFFD.

util.transferableAbortController() ​

Добавлено в: v18.11.0

[Стабильность: 1 - Экспериментально]

Стабильность: 1 Стабильность: 1 - Экспериментально

Создает и возвращает экземпляр <AbortController>, сигнал <AbortSignal> которого помечен как передаваемый и может использоваться с structuredClone() или postMessage().

util.transferableAbortSignal(signal) ​

Добавлено в: v18.11.0

[Стабильность: 1 - Экспериментально]

Стабильность: 1 Стабильность: 1 - Экспериментально

Помечает данный <AbortSignal> как передаваемый, чтобы его можно было использовать с structuredClone() и postMessage().

js
const signal = transferableAbortSignal(AbortSignal.timeout(100))
const channel = new MessageChannel()
channel.port2.postMessage(signal, [signal])

util.aborted(signal, resource) ​

Добавлено в: v19.7.0, v18.16.0

[Стабильность: 1 - Экспериментально]

Стабильность: 1 Стабильность: 1 - Экспериментально

  • signal <AbortSignal>
  • resource <Object> Любой не нулевой объект, привязанный к прерываемой операции и слабо удерживаемый. Если resource будет собрано сборщиком мусора до прерывания signal, promise останется в ожидании, позволяя Node.js прекратить его отслеживание. Это помогает предотвратить утечки памяти в длительных или неотменяемых операциях.
  • Возвращает: <Promise>

Прослушивает событие прерывания в предоставленном signal и возвращает promise, который разрешается, когда signal прерывается. Если предоставлен resource, он слабо ссылается на связанный с операцией объект, поэтому если resource будет собрано сборщиком мусора до прерывания signal, возвращенный promise останется в ожидании. Это предотвращает утечки памяти в длительных или неотменяемых операциях.

js
const { aborted } = require('node:util')

// Получение объекта с прерываемым сигналом, например, настраиваемого ресурса или операции.
const dependent = obtainSomethingAbortable()

// Передача `dependent` в качестве ресурса, указывающая, что promise должен разрешиться
// только если `dependent` все еще находится в памяти, когда сигнал прерывается.
aborted(dependent.signal, dependent).then(() => {
  // Этот код выполняется, когда `dependent` прерывается.
  console.log('Прерван зависимый ресурс.')
})

// Имитация события, которое вызывает прерывание.
dependent.on('event', () => {
  dependent.abort() // Это приведет к разрешению promise `aborted`.
})
js
import { aborted } from 'node:util'

// Получение объекта с прерываемым сигналом, например, настраиваемого ресурса или операции.
const dependent = obtainSomethingAbortable()

// Передача `dependent` в качестве ресурса, указывающая, что promise должен разрешиться
// только если `dependent` все еще находится в памяти, когда сигнал прерывается.
aborted(dependent.signal, dependent).then(() => {
  // Этот код выполняется, когда `dependent` прерывается.
  console.log('Прерван зависимый ресурс.')
})

// Имитация события, которое вызывает прерывание.
dependent.on('event', () => {
  dependent.abort() // Это приведет к разрешению promise `aborted`.
})

util.types ​

[История]

ВерсияИзменения
v15.3.0Доступен как require('util/types').
v10.0.0Добавлен в: v10.0.0

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

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

API доступен через require('node:util').types или require('node:util/types').

util.types.isAnyArrayBuffer(value) ​

Добавлен в: v10.0.0

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

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

js
util.types.isAnyArrayBuffer(new ArrayBuffer()) // Возвращает true
util.types.isAnyArrayBuffer(new SharedArrayBuffer()) // Возвращает true

util.types.isArrayBufferView(value) ​

Добавлен в: v10.0.0

Возвращает true, если значение является экземпляром одного из представлений ArrayBuffer, таких как объекты типизированных массивов или DataView. Эквивалентно ArrayBuffer.isView().

js
util.types.isArrayBufferView(new Int8Array()) // true
util.types.isArrayBufferView(Buffer.from('hello world')) // true
util.types.isArrayBufferView(new DataView(new ArrayBuffer(16))) // true
util.types.isArrayBufferView(new ArrayBuffer()) // false

util.types.isArgumentsObject(value) ​

Добавлен в: v10.0.0

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

js
function foo() {
  util.types.isArgumentsObject(arguments) // Возвращает true
}

util.types.isArrayBuffer(value) ​

Добавлен в: v10.0.0

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

js
util.types.isArrayBuffer(new ArrayBuffer()) // Возвращает true
util.types.isArrayBuffer(new SharedArrayBuffer()) // Возвращает false

util.types.isAsyncFunction(value) ​

Добавлен в: v10.0.0

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

js
util.types.isAsyncFunction(function foo() {}) // Возвращает false
util.types.isAsyncFunction(async function foo() {}) // Возвращает true

util.types.isBigInt64Array(value) ​

Добавлено в: v10.0.0

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

js
util.types.isBigInt64Array(new BigInt64Array()) // Возвращает true
util.types.isBigInt64Array(new BigUint64Array()) // Возвращает false

util.types.isBigIntObject(value) ​

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

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

js
util.types.isBigIntObject(Object(BigInt(123))) // Возвращает true
util.types.isBigIntObject(BigInt(123)) // Возвращает false
util.types.isBigIntObject(123) // Возвращает false

util.types.isBigUint64Array(value) ​

Добавлено в: v10.0.0

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

js
util.types.isBigUint64Array(new BigInt64Array()) // Возвращает false
util.types.isBigUint64Array(new BigUint64Array()) // Возвращает true

util.types.isBooleanObject(value) ​

Добавлено в: v10.0.0

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

js
util.types.isBooleanObject(false) // Возвращает false
util.types.isBooleanObject(true) // Возвращает false
util.types.isBooleanObject(new Boolean(false)) // Возвращает true
util.types.isBooleanObject(new Boolean(true)) // Возвращает true
util.types.isBooleanObject(Boolean(false)) // Возвращает false
util.types.isBooleanObject(Boolean(true)) // Возвращает false

util.types.isBoxedPrimitive(value) ​

Добавлен в: v10.11.0

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

Например:

js
util.types.isBoxedPrimitive(false) // Возвращает false
util.types.isBoxedPrimitive(new Boolean(false)) // Возвращает true
util.types.isBoxedPrimitive(Symbol('foo')) // Возвращает false
util.types.isBoxedPrimitive(Object(Symbol('foo'))) // Возвращает true
util.types.isBoxedPrimitive(Object(BigInt(5))) // Возвращает true

util.types.isCryptoKey(value) ​

Добавлен в: v16.2.0

Возвращает true, если value является <CryptoKey>, false в противном случае.

util.types.isDataView(value) ​

Добавлен в: v10.0.0

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

js
const ab = new ArrayBuffer(20)
util.types.isDataView(new DataView(ab)) // Возвращает true
util.types.isDataView(new Float64Array()) // Возвращает false

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

util.types.isDate(value) ​

Добавлен в: v10.0.0

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

js
util.types.isDate(new Date()) // Возвращает true

util.types.isExternal(value) ​

Добавлено в: v10.0.0

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

Собственное значение External — это специальный тип объекта, содержащий необработанный указатель C++ (void*) для доступа из собственного кода и не имеющий других свойств. Такие объекты создаются либо внутренними компонентами Node.js, либо собственными надстройками. В JavaScript они являются замороженными объектами с прототипом null.

C
#include <js_native_api.h>
#include <stdlib.h>
napi_value result;
static napi_value MyNapi(napi_env env, napi_callback_info info) {
  int* raw = (int*) malloc(1024);
  napi_status status = napi_create_external(env, (void*) raw, NULL, NULL, &result);
  if (status != napi_ok) {
    napi_throw_error(env, NULL, "napi_create_external failed");
    return NULL;
  }
  return result;
}
...
DECLARE_NAPI_PROPERTY("myNapi", MyNapi)
...
js
const native = require('napi_addon.node')
const data = native.myNapi()
util.types.isExternal(data) // возвращает true
util.types.isExternal(0) // возвращает false
util.types.isExternal(new String('foo')) // возвращает false

Для получения дополнительной информации о napi_create_external обратитесь к napi_create_external().

util.types.isFloat32Array(value) ​

Добавлено в: v10.0.0

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

js
util.types.isFloat32Array(new ArrayBuffer()) // Возвращает false
util.types.isFloat32Array(new Float32Array()) // Возвращает true
util.types.isFloat32Array(new Float64Array()) // Возвращает false

util.types.isFloat64Array(value) ​

Добавлено в: v10.0.0

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

js
util.types.isFloat64Array(new ArrayBuffer()) // Возвращает false
util.types.isFloat64Array(new Uint8Array()) // Возвращает false
util.types.isFloat64Array(new Float64Array()) // Возвращает true

util.types.isGeneratorFunction(value) ​

Добавлено в: v10.0.0

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

js
util.types.isGeneratorFunction(function foo() {}) // Возвращает false
util.types.isGeneratorFunction(function* foo() {}) // Возвращает true

util.types.isGeneratorObject(value) ​

Добавлено в: v10.0.0

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

js
function* foo() {}
const generator = foo()
util.types.isGeneratorObject(generator) // Возвращает true

util.types.isInt8Array(value) ​

Добавлено в: v10.0.0

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

js
util.types.isInt8Array(new ArrayBuffer()) // Возвращает false
util.types.isInt8Array(new Int8Array()) // Возвращает true
util.types.isInt8Array(new Float64Array()) // Возвращает false

util.types.isInt16Array(value) ​

Добавлено в: v10.0.0

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

js
util.types.isInt16Array(new ArrayBuffer()) // Возвращает false
util.types.isInt16Array(new Int16Array()) // Возвращает true
util.types.isInt16Array(new Float64Array()) // Возвращает false

util.types.isInt32Array(value) ​

Добавлено в: v10.0.0

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

js
util.types.isInt32Array(new ArrayBuffer()) // Возвращает false
util.types.isInt32Array(new Int32Array()) // Возвращает true
util.types.isInt32Array(new Float64Array()) // Возвращает false

util.types.isKeyObject(value) ​

Добавлено в: v16.2.0

Возвращает true, если value является <KeyObject>, false в противном случае.

util.types.isMap(value) ​

Добавлено в: v10.0.0

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

js
util.types.isMap(new Map()) // Возвращает true

util.types.isMapIterator(value) ​

Добавлено в: v10.0.0

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

js
const map = new Map()
util.types.isMapIterator(map.keys()) // Возвращает true
util.types.isMapIterator(map.values()) // Возвращает true
util.types.isMapIterator(map.entries()) // Возвращает true
util.types.isMapIterator(map[Symbol.iterator]()) // Возвращает true

util.types.isModuleNamespaceObject(value) ​

Добавлено в: v10.0.0

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

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

util.types.isModuleNamespaceObject(ns) // Возвращает true

util.types.isNativeError(value) ​

Добавлено в: v10.0.0

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

js
console.log(util.types.isNativeError(new Error())) // true
console.log(util.types.isNativeError(new TypeError())) // true
console.log(util.types.isNativeError(new RangeError())) // true

Подклассы встроенных типов ошибок также являются собственными ошибками:

js
class MyError extends Error {}
console.log(util.types.isNativeError(new MyError())) // true

Значение, являющееся instanceof собственного класса ошибки, не эквивалентно тому, что isNativeError() возвращает true для этого значения. isNativeError() возвращает true для ошибок, которые поступают из другой сферы, в то время как instanceof Error возвращает false для этих ошибок:

js
const vm = require('node:vm')
const context = vm.createContext({})
const myError = vm.runInContext('new Error()', context)
console.log(util.types.isNativeError(myError)) // true
console.log(myError instanceof Error) // false

И наоборот, isNativeError() возвращает false для всех объектов, которые не были возвращены конструктором собственной ошибки. Это включает в себя значения, которые являются instanceof собственными ошибками:

js
const myError = { __proto__: Error.prototype }
console.log(util.types.isNativeError(myError)) // false
console.log(myError instanceof Error) // true

util.types.isNumberObject(value) ​

Добавлено в: v10.0.0

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

js
util.types.isNumberObject(0) // Возвращает false
util.types.isNumberObject(new Number(0)) // Возвращает true

util.types.isPromise(value) ​

Добавлено в: v10.0.0

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

js
util.types.isPromise(Promise.resolve(42)) // Возвращает true

util.types.isProxy(value) ​

Добавлено в: v10.0.0

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

js
const target = {}
const proxy = new Proxy(target, {})
util.types.isProxy(target) // Возвращает false
util.types.isProxy(proxy) // Возвращает true

util.types.isRegExp(value) ​

Добавлено в: v10.0.0

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

js
util.types.isRegExp(/abc/) // Возвращает true
util.types.isRegExp(new RegExp('abc')) // Возвращает true

util.types.isSet(value) ​

Добавлен в: v10.0.0

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

js
util.types.isSet(new Set()) // Возвращает true

util.types.isSetIterator(value) ​

Добавлен в: v10.0.0

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

js
const set = new Set()
util.types.isSetIterator(set.keys()) // Возвращает true
util.types.isSetIterator(set.values()) // Возвращает true
util.types.isSetIterator(set.entries()) // Возвращает true
util.types.isSetIterator(set[Symbol.iterator]()) // Возвращает true

util.types.isSharedArrayBuffer(value) ​

Добавлен в: v10.0.0

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

js
util.types.isSharedArrayBuffer(new ArrayBuffer()) // Возвращает false
util.types.isSharedArrayBuffer(new SharedArrayBuffer()) // Возвращает true

util.types.isStringObject(value) ​

Добавлено в: v10.0.0

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

js
util.types.isStringObject('foo') // Возвращает false
util.types.isStringObject(new String('foo')) // Возвращает true

util.types.isSymbolObject(value) ​

Добавлено в: v10.0.0

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

js
const symbol = Symbol('foo')
util.types.isSymbolObject(symbol) // Возвращает false
util.types.isSymbolObject(Object(symbol)) // Возвращает true

util.types.isTypedArray(value) ​

Добавлено в: v10.0.0

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

js
util.types.isTypedArray(new ArrayBuffer()) // Возвращает false
util.types.isTypedArray(new Uint8Array()) // Возвращает true
util.types.isTypedArray(new Float64Array()) // Возвращает true

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

util.types.isUint8Array(value) ​

Добавлено в: v10.0.0

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

js
util.types.isUint8Array(new ArrayBuffer()) // Возвращает false
util.types.isUint8Array(new Uint8Array()) // Возвращает true
util.types.isUint8Array(new Float64Array()) // Возвращает false

util.types.isUint8ClampedArray(value) ​

Добавлен в: v10.0.0

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

js
util.types.isUint8ClampedArray(new ArrayBuffer()) // Возвращает false
util.types.isUint8ClampedArray(new Uint8ClampedArray()) // Возвращает true
util.types.isUint8ClampedArray(new Float64Array()) // Возвращает false

util.types.isUint16Array(value) ​

Добавлен в: v10.0.0

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

js
util.types.isUint16Array(new ArrayBuffer()) // Возвращает false
util.types.isUint16Array(new Uint16Array()) // Возвращает true
util.types.isUint16Array(new Float64Array()) // Возвращает false

util.types.isUint32Array(value) ​

Добавлен в: v10.0.0

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

js
util.types.isUint32Array(new ArrayBuffer()) // Возвращает false
util.types.isUint32Array(new Uint32Array()) // Возвращает true
util.types.isUint32Array(new Float64Array()) // Возвращает false

util.types.isWeakMap(value) ​

Добавлен в: v10.0.0

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

js
util.types.isWeakMap(new WeakMap()) // Возвращает true

util.types.isWeakSet(value) ​

Добавлен в: v10.0.0

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

js
util.types.isWeakSet(new WeakSet()) // Возвращает true

Устаревшие API ​

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

util._extend(target, source) ​

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

Устарел с: v6.0.0

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

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

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

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

util.isArray(object) ​

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

Устарел с: v4.0.0

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

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

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

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

js
const util = require('node:util')

util.isArray([])
// Возвращает: true
util.isArray(new Array())
// Возвращает: true
util.isArray({})
// Возвращает: false