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: nodejs#28721
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>

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);
+  return readline.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);
+  return readline.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);
+  return readline.clearLine(this, dir, callback);
 };
-WriteStream.prototype.clearScreenDown = function() {
+WriteStream.prototype.clearScreenDown = function(callback) {
   if (readline === undefined) readline = require('readline');
-  readline.clearScreenDown(this);
+  return readline.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';
 const common = require('../common');
+const assert = require('assert');
+const readline = require('readline');
 
 const noop = () => {};
 const { internalBinding } = require('internal/test/binding');
@@ -13,15 +15,32 @@ TTY.prototype = {
 
 const { WriteStream } = require('tty');
 
-const methods = [
+[
   'cursorTo',
   'moveCursor',
   'clearLine',
   'clearScreenDown'
-];
+].forEach((method) => {
+  readline[method] = common.mustCall(function() {
+    const lastArg = arguments[arguments.length - 1];
 
-methods.forEach((method) => {
-  require('readline')[method] = common.mustCall();
-  const writeStream = new WriteStream(1);
-  writeStream[method](1, 2);
+    if (typeof lastArg === 'function') {
+      process.nextTick(lastArg);
+    }
+
+    return true;
+  }, 2);
 });
+
+const writeStream = new WriteStream(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);