readline: expose stream API in clearScreenDown()

This commit adds an optional callback to clearScreenDown(),
which is passed to the stream's write() method. It also
exposes the return value of write().

PR-URL: #28641
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>

doc/api/readline.md

@@ -360,12 +360,20 @@ added: v0.7.7
 The `readline.clearLine()` method clears current line of given [TTY][] stream
 in a specified direction identified by `dir`.
 
-## readline.clearScreenDown(stream)
+## readline.clearScreenDown(stream[, callback])
 <!-- YAML
 added: v0.7.7
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/28641
+    description: The stream's write() callback and return value are exposed.
 -->
 
 * `stream` {stream.Writable}
+* `callback` {Function} Invoked once the operation completes.
+* Returns: {boolean} `false` if `stream` wishes for the calling code to wait for
+  the `'drain'` event to be emitted before continuing to write additional data;
+  otherwise `true`.
 
 The `readline.clearScreenDown()` method clears the given [TTY][] stream from
 the current position of the cursor down.

lib/readline.js

@@ -30,6 +30,7 @@
 const { Math, Object } = primordials;
 
 const {
+  ERR_INVALID_CALLBACK,
   ERR_INVALID_CURSOR_POS,
   ERR_INVALID_OPT_VALUE
 } = require('internal/errors').codes;
@@ -1253,11 +1254,17 @@ function clearLine(stream, dir) {
  * clears the screen from the current position of the cursor down
  */
 
-function clearScreenDown(stream) {
-  if (stream === null || stream === undefined)
-    return;
+function clearScreenDown(stream, callback) {
+  if (callback !== undefined && typeof callback !== 'function')
+    throw new ERR_INVALID_CALLBACK(callback);
+
+  if (stream === null || stream === undefined) {
+    if (typeof callback === 'function')
+      process.nextTick(callback);
+    return true;
+  }
 
-  stream.write(kClearScreenDown);
+  return stream.write(kClearScreenDown, callback);
 }
 
 module.exports = {

test/parallel/test-readline-csi.js

@@ -29,8 +29,19 @@ class TestWritable extends Writable {
 
 const writable = new TestWritable();
 
-readline.clearScreenDown(writable);
+assert.strictEqual(readline.clearScreenDown(writable), true);
 assert.deepStrictEqual(writable.data, CSI.kClearScreenDown);
+assert.strictEqual(readline.clearScreenDown(writable, common.mustCall()), true);
+
+// Verify that clearScreenDown() throws on invalid callback.
+assert.throws(() => {
+  readline.clearScreenDown(writable, null);
+}, /ERR_INVALID_CALLBACK/);
+
+// Verify that clearScreenDown() does not throw on null or undefined stream.
+assert.strictEqual(readline.clearScreenDown(null, common.mustCall()), true);
+assert.strictEqual(readline.clearScreenDown(undefined, common.mustCall()),
+                   true);
 
 writable.data = '';
 readline.clearLine(writable, -1);