{ "source": "doc/api/console.md", "modules": [ { "textRaw": "Console", "name": "console", "introduced_in": "v0.10.13", "stability": 2, "stabilityText": "Stable", "desc": "<p>The <code>console</code> module provides a simple debugging console that is similar to the\nJavaScript console mechanism provided by web browsers.</p>\n<p>The module exports two specific components:</p>\n<ul>\n<li>A <code>Console</code> class with methods such as <code>console.log()</code>, <code>console.error()</code> and\n<code>console.warn()</code> that can be used to write to any Node.js stream.</li>\n<li>A global <code>console</code> instance configured to write to <a href=\"process.html#process_process_stdout\"><code>process.stdout</code></a> and\n<a href=\"process.html#process_process_stderr\"><code>process.stderr</code></a>. The global <code>console</code> can be used without calling\n<code>require('console')</code>.</li>\n</ul>\n<p><strong><em>Warning</em></strong>: The global console object's methods are neither consistently\nsynchronous like the browser APIs they resemble, nor are they consistently\nasynchronous like all other Node.js streams. See the <a href=\"process.html#process_a_note_on_process_i_o\">note on process I/O</a> for\nmore information.</p>\n<p>Example using the global <code>console</code>:</p>\n<pre><code class=\"lang-js\">console.log('hello world');\n// Prints: hello world, to stdout\nconsole.log('hello %s', 'world');\n// Prints: hello world, to stdout\nconsole.error(new Error('Whoops, something bad happened'));\n// Prints: [Error: Whoops, something bad happened], to stderr\n\nconst name = 'Will Robinson';\nconsole.warn(`Danger ${name}! Danger!`);\n// Prints: Danger Will Robinson! Danger!, to stderr\n</code></pre>\n<p>Example using the <code>Console</code> class:</p>\n<pre><code class=\"lang-js\">const out = getStreamSomehow();\nconst err = getStreamSomehow();\nconst myConsole = new console.Console(out, err);\n\nmyConsole.log('hello world');\n// Prints: hello world, to out\nmyConsole.log('hello %s', 'world');\n// Prints: hello world, to out\nmyConsole.error(new Error('Whoops, something bad happened'));\n// Prints: [Error: Whoops, something bad happened], to err\n\nconst name = 'Will Robinson';\nmyConsole.warn(`Danger ${name}! Danger!`);\n// Prints: Danger Will Robinson! Danger!, to err\n</code></pre>\n", "classes": [ { "textRaw": "Class: Console", "type": "class", "name": "Console", "desc": "<p>The <code>Console</code> class can be used to create a simple logger with configurable\noutput streams and can be accessed using either <code>require('console').Console</code>\nor <code>console.Console</code>:</p>\n<pre><code class=\"lang-js\">const Console = require('console').Console;\n</code></pre>\n<pre><code class=\"lang-js\">const Console = console.Console;\n</code></pre>\n", "methods": [ { "textRaw": "console.assert(value[, message][, ...args])", "type": "method", "name": "assert", "meta": { "added": [ "v0.1.101" ] }, "desc": "<p>A simple assertion test that verifies whether <code>value</code> is truthy. If it is not,\nan <code>AssertionError</code> is thrown. If provided, the error <code>message</code> is formatted\nusing <a href=\"util.html#util_util_format_format_args\"><code>util.format()</code></a> and used as the error message.</p>\n<pre><code class=\"lang-js\">console.assert(true, 'does nothing');\n// OK\nconsole.assert(false, 'Whoops %s', 'didn\\'t work');\n// AssertionError: Whoops didn't work\n</code></pre>\n<p><em>Note: the <code>console.assert()</code> method is implemented differently in Node.js\nthan the <code>console.assert()</code> method <a href=\"https://developer.mozilla.org/en-US/docs/Web/API/console/assert\">available in browsers</a>.</em></p>\n<p>Specifically, in browsers, calling <code>console.assert()</code> with a falsy\nassertion will cause the <code>message</code> to be printed to the console without\ninterrupting execution of subsequent code. In Node.js, however, a falsy\nassertion will cause an <code>AssertionError</code> to be thrown.</p>\n<p>Functionality approximating that implemented by browsers can be implemented\nby extending Node.js' <code>console</code> and overriding the <code>console.assert()</code> method.</p>\n<p>In the following example, a simple module is created that extends and overrides\nthe default behavior of <code>console</code> in Node.js.</p>\n<pre><code class=\"lang-js\">'use strict';\n\n// Creates a simple extension of console with a\n// new impl for assert without monkey-patching.\nconst myConsole = Object.create(console, {\n assert: {\n value(assertion, message, ...args) {\n try {\n console.assert(assertion, message, ...args);\n } catch (err) {\n console.error(err.stack);\n }\n },\n configurable: true,\n enumerable: true,\n writable: true,\n },\n});\n\nmodule.exports = myConsole;\n</code></pre>\n<p>This can then be used as a direct replacement for the built in console:</p>\n<pre><code class=\"lang-js\">const console = require('./myConsole');\nconsole.assert(false, 'this message will print, but no error thrown');\nconsole.log('this will also print');\n</code></pre>\n", "signatures": [ { "params": [ { "name": "value" }, { "name": "message", "optional": true }, { "name": "...args", "optional": true } ] } ] }, { "textRaw": "console.clear()", "type": "method", "name": "clear", "meta": { "added": [ "v6.13.0" ] }, "desc": "<p>When <code>stdout</code> is a TTY, calling <code>console.clear()</code> will attempt to clear the\nTTY. When <code>stdout</code> is not a TTY, this method does nothing.</p>\n<p><em>Note</em>: The specific operation of <code>console.clear()</code> can vary across operating\nsystems and terminal types. For most Linux operating systems, <code>console.clear()</code>\noperates similarly to the <code>clear</code> shell command. On Windows, <code>console.clear()</code>\nwill clear only the output in the current terminal viewport for the Node.js\nbinary.</p>\n", "signatures": [ { "params": [] } ] }, { "textRaw": "console.count([label])", "type": "method", "name": "count", "meta": { "added": [ "v6.13.0" ] }, "signatures": [ { "params": [ { "textRaw": "`label` {string} The display label for the counter. Defaults to `'default'`. ", "name": "label", "type": "string", "desc": "The display label for the counter. Defaults to `'default'`.", "optional": true } ] }, { "params": [ { "name": "label", "optional": true } ] } ], "desc": "<p>Maintains an internal counter specific to <code>label</code> and outputs to <code>stdout</code> the\nnumber of times <code>console.count()</code> has been called with the given <code>label</code>.</p>\n<!-- eslint-skip -->\n<pre><code class=\"lang-js\">> console.count()\ndefault: 1\nundefined\n> console.count('default')\ndefault: 2\nundefined\n> console.count('abc')\nabc: 1\nundefined\n> console.count('xyz')\nxyz: 1\nundefined\n> console.count('abc')\nabc: 2\nundefined\n> console.count()\ndefault: 3\nundefined\n>\n</code></pre>\n" }, { "textRaw": "console.countReset([label = 'default'])", "type": "method", "name": "countReset", "meta": { "added": [ "v6.13.0" ] }, "signatures": [ { "params": [ { "textRaw": "`label` {string} The display label for the counter. Defaults to `'default'`. ", "name": "label", "type": "string", "desc": "The display label for the counter. Defaults to `'default'`.", "optional": true, "default": " 'default'" } ] }, { "params": [ { "name": "label ", "optional": true, "default": " 'default'" } ] } ], "desc": "<p>Resets the internal counter specific to <code>label</code>.</p>\n<!-- eslint-skip -->\n<pre><code class=\"lang-js\">> console.count('abc');\nabc: 1\nundefined\n> console.countReset('abc');\nundefined\n> console.count('abc');\nabc: 1\nundefined\n>\n</code></pre>\n<!-- eslint-enable -->\n" }, { "textRaw": "console.dir(obj[, options])", "type": "method", "name": "dir", "meta": { "added": [ "v0.1.101" ] }, "signatures": [ { "params": [ { "textRaw": "`obj` {any} ", "name": "obj", "type": "any" }, { "textRaw": "`options` {Object} ", "options": [ { "textRaw": "`showHidden` {boolean} ", "name": "showHidden", "type": "boolean" }, { "textRaw": "`depth` {number} ", "name": "depth", "type": "number" }, { "textRaw": "`colors` {boolean} ", "name": "colors", "type": "boolean" } ], "name": "options", "type": "Object", "optional": true } ] }, { "params": [ { "name": "obj" }, { "name": "options", "optional": true } ] } ], "desc": "<p>Uses <a href=\"util.html#util_util_inspect_object_options\"><code>util.inspect()</code></a> on <code>obj</code> and prints the resulting string to <code>stdout</code>.\nThis function bypasses any custom <code>inspect()</code> function defined on <code>obj</code>. An\noptional <code>options</code> object may be passed to alter certain aspects of the\nformatted string:</p>\n<ul>\n<li><p><code>showHidden</code> - if <code>true</code> then the object's non-enumerable and symbol\nproperties will be shown too. Defaults to <code>false</code>.</p>\n</li>\n<li><p><code>depth</code> - tells <a href=\"util.html#util_util_inspect_object_options\"><code>util.inspect()</code></a> how many times to recurse while\nformatting the object. This is useful for inspecting large complicated objects.\nDefaults to <code>2</code>. To make it recurse indefinitely, pass <code>null</code>.</p>\n</li>\n<li><p><code>colors</code> - if <code>true</code>, then the output will be styled with ANSI color codes.\nDefaults to <code>false</code>. Colors are customizable; see\n<a href=\"util.html#util_customizing_util_inspect_colors\">customizing <code>util.inspect()</code> colors</a>.</p>\n</li>\n</ul>\n" }, { "textRaw": "console.error([data][, ...args])", "type": "method", "name": "error", "meta": { "added": [ "v0.1.100" ] }, "desc": "<p>Prints to <code>stderr</code> with newline. Multiple arguments can be passed, with the\nfirst used as the primary message and all additional used as substitution\nvalues similar to printf(3) (the arguments are all passed to\n<a href=\"util.html#util_util_format_format_args\"><code>util.format()</code></a>).</p>\n<pre><code class=\"lang-js\">const code = 5;\nconsole.error('error #%d', code);\n// Prints: error #5, to stderr\nconsole.error('error', code);\n// Prints: error 5, to stderr\n</code></pre>\n<p>If formatting elements (e.g. <code>%d</code>) are not found in the first string then\n<a href=\"util.html#util_util_inspect_object_options\"><code>util.inspect()</code></a> is called on each argument and the resulting string\nvalues are concatenated. See <a href=\"util.html#util_util_format_format_args\"><code>util.format()</code></a> for more information.</p>\n", "signatures": [ { "params": [ { "name": "data", "optional": true }, { "name": "...args", "optional": true } ] } ] }, { "textRaw": "console.info([data][, ...args])", "type": "method", "name": "info", "meta": { "added": [ "v0.1.100" ] }, "desc": "<p>The <code>console.info()</code> function is an alias for <a href=\"#console_console_log_data_args\"><code>console.log()</code></a>.</p>\n", "signatures": [ { "params": [ { "name": "data", "optional": true }, { "name": "...args", "optional": true } ] } ] }, { "textRaw": "console.log([data][, ...args])", "type": "method", "name": "log", "meta": { "added": [ "v0.1.100" ] }, "desc": "<p>Prints to <code>stdout</code> with newline. Multiple arguments can be passed, with the\nfirst used as the primary message and all additional used as substitution\nvalues similar to printf(3) (the arguments are all passed to\n<a href=\"util.html#util_util_format_format_args\"><code>util.format()</code></a>).</p>\n<pre><code class=\"lang-js\">const count = 5;\nconsole.log('count: %d', count);\n// Prints: count: 5, to stdout\nconsole.log('count:', count);\n// Prints: count: 5, to stdout\n</code></pre>\n<p>See <a href=\"util.html#util_util_format_format_args\"><code>util.format()</code></a> for more information.</p>\n", "signatures": [ { "params": [ { "name": "data", "optional": true }, { "name": "...args", "optional": true } ] } ] }, { "textRaw": "console.time(label)", "type": "method", "name": "time", "meta": { "added": [ "v0.1.104" ] }, "signatures": [ { "params": [ { "textRaw": "`label` {string} ", "name": "label", "type": "string" } ] }, { "params": [ { "name": "label" } ] } ], "desc": "<p>Starts a timer that can be used to compute the duration of an operation. Timers\nare identified by a unique <code>label</code>. Use the same <code>label</code> when you call\n<a href=\"#console_console_timeend_label\"><code>console.timeEnd()</code></a> to stop the timer and output the elapsed time in\nmilliseconds to <code>stdout</code>. Timer durations are accurate to the sub-millisecond.</p>\n" }, { "textRaw": "console.timeEnd(label)", "type": "method", "name": "timeEnd", "meta": { "added": [ "v0.1.104" ] }, "signatures": [ { "params": [ { "textRaw": "`label` {string} ", "name": "label", "type": "string" } ] }, { "params": [ { "name": "label" } ] } ], "desc": "<p>Stops a timer that was previously started by calling <a href=\"#console_console_time_label\"><code>console.time()</code></a> and\nprints the result to <code>stdout</code>:</p>\n<pre><code class=\"lang-js\">console.time('100-elements');\nfor (let i = 0; i < 100; i++) ;\nconsole.timeEnd('100-elements');\n// prints 100-elements: 225.438ms\n</code></pre>\n<p><em>Note: As of Node.js v6.0.0, <code>console.timeEnd()</code> deletes the timer to avoid\nleaking it. On older versions, the timer persisted. This allowed\n<code>console.timeEnd()</code> to be called multiple times for the same label. This\nfunctionality was unintended and is no longer supported.</em></p>\n" }, { "textRaw": "console.trace(message[, ...args])", "type": "method", "name": "trace", "meta": { "added": [ "v0.1.104" ] }, "desc": "<p>Prints to <code>stderr</code> the string <code>'Trace :'</code>, followed by the <a href=\"util.html#util_util_format_format_args\"><code>util.format()</code></a>\nformatted message and stack trace to the current position in the code.</p>\n<pre><code class=\"lang-js\">console.trace('Show me');\n// Prints: (stack trace will vary based on where trace is called)\n// Trace: Show me\n// at repl:2:9\n// at REPLServer.defaultEval (repl.js:248:27)\n// at bound (domain.js:287:14)\n// at REPLServer.runBound [as eval] (domain.js:300:12)\n// at REPLServer.<anonymous> (repl.js:412:12)\n// at emitOne (events.js:82:20)\n// at REPLServer.emit (events.js:169:7)\n// at REPLServer.Interface._onLine (readline.js:210:10)\n// at REPLServer.Interface._line (readline.js:549:8)\n// at REPLServer.Interface._ttyWrite (readline.js:826:14)\n</code></pre>\n", "signatures": [ { "params": [ { "name": "message" }, { "name": "...args", "optional": true } ] } ] }, { "textRaw": "console.warn([data][, ...args])", "type": "method", "name": "warn", "meta": { "added": [ "v0.1.100" ] }, "desc": "<p>The <code>console.warn()</code> function is an alias for <a href=\"#console_console_error_data_args\"><code>console.error()</code></a>.</p>\n", "signatures": [ { "params": [ { "name": "data", "optional": true }, { "name": "...args", "optional": true } ] } ] } ], "signatures": [ { "params": [ { "name": "stdout" }, { "name": "stderr", "optional": true } ], "desc": "<p>Creates a new <code>Console</code> with one or two writable stream instances. <code>stdout</code> is a\nwritable stream to print log or info output. <code>stderr</code> is used for warning or\nerror output. If <code>stderr</code> is not provided, <code>stdout</code> is used for <code>stderr</code>.</p>\n<pre><code class=\"lang-js\">const output = fs.createWriteStream('./stdout.log');\nconst errorOutput = fs.createWriteStream('./stderr.log');\n// custom simple logger\nconst logger = new Console(output, errorOutput);\n// use it like console\nconst count = 5;\nlogger.log('count: %d', count);\n// in stdout.log: count 5\n</code></pre>\n<p>The global <code>console</code> is a special <code>Console</code> whose output is sent to\n<a href=\"process.html#process_process_stdout\"><code>process.stdout</code></a> and <a href=\"process.html#process_process_stderr\"><code>process.stderr</code></a>. It is equivalent to calling:</p>\n<pre><code class=\"lang-js\">new Console(process.stdout, process.stderr);\n</code></pre>\n" } ] } ], "type": "module", "displayName": "Console" } ] }