tty: expose stream API from readline methods

This commit exposes the return value and callback of the
underlying readline APIs from the tty module.
PR-URL: #28721
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>

Author: cjihrig

doc/api/tty.md

@@ -99,24 +99,41 @@ process.stdout.on('resize', () => {
 });
 ```
 
-### writeStream.clearLine(dir)
+### writeStream.clearLine(dir[, callback])
 <!-- YAML
 added: v0.7.7
+changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/28721
+ description: The stream's write() callback and return value are exposed.
 -->
 
 *`dir` {number}
 *`-1` - to the left from cursor
 *`1` - to the right from cursor
 *`0` - the entire line
+*`callback` {Function} Invoked once the operation completes.
+* Returns: {boolean} `false` if the stream wishes for the calling code to wait
+ for the `'drain'` event to be emitted before continuing to write additional
+ data; otherwise `true`.
 
 `writeStream.clearLine()` clears the current line of this `WriteStream` in a
 direction identified by `dir`.
 
-### writeStream.clearScreenDown()
+### writeStream.clearScreenDown([callback])
 <!-- YAML
 added: v0.7.7
+changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/28721
+ description: The stream's write() callback and return value are exposed.
 -->
 
+*`callback` {Function} Invoked once the operation completes.
+* Returns: {boolean} `false` if the stream wishes for the calling code to wait
+ for the `'drain'` event to be emitted before continuing to write additional
+ data; otherwise `true`.
+
 `writeStream.clearScreenDown()` clears this `WriteStream` from the current
 cursor down.
 
@@ -128,13 +145,21 @@ added: v0.7.7
 A `number` specifying the number of columns the TTY currently has. This property
 is updated whenever the `'resize'` event is emitted.
 
-### writeStream.cursorTo(x, y)
+### writeStream.cursorTo(x, y[, callback])
 <!-- YAML
 added: v0.7.7
+changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/28721
+ description: The stream's write() callback and return value are exposed.
 -->
 
 *`x` {number}
 *`y` {number}
+*`callback` {Function} Invoked once the operation completes.
+* Returns: {boolean} `false` if the stream wishes for the calling code to wait
+ for the `'drain'` event to be emitted before continuing to write additional
+ data; otherwise `true`.
 
 `writeStream.cursorTo()` moves this `WriteStream`'s cursor to the specified
 position.
@@ -220,13 +245,21 @@ added: v0.5.8
 
 A `boolean` that is always `true`.
 
-### writeStream.moveCursor(dx, dy)
+### writeStream.moveCursor(dx, dy[, callback])
 <!-- YAML
 added: v0.7.7
+changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/28721
+ description: The stream's write() callback and return value are exposed.
 -->
 
 *`dx` {number}
 *`dy` {number}
+*`callback` {Function} Invoked once the operation completes.
+* Returns: {boolean} `false` if the stream wishes for the calling code to wait
+ for the `'drain'` event to be emitted before continuing to write additional
+ data; otherwise `true`.
 
 `writeStream.moveCursor()` moves this `WriteStream`'s cursor *relative* to its
 current position.

lib/tty.js

@@ -137,21 +137,21 @@ WriteStream.prototype._refreshSize = function() {
 };
 
 // Backwards-compat
-WriteStream.prototype.cursorTo=function(x,y){
+WriteStream.prototype.cursorTo=function(x,y,callback){
 if(readline===undefined)readline=require('readline');
-readline.cursorTo(this,x,y);
+returnreadline.cursorTo(this,x,y,callback);
 };
-WriteStream.prototype.moveCursor=function(dx,dy){
+WriteStream.prototype.moveCursor=function(dx,dy,callback){
 if(readline===undefined)readline=require('readline');
-readline.moveCursor(this,dx,dy);
+returnreadline.moveCursor(this,dx,dy,callback);
 };
-WriteStream.prototype.clearLine=function(dir){
+WriteStream.prototype.clearLine=function(dir,callback){
 if(readline===undefined)readline=require('readline');
-readline.clearLine(this,dir);
+returnreadline.clearLine(this,dir,callback);
 };
-WriteStream.prototype.clearScreenDown=function(){
+WriteStream.prototype.clearScreenDown=function(callback){
 if(readline===undefined)readline=require('readline');
-readline.clearScreenDown(this);
+returnreadline.clearScreenDown(this,callback);
 };
 WriteStream.prototype.getWindowSize=function(){
 return[this.columns,this.rows];

test/parallel/test-tty-backwards-api.js

@@ -1,6 +1,8 @@
 // Flags: --expose-internals
 'use strict';
 constcommon=require('../common');
+constassert=require('assert');
+constreadline=require('readline');
 
 constnoop=()=>{};
 const{ internalBinding }=require('internal/test/binding');
@@ -13,15 +15,32 @@ TTY.prototype = {
 
 const{ WriteStream }=require('tty');
 
-constmethods=[
+[
 'cursorTo',
 'moveCursor',
 'clearLine',
 'clearScreenDown'
-];
+].forEach((method)=>{
+readline[method]=common.mustCall(function(){
+constlastArg=arguments[arguments.length-1];
 
-methods.forEach((method)=>{
-require('readline')[method]=common.mustCall();
-constwriteStream=newWriteStream(1);
-writeStream[method](1,2);
+if(typeoflastArg==='function'){
+process.nextTick(lastArg);
+}
+
+returntrue;
+},2);
 });
+
+constwriteStream=newWriteStream(1);
+
+// Verify that the corresponding readline methods are called, that the return
+// values are propagated, and any callbacks are invoked.
+assert.strictEqual(writeStream.cursorTo(1,2),true);
+assert.strictEqual(writeStream.cursorTo(1,2,common.mustCall()),true);
+assert.strictEqual(writeStream.moveCursor(1,2),true);
+assert.strictEqual(writeStream.moveCursor(1,2,common.mustCall()),true);
+assert.strictEqual(writeStream.clearLine(1),true);
+assert.strictEqual(writeStream.clearLine(1,common.mustCall()),true);
+assert.strictEqual(writeStream.clearScreenDown(),true);
+assert.strictEqual(writeStream.clearScreenDown(common.mustCall()),true);