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: https://github.com/nodejs/node/pull/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>

1 files changed, 9 insertions, 1 deletions

diff --git a/doc/api/readline.md b/doc/api/readline.md
index b295ace5b3f..936ffb5d842 100644
--- a/doc/api/readline.md
+++ b/doc/api/readline.md
@@ -346,9 +346,13 @@ 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}
@@ -356,6 +360,10 @@ added: v0.7.7
   * `-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`.