readline: expose stream API in clearLine()

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

PR-URL: #28674
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>

doc/api/readline.md

@@ -346,16 +346,24 @@ async function processLineByLine() {
 }
 ```
 
-## readline.clearLine(stream, dir)
+## readline.clearLine(stream, dir[, callback])
 <!-- YAML
 added: v0.7.7
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/28674
+    description: The stream's write() callback and return value are exposed.
 -->
 
 * `stream` {stream.Writable}
 * `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 `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.clearLine()` method clears current line of given [TTY][] stream
 in a specified direction identified by `dir`.

lib/readline.js

@@ -1234,20 +1234,18 @@ function moveCursor(stream, dx, dy) {
  *    0 for the entire line
  */
 
-function clearLine(stream, dir) {
-  if (stream === null || stream === undefined)
-    return;
+function clearLine(stream, dir, callback) {
+  if (callback !== undefined && typeof callback !== 'function')
+    throw new ERR_INVALID_CALLBACK(callback);
 
-  if (dir < 0) {
-    // to the beginning
-    stream.write(kClearToBeginning);
-  } else if (dir > 0) {
-    // to the end
-    stream.write(kClearToEnd);
-  } else {
-    // entire line
-    stream.write(kClearLine);
+  if (stream === null || stream === undefined) {
+    if (typeof callback === 'function')
+      process.nextTick(callback);
+    return true;
   }
+
+  const type = dir < 0 ? kClearToBeginning : dir > 0 ? kClearToEnd : kClearLine;
+  return stream.write(type, callback);
 }
 
 /**

test/parallel/test-readline-csi.js

@@ -44,17 +44,32 @@ assert.strictEqual(readline.clearScreenDown(undefined, common.mustCall()),
                    true);
 
 writable.data = '';
-readline.clearLine(writable, -1);
+assert.strictEqual(readline.clearLine(writable, -1), true);
 assert.deepStrictEqual(writable.data, CSI.kClearToBeginning);
 
 writable.data = '';
-readline.clearLine(writable, 1);
+assert.strictEqual(readline.clearLine(writable, 1), true);
 assert.deepStrictEqual(writable.data, CSI.kClearToEnd);
 
 writable.data = '';
-readline.clearLine(writable, 0);
+assert.strictEqual(readline.clearLine(writable, 0), true);
 assert.deepStrictEqual(writable.data, CSI.kClearLine);
 
+writable.data = '';
+assert.strictEqual(readline.clearLine(writable, -1, common.mustCall()), true);
+assert.deepStrictEqual(writable.data, CSI.kClearToBeginning);
+
+// Verify that clearLine() throws on invalid callback.
+assert.throws(() => {
+  readline.clearLine(writable, 0, null);
+}, /ERR_INVALID_CALLBACK/);
+
+// Verify that clearLine() does not throw on null or undefined stream.
+assert.strictEqual(readline.clearLine(null, 0), true);
+assert.strictEqual(readline.clearLine(undefined, 0), true);
+assert.strictEqual(readline.clearLine(null, 0, common.mustCall()), true);
+assert.strictEqual(readline.clearLine(undefined, 0, common.mustCall()), true);
+
 // Nothing is written when moveCursor 0, 0
 [
   [0, 0, ''],