Console

[Estável: 2 - Estável]

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

Código-fonte: lib/console.js

O módulo node:console fornece um console de depuração simples que é semelhante ao mecanismo de console JavaScript fornecido pelos navegadores da web.

O módulo exporta dois componentes específicos:

• Uma classe Console com métodos como console.log(), console.error() e console.warn() que podem ser usados para escrever em qualquer stream do Node.js.
• Uma instância global console configurada para escrever em process.stdout e process.stderr. O console global pode ser usado sem chamar require('node:console').

Aviso: Os métodos do objeto console global não são consistentemente síncronos como as APIs do navegador que eles se assemelham, nem são consistentemente assíncronos como todos os outros streams do Node.js. Os programas que desejam depender do comportamento síncrono/assíncrono das funções do console devem primeiro descobrir a natureza do stream de suporte do console. Isso ocorre porque o stream depende da plataforma subjacente e da configuração de stream padrão do processo atual. Consulte a nota sobre E/S de processo para obter mais informações.

Exemplo usando o console global:

console.log('olá mundo')
// Imprime: olá mundo, para stdout
console.log('olá %s', 'mundo')
// Imprime: olá mundo, para stdout
console.error(new Error('Opa, algo ruim aconteceu'))
// Imprime mensagem de erro e rastreamento de pilha para stderr:
//   Error: Opa, algo ruim aconteceu
//     em [eval]:5:15
//     em Script.runInThisContext (node:vm:132:18)
//     em Object.runInThisContext (node:vm:309:38)
//     em node:internal/process/execution:77:19
//     em [eval]-wrapper:6:22
//     em evalScript (node:internal/process/execution:76:60)
//     em node:internal/main/eval_string:23:3

const name = 'Will Robinson'
console.warn(`Perigo ${name}! Perigo!`)
// Imprime: Perigo Will Robinson! Perigo!, para stderr

Exemplo usando a classe Console:

const out = getStreamSomehow()
const err = getStreamSomehow()
const myConsole = new console.Console(out, err)

myConsole.log('olá mundo')
// Imprime: olá mundo, para out
myConsole.log('olá %s', 'mundo')
// Imprime: olá mundo, para out
myConsole.error(new Error('Opa, algo ruim aconteceu'))
// Imprime: [Error: Opa, algo ruim aconteceu], para err

const name = 'Will Robinson'
myConsole.warn(`Perigo ${name}! Perigo!`)
// Imprime: Perigo Will Robinson! Perigo!, para err

Classe: Console

[Histórico]

Versão	Mudanças
v8.0.0	Erros que ocorrem durante a escrita nos fluxos subjacentes agora serão ignorados por padrão.

A classe Console pode ser usada para criar um logger simples com fluxos de saída configuráveis e pode ser acessada usando require('node:console').Console ou console.Console (ou suas contrapartes desestruturadas):

ESM

import { Console } from 'node:console'

CJS

const { Console } = require('node:console')

const { Console } = console

new Console(stdout[, stderr][, ignoreErrors])

new Console(options)

[Histórico]

Versão	Mudanças
v14.2.0, v12.17.0	A opção groupIndentation foi introduzida.
v11.7.0	A opção inspectOptions foi introduzida.
v10.0.0	O construtor Console agora suporta um argumento options, e a opção colorMode foi introduzida.
v8.0.0	A opção ignoreErrors foi introduzida.

• options <Objeto>
  • stdout <stream.Writable>
  • stderr <stream.Writable>
  • ignoreErrors <boolean> Ignora erros ao escrever nos fluxos subjacentes. Padrão: true.
  • colorMode <boolean> | <string> Define o suporte de cor para esta instância de Console. Definir como true habilita a coloração ao inspecionar valores. Definir como false desabilita a coloração ao inspecionar valores. Definir como 'auto' faz com que o suporte de cor dependa do valor da propriedade isTTY e do valor retornado por getColorDepth() no fluxo respectivo. Esta opção não pode ser usada se inspectOptions.colors também estiver definido. Padrão: 'auto'.
  • inspectOptions <Objeto> Especifica as opções que são passadas para util.inspect().
  • groupIndentation <number> Define o recuo do grupo. Padrão: 2.

Cria um novo Console com uma ou duas instâncias de fluxo gravável. stdout é um fluxo gravável para imprimir o log ou informações de saída. stderr é usado para avisos ou erros de saída. Se stderr não for fornecido, stdout é usado para stderr.

ESM

import { createWriteStream } from 'node:fs'
import { Console } from 'node:console'
// Alternativamente
// const { Console } = console;

const output = createWriteStream('./stdout.log')
const errorOutput = createWriteStream('./stderr.log')
// Logger simples personalizado
const logger = new Console({ stdout: output, stderr: errorOutput })
// use como console
const count = 5
logger.log('count: %d', count)
// Em stdout.log: count 5

CJS

const fs = require('node:fs')
const { Console } = require('node:console')
// Alternativamente
// const { Console } = console;

const output = fs.createWriteStream('./stdout.log')
const errorOutput = fs.createWriteStream('./stderr.log')
// Logger simples personalizado
const logger = new Console({ stdout: output, stderr: errorOutput })
// use como console
const count = 5
logger.log('count: %d', count)
// Em stdout.log: count 5

O console global é um Console especial cuja saída é enviada para process.stdout e process.stderr. É equivalente a chamar:

new Console({ stdout: process.stdout, stderr: process.stderr })

console.assert(value[, ...message])

[Histórico]

Versão	Mudanças
v10.0.0	A implementação agora está em conformidade com a especificação e não lança mais erros.
v0.1.101	Adicionado em: v0.1.101

• value <any> O valor testado para ser verdadeiro.
• ...message <any> Todos os argumentos além de value são usados como mensagem de erro.

console.assert() escreve uma mensagem se value for falsy ou omitido. Ele apenas escreve uma mensagem e não afeta a execução de outra forma. A saída sempre começa com "Assertion failed". Se fornecido, message é formatado usando util.format().

Se value for truthy, nada acontece.

console.assert(true, 'não faz nada')

console.assert(false, 'Opa, %s não funcionou', 'não')
// Assertion failed: Opa, não funcionou

console.assert()
// Assertion failed

console.clear()

Adicionado em: v8.3.0

Quando stdout é um TTY, chamar console.clear() tentará limpar o TTY. Quando stdout não é um TTY, este método não faz nada.

A operação específica de console.clear() pode variar entre sistemas operacionais e tipos de terminal. Para a maioria dos sistemas operacionais Linux, console.clear() opera de forma semelhante ao comando clear do shell. No Windows, console.clear() limpará apenas a saída na janela de terminal atual para o binário Node.js.

console.count([label])

Adicionado em: v8.3.0

• label <string> O rótulo de exibição para o contador. Padrão: 'default'.

Mantém um contador interno específico para label e envia para stdout o número de vezes que console.count() foi chamado com o label fornecido.

> console.count()
default: 1
undefined
> console.count('default')
default: 2
undefined
> console.count('abc')
abc: 1
undefined
> console.count('xyz')
xyz: 1
undefined
> console.count('abc')
abc: 2
undefined
> console.count()
default: 3
undefined
>

console.countReset([label])

Adicionado em: v8.3.0

• label <string> O rótulo de exibição para o contador. Padrão: 'default'.

Redefine o contador interno específico para label.

> console.count('abc');
abc: 1
undefined
> console.countReset('abc');
undefined
> console.count('abc');
abc: 1
undefined
>

console.debug(data[, ...args])

[Histórico]

Versão	Alterações
v8.10.0	console.debug agora é um alias para console.log.
v8.0.0	Adicionado em: v8.0.0

• data <any>
• ...args <any>

A função console.debug() é um alias para console.log().

console.dir(obj[, options])

Adicionado em: v0.1.101

• obj <any>
• options <Object>
  • showHidden <boolean> Se true, as propriedades não enumeráveis e de símbolo do objeto também serão exibidas. Padrão: false.
  • depth <number> Diz para util.inspect() quantas vezes recorrer ao formatar o objeto. Isso é útil para inspecionar objetos grandes e complicados. Para fazê-lo recorrer indefinidamente, passe null. Padrão: 2.
  • colors <boolean> Se true, a saída será estilizada com códigos de cores ANSI. As cores são personalizáveis; consulte personalizar cores util.inspect(). Padrão: false.

Usa util.inspect() em obj e imprime a string resultante em stdout. Esta função ignora qualquer função inspect() personalizada definida em obj.

console.dirxml(...data)

[Histórico]

Versão	Alterações
v9.3.0	console.dirxml agora chama console.log para seus argumentos.
v8.0.0	Adicionado em: v8.0.0

• ...data <any>

Este método chama console.log() passando os argumentos recebidos. Este método não produz nenhuma formatação XML.

console.error([data][, ...args])

Adicionado em: v0.1.100

• data <any>
• ...args <any>

Imprime para stderr com nova linha. Vários argumentos podem ser passados, com o primeiro sendo usado como a mensagem primária e todos os adicionais usados como valores de substituição semelhante a printf(3) (os argumentos são todos passados para util.format()).

const code = 5
console.error('erro #%d', code)
// Imprime: erro #5, para stderr
console.error('erro', code)
// Imprime: erro 5, para stderr

Se elementos de formatação (ex: %d) não forem encontrados na primeira string, então util.inspect() é chamado em cada argumento e os valores de string resultantes são concatenados. Veja util.format() para mais informações.

console.group([...label])

Adicionado em: v8.5.0

• ...label <any>

Aumenta a indentação das linhas subsequentes por espaços para o comprimento de groupIndentation.

Se um ou mais labels forem fornecidos, eles são impressos primeiro sem a indentação adicional.

console.groupCollapsed()

Adicionado em: v8.5.0

Um alias para console.group().

console.groupEnd()

Adicionado em: v8.5.0

Diminui a indentação das linhas subsequentes por espaços para o comprimento de groupIndentation.

console.info([data][, ...args])

Adicionado em: v0.1.100

• data <any>
• ...args <any>

A função console.info() é um alias para console.log().

console.log([data][, ...args])

Adicionado em: v0.1.100

• data <any>
• ...args <any>

Imprime em stdout com nova linha. Múltiplos argumentos podem ser passados, com o primeiro sendo usado como a mensagem principal e todos os adicionais usados como valores de substituição similar ao printf(3) (os argumentos são todos passados para util.format()).

const count = 5
console.log('count: %d', count)
// Imprime: count: 5, para stdout
console.log('count:', count)
// Imprime: count: 5, para stdout

Veja util.format() para mais informações.

console.table(tabularData[, properties])

Adicionado em: v10.0.0

• tabularData <any>
• properties <string[]> Propriedades alternativas para construir a tabela.

Tenta construir uma tabela com as colunas das propriedades de tabularData (ou usa properties) e linhas de tabularData e a registra. Reverte para apenas registrar o argumento se ele não puder ser analisado como tabular.

// Estes não podem ser analisados como dados tabulares
console.table(Symbol())
// Symbol()

console.table(undefined)
// undefined

console.table([
  { a: 1, b: 'Y' },
  { a: 'Z', b: 2 },
])
// ┌─────────┬─────┬─────┐
// │ (index) │ a   │ b   │
// ├─────────┼─────┼─────┤
// │ 0       │ 1   │ 'Y' │
// │ 1       │ 'Z' │ 2   │
// └─────────┴─────┴─────┘

console.table(
  [
    { a: 1, b: 'Y' },
    { a: 'Z', b: 2 },
  ],
  ['a']
)
// ┌─────────┬─────┐
// │ (index) │ a   │
// ├─────────┼─────┤
// │ 0       │ 1   │
// │ 1       │ 'Z' │
// └─────────┴─────┘

console.time([label])

Adicionado em: v0.1.104

• label <string> Padrão: 'default'

Inicia um temporizador que pode ser usado para calcular a duração de uma operação. Os temporizadores são identificados por um label exclusivo. Use o mesmo label ao chamar console.timeEnd() para parar o temporizador e emitir o tempo decorrido em unidades de tempo adequadas para stdout. Por exemplo, se o tempo decorrido for 3869 ms, console.timeEnd() exibe "3,869s".

console.timeEnd([label])

[Histórico]

Versão	Alterações
v13.0.0	O tempo decorrido é exibido com uma unidade de tempo adequada.
v6.0.0	Este método não oferece mais suporte a múltiplas chamadas que não se mapeiam para chamadas individuais de console.time(); consulte abaixo para obter detalhes.
v0.1.104	Adicionado em: v0.1.104

• label <string> Padrão: 'default'

Para um temporizador que foi iniciado anteriormente chamando console.time() e imprime o resultado em stdout:

console.time('bunch-of-stuff')
// Faz um monte de coisas.
console.timeEnd('bunch-of-stuff')
// Imprime: bunch-of-stuff: 225.438ms

console.timeLog([label][, ...data])

Adicionado em: v10.7.0

• label <string> Padrão: 'default'
• ...data <any>

Para um temporizador que foi iniciado anteriormente chamando console.time(), imprime o tempo decorrido e outros argumentos data em stdout:

console.time('process')
const value = expensiveProcess1() // Retorna 42
console.timeLog('process', value)
// Imprime "process: 365.227ms 42".
doExpensiveProcess2(value)
console.timeEnd('process')

console.trace([message][, ...args])

Adicionado em: v0.1.104

• message <any>
• ...args <any>

Imprime para stderr a string 'Trace: ', seguido pela mensagem formatada util.format() e rastreamento de pilha para a posição atual no código.

console.trace('Show me')
// Imprime: (o rastreamento de pilha irá variar com base em onde o rastreamento é chamado)
//  Trace: Show me
//    at repl:2:9
//    at REPLServer.defaultEval (repl.js:248:27)
//    at bound (domain.js:287:14)
//    at REPLServer.runBound [as eval] (domain.js:300:12)
//    at REPLServer.<anonymous> (repl.js:412:12)
//    at emitOne (events.js:82:20)
//    at REPLServer.emit (events.js:169:7)
//    at REPLServer.Interface._onLine (readline.js:210:10)
//    at REPLServer.Interface._line (readline.js:549:8)
//    at REPLServer.Interface._ttyWrite (readline.js:826:14)

console.warn([data][, ...args])

Adicionado em: v0.1.100

• data <any>
• ...args <any>

A função console.warn() é um alias para console.error().

Métodos somente do inspetor

Os seguintes métodos são expostos pelo mecanismo V8 na API geral, mas não exibem nada, a menos que sejam usados em conjunto com o inspetor (flag --inspect).

console.profile([label])

Adicionado em: v8.0.0

• label <string>

Este método não exibe nada, a menos que seja usado no inspetor. O método console.profile() inicia um perfil de CPU JavaScript com um rótulo opcional até que console.profileEnd() seja chamado. O perfil é então adicionado ao painel Perfil do inspetor.

console.profile('MeuRótulo')
// Algum código
console.profileEnd('MeuRótulo')
// Adiciona o perfil 'MeuRótulo' ao painel Perfis do inspetor.

console.profileEnd([label])

Adicionado em: v8.0.0

• label <string>

Este método não exibe nada, a menos que seja usado no inspetor. Interrompe a sessão atual de perfil de CPU JavaScript, se uma tiver sido iniciada, e imprime o relatório no painel Perfis do inspetor. Veja console.profile() para um exemplo.

Se este método for chamado sem um rótulo, o perfil iniciado mais recentemente é interrompido.

console.timeStamp([label])

Adicionado em: v8.0.0

• label <string>

Este método não exibe nada, a menos que seja usado no inspetor. O método console.timeStamp() adiciona um evento com o rótulo 'label' ao painel Linha do Tempo do inspetor.