console.d.ts (21255B)
1 /** 2 * The `node:console` module provides a simple debugging console that is similar to 3 * the JavaScript console mechanism provided by web browsers. 4 * 5 * The module exports two specific components: 6 * 7 * * A `Console` class with methods such as `console.log()`, `console.error()`, and `console.warn()` that can be used to write to any Node.js stream. 8 * * A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v16.x/api/process.html#processstdout) and 9 * [`process.stderr`](https://nodejs.org/docs/latest-v16.x/api/process.html#processstderr). The global `console` can be used without importing the `node:console` module. 10 * 11 * _**Warning**_: The global console object's methods are neither consistently 12 * synchronous like the browser APIs they resemble, nor are they consistently 13 * asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v16.x/api/process.html#a-note-on-process-io) for 14 * more information. 15 * 16 * Example using the global `console`: 17 * 18 * ```js 19 * console.log('hello world'); 20 * // Prints: hello world, to stdout 21 * console.log('hello %s', 'world'); 22 * // Prints: hello world, to stdout 23 * console.error(new Error('Whoops, something bad happened')); 24 * // Prints error message and stack trace to stderr: 25 * // Error: Whoops, something bad happened 26 * // at [eval]:5:15 27 * // at Script.runInThisContext (node:vm:132:18) 28 * // at Object.runInThisContext (node:vm:309:38) 29 * // at node:internal/process/execution:77:19 30 * // at [eval]-wrapper:6:22 31 * // at evalScript (node:internal/process/execution:76:60) 32 * // at node:internal/main/eval_string:23:3 33 * 34 * const name = 'Will Robinson'; 35 * console.warn(`Danger ${name}! Danger!`); 36 * // Prints: Danger Will Robinson! Danger!, to stderr 37 * ``` 38 * 39 * Example using the `Console` class: 40 * 41 * ```js 42 * const out = getStreamSomehow(); 43 * const err = getStreamSomehow(); 44 * const myConsole = new console.Console(out, err); 45 * 46 * myConsole.log('hello world'); 47 * // Prints: hello world, to out 48 * myConsole.log('hello %s', 'world'); 49 * // Prints: hello world, to out 50 * myConsole.error(new Error('Whoops, something bad happened')); 51 * // Prints: [Error: Whoops, something bad happened], to err 52 * 53 * const name = 'Will Robinson'; 54 * myConsole.warn(`Danger ${name}! Danger!`); 55 * // Prints: Danger Will Robinson! Danger!, to err 56 * ``` 57 * @see [source](https://github.com/nodejs/node/blob/v16.20.2/lib/console.js) 58 */ 59 declare module "console" { 60 import console = require("node:console"); 61 export = console; 62 } 63 declare module "node:console" { 64 import { InspectOptions } from "node:util"; 65 global { 66 // This needs to be global to avoid TS2403 in case lib.dom.d.ts is present in the same build 67 interface Console { 68 Console: console.ConsoleConstructor; 69 /** 70 * `console.assert()` writes a message if `value` is [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy) or omitted. It only 71 * writes a message and does not otherwise affect execution. The output always 72 * starts with `"Assertion failed"`. If provided, `message` is formatted using 73 * [`util.format()`](https://nodejs.org/docs/latest-v16.x/api/util.html#utilformatformat-args). 74 * 75 * If `value` is [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy), nothing happens. 76 * 77 * ```js 78 * console.assert(true, 'does nothing'); 79 * 80 * console.assert(false, 'Whoops %s work', 'didn\'t'); 81 * // Assertion failed: Whoops didn't work 82 * 83 * console.assert(); 84 * // Assertion failed 85 * ``` 86 * @since v0.1.101 87 * @param value The value tested for being truthy. 88 * @param message All arguments besides `value` are used as error message. 89 */ 90 assert(value: any, message?: string, ...optionalParams: any[]): void; 91 /** 92 * When `stdout` is a TTY, calling `console.clear()` will attempt to clear the 93 * TTY. When `stdout` is not a TTY, this method does nothing. 94 * 95 * The specific operation of `console.clear()` can vary across operating systems 96 * and terminal types. For most Linux operating systems, `console.clear()` operates similarly to the `clear` shell command. On Windows, `console.clear()` will clear only the output in the 97 * current terminal viewport for the Node.js 98 * binary. 99 * @since v8.3.0 100 */ 101 clear(): void; 102 /** 103 * Maintains an internal counter specific to `label` and outputs to `stdout` the 104 * number of times `console.count()` has been called with the given `label`. 105 * 106 * ```js 107 * > console.count() 108 * default: 1 109 * undefined 110 * > console.count('default') 111 * default: 2 112 * undefined 113 * > console.count('abc') 114 * abc: 1 115 * undefined 116 * > console.count('xyz') 117 * xyz: 1 118 * undefined 119 * > console.count('abc') 120 * abc: 2 121 * undefined 122 * > console.count() 123 * default: 3 124 * undefined 125 * > 126 * ``` 127 * @since v8.3.0 128 * @param [label='default'] The display label for the counter. 129 */ 130 count(label?: string): void; 131 /** 132 * Resets the internal counter specific to `label`. 133 * 134 * ```js 135 * > console.count('abc'); 136 * abc: 1 137 * undefined 138 * > console.countReset('abc'); 139 * undefined 140 * > console.count('abc'); 141 * abc: 1 142 * undefined 143 * > 144 * ``` 145 * @since v8.3.0 146 * @param [label='default'] The display label for the counter. 147 */ 148 countReset(label?: string): void; 149 /** 150 * The `console.debug()` function is an alias for {@link log}. 151 * @since v8.0.0 152 */ 153 debug(message?: any, ...optionalParams: any[]): void; 154 /** 155 * Uses [`util.inspect()`](https://nodejs.org/docs/latest-v16.x/api/util.html#utilinspectobject-options) on `obj` and prints the resulting string to `stdout`. 156 * This function bypasses any custom `inspect()` function defined on `obj`. 157 * @since v0.1.101 158 */ 159 dir(obj: any, options?: InspectOptions): void; 160 /** 161 * This method calls `console.log()` passing it the arguments received. 162 * This method does not produce any XML formatting. 163 * @since v8.0.0 164 */ 165 dirxml(...data: any[]): void; 166 /** 167 * Prints to `stderr` with newline. Multiple arguments can be passed, with the 168 * first used as the primary message and all additional used as substitution 169 * values similar to [`printf(3)`](http://man7.org/linux/man-pages/man3/printf.3.html) 170 * (the arguments are all passed to [`util.format()`](https://nodejs.org/docs/latest-v16.x/api/util.html#utilformatformat-args)). 171 * 172 * ```js 173 * const code = 5; 174 * console.error('error #%d', code); 175 * // Prints: error #5, to stderr 176 * console.error('error', code); 177 * // Prints: error 5, to stderr 178 * ``` 179 * 180 * If formatting elements (e.g. `%d`) are not found in the first string then 181 * [`util.inspect()`](https://nodejs.org/docs/latest-v16.x/api/util.html#utilinspectobject-options) is called on each argument and the 182 * resulting string values are concatenated. See [`util.format()`](https://nodejs.org/docs/latest-v16.x/api/util.html#utilformatformat-args) 183 * for more information. 184 * @since v0.1.100 185 */ 186 error(message?: any, ...optionalParams: any[]): void; 187 /** 188 * Increases indentation of subsequent lines by spaces for `groupIndentation` length. 189 * 190 * If one or more `label`s are provided, those are printed first without the 191 * additional indentation. 192 * @since v8.5.0 193 */ 194 group(...label: any[]): void; 195 /** 196 * An alias for {@link group}. 197 * @since v8.5.0 198 */ 199 groupCollapsed(...label: any[]): void; 200 /** 201 * Decreases indentation of subsequent lines by spaces for `groupIndentation` length. 202 * @since v8.5.0 203 */ 204 groupEnd(): void; 205 /** 206 * The `console.info()` function is an alias for {@link log}. 207 * @since v0.1.100 208 */ 209 info(message?: any, ...optionalParams: any[]): void; 210 /** 211 * Prints to `stdout` with newline. Multiple arguments can be passed, with the 212 * first used as the primary message and all additional used as substitution 213 * values similar to [`printf(3)`](http://man7.org/linux/man-pages/man3/printf.3.html) 214 * (the arguments are all passed to [`util.format()`](https://nodejs.org/docs/latest-v16.x/api/util.html#utilformatformat-args)). 215 * 216 * ```js 217 * const count = 5; 218 * console.log('count: %d', count); 219 * // Prints: count: 5, to stdout 220 * console.log('count:', count); 221 * // Prints: count: 5, to stdout 222 * ``` 223 * 224 * See [`util.format()`](https://nodejs.org/docs/latest-v16.x/api/util.html#utilformatformat-args) for more information. 225 * @since v0.1.100 226 */ 227 log(message?: any, ...optionalParams: any[]): void; 228 /** 229 * Try to construct a table with the columns of the properties of `tabularData` (or use `properties`) and rows of `tabularData` and log it. Falls back to just 230 * logging the argument if it can't be parsed as tabular. 231 * 232 * ```js 233 * // These can't be parsed as tabular data 234 * console.table(Symbol()); 235 * // Symbol() 236 * 237 * console.table(undefined); 238 * // undefined 239 * 240 * console.table([{ a: 1, b: 'Y' }, { a: 'Z', b: 2 }]); 241 * // ┌─────────┬─────┬─────┐ 242 * // │ (index) │ a │ b │ 243 * // ├─────────┼─────┼─────┤ 244 * // │ 0 │ 1 │ 'Y' │ 245 * // │ 1 │ 'Z' │ 2 │ 246 * // └─────────┴─────┴─────┘ 247 * 248 * console.table([{ a: 1, b: 'Y' }, { a: 'Z', b: 2 }], ['a']); 249 * // ┌─────────┬─────┐ 250 * // │ (index) │ a │ 251 * // ├─────────┼─────┤ 252 * // │ 0 │ 1 │ 253 * // │ 1 │ 'Z' │ 254 * // └─────────┴─────┘ 255 * ``` 256 * @since v10.0.0 257 * @param properties Alternate properties for constructing the table. 258 */ 259 table(tabularData: any, properties?: readonly string[]): void; 260 /** 261 * Starts a timer that can be used to compute the duration of an operation. Timers 262 * are identified by a unique `label`. Use the same `label` when calling {@link timeEnd} to stop the timer and output the elapsed time in 263 * suitable time units to `stdout`. For example, if the elapsed 264 * time is 3869ms, `console.timeEnd()` displays "3.869s". 265 * @since v0.1.104 266 * @param [label='default'] 267 */ 268 time(label?: string): void; 269 /** 270 * Stops a timer that was previously started by calling {@link time} and 271 * prints the result to `stdout`: 272 * 273 * ```js 274 * console.time('bunch-of-stuff'); 275 * // Do a bunch of stuff. 276 * console.timeEnd('bunch-of-stuff'); 277 * // Prints: bunch-of-stuff: 225.438ms 278 * ``` 279 * @since v0.1.104 280 * @param [label='default'] 281 */ 282 timeEnd(label?: string): void; 283 /** 284 * For a timer that was previously started by calling {@link time}, prints 285 * the elapsed time and other `data` arguments to `stdout`: 286 * 287 * ```js 288 * console.time('process'); 289 * const value = expensiveProcess1(); // Returns 42 290 * console.timeLog('process', value); 291 * // Prints "process: 365.227ms 42". 292 * doExpensiveProcess2(value); 293 * console.timeEnd('process'); 294 * ``` 295 * @since v10.7.0 296 * @param [label='default'] 297 */ 298 timeLog(label?: string, ...data: any[]): void; 299 /** 300 * Prints to `stderr` the string `'Trace: '`, followed by the [`util.format()`](https://nodejs.org/docs/latest-v16.x/api/util.html#utilformatformat-args) 301 * formatted message and stack trace to the current position in the code. 302 * 303 * ```js 304 * console.trace('Show me'); 305 * // Prints: (stack trace will vary based on where trace is called) 306 * // Trace: Show me 307 * // at repl:2:9 308 * // at REPLServer.defaultEval (repl.js:248:27) 309 * // at bound (domain.js:287:14) 310 * // at REPLServer.runBound [as eval] (domain.js:300:12) 311 * // at REPLServer.<anonymous> (repl.js:412:12) 312 * // at emitOne (events.js:82:20) 313 * // at REPLServer.emit (events.js:169:7) 314 * // at REPLServer.Interface._onLine (readline.js:210:10) 315 * // at REPLServer.Interface._line (readline.js:549:8) 316 * // at REPLServer.Interface._ttyWrite (readline.js:826:14) 317 * ``` 318 * @since v0.1.104 319 */ 320 trace(message?: any, ...optionalParams: any[]): void; 321 /** 322 * The `console.warn()` function is an alias for {@link error}. 323 * @since v0.1.100 324 */ 325 warn(message?: any, ...optionalParams: any[]): void; 326 // --- Inspector mode only --- 327 /** 328 * This method does not display anything unless used in the inspector. The `console.profile()` 329 * method starts a JavaScript CPU profile with an optional label until {@link profileEnd} 330 * is called. The profile is then added to the Profile panel of the inspector. 331 * 332 * ```js 333 * console.profile('MyLabel'); 334 * // Some code 335 * console.profileEnd('MyLabel'); 336 * // Adds the profile 'MyLabel' to the Profiles panel of the inspector. 337 * ``` 338 * @since v8.0.0 339 */ 340 profile(label?: string): void; 341 /** 342 * This method does not display anything unless used in the inspector. Stops the current 343 * JavaScript CPU profiling session if one has been started and prints the report to the 344 * Profiles panel of the inspector. See {@link profile} for an example. 345 * 346 * If this method is called without a label, the most recently started profile is stopped. 347 * @since v8.0.0 348 */ 349 profileEnd(label?: string): void; 350 /** 351 * This method does not display anything unless used in the inspector. The `console.timeStamp()` 352 * method adds an event with the label `'label'` to the Timeline panel of the inspector. 353 * @since v8.0.0 354 */ 355 timeStamp(label?: string): void; 356 } 357 /** 358 * The `console` module provides a simple debugging console that is similar to the 359 * JavaScript console mechanism provided by web browsers. 360 * 361 * The module exports two specific components: 362 * 363 * * A `Console` class with methods such as `console.log()`, `console.error()` and `console.warn()` that can be used to write to any Node.js stream. 364 * * A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v16.x/api/process.html#processstdout) and 365 * [`process.stderr`](https://nodejs.org/docs/latest-v16.x/api/process.html#processstderr). The global `console` can be used without importing the `node:console` module. 366 * 367 * _**Warning**_: The global console object's methods are neither consistently 368 * synchronous like the browser APIs they resemble, nor are they consistently 369 * asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v16.x/api/process.html#a-note-on-process-io) for 370 * more information. 371 * 372 * Example using the global `console`: 373 * 374 * ```js 375 * console.log('hello world'); 376 * // Prints: hello world, to stdout 377 * console.log('hello %s', 'world'); 378 * // Prints: hello world, to stdout 379 * console.error(new Error('Whoops, something bad happened')); 380 * // Prints error message and stack trace to stderr: 381 * // Error: Whoops, something bad happened 382 * // at [eval]:5:15 383 * // at Script.runInThisContext (node:vm:132:18) 384 * // at Object.runInThisContext (node:vm:309:38) 385 * // at node:internal/process/execution:77:19 386 * // at [eval]-wrapper:6:22 387 * // at evalScript (node:internal/process/execution:76:60) 388 * // at node:internal/main/eval_string:23:3 389 * 390 * const name = 'Will Robinson'; 391 * console.warn(`Danger ${name}! Danger!`); 392 * // Prints: Danger Will Robinson! Danger!, to stderr 393 * ``` 394 * 395 * Example using the `Console` class: 396 * 397 * ```js 398 * const out = getStreamSomehow(); 399 * const err = getStreamSomehow(); 400 * const myConsole = new console.Console(out, err); 401 * 402 * myConsole.log('hello world'); 403 * // Prints: hello world, to out 404 * myConsole.log('hello %s', 'world'); 405 * // Prints: hello world, to out 406 * myConsole.error(new Error('Whoops, something bad happened')); 407 * // Prints: [Error: Whoops, something bad happened], to err 408 * 409 * const name = 'Will Robinson'; 410 * myConsole.warn(`Danger ${name}! Danger!`); 411 * // Prints: Danger Will Robinson! Danger!, to err 412 * ``` 413 * @see [source](https://github.com/nodejs/node/blob/v16.20.2/lib/console.js) 414 */ 415 namespace console { 416 interface ConsoleConstructorOptions { 417 stdout: NodeJS.WritableStream; 418 stderr?: NodeJS.WritableStream | undefined; 419 /** 420 * Ignore errors when writing to the underlying streams. 421 * @default true 422 */ 423 ignoreErrors?: boolean | undefined; 424 /** 425 * Set color support for this `Console` instance. Setting to true enables coloring while inspecting 426 * values. Setting to `false` disables coloring while inspecting values. Setting to `'auto'` makes color 427 * support depend on the value of the `isTTY` property and the value returned by `getColorDepth()` on the 428 * respective stream. This option can not be used, if `inspectOptions.colors` is set as well. 429 * @default auto 430 */ 431 colorMode?: boolean | "auto" | undefined; 432 /** 433 * Specifies options that are passed along to 434 * [`util.inspect()`](https://nodejs.org/docs/latest-v16.x/api/util.html#utilinspectobject-options). 435 */ 436 inspectOptions?: InspectOptions | undefined; 437 /** 438 * Set group indentation. 439 * @default 2 440 */ 441 groupIndentation?: number | undefined; 442 } 443 interface ConsoleConstructor { 444 prototype: Console; 445 new(stdout: NodeJS.WritableStream, stderr?: NodeJS.WritableStream, ignoreErrors?: boolean): Console; 446 new(options: ConsoleConstructorOptions): Console; 447 } 448 } 449 var console: Console; 450 } 451 export = globalThis.console; 452 }