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, as produced by the %o and %O specifiers). 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.

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. 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. Interface Console

[NoInterfaceObject, Exposed=(Window,Worker)]
interface Console {
  // Logging
  void assert(optional boolean condition = false, any... data);
  void clear();
  void count(optional DOMString label = "");
  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);

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

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

partial interface Window {
  [Replaceable] readonly attribute Console console;
};

partial interface WorkerGlobalScope {
  [Replaceable] readonly attribute Console console;
};

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.

2.1. Logging methods

2.1.1. assert(condition, ...data)

If condition is false, perform Logger("error", data).

2.1.2. clear()

If possible for the environment, clear the console. Otherwise, do nothing.

2.1.3. count(label)