readline: add history event and option to set initial history

Add a history event which is emitted when the history has
been changed. This enables persisting of the history in
some way but also to allows a listener to alter the
history. One use-case could be to prevent passwords from
ending up in the history.

A constructor option is also added to allow for setting
an initial history list when creating a Readline interface.

PR-URL: https://github.com/nodejs/node/pull/33662
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

1 files changed, 32 insertions, 3 deletions

diff --git a/doc/api/readline.md b/doc/api/readline.md
index 38c4cb2f106..2a2a0018a3d 100644
--- a/doc/api/readline.md
+++ b/doc/api/readline.md
@@ -88,6 +88,28 @@ rl.on('line', (input) => {
 });
 ```
 
+### Event: `'history'`
+<!-- YAML
+added: REPLACEME
+-->
+
+The `'history'` event is emitted whenever the history array has changed.
+
+The listener function is called with an array containing the history array.
+It will reflect all changes, added lines and removed lines due to
+`historySize` and `removeHistoryDuplicates`.
+
+The primary purpose is to allow a listener to persist the history.
+It is also possible for the listener to change the history object. This
+could be useful to prevent certain lines to be added to the history, like
+a password.
+
+```js
+rl.on('history', (history) => {
+  console.log(`Received: ${history}`);
+});
+```
+
 ### Event: `'pause'`
 <!-- YAML
 added: v0.7.5
@@ -522,6 +544,9 @@ the current position of the cursor down.
 <!-- YAML
 added: v0.1.98
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/33662
+    description: The `history` option is supported now.
   - version: v13.9.0
     pr-url: https://github.com/nodejs/node/pull/31318
     description: The `tabSize` option is supported now.
@@ -550,11 +575,18 @@ changes:
   * `terminal` {boolean} `true` if the `input` and `output` streams should be
     treated like a TTY, and have ANSI/VT100 escape codes written to it.
     **Default:** checking `isTTY` on the `output` stream upon instantiation.
+  * `history` {string[]} Initial list of history lines. This option makes sense
+    only if `terminal` is set to `true` by the user or by an internal `output`
+    check, otherwise the history caching mechanism is not initialized at all.
+    **Default:** `[]`.
   * `historySize` {number} Maximum number of history lines retained. To disable
     the history set this value to `0`. This option makes sense only if
     `terminal` is set to `true` by the user or by an internal `output` check,
     otherwise the history caching mechanism is not initialized at all.
     **Default:** `30`.
+  * `removeHistoryDuplicates` {boolean} If `true`, when a new input line added
+    to the history list duplicates an older one, this removes the older line
+    from the list. **Default:** `false`.
   * `prompt` {string} The prompt string to use. **Default:** `'> '`.
   * `crlfDelay` {number} If the delay between `\r` and `\n` exceeds
     `crlfDelay` milliseconds, both `\r` and `\n` will be treated as separate
@@ -562,9 +594,6 @@ changes:
     `100`. It can be set to `Infinity`, in which case `\r` followed by `\n`
     will always be considered a single newline (which may be reasonable for
     [reading files][] with `\r\n` line delimiter). **Default:** `100`.
-  * `removeHistoryDuplicates` {boolean} If `true`, when a new input line added
-    to the history list duplicates an older one, this removes the older line
-    from the list. **Default:** `false`.
   * `escapeCodeTimeout` {number} The duration `readline` will wait for a
     character (when reading an ambiguous key sequence in milliseconds one that
     can both form a complete key sequence using the input read so far and can