iDoc.dev

Português

English
简体中文
Español
Français
Deutsch
Italiano
日本語
한국어
Русский
العربية

Português

English
简体中文
Español
Français
Deutsch
Italiano
日本語
한국어
Русский
العربية

Tema

Util ​

[Estável: 2 - Estável]

Estável: 2 Estabilidade: 2 - Estável

Código-Fonte: lib/util.js

O módulo node:util suporta as necessidades das APIs internas do Node.js. Muitas das utilidades são úteis para desenvolvedores de aplicativos e módulos também. Para acessá-lo:

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

util.callbackify(original) ​

Adicionado em: v8.2.0

Recebe uma função async (ou uma função que retorna uma Promise) e retorna uma função seguindo o estilo de callback error-first, ou seja, recebendo um callback (err, value) =\> ... como último argumento. No callback, o primeiro argumento será a razão da rejeição (ou null se a Promise foi resolvida), e o segundo argumento será o valor resolvido.

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

Imprimir:

text
hello world

O callback é executado assincronamente e terá um rastro de pilha limitado. Se o callback lançar uma exceção, o processo emitirá um evento 'uncaughtException', e se não for tratado, sairá.

Como null tem um significado especial como o primeiro argumento de um callback, se uma função encapsulada rejeitar uma Promise com um valor falsy como razão, o valor é encapsulado em um Error com o valor original armazenado em um campo chamado reason.

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

callbackFunction((err, ret) => {
  // Quando a Promise foi rejeitada com `null` ela é encapsulada com um Error e
  // o valor original é armazenado em `reason`.
  err && Object.hasOwn(err, 'reason') && err.reason === null // true
})

util.debuglog(section[, callback]) ​

Adicionado em: v0.11.3

  • section <string> Uma string identificando a porção do aplicativo para a qual a função debuglog está sendo criada.
  • callback <Function> Uma função de retorno de chamada invocada na primeira vez que a função de registro é chamada com um argumento de função que é uma função de registro mais otimizada.
  • Retorna: <Function> A função de registro

O método util.debuglog() é usado para criar uma função que condicionalmente escreve mensagens de depuração para stderr com base na existência da variável de ambiente NODE_DEBUG. Se o nome da section aparecer dentro do valor dessa variável de ambiente, a função retornada opera de forma semelhante à console.error(). Caso contrário, a função retornada é uma operação sem efeito.

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

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

Se este programa for executado com NODE_DEBUG=foo no ambiente, ele produzirá algo como:

bash
FOO 3245: hello from foo [123]

onde 3245 é o ID do processo. Se não for executado com essa variável de ambiente definida, ele não imprimirá nada.

A section também suporta caracteres curinga:

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

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

se for executado com NODE_DEBUG=foo* no ambiente, ele produzirá algo como:

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

Múltiplos nomes de section separados por vírgula podem ser especificados na variável de ambiente NODE_DEBUG: NODE_DEBUG=fs,net,tls.

O argumento callback opcional pode ser usado para substituir a função de registro por uma função diferente que não tenha nenhuma inicialização ou encapsulamento desnecessário.

js
const util = require('node:util')
let debuglog = util.debuglog('internals', debug => {
  // Substitua por uma função de registro que otimiza a
  // verificação se a seção está habilitada
  debuglog = debug
})

debuglog().enabled ​

Adicionado em: v14.9.0

O getter util.debuglog().enabled é usado para criar um teste que pode ser usado em condicionais com base na existência da variável de ambiente NODE_DEBUG. Se o nome da section aparecer no valor dessa variável de ambiente, o valor retornado será true. Caso contrário, o valor retornado será false.

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

Se este programa for executado com NODE_DEBUG=foo no ambiente, ele produzirá algo como:

bash
hello from foo [123]

util.debug(section) ​

Adicionado em: v14.9.0

Alias para util.debuglog. O uso permite a legibilidade que não implica em log quando apenas util.debuglog().enabled é usado.

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

[Histórico]

VersãoAlterações
v10.0.0Os avisos de depreciação são emitidos apenas uma vez para cada código.
v0.8.0Adicionada em: v0.8.0
  • fn <Function> A função que está sendo depreciada.
  • msg <string> Uma mensagem de aviso a ser exibida quando a função depreciada for invocada.
  • code <string> Um código de depreciação. Veja a lista de APIs depreciadas para uma lista de códigos.
  • Retorna: <Function> A função depreciada encapsulada para emitir um aviso.

O método util.deprecate() encapsula fn (que pode ser uma função ou classe) de forma que seja marcado como depreciado.

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

exports.obsoleteFunction = util.deprecate(() => {
  // Faça algo aqui.
}, 'obsoleteFunction() está depreciada. Use newShinyFunction() em vez disso.')

Quando chamado, util.deprecate() retornará uma função que emitirá um DeprecationWarning usando o evento 'warning'. O aviso será emitido e impresso em stderr na primeira vez que a função retornada for chamada. Após o aviso ser emitido, a função encapsulada é chamada sem emitir um aviso.

Se o mesmo code opcional for fornecido em várias chamadas a util.deprecate(), o aviso será emitido apenas uma vez para esse code.

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

const fn1 = util.deprecate(someFunction, someMessage, 'DEP0001')
const fn2 = util.deprecate(someOtherFunction, someOtherMessage, 'DEP0001')
fn1() // Emite um aviso de depreciação com o código DEP0001
fn2() // Não emite um aviso de depreciação porque tem o mesmo código

Se as bandeiras de linha de comando --no-deprecation ou --no-warnings forem usadas, ou se a propriedade process.noDeprecation for definida como true antes do primeiro aviso de depreciação, o método util.deprecate() não fará nada.

Se as bandeiras de linha de comando --trace-deprecation ou --trace-warnings estiverem definidas, ou se a propriedade process.traceDeprecation estiver definida como true, um aviso e um rastreamento de pilha serão impressos em stderr na primeira vez que a função depreciada for chamada.

Se a bandeira de linha de comando --throw-deprecation estiver definida, ou se a propriedade process.throwDeprecation estiver definida como true, uma exceção será lançada quando a função depreciada for chamada.

A bandeira de linha de comando --throw-deprecation e a propriedade process.throwDeprecation têm precedência sobre --trace-deprecation e process.traceDeprecation.

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

[Histórico]

VersãoAlterações
v12.11.0O especificador %c agora é ignorado.
v12.0.0O argumento format agora só é considerado como tal se realmente contiver especificadores de formato.
v12.0.0Se o argumento format não for uma string de formato, a formatação da string de saída não dependerá mais do tipo do primeiro argumento. Essa alteração remove as aspas anteriormente presentes em strings que estavam sendo exibidas quando o primeiro argumento não era uma string.
v11.4.0Os especificadores %d, %f e %i agora suportam corretamente Símbolos.
v11.4.0A profundidade (depth) do especificador %o tem novamente a profundidade padrão de 4.
v11.0.0A opção de profundidade (depth) do especificador %o agora retornará à profundidade padrão.
v10.12.0Os especificadores %d e %i agora suportam BigInt.
v8.4.0Os especificadores %o e %O agora são suportados.
v0.5.3Adicionado em: v0.5.3
  • format <string> Uma string de formato semelhante a printf.

O método util.format() retorna uma string formatada usando o primeiro argumento como uma string de formato semelhante a printf, que pode conter zero ou mais especificadores de formato. Cada especificador é substituído pelo valor convertido do argumento correspondente. Os especificadores suportados são:

  • %s: String será usado para converter todos os valores, exceto BigInt, Object e -0. Valores BigInt serão representados com um n e Objetos que não têm uma função toString definida pelo usuário são inspecionados usando util.inspect() com as opções { depth: 0, colors: false, compact: 3 }.
  • %d: Number será usado para converter todos os valores, exceto BigInt e Symbol.
  • %i: parseInt(value, 10) é usado para todos os valores, exceto BigInt e Symbol.
  • %f: parseFloat(value) é usado para todos os valores, exceto Symbol.
  • %j: JSON. Substituído pela string '[Circular]' se o argumento contiver referências circulares.
  • %o: Object. Uma representação em string de um objeto com formatação de objeto JavaScript genérica. Semelhante a util.inspect() com as opções { showHidden: true, showProxy: true }. Isso mostrará o objeto completo, incluindo propriedades não enumeráveis e proxies.
  • %O: Object. Uma representação em string de um objeto com formatação de objeto JavaScript genérica. Semelhante a util.inspect() sem opções. Isso mostrará o objeto completo, não incluindo propriedades não enumeráveis e proxies.
  • %c: CSS. Este especificador é ignorado e pulará qualquer CSS passado.
  • %%: sinal de porcentagem único ('%'). Isso não consome um argumento.
  • Retorna: <string> A string formatada

Se um especificador não tiver um argumento correspondente, ele não será substituído:

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

Valores que não fazem parte da string de formato são formatados usando util.inspect() se seu tipo não for string.

Se houver mais argumentos passados para o método util.format() do que o número de especificadores, os argumentos extras são concatenados à string retornada, separados por espaços:

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

Se o primeiro argumento não contiver um especificador de formato válido, util.format() retorna uma string que é a concatenação de todos os argumentos separados por espaços:

js
util.format(1, 2, 3)
// Retorna: '1 2 3'

Se apenas um argumento for passado para util.format(), ele será retornado como está, sem nenhuma formatação:

js
util.format('%% %s')
// Retorna: '%% %s'

util.format() é um método síncrono que se destina a ser uma ferramenta de depuração. Alguns valores de entrada podem ter uma sobrecarga de desempenho significativa que pode bloquear o loop de eventos. Use esta função com cuidado e nunca em um caminho de código crítico.

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

Adicionado em: v10.0.0

Esta função é idêntica à util.format(), exceto que recebe um argumento inspectOptions que especifica opções que são passadas para util.inspect().

js
util.formatWithOptions({ colors: true }, 'See object %O', { foo: 42 })
// Retorna 'See object { foo: 42 }', onde `42` é colorido como um número
// quando impresso em um terminal.

util.getCallSites(frameCountOrOptions, [options]) ​

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1.1 - Desenvolvimento ativo

[Histórico]

VersãoAlterações
v23.3.0A API foi renomeada de util.getCallSite para util.getCallSites().
v22.9.0Adicionada em: v22.9.0

  • frameCount <number> Número opcional de frames para capturar como objetos de local de chamada. Padrão: 10. A faixa permitida está entre 1 e 200.

  • options <Object> Opcional

    • sourceMap <boolean> Reconstrua o local original no rastreamento de pilha a partir do mapa de origem. Ativado por padrão com a flag --enable-source-maps.

  • Retorna: <Object[]> Uma matriz de objetos de local de chamada

    • functionName <string> Retorna o nome da função associada a este local de chamada.
    • scriptName <string> Retorna o nome do recurso que contém o script para a função deste local de chamada.
    • lineNumber <number> Retorna o número, baseado em 1, da linha para a chamada da função associada.
    • column <number> Retorna o deslocamento da coluna baseado em 1 na linha para a chamada da função associada.

Retorna uma matriz de objetos de local de chamada contendo a pilha da função de chamada.

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

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

  console.log('Locais de Chamada:')
  callSites.forEach((callSite, index) => {
    console.log(`Local de Chamada ${index + 1}:`)
    console.log(`Nome da Função: ${callSite.functionName}`)
    console.log(`Nome do Script: ${callSite.scriptName}`)
    console.log(`Número da Linha: ${callSite.lineNumber}`)
    console.log(`Número da Coluna: ${callSite.column}`)
  })
  // Local de Chamada 1:
  // Nome da Função: exampleFunction
  // Nome do Script: /home/example.js
  // Número da Linha: 5
  // Número da Coluna: 26

  // Local de Chamada 2:
  // Nome da Função: anotherFunction
  // Nome do Script: /home/example.js
  // Número da Linha: 22
  // Número da Coluna: 3

  // ...
}

// Uma função para simular outra camada de pilha
function anotherFunction() {
  exampleFunction()
}

anotherFunction()

É possível reconstruir os locais originais definindo a opção sourceMap como true. Se o mapa de origem não estiver disponível, o local original será o mesmo que o local atual. Quando a flag --enable-source-maps estiver ativada, por exemplo, ao usar --experimental-transform-types, sourceMap será true por padrão.

ts
import util from 'node:util'

interface Foo {
  foo: string
}

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

// Com sourceMap:
// Nome da Função: ''
// Nome do Script: example.js
// Número da Linha: 7
// Número da Coluna: 26

// Sem sourceMap:
// Nome da Função: ''
// Nome do Script: example.js
// Número da Linha: 2
// Número da Coluna: 26

util.getSystemErrorName(err) ​

Adicionado em: v9.7.0

Retorna o nome da string para um código de erro numérico que vem de uma API Node.js. O mapeamento entre códigos de erro e nomes de erro depende da plataforma. Veja Erros de Sistema Comuns para os nomes dos erros comuns.

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

util.getSystemErrorMap() ​

Adicionado em: v16.0.0, v14.17.0

Retorna um Map de todos os códigos de erro do sistema disponíveis na API Node.js. O mapeamento entre códigos de erro e nomes de erro depende da plataforma. Veja Erros de Sistema Comuns para os nomes dos erros comuns.

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

Adicionado em: v23.1.0

Retorna a mensagem de string para um código de erro numérico que vem de uma API Node.js. O mapeamento entre códigos de erro e mensagens de string depende da plataforma.

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

[Histórico]

VersãoAlterações
v5.0.0O parâmetro constructor agora pode referir-se a uma classe ES6.
v0.3.0Adicionada em: v0.3.0

[Estável: 3 - Legado]

Estável: 3 Estabilidade: 3 - Legado: Use a sintaxe de classe ES2015 e a palavra-chave extends em vez disso.

O uso de util.inherits() é desencorajado. Por favor, use as palavras-chave ES6 class e extends para obter suporte de herança em nível de linguagem. Observe também que os dois estilos são semanticamente incompatíveis.

Herda os métodos de protótipo de um construtor para outro. O protótipo de constructor será definido como um novo objeto criado a partir de superConstructor.

Isso adiciona principalmente alguma validação de entrada em cima de Object.setPrototypeOf(constructor.prototype, superConstructor.prototype). Como uma conveniência adicional, superConstructor estará acessível através da propriedade 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(`Received data: "${data}"`)
})
stream.write('It works!') // Received data: "It works!"

Exemplo ES6 usando class e 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(`Received data: "${data}"`)
})
stream.write('With ES6')

util.inspect(object[, options]) ​

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

[Histórico]

VersãoAlterações
v16.18.0Adiciona suporte para maxArrayLength ao inspecionar Set e Map.
v17.3.0, v16.14.0A opção numericSeparator agora é suportada.
v13.0.0Referências circulares agora incluem um marcador para a referência.
v14.6.0, v12.19.0Se object for de um vm.Context diferente agora, uma função de inspeção personalizada nele não receberá mais argumentos específicos do contexto.
v13.13.0, v12.17.0A opção maxStringLength agora é suportada.
v13.5.0, v12.16.0Propriedades de protótipo definidas pelo usuário são inspecionadas caso showHidden seja true.
v12.0.0O padrão das opções compact foi alterado para 3 e o padrão das opções breakLength foi alterado para 80.
v12.0.0Propriedades internas não aparecem mais no argumento de contexto de uma função de inspeção personalizada.
v11.11.0A opção compact aceita números para um novo modo de saída.
v11.7.0ArrayBuffers agora também mostram seus conteúdos binários.
v11.5.0A opção getters agora é suportada.
v11.4.0O padrão de depth voltou para 2.
v11.0.0O padrão de depth mudou para 20.
v11.0.0A saída de inspeção agora é limitada a cerca de 128 MiB. Dados acima desse tamanho não serão totalmente inspecionados.
v10.12.0A opção sorted agora é suportada.
v10.6.0Inspecionar listas ligadas e objetos semelhantes agora é possível até o tamanho máximo da pilha de chamadas.
v10.0.0As entradas WeakMap e WeakSet agora também podem ser inspecionadas.
v9.9.0A opção compact agora é suportada.
v6.6.0Funções de inspeção personalizadas agora podem retornar this.
v6.3.0A opção breakLength agora é suportada.
v6.1.0A opção maxArrayLength agora é suportada; em particular, matrizes longas são truncadas por padrão.
v6.1.0A opção showProxy agora é suportada.
v0.3.0Adicionada em: v0.3.0

  • object <qualquer> Qualquer primitivo JavaScript ou Object.

  • options <Object>

    • showHidden <boolean> Se true, os símbolos e propriedades não enumeráveis de object são incluídos no resultado formatado. Entradas WeakMap e WeakSet também são incluídas, assim como propriedades de protótipo definidas pelo usuário (excluindo propriedades de método). Padrão: false.
    • depth <number> Especifica o número de vezes para recursar enquanto formata object. Isso é útil para inspecionar objetos grandes. Para recursar até o tamanho máximo da pilha de chamadas, passe Infinity ou null. Padrão: 2.
    • colors <boolean> Se true, a saída é estilizada com códigos de cores ANSI. As cores são personalizáveis. Veja Personalizando cores util.inspect. Padrão: false.
    • customInspect <boolean> Se false, as funções [util.inspect.custom](depth, opts, inspect) não são invocadas. Padrão: true.
    • showProxy <boolean> Se true, a inspeção Proxy inclui os objetos target e handler. Padrão: false.
    • maxArrayLength <inteiro> Especifica o número máximo de elementos Array, TypedArray, Map, Set, WeakMap e WeakSet a incluir ao formatar. Defina como null ou Infinity para mostrar todos os elementos. Defina como 0 ou negativo para não mostrar elementos. Padrão: 100.
    • maxStringLength <inteiro> Especifica o número máximo de caracteres a incluir ao formatar. Defina como null ou Infinity para mostrar todos os elementos. Defina como 0 ou negativo para não mostrar caracteres. Padrão: 10000.
    • breakLength <inteiro> O comprimento em que os valores de entrada são divididos em várias linhas. Defina como Infinity para formatar a entrada como uma única linha (em combinação com compact definido como true ou qualquer número >= 1). Padrão: 80.
    • compact <boolean> | <inteiro> Definir isso como false faz com que cada chave de objeto seja exibida em uma nova linha. Ele quebrará em novas linhas em texto que seja mais longo que breakLength. Se definido como um número, os n elementos internos mais internos são unidos em uma única linha, desde que todas as propriedades caibam em breakLength. Elementos de matriz curtos também são agrupados. Para mais informações, veja o exemplo abaixo. Padrão: 3.
    • sorted <boolean> | <Function> Se definido como true ou uma função, todas as propriedades de um objeto e as entradas Set e Map são classificadas na string resultante. Se definido como true, a classificação padrão é usada. Se definido como uma função, ela é usada como uma função de comparação.
    • getters <boolean> | <string> Se definido como true, os getters são inspecionados. Se definido como 'get', apenas os getters sem um setter correspondente são inspecionados. Se definido como 'set', apenas os getters com um setter correspondente são inspecionados. Isso pode causar efeitos colaterais dependendo da função getter. Padrão: false.
    • numericSeparator <boolean> Se definido como true, um sublinhado é usado para separar a cada três dígitos em todos os bigints e números. Padrão: false.

  • Retorna: <string> A representação de object.

O método util.inspect() retorna uma representação de string de object que se destina à depuração. A saída de util.inspect pode mudar a qualquer momento e não deve ser dependida programaticamente. Opções adicionais podem ser passadas que alteram o resultado. util.inspect() usará o nome do construtor e/ou @@toStringTag para criar uma tag identificável para um valor inspecionado.

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

Referências circulares apontam para sua âncora usando um índice de referência:

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] }
// }

O exemplo a seguir inspeciona todas as propriedades do objeto util:

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

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

O exemplo a seguir destaca o efeito da opção 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 [...]', // A long line
//           'test',
//           'foo' ] ],
//     4 ],
//   b: Map(2) { 'za' => 1, 'zb' => 'test' } }

// Definindo `compact` como false ou um inteiro cria uma saída mais amigável ao leitor.
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'
//   }
// }

// Definir `breakLength` como, por exemplo, 150 imprimirá o texto "Lorem ipsum" em uma
// única linha.

A opção showHidden permite que as entradas WeakMap e WeakSet sejam inspecionadas. Se houver mais entradas do que maxArrayLength, não há garantia de quais entradas serão exibidas. Isso significa que recuperar as mesmas entradas WeakSet duas vezes pode resultar em uma saída diferente. Além disso, entradas sem referências fortes restantes podem ser coletadas pelo garbage collector a qualquer momento.

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 } }

A opção sorted garante que a ordem de inserção de propriedades de um objeto não afete o resultado de 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 }))

A opção numericSeparator adiciona um sublinhado a cada três dígitos para todos os números.

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() é um método síncrono destinado à depuração. Seu comprimento de saída máximo é aproximadamente 128 MiB. Entradas que resultam em uma saída mais longa serão truncadas.

Personalizando as cores do util.inspect ​

A saída colorida (se habilitada) do util.inspect é personalizável globalmente através das propriedades util.inspect.styles e util.inspect.colors.

util.inspect.styles é um mapa associando um nome de estilo a uma cor de util.inspect.colors.

Os estilos padrão e as cores associadas são:

  • bigint: yellow
  • boolean: yellow
  • date: magenta
  • module: underline
  • name: (sem estilo)
  • null: bold
  • number: yellow
  • regexp: red
  • special: cyan (ex: Proxies)
  • string: green
  • symbol: green
  • undefined: grey

O estilo de cor usa códigos de controle ANSI que podem não ser suportados em todos os terminais. Para verificar o suporte de cor, use tty.hasColors().

Os códigos de controle predefinidos são listados abaixo (agrupados como "Modificadores", "Cores de primeiro plano" e "Cores de fundo").

Modificadores ​

O suporte a modificadores varia entre diferentes terminais. Eles serão principalmente ignorados, se não suportados.

  • reset - Redefine todos os modificadores (de cor) para seus padrões
  • bold - Deixa o texto em negrito
  • italic - Deixa o texto em itálico
  • underline - Sublinha o texto
  • strikethrough - Coloca uma linha horizontal no centro do texto (Alias: strikeThrough, crossedout, crossedOut)
  • hidden - Imprime o texto, mas o torna invisível (Alias: conceal)
  • dim - Diminui a intensidade da cor (Alias: faint)
  • overlined - Faz o texto ficar sobrelinhado
  • blink - Esconde e mostra o texto em um intervalo
  • inverse - Troca as cores de primeiro plano e de fundo (Alias: swapcolors, swapColors)
  • doubleunderline - Sublinha o texto duas vezes (Alias: doubleUnderline)
  • framed - Desenha uma moldura em torno do texto

Cores de primeiro plano ​

  • black
  • red
  • green
  • yellow
  • blue
  • magenta
  • cyan
  • white
  • gray (alias: grey, blackBright)
  • redBright
  • greenBright
  • yellowBright
  • blueBright
  • magentaBright
  • cyanBright
  • whiteBright

Cores de fundo ​

  • bgBlack
  • bgRed
  • bgGreen
  • bgYellow
  • bgBlue
  • bgMagenta
  • bgCyan
  • bgWhite
  • bgGray (alias: bgGrey, bgBlackBright)
  • bgRedBright
  • bgGreenBright
  • bgYellowBright
  • bgBlueBright
  • bgMagentaBright
  • bgCyanBright
  • bgWhiteBright

Funções de inspeção personalizadas em objetos ​

[Histórico]

VersãoAlterações
v17.3.0, v16.14.0O argumento inspect foi adicionado para maior interoperabilidade.
v0.1.97Adicionado em: v0.1.97

Os objetos também podem definir sua própria função [util.inspect.custom](depth, opts, inspect), que util.inspect() invocará e usará o resultado ao inspecionar o objeto.

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,
    })

    // Preenchimento de cinco espaços porque esse é o tamanho de "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)
// Retorna: "Box< true >"

As funções [util.inspect.custom](depth, opts, inspect) personalizadas geralmente retornam uma string, mas podem retornar um valor de qualquer tipo que será formatado de acordo com 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)
// Retorna: "{ bar: 'baz' }"

util.inspect.custom ​

[Histórico]

VersãoAlterações
v10.12.0Isso agora é definido como um símbolo compartilhado.
v6.6.0Adicionado em: v6.6.0
  • <symbol> que pode ser usado para declarar funções de inspeção personalizadas.

Além de ser acessível através de util.inspect.custom, este símbolo está registrado globalmente e pode ser acessado em qualquer ambiente como Symbol.for('nodejs.util.inspect.custom').

O uso disso permite que o código seja escrito de forma portátil, de modo que a função de inspeção personalizada seja usada em um ambiente Node.js e ignorada no navegador. A própria função util.inspect() é passada como terceiro argumento para a função de inspeção personalizada para permitir maior portabilidade.

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)
// Imprime Password <xxxxxxxx>

Veja Funções de inspeção personalizadas em objetos para mais detalhes.

util.inspect.defaultOptions ​

Adicionado em: v6.4.0

O valor defaultOptions permite a personalização das opções padrão usadas por util.inspect. Isso é útil para funções como console.log ou util.format que implicitamente chamam util.inspect. Deve ser definido como um objeto contendo uma ou mais opções válidas util.inspect(). A definição de propriedades de opção diretamente também é suportada.

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

console.log(arr) // Registra o array truncado
util.inspect.defaultOptions.maxArrayLength = null
console.log(arr) // Registra o array completo

util.isDeepStrictEqual(val1, val2) ​

Adicionado em: v9.0.0

Retorna true se houver igualdade estrita profunda entre val1 e val2. Caso contrário, retorna false.

Veja assert.deepStrictEqual() para mais informações sobre igualdade estrita profunda.

Classe: util.MIMEType ​

Adicionado em: v19.1.0, v18.13.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

Uma implementação da classe MIMEType.

De acordo com as convenções do navegador, todas as propriedades dos objetos MIMEType são implementadas como getters e setters no protótipo da classe, em vez de como propriedades de dados no próprio objeto.

Uma string MIME é uma string estruturada contendo vários componentes significativos. Quando analisada, um objeto MIMEType é retornado contendo propriedades para cada um desses componentes.

Construtor: new MIMEType(input) ​

  • input <string> O MIME de entrada para análise

Cria um novo objeto MIMEType analisando a 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')

Um TypeError será lançado se a input não for um MIME válido. Observe que será feito um esforço para converter os valores fornecidos em strings. Por exemplo:

js
import { MIMEType } from 'node:util'
const myMIME = new MIMEType({ toString: () => 'text/plain' })
console.log(String(myMIME))
// Imprime: text/plain
js
const { MIMEType } = require('node:util')
const myMIME = new MIMEType({ toString: () => 'text/plain' })
console.log(String(myMIME))
// Imprime: text/plain

mime.type ​

Obtém e define a parte do tipo do MIME.

js
import { MIMEType } from 'node:util'

const myMIME = new MIMEType('text/javascript')
console.log(myMIME.type)
// Imprime: text
myMIME.type = 'application'
console.log(myMIME.type)
// Imprime: application
console.log(String(myMIME))
// Imprime: application/javascript
js
const { MIMEType } = require('node:util')

const myMIME = new MIMEType('text/javascript')
console.log(myMIME.type)
// Imprime: text
myMIME.type = 'application'
console.log(myMIME.type)
// Imprime: application
console.log(String(myMIME))
// Imprime: application/javascript

mime.subtype ​

Obtém e define a parte do subtipo do MIME.

js
import { MIMEType } from 'node:util'

const myMIME = new MIMEType('text/ecmascript')
console.log(myMIME.subtype)
// Imprime: ecmascript
myMIME.subtype = 'javascript'
console.log(myMIME.subtype)
// Imprime: javascript
console.log(String(myMIME))
// Imprime: text/javascript
js
const { MIMEType } = require('node:util')

const myMIME = new MIMEType('text/ecmascript')
console.log(myMIME.subtype)
// Imprime: ecmascript
myMIME.subtype = 'javascript'
console.log(myMIME.subtype)
// Imprime: javascript
console.log(String(myMIME))
// Imprime: text/javascript

mime.essence ​

Obtém a essência do MIME. Esta propriedade é somente leitura. Use mime.type ou mime.subtype para alterar o MIME.

js
import { MIMEType } from 'node:util'

const myMIME = new MIMEType('text/javascript;key=value')
console.log(myMIME.essence)
// Imprime: text/javascript
myMIME.type = 'application'
console.log(myMIME.essence)
// Imprime: application/javascript
console.log(String(myMIME))
// Imprime: application/javascript;key=value
js
const { MIMEType } = require('node:util')

const myMIME = new MIMEType('text/javascript;key=value')
console.log(myMIME.essence)
// Imprime: text/javascript
myMIME.type = 'application'
console.log(myMIME.essence)
// Imprime: application/javascript
console.log(String(myMIME))
// Imprime: application/javascript;key=value

mime.params ​

Obtém o objeto MIMEParams que representa os parâmetros do MIME. Esta propriedade é somente leitura. Consulte a documentação MIMEParams para obter detalhes.

mime.toString() ​

O método toString() no objeto MIMEType retorna o MIME serializado.

Devido à necessidade de conformidade com os padrões, este método não permite que os usuários personalizem o processo de serialização do MIME.

mime.toJSON() ​

Alias para mime.toString().

Este método é chamado automaticamente quando um objeto MIMEType é serializado com JSON.stringify().

js
import { MIMEType } from 'node:util'

const myMIMES = [new MIMEType('image/png'), new MIMEType('image/gif')]
console.log(JSON.stringify(myMIMES))
// Imprime: ["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))
// Imprime: ["image/png", "image/gif"]

Classe: util.MIMEParams ​

Adicionado em: v19.1.0, v18.13.0

A API MIMEParams fornece acesso de leitura e gravação aos parâmetros de um MIMEType.

Construtor: new MIMEParams() ​

Cria um novo objeto MIMEParams com parâmetros vazios.

js
import { MIMEParams } from 'node:util'

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

const myParams = new MIMEParams()

mimeParams.delete(name) ​

Remove todos os pares nome-valor cujo nome é name.

mimeParams.entries() ​

Retorna um iterador sobre cada um dos pares nome-valor nos parâmetros. Cada item do iterador é um Array JavaScript. O primeiro item do array é o nome, o segundo item do array é o valor.

mimeParams.get(name) ​

  • name <string>
  • Retorna: <string> | <null> Uma string ou null se não houver nenhum par nome-valor com o name fornecido.

Retorna o valor do primeiro par nome-valor cujo nome é name. Se não houver tais pares, null é retornado.

mimeParams.has(name) ​

Retorna true se houver pelo menos um par nome-valor cujo nome é name.

mimeParams.keys() ​

Retorna um iterador sobre os nomes de cada par nome-valor.

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)
}
// Imprime:
//   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)
}
// Imprime:
//   foo
//   bar

mimeParams.set(name, value) ​

Define o valor no objeto MIMEParams associado a name para value. Se houver algum par nome-valor preexistente cujos nomes sejam name, define o valor do primeiro par como 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())
// Imprime: 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())
// Imprime: foo=def;bar=1;baz=xyz

mimeParams.values() ​

Retorna um iterador sobre os valores de cada par nome-valor.

mimeParams[@@iterator]() ​

Alias para 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)
}
// Imprime:
//   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)
}
// Imprime:
//   foo bar
//   xyz baz

util.parseArgs([config]) ​

[Histórico]

VersãoAlterações
v22.4.0, v20.16.0Adiciona suporte para permitir opções negativas na entrada config.
v20.0.0A API não é mais experimental.
v18.11.0, v16.19.0Adiciona suporte para valores padrão na entrada config.
v18.7.0, v16.17.0Adiciona suporte para retornar informações detalhadas de análise usando tokens na entrada config e propriedades retornadas.
v18.3.0, v16.17.0Adicionado em: v18.3.0, v16.17.0

  • config <Object> Usado para fornecer argumentos para análise e configurar o analisador. config suporta as seguintes propriedades:

    • args <string[]> array de strings de argumento. Padrão: process.argv com execPath e filename removidos.

    • options <Object> Usado para descrever argumentos conhecidos pelo analisador. As chaves de options são os nomes longos das opções e os valores são um <Object> que aceita as seguintes propriedades:

    • type <string> Tipo de argumento, que deve ser boolean ou string.

    • multiple <boolean> Se esta opção pode ser fornecida várias vezes. Se true, todos os valores serão coletados em um array. Se false, os valores para a opção são os últimos a vencerem. Padrão: false.

    • short <string> Um alias de caractere único para a opção.

    • default <string> | <boolean> | <string[]> | <boolean[]> O valor padrão da opção quando não definido por args. Deve ser do mesmo tipo que a propriedade type. Quando multiple é true, deve ser um array.

    • strict <boolean> Um erro deve ser lançado quando argumentos desconhecidos são encontrados ou quando argumentos são passados que não correspondem ao type configurado em options. Padrão: true.

    • allowPositionals <boolean> Se este comando aceita argumentos posicionais. Padrão: false se strict for true, caso contrário true.

    • allowNegative <boolean> Se true, permite definir explicitamente opções booleanas como false prefixando o nome da opção com --no-. Padrão: false.

    • tokens <boolean> Retorna os tokens analisados. Isso é útil para estender o comportamento interno, desde adicionar verificações adicionais até reprocessar os tokens de diferentes maneiras. Padrão: false.

  • Retorna: <Object> Os argumentos de linha de comando analisados:

Fornece uma API de nível superior para análise de argumentos de linha de comando do que interagir com process.argv diretamente. Recebe uma especificação para os argumentos esperados e retorna um objeto estruturado com as opções e posicionais analisados.

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)
// Imprime: [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)
// Imprime: [Object: null prototype] { foo: true, bar: 'b' } []

parseArgs tokens ​

Informações detalhadas de análise estão disponíveis para adicionar comportamentos personalizados especificando tokens: true na configuração. Os tokens retornados possuem propriedades que descrevem:

  • todos os tokens

    • kind <string> Um de 'option', 'positional', ou 'option-terminator'.
    • index <number> Índice do elemento em args contendo o token. Portanto, o argumento de origem para um token é args[token.index].

  • tokens de opção

    • name <string> Nome longo da opção.
    • rawName <string> Como a opção é usada em args, como -f de --foo.
    • value <string> | <undefined> Valor da opção especificado em args. Indefinido para opções booleanas.
    • inlineValue <boolean> | <undefined> Se o valor da opção foi especificado em linha, como --foo=bar.

  • tokens posicionais

    • value <string> O valor do argumento posicional em args (ou seja, args[index]).

  • token option-terminator

Os tokens retornados estão na ordem em que foram encontrados nos argumentos de entrada. Opções que aparecem mais de uma vez em args produzem um token para cada uso. Grupos de opções curtas como -xy expandem para um token para cada opção. Assim, -xxx produz três tokens.

Por exemplo, para adicionar suporte a uma opção negada como --no-color (que allowNegative suporta quando a opção é do tipo boolean), os tokens retornados podem ser reprocessados para alterar o valor armazenado para a opção negada.

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

// Reprocessa os tokens de opção e sobrescreve os valores retornados.
tokens
  .filter(token => token.kind === 'option')
  .forEach(token => {
    if (token.name.startsWith('no-')) {
      // Armazena foo:false para --no-foo
      const positiveName = token.name.slice(3)
      values[positiveName] = false
      delete values[token.name]
    } else {
      // Salva novamente o valor para que o último ganhe se ambos --foo e --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 })

// Reprocessa os tokens de opção e sobrescreve os valores retornados.
tokens
  .filter(token => token.kind === 'option')
  .forEach(token => {
    if (token.name.startsWith('no-')) {
      // Armazena foo:false para --no-foo
      const positiveName = token.name.slice(3)
      values[positiveName] = false
      delete values[token.name]
    } else {
      // Salva novamente o valor para que o último ganhe se ambos --foo e --no-foo.
      values[token.name] = token.value ?? true
    }
  })

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

console.log({ logfile, color })

Exemplo de uso mostrando opções negadas, e quando uma opção é usada de várias maneiras, a última ganha.

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

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1.1 - Desenvolvimento ativo

Adicionado em: v21.7.0, v20.12.0

O conteúdo bruto de um arquivo .env.

Dado um exemplo de arquivo .env:

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

parseEnv('HELLO=world\nHELLO=oh my\n')
// Retorna: { HELLO: 'oh my' }
js
import { parseEnv } from 'node:util'

parseEnv('HELLO=world\nHELLO=oh my\n')
// Retorna: { HELLO: 'oh my' }

util.promisify(original) ​

[Histórico]

VersãoAlterações
v20.8.0Chamar promisify em uma função que retorna uma Promise está depreciado.
v8.0.0Adicionada em: v8.0.0

Recebe uma função seguindo o estilo comum de callback com erro em primeiro lugar, ou seja, recebendo um callback (err, value) =\> ... como último argumento, e retorna uma versão que retorna promises.

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

const stat = util.promisify(fs.stat)
stat('.')
  .then(stats => {
    // Faça algo com `stats`
  })
  .catch(error => {
    // Lidar com o erro.
  })

Ou, equivalentemente usando async functions:

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(`Este diretório é de propriedade de ${stats.uid}`)
}

callStat()

Se houver uma propriedade original[util.promisify.custom] presente, promisify retornará seu valor, veja Funções promissified personalizadas.

promisify() assume que original é uma função que recebe um callback como seu último argumento em todos os casos. Se original não for uma função, promisify() lançará um erro. Se original for uma função, mas seu último argumento não for um callback com erro em primeiro lugar, ainda será passado um callback com erro em primeiro lugar como seu último argumento.

Usar promisify() em métodos de classe ou outros métodos que usam this pode não funcionar como esperado a menos que seja tratado especialmente:

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'

Funções promissificadas personalizadas ​

Usando o símbolo util.promisify.custom, pode-se substituir o valor retornado por 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])
// imprime 'true'

Isso pode ser útil em casos onde a função original não segue o formato padrão de receber um callback de erro como último argumento.

Por exemplo, com uma função que recebe (foo, onSuccessCallback, onErrorCallback):

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

Se promisify.custom estiver definido, mas não for uma função, promisify() lançará um erro.

util.promisify.custom ​

[Histórico]

VersãoAlterações
v13.12.0, v12.16.2Agora definido como um símbolo compartilhado.
v8.0.0Adicionado em: v8.0.0

Além de ser acessível através de util.promisify.custom, este símbolo está registrado globalmente e pode ser acessado em qualquer ambiente como Symbol.for('nodejs.util.promisify.custom').

Por exemplo, com uma função que recebe (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) ​

Adicionado em: v16.11.0

Retorna str com quaisquer códigos de escape ANSI removidos.

js
console.log(util.stripVTControlCharacters('\u001B[4mvalue\u001B[0m'))
// Imprime "value"

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

[Estável: 2 - Estável]

Estável: 2 Estabilidade: 2 - Estável.

[Histórico]

VersãoAlterações
v23.5.0styleText agora está estável.
v22.8.0, v20.18.0Respeita isTTY e variáveis de ambiente como NO_COLORS, NODE_DISABLE_COLORS e FORCE_COLOR.
v21.7.0, v20.12.0Adicionada em: v21.7.0, v20.12.0
  • format <string> | <Array> Um formato de texto ou um Array de formatos de texto definidos em util.inspect.colors.
  • text <string> O texto a ser formatado.
  • options <Object>
    • validateStream <boolean> Quando verdadeiro, stream é verificado para ver se ele pode lidar com cores. Padrão: true.
    • stream <Stream> Um fluxo que será validado se puder ser colorido. Padrão: process.stdout.

Esta função retorna um texto formatado considerando o format passado para impressão em um terminal. Ela está ciente das capacidades do terminal e age de acordo com a configuração definida pelas variáveis de ambiente NO_COLORS, NODE_DISABLE_COLORS e 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!',
  // Validar se process.stderr tem 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!',
  // Validar se process.stderr tem TTY
  { stream: stderr }
)
console.error(successMessage)

util.inspect.colors também fornece formatos de texto como italic e underline e você pode combinar ambos:

js
console.log(util.styleText(['underline', 'italic'], 'Minha mensagem itálica sublinhada'))

Ao passar um array de formatos, a ordem do formato aplicado é da esquerda para a direita, portanto, o estilo seguinte pode sobrescrever o anterior.

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

A lista completa de formatos pode ser encontrada em modificadores.

Classe: util.TextDecoder ​

[Histórico]

VersãoAlterações
v11.0.0A classe agora está disponível no objeto global.
v8.3.0Adicionada em: v8.3.0

Uma implementação da API TextDecoder do Padrão de Codificação WHATWG.

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

Codificações suportadas pelo WHATWG ​

Conforme o Padrão de Codificação WHATWG, as codificações suportadas pela API TextDecoder são descritas nas tabelas abaixo. Para cada codificação, um ou mais aliases podem ser usados.

Diferentes configurações de compilação do Node.js suportam diferentes conjuntos de codificações. (veja Internacionalização)

Codificações suportadas por padrão (com dados ICU completos) ​

CodificaçãoAliases
'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'

Codificações suportadas quando o Node.js é construído com a opção small-icu ​

CodificaçãoApelidos
'utf-8''unicode-1-1-utf-8', 'utf8'
'utf-16le''utf-16'
'utf-16be'

Codificações suportadas quando o ICU está desabilitado ​

CodificaçãoApelidos
'utf-8''unicode-1-1-utf-8', 'utf8'
'utf-16le''utf-16'

A codificação 'iso-8859-16' listada no Padrão de Codificação WHATWG não é suportada.

new TextDecoder([encoding[, options]]) ​

  • encoding <string> Identifica a codificação que esta instância TextDecoder suporta. Padrão: 'utf-8'.
  • options <Object>
    • fatal <boolean> true se falhas de decodificação são fatais. Esta opção não é suportada quando o ICU está desabilitado (veja Internacionalização). Padrão: false.
    • ignoreBOM <boolean> Quando true, o TextDecoder incluirá a marca de ordem de bytes no resultado decodificado. Quando false, a marca de ordem de bytes será removida da saída. Esta opção só é usada quando encoding é 'utf-8', 'utf-16be' ou 'utf-16le'. Padrão: false.

Cria uma nova instância TextDecoder. A codificação pode especificar uma das codificações suportadas ou um apelido.

A classe TextDecoder também está disponível no objeto global.

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

Decodifica a entrada e retorna uma string. Se options.stream for true, quaisquer sequências de bytes incompletas que ocorram no final da entrada serão armazenadas em buffer internamente e emitidas após a próxima chamada para textDecoder.decode().

Se textDecoder.fatal for true, erros de decodificação que ocorrerem resultarão em um TypeError sendo lançado.

textDecoder.encoding ​

A codificação suportada pela instância TextDecoder.

textDecoder.fatal ​

O valor será true se erros de decodificação resultarem em um erro TypeError sendo lançado.

textDecoder.ignoreBOM ​

O valor será true se o resultado da decodificação incluir a marca de ordem de bytes.

Classe: util.TextEncoder ​

[Histórico]

VersãoAlterações
v11.0.0A classe agora está disponível no objeto global.
v8.3.0Adicionada em: v8.3.0

Uma implementação da API TextEncoder do Padrão de Codificação WHATWG. Todas as instâncias de TextEncoder somente suportam codificação UTF-8.

js
const encoder = new TextEncoder()
const uint8array = encoder.encode('estes são alguns dados')

A classe TextEncoder também está disponível no objeto global.

textEncoder.encode([input]) ​

Codifica o texto de entrada em UTF-8 e retorna um Uint8Array contendo os bytes codificados.

textEncoder.encodeInto(src, dest) ​

Adicionado em: v12.11.0

  • src <string> O texto a ser codificado.
  • dest <Uint8Array> O array para armazenar o resultado da codificação.
  • Retorna: <Object>
    • read <number> As unidades de código Unicode lidas de src.
    • written <number> Os bytes UTF-8 escritos em dest.

Codifica a string src em UTF-8 para o dest Uint8Array e retorna um objeto contendo as unidades de código Unicode lidas e os bytes UTF-8 escritos.

js
const encoder = new TextEncoder()
const src = 'estes são alguns dados'
const dest = new Uint8Array(10)
const { read, written } = encoder.encodeInto(src, dest)

textEncoder.encoding ​

Codificação suportada pela instância TextEncoder. Sempre definida como 'utf-8'.

util.toUSVString(string) ​

Adicionado em: v16.8.0, v14.18.0

Retorna a string após substituir quaisquer pontos de código suplentes (ou, equivalentemente, quaisquer unidades de código suplentes não emparelhadas) pelo caractere de "substituição" Unicode U+FFFD.

util.transferableAbortController() ​

Adicionado em: v18.11.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

Cria e retorna uma instância <AbortController> cujo <AbortSignal> é marcado como transferível e pode ser usado com structuredClone() ou postMessage().

util.transferableAbortSignal(signal) ​

Adicionado em: v18.11.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

Marca o <AbortSignal> fornecido como transferível para que possa ser usado com structuredClone() e postMessage().

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

util.aborted(signal, resource) ​

Adicionado em: v19.7.0, v18.16.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

  • signal <AbortSignal>
  • resource <Object> Qualquer objeto não nulo vinculado à operação anulável e mantido fracamente. Se resource for coletado como lixo antes do signal ser abortado, a promise permanece pendente, permitindo que o Node.js pare de rastreá-la. Isso ajuda a evitar vazamentos de memória em operações de longa duração ou não anuláveis.
  • Retorna: <Promise>

Escuta o evento de aborto no signal fornecido e retorna uma promise que é resolvida quando o signal é abortado. Se resource for fornecido, ele referencia fracamente o objeto associado à operação, portanto, se resource for coletado como lixo antes do signal ser abortado, a promise retornada permanecerá pendente. Isso evita vazamentos de memória em operações de longa duração ou não anuláveis.

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

// Obtenha um objeto com um sinal anulável, como um recurso ou operação personalizado.
const dependent = obtainSomethingAbortable()

// Passe `dependent` como recurso, indicando que a promise só deve ser resolvida
// se `dependent` ainda estiver na memória quando o sinal for abortado.
aborted(dependent.signal, dependent).then(() => {
  // Este código é executado quando `dependent` é abortado.
  console.log('Recurso dependente foi abortado.')
})

// Simule um evento que aciona o aborto.
dependent.on('event', () => {
  dependent.abort() // Isso fará com que a promise `aborted` seja resolvida.
})
js
import { aborted } from 'node:util'

// Obtenha um objeto com um sinal anulável, como um recurso ou operação personalizado.
const dependent = obtainSomethingAbortable()

// Passe `dependent` como recurso, indicando que a promise só deve ser resolvida
// se `dependent` ainda estiver na memória quando o sinal for abortado.
aborted(dependent.signal, dependent).then(() => {
  // Este código é executado quando `dependent` é abortado.
  console.log('Recurso dependente foi abortado.')
})

// Simule um evento que aciona o aborto.
dependent.on('event', () => {
  dependent.abort() // Isso fará com que a promise `aborted` seja resolvida.
})

util.types ​

[Histórico]

VersãoAlterações
v15.3.0Exposto como require('util/types').
v10.0.0Adicionado em: v10.0.0

util.types fornece verificações de tipo para diferentes tipos de objetos integrados. Ao contrário de instanceof ou Object.prototype.toString.call(value), essas verificações não inspecionam as propriedades do objeto acessíveis a partir do JavaScript (como seu protótipo) e geralmente têm a sobrecarga de chamar o C++.

O resultado geralmente não oferece garantias sobre quais tipos de propriedades ou comportamento um valor expõe em JavaScript. Elas são principalmente úteis para desenvolvedores de addons que preferem fazer verificação de tipo em JavaScript.

A API é acessível via require('node:util').types ou require('node:util/types').

util.types.isAnyArrayBuffer(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for uma instância integrada de ArrayBuffer ou SharedArrayBuffer.

Veja também util.types.isArrayBuffer() e util.types.isSharedArrayBuffer().

js
util.types.isAnyArrayBuffer(new ArrayBuffer()) // Retorna true
util.types.isAnyArrayBuffer(new SharedArrayBuffer()) // Retorna true

util.types.isArrayBufferView(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for uma instância de uma das visualizações ArrayBuffer, como objetos de array tipados ou DataView. Equivalente a 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) ​

Adicionado em: v10.0.0

Retorna true se o valor for um objeto arguments.

js
function foo() {
  util.types.isArgumentsObject(arguments) // Retorna true
}

util.types.isArrayBuffer(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for uma instância ArrayBuffer integrada. Isso não inclui instâncias SharedArrayBuffer. Normalmente, é desejável testar ambos; veja util.types.isAnyArrayBuffer() para isso.

js
util.types.isArrayBuffer(new ArrayBuffer()) // Retorna true
util.types.isArrayBuffer(new SharedArrayBuffer()) // Retorna false

util.types.isAsyncFunction(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for uma função assíncrona. Isso apenas retorna o que o mecanismo JavaScript está vendo; em particular, o valor retornado pode não corresponder ao código-fonte original se uma ferramenta de transpilação foi usada.

js
util.types.isAsyncFunction(function foo() {}) // Retorna false
util.types.isAsyncFunction(async function foo() {}) // Retorna true

util.types.isBigInt64Array(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for uma instância de BigInt64Array.

js
util.types.isBigInt64Array(new BigInt64Array()) // Retorna true
util.types.isBigInt64Array(new BigUint64Array()) // Retorna false

util.types.isBigIntObject(value) ​

Adicionado em: v10.4.0

Retorna true se o valor for um objeto BigInt, por exemplo, criado por Object(BigInt(123)).

js
util.types.isBigIntObject(Object(BigInt(123))) // Retorna true
util.types.isBigIntObject(BigInt(123)) // Retorna false
util.types.isBigIntObject(123) // Retorna false

util.types.isBigUint64Array(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for uma instância de BigUint64Array.

js
util.types.isBigUint64Array(new BigInt64Array()) // Retorna false
util.types.isBigUint64Array(new BigUint64Array()) // Retorna true

util.types.isBooleanObject(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for um objeto booleano, por exemplo, criado por new Boolean().

js
util.types.isBooleanObject(false) // Retorna false
util.types.isBooleanObject(true) // Retorna false
util.types.isBooleanObject(new Boolean(false)) // Retorna true
util.types.isBooleanObject(new Boolean(true)) // Retorna true
util.types.isBooleanObject(Boolean(false)) // Retorna false
util.types.isBooleanObject(Boolean(true)) // Retorna false

util.types.isBoxedPrimitive(value) ​

Adicionado em: v10.11.0

Retorna true se o valor for qualquer objeto primitivo em caixa, por exemplo, criado por new Boolean(), new String() ou Object(Symbol()).

Por exemplo:

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

util.types.isCryptoKey(value) ​

Adicionado em: v16.2.0

Retorna true se value for um <CryptoKey>, false caso contrário.

util.types.isDataView(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for uma instância DataView integrada.

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

Veja também ArrayBuffer.isView().

util.types.isDate(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for uma instância Date integrada.

js
util.types.isDate(new Date()) // Retorna true

util.types.isExternal(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for um valor External nativo.

Um valor External nativo é um tipo especial de objeto que contém um ponteiro C++ bruto (void*) para acesso a partir do código nativo, e não possui outras propriedades. Esses objetos são criados pelos internos do Node.js ou por addons nativos. Em JavaScript, são objetos congelados com um protótipo 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) // retorna true
util.types.isExternal(0) // retorna false
util.types.isExternal(new String('foo')) // retorna false

Para mais informações sobre napi_create_external, consulte napi_create_external().

util.types.isFloat32Array(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for uma instância Float32Array integrada.

js
util.types.isFloat32Array(new ArrayBuffer()) // Retorna false
util.types.isFloat32Array(new Float32Array()) // Retorna true
util.types.isFloat32Array(new Float64Array()) // Retorna false

util.types.isFloat64Array(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for uma instância Float64Array integrada.

js
util.types.isFloat64Array(new ArrayBuffer()) // Retorna false
util.types.isFloat64Array(new Uint8Array()) // Retorna false
util.types.isFloat64Array(new Float64Array()) // Retorna true

util.types.isGeneratorFunction(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for uma função geradora. Isso apenas reporta o que o mecanismo JavaScript está vendo; em particular, o valor retornado pode não corresponder ao código-fonte original se uma ferramenta de transpilação foi usada.

js
util.types.isGeneratorFunction(function foo() {}) // Retorna false
util.types.isGeneratorFunction(function* foo() {}) // Retorna true

util.types.isGeneratorObject(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for um objeto gerador, como retornado de uma função geradora integrada. Isso apenas reporta o que o mecanismo JavaScript está vendo; em particular, o valor retornado pode não corresponder ao código-fonte original se uma ferramenta de transpilação foi usada.

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

util.types.isInt8Array(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for uma instância Int8Array integrada.

js
util.types.isInt8Array(new ArrayBuffer()) // Retorna false
util.types.isInt8Array(new Int8Array()) // Retorna true
util.types.isInt8Array(new Float64Array()) // Retorna false

util.types.isInt16Array(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for uma instância Int16Array built-in.

js
util.types.isInt16Array(new ArrayBuffer()) // Retorna false
util.types.isInt16Array(new Int16Array()) // Retorna true
util.types.isInt16Array(new Float64Array()) // Retorna false

util.types.isInt32Array(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for uma instância Int32Array built-in.

js
util.types.isInt32Array(new ArrayBuffer()) // Retorna false
util.types.isInt32Array(new Int32Array()) // Retorna true
util.types.isInt32Array(new Float64Array()) // Retorna false

util.types.isKeyObject(value) ​

Adicionado em: v16.2.0

Retorna true se value for um <KeyObject>, false caso contrário.

util.types.isMap(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for uma instância Map built-in.

js
util.types.isMap(new Map()) // Retorna true

util.types.isMapIterator(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for um iterador retornado para uma instância Map integrada.

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

util.types.isModuleNamespaceObject(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for uma instância de um Objeto de Espaço de Nome de Módulo.

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

util.types.isModuleNamespaceObject(ns) // Retorna true

util.types.isNativeError(value) ​

Adicionado em: v10.0.0

Retorna true se o valor foi retornado pelo construtor de um tipo Error integrado.

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

Subclasses dos tipos de erro nativos também são erros nativos:

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

Um valor sendo instanceof uma classe de erro nativa não é equivalente a isNativeError() retornando true para esse valor. isNativeError() retorna true para erros que vêm de um reino diferente, enquanto instanceof Error retorna false para esses erros:

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

Inversamente, isNativeError() retorna false para todos os objetos que não foram retornados pelo construtor de um erro nativo. Isso inclui valores que são instanceof erros nativos:

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

util.types.isNumberObject(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for um objeto número, por exemplo, criado por new Number().

js
util.types.isNumberObject(0) // Retorna false
util.types.isNumberObject(new Number(0)) // Retorna true

util.types.isPromise(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for uma Promise integrada.

js
util.types.isPromise(Promise.resolve(42)) // Retorna true

util.types.isProxy(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for uma instância Proxy.

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

util.types.isRegExp(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for um objeto de expressão regular.

js
util.types.isRegExp(/abc/) // Retorna true
util.types.isRegExp(new RegExp('abc')) // Retorna true

util.types.isSet(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for uma instância Set integrada.

js
util.types.isSet(new Set()) // Retorna true

util.types.isSetIterator(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for um iterador retornado para uma instância Set integrada.

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

util.types.isSharedArrayBuffer(value) ​

Adicionado em: v10.0.0

Retorna true se o valor for uma instância SharedArrayBuffer integrada. Isso não inclui instâncias ArrayBuffer. Normalmente, é desejável testar ambos; Veja util.types.isAnyArrayBuffer() para isso.

js
util.types.isSharedArrayBuffer(new ArrayBuffer()) // Retorna false
util.types.isSharedArrayBuffer(new SharedArrayBuffer()) // Retorna true

util.types.isStringObject(value) ​

Adicionado em: v10.0.0

Retorna true se o valor é um objeto string, por exemplo, criado por new String().

js
util.types.isStringObject('foo') // Retorna false
util.types.isStringObject(new String('foo')) // Retorna true

util.types.isSymbolObject(value) ​

Adicionado em: v10.0.0

Retorna true se o valor é um objeto símbolo, criado chamando Object() em um primitivo Symbol.

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

util.types.isTypedArray(value) ​

Adicionado em: v10.0.0

Retorna true se o valor é uma instância TypedArray integrada.

js
util.types.isTypedArray(new ArrayBuffer()) // Retorna false
util.types.isTypedArray(new Uint8Array()) // Retorna true
util.types.isTypedArray(new Float64Array()) // Retorna true

Veja também ArrayBuffer.isView().

util.types.isUint8Array(value) ​

Adicionado em: v10.0.0

Retorna true se o valor é uma instância Uint8Array integrada.

js
util.types.isUint8Array(new ArrayBuffer()) // Retorna false
util.types.isUint8Array(new Uint8Array()) // Retorna true
util.types.isUint8Array(new Float64Array()) // Retorna false

util.types.isUint8ClampedArray(value) ​

Adicionado em: v10.0.0

Retorna true se o valor é uma instância Uint8ClampedArray built-in.

js
util.types.isUint8ClampedArray(new ArrayBuffer()) // Retorna false
util.types.isUint8ClampedArray(new Uint8ClampedArray()) // Retorna true
util.types.isUint8ClampedArray(new Float64Array()) // Retorna false

util.types.isUint16Array(value) ​

Adicionado em: v10.0.0

Retorna true se o valor é uma instância Uint16Array built-in.

js
util.types.isUint16Array(new ArrayBuffer()) // Retorna false
util.types.isUint16Array(new Uint16Array()) // Retorna true
util.types.isUint16Array(new Float64Array()) // Retorna false

util.types.isUint32Array(value) ​

Adicionado em: v10.0.0

Retorna true se o valor é uma instância Uint32Array built-in.

js
util.types.isUint32Array(new ArrayBuffer()) // Retorna false
util.types.isUint32Array(new Uint32Array()) // Retorna true
util.types.isUint32Array(new Float64Array()) // Retorna false

util.types.isWeakMap(value) ​

Adicionado em: v10.0.0

Retorna true se o valor é uma instância WeakMap built-in.

js
util.types.isWeakMap(new WeakMap()) // Retorna true

util.types.isWeakSet(value) ​

Adicionado em: v10.0.0

Retorna true se o valor é uma instância WeakSet integrada.

js
util.types.isWeakSet(new WeakSet()) // Retorna true

APIs Obsoletas ​

As APIs a seguir estão obsoletas e não devem mais ser usadas. Aplicações e módulos existentes devem ser atualizados para encontrar abordagens alternativas.

util._extend(target, source) ​

Adicionado em: v0.7.5

Obsoleto desde: v6.0.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto: Use Object.assign() em vez disso.

O método util._extend() nunca teve a intenção de ser usado fora dos módulos internos do Node.js. A comunidade o encontrou e usou de qualquer maneira.

Ele está obsoleto e não deve ser usado em código novo. JavaScript possui funcionalidade integrada muito semelhante por meio de Object.assign().

util.isArray(object) ​

Adicionado em: v0.6.0

Obsoleto desde: v4.0.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto: Use Array.isArray() em vez disso.

Alias para Array.isArray().

Retorna true se o object fornecido é um Array. Caso contrário, retorna false.

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

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