console: add console.count() and console.clear()

Both are simple utility functions defined by the WHATWG console spec (https://console.spec.whatwg.org/). PR-URL: #12678 Ref: #12675 Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Daijiro Wachi <[email protected]> Reviewed-By: Timothy Gu <[email protected]> Reviewed-By: Tobias Nießen <[email protected]>

Author: jasnell

doc/api/console.md

@@ -155,6 +155,76 @@ console.assert(false, 'this message will print, but no error thrown');
 console.log('this will also print');
 ```
 
+### console.clear()
+<!-- YAML
+added: REPLACEME
+-->
+
+When `stdout` is a TTY, calling `console.clear()` will attempt to clear the
+TTY. When `stdout` is not a TTY, this method does nothing.
+
+*Note*: The specific operation of `console.clear()` can vary across operating
+systems 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 current terminal viewport for the Node.js
+binary.
+
+### console.count([label])
+<!-- YAML
+added: REPLACEME
+-->
+
+*`label`{string} The display label for the counter. Defaults to `'default'`.
+
+Maintains an internal counter specific to `label` and outputs to `stdout` the
+number of times `console.count()` has been called with the given `label`.
+
+<!-- eslint-skip -->
+```js
+>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 = 'default'])
+<!-- YAML
+added: REPLACEME
+-->
+
+*`label`{string} The display label for the counter. Defaults to `'default'`.
+
+Resets the internal counter specific to `label`.
+
+<!-- eslint-skip -->
+```js
+>console.count('abc');
+abc:1
+undefined
+>console.countReset('abc');
+undefined
+>console.count('abc');
+abc:1
+undefined
+>
+```
+<!-- eslint-enable -->
+
 ### console.dir(obj[, options])
 <!-- YAML
 added: v0.1.101

lib/console.js

@@ -1,6 +1,7 @@
 'use strict';
 
 constutil=require('util');
+constkCounts=Symbol('counts');
 
 functionConsole(stdout,stderr){
 if(!(thisinstanceofConsole)){
@@ -27,6 +28,8 @@ function Console(stdout, stderr){
 prop.value=newMap();
 Object.defineProperty(this,'_times',prop);
 
+this[kCounts]=newMap();
+
 // bind the prototype functions to this Console instance
 varkeys=Object.keys(Console.prototype);
 for(varv=0;v<keys.length;v++){
@@ -96,6 +99,42 @@ Console.prototype.assert = function(expression, ...args){
 }
 };
 
+// Defined by: https://console.spec.whatwg.org/#clear
+Console.prototype.clear=functionclear(){
+// It only makes sense to clear if _stdout is a TTY.
+// Otherwise, do nothing.
+if(this._stdout.isTTY){
+// The require is here intentionally to avoid readline being
+// required too early when console is first loaded.
+const{ cursorTo, clearScreenDown }=require('readline');
+cursorTo(this._stdout,0,0);
+clearScreenDown(this._stdout);
+}
+};
+
+// Defined by: https://console.spec.whatwg.org/#count
+Console.prototype.count=functioncount(label='default'){
+// Ensures that label is a string, and only things that can be
+// coerced to strings. e.g. Symbol is not allowed
+label=`${label}`;
+constcounts=this[kCounts];
+letcount=counts.get(label);
+if(count===undefined)
+count=1;
+else
+count++;
+counts.set(label,count);
+this.log(`${label}: ${count}`);
+};
+
+// Not yet defined by the https://console.spec.whatwg.org, but
+// proposed to be added and currently implemented by Edge. Having
+// the ability to reset counters is important to help prevent
+// the counter from being a memory leak.
+Console.prototype.countReset=functioncountReset(label='default'){
+constcounts=this[kCounts];
+counts.delete(`${label}`);
+};
 
 module.exports=newConsole(process.stdout,process.stderr);
 module.exports.Console=Console;

test/parallel/test-console-clear.js

@@ -0,0 +1,22 @@
+'use strict';
+
+require('../common');
+constassert=require('assert');
+
+conststdoutWrite=process.stdout.write;
+
+// The sequence for moving the cursor to 0,0 and clearing screen down
+constcheck='\u001b[1;1H\u001b[0J';
+
+functiondoTest(isTTY,check){
+letbuf='';
+process.stdout.isTTY=isTTY;
+process.stdout.write=(string)=>buf+=string;
+console.clear();
+process.stdout.write=stdoutWrite;
+assert.strictEqual(buf,check);
+}
+
+// Fake TTY
+doTest(true,check);
+doTest(false,'');

test/parallel/test-console-count.js

@@ -0,0 +1,63 @@
+'use strict';
+
+require('../common');
+constassert=require('assert');
+
+conststdoutWrite=process.stdout.write;
+
+letbuf='';
+
+process.stdout.write=(string)=>buf=string;
+
+console.count();
+assert.strictEqual(buf,'default: 1\n');
+
+// 'default' and undefined are equivalent
+console.count('default');
+assert.strictEqual(buf,'default: 2\n');
+
+console.count('a');
+assert.strictEqual(buf,'a: 1\n');
+
+console.count('b');
+assert.strictEqual(buf,'b: 1\n');
+
+console.count('a');
+assert.strictEqual(buf,'a: 2\n');
+
+console.count();
+assert.strictEqual(buf,'default: 3\n');
+
+console.count({});
+assert.strictEqual(buf,'[object Object]: 1\n');
+
+console.count(1);
+assert.strictEqual(buf,'1: 1\n');
+
+console.count(null);
+assert.strictEqual(buf,'null: 1\n');
+
+console.count('null');
+assert.strictEqual(buf,'null: 2\n');
+
+console.countReset();
+console.count();
+assert.strictEqual(buf,'default: 1\n');
+
+console.countReset('a');
+console.count('a');
+assert.strictEqual(buf,'a: 1\n');
+
+// countReset('a') only reset the a counter
+console.count();
+assert.strictEqual(buf,'default: 2\n');
+
+process.stdout.write=stdoutWrite;
+
+// Symbol labels do not work
+assert.throws(
+()=>console.count(Symbol('test')),
+/^TypeError:CannotconvertaSymbolvaluetoastring$/);
+assert.throws(
+()=>console.countReset(Symbol('test')),
+/^TypeError:CannotconvertaSymbolvaluetoastring$/);