Console

Status

This specification is an early work in progress that welcomes feedback to refine toward more precise and compatible definitions. It is also the editors' first specification, so please be kind and constructive.

Please join us in the issue tracker for more discussion.

1. Supporting abstract operations

1.1. Logger(logLevel, args)

The logger operation accepts a log level and a List of other arguments. Its main output is the implementation-defined side effect of printing the result to the console. This specification describes how it processes format specifiers while doing so.

1.2. Formatter(args)

The formatter operation tries to format the first argument provided, using the other arguments. It will try to format the input until no formatting specifiers are left in the first argument, or no more arguments are left. It returns a List of objects suitable for printing.

1.2.1. Summary of formatting specifiers

The following is an informative summary of the format specifiers processed by the above algorithm.

1.3. Printer(logLevel, args)

The printer operation is implementation-defined. It accepts a log level indicating severity, and a List of arguments to print (which are either JavaScript objects, of any type, or are implementation-specific representations of printable things such as a stack trace, a group, or objects with either generic JavaScript object formatting or optimally useful formatting applied). How the implementation prints args is up to the implementation, but implementations should separate the objects by a space or something similar, as that has become a developer expectation.

By the time the printer operation is called, all format specifiers will have been taken into account, and any arguments that are meant to be consumed by format specifiers will not be present in args. The implementation’s job is simply to print the List. The output produced by calls to Printer should appear only within the last group on the appropriate group stack if the group stack is not empty, or in the elsewhere in the console otherwise.

If the console is not open when the printer operation is called, implementations should buffer messages to show them in the future up to an implementation-chosen limit (typically on the order of at least 100).

1.3.1. Common Object Formats

Typically objects will be printed in a format that is suitable for their context. This section describes common ways in which objects are formatted to be most useful in their context. It should be noted that the formatting described in this section is applied to implementation-specific object representations that will eventually be passed into Printer, where the actual side effect of formatting will be seen.

An object with generic JavaScript object formatting is a potentially expandable representation of a generic JavaScript object. An object with optimally useful formatting is an implementation-specific, potentially-interactive representation of an object judged to be maximally useful and informative.

1.3.2. Example printer in Node.js

const util = require('util');

function print(logLevel, ...args) {
  const message = util.format(...args);

  if (logLevel === 'error') {
    process.stderr.write(message + '\n');
  } else if (logLevel === 'log' || logLevel === 'info' || logLevel === 'warn') {
    process.stdout.write(message + '\n');
  }
}

print('log', 'duck', [{foo: 'bar'}]);     // prints: `duck [ { foo: 'bar' } ]\n` on stdout
print('log', 'duck', false);              // prints: `duck false\n` on stdout
print('log', 'duck', undefined);          // prints: `duck undefined\n` on stdout

2. Namespace console

[Exposed=(Window,Worker,Worklet)]
namespace console { // but see namespace object requirements below
  // Logging
  void assert(optional boolean condition = false, any... data);
  void clear();
  void count(optional DOMString label = "default");
  void debug(any... data);
  void error(any... data);
  void info(any... data);
  void log(any... data);
  void table(any tabularData, optional sequence<DOMString> properties);
  void trace(any... data);
  void warn(any... data);
  void dir(any item);
  void dirxml(any... data);

  // Grouping
  void group(any... data);
  void groupCollapsed(any... data);
  void groupEnd();

  // Timing
  void time(optional DOMString label = "default");
  void timeEnd(optional DOMString label = "default");
};

For historical reasons, console is lowercased.

It is important that console is always visible and usable to scripts, even if the developer console has not been opened or does not exist.

For historical web-compatibility reasons, the namespace object for console must have as its [[Prototype]] an empty object, created as if by ObjectCreate(%ObjectPrototype%), instead of %ObjectPrototype%.

2.1. Logging methods

2.1.1. assert(condition, ...data)

2.1.2. clear()

Empty the appropriate group stack, and if possible for the environment, clear the console. Otherwise, do nothing.

2.1.3. count(label)

2.1.4. debug(...data)

Perform Logger("log", data).

2.1.5. error(...data)

Perform Logger("error", data).

2.1.6. info(...data)

Perform Logger("info", data).

2.1.7. log(...data)

Perform Logger("log", data).

2.1.8. table(tabularData, properties)

Try to construct a table with the columns of the properties of tabularData (or use properties) and rows of tabularData and log it with a logLevel of log. Fall back to just logging the argument if it can’t be parsed as tabular.

TODO: This will need a good algorithm.

2.1.9. trace(...data)

The identifier of a function printed in a stack trace is implementation-dependant. It is also not guaranteed to be the same identifier that would be seen in new Error().stack

2.1.10. warn(...data)

Perform Logger("warn", data).

2.1.11. dir(item)

2.1.12. dirxml(...data)

2.2. Grouping methods

A group is an implementation-specific, potentially-interactive view for output produced by calls to Printer, with one further level of indentation than its parent. Each console namespace object has an associated group stack, which is a stack, initially empty. Only the last group in a group stack will host output produced by calls to Printer.

2.2.1. group(...data)

2.2.2. groupCollapsed(...data)

2.2.3. groupEnd()

Pop the last group from the group stack.

2.3. Timing methods

2.3.1. time(label)

Start an internal timer stored in the timer table with key label.

2.3.2. timeEnd(label)

Let duration be the current value of the internal timer with key label in the timer table. Remove the timer from the timer table. Then, perform Logger("info", «label, duration»).

3. JavaScript object inspection

TODO: Define an interface that allows JavaScript objects to format themselves for inspection.

Acknowledgments

The editors would like to thank Boris Zbarsky, Brent S.A. Cowgill, Brian Grinstead, Corey Farwell, Ian Kilpatrick, Jeff Carpenter, Joseph Pecoraro, Justin Woo, Noah Bass, Paul Irish, Raphaël, and Victor Costan for their contributions to this specification. You are awesome!

This standard is written by Terin Stock (terin@terinstock.com), Robert Kowalski (rok@kowalski.gd), and Dominic Farolino (domfarolino@gmail.com) with major help from Domenic Denicola (Google, d@domenic.me).

Per CC0, to the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work.