From 17df75f5c961bfbaddf8f18359ccc7d18092c5c2 Mon Sep 17 00:00:00 2001
From: cjihrig <cjihrig@gmail.com>
Date: Thu, 11 Jul 2019 12:35:34 -0400
Subject: [PATCH] readline: expose stream API in clearScreenDown()
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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: https://github.com/nodejs/node/pull/28641
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
---
 doc/api/readline.md                | 10 +++++++++-
 lib/readline.js                    | 15 +++++++++++----
 test/parallel/test-readline-csi.js | 13 ++++++++++++-
 3 files changed, 32 insertions(+), 6 deletions(-)

diff --git a/doc/api/readline.md b/doc/api/readline.md
index 8f372a8473e06d..b295ace5b3f00b 100644
--- a/doc/api/readline.md
+++ b/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.
diff --git a/lib/readline.js b/lib/readline.js
index b480a31baec7d9..fe0c093a5624a7 100644
--- a/lib/readline.js
+++ b/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 = {
diff --git a/test/parallel/test-readline-csi.js b/test/parallel/test-readline-csi.js
index 25d5a5eb6e79d7..c753c5d93c26ec 100644
--- a/test/parallel/test-readline-csi.js
+++ b/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);