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.

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
@@ -479,6 +501,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.
@@ -507,21 +532,25 @@ 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` {array} 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
     end-of-line input. `crlfDelay` will be coerced to a number no less than
     `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

lib/readline.js

@@ -37,6 +37,7 @@ const {
   ArrayPrototypeReverse,
   ArrayPrototypeSplice,
   ArrayPrototypeUnshift,
+  Array,
   DateNow,
   FunctionPrototypeBind,
   FunctionPrototypeCall,
@@ -133,6 +134,7 @@ function Interface(input, output, completer, terminal) {
   this.tabSize = 8;
 
   FunctionPrototypeCall(EventEmitter, this,);
+  let history;
   let historySize;
   let removeHistoryDuplicates = false;
   let crlfDelay;
@@ -143,6 +145,7 @@ function Interface(input, output, completer, terminal) {
     output = input.output;
     completer = input.completer;
     terminal = input.terminal;
+    history = input.history;
     historySize = input.historySize;
     if (input.tabSize !== undefined) {
       validateUint32(input.tabSize, 'tabSize', true);
@@ -170,6 +173,14 @@ function Interface(input, output, completer, terminal) {
     throw new ERR_INVALID_ARG_VALUE('completer', completer);
   }
 
+  if (history === undefined) {
+    history = [];
+  }
+
+  if (!(history instanceof Array)) {
+    throw new ERR_INVALID_OPT_VALUE.RangeError('history', history);
+  }
+
   if (historySize === undefined) {
     historySize = kHistorySize;
   }
@@ -191,6 +202,7 @@ function Interface(input, output, completer, terminal) {
   this[kSubstringSearch] = null;
   this.output = output;
   this.input = input;
+  this.history = history;
   this.historySize = historySize;
   this.removeHistoryDuplicates = !!removeHistoryDuplicates;
   this.crlfDelay = crlfDelay ?
@@ -291,7 +303,6 @@ function Interface(input, output, completer, terminal) {
     // Cursor position on the line.
     this.cursor = 0;
 
-    this.history = [];
     this.historyIndex = -1;
 
     if (output !== null && output !== undefined)
@@ -404,7 +415,16 @@ Interface.prototype._addHistory = function() {
   }
 
   this.historyIndex = -1;
-  return this.history[0];
+
+  // The listener could change the history object, possibly
+  // to remove the last added entry if it is sensitive and should
+  // not be persisted in the history, like a password
+  const line = this.history[0];
+
+  // Emit history event to notify listeners of update
+  this.emit('history', this.history);
+
+  return line;
 };
 
 

test/parallel/test-readline-interface.js

@@ -115,6 +115,47 @@ function assertCursorRowsAndCols(rli, rows, cols) {
     code: 'ERR_INVALID_ARG_VALUE'
   });
 
+  // Constructor throws if history is not an array
+  assert.throws(() => {
+    readline.createInterface({
+      input,
+      history: 'not an array'
+    });
+  }, {
+    name: 'RangeError',
+    code: 'ERR_INVALID_OPT_VALUE'
+  });
+
+  assert.throws(() => {
+    readline.createInterface({
+      input,
+      history: 123
+    });
+  }, {
+    name: 'RangeError',
+    code: 'ERR_INVALID_OPT_VALUE'
+  });
+
+  assert.throws(() => {
+    readline.createInterface({
+      input,
+      history: {}
+    });
+  }, {
+    name: 'RangeError',
+    code: 'ERR_INVALID_OPT_VALUE'
+  });
+
+  assert.throws(() => {
+    readline.createInterface({
+      input,
+      history: true
+    });
+  }, {
+    name: 'RangeError',
+    code: 'ERR_INVALID_OPT_VALUE'
+  });
+
   // Constructor throws if historySize is not a positive number
   assert.throws(() => {
     readline.createInterface({
@@ -238,6 +279,38 @@ function assertCursorRowsAndCols(rli, rows, cols) {
   rli.close();
 }
 
+// Adding history lines should emit the history event with
+// the history array
+{
+  const [rli, fi] = getInterface({ terminal: true });
+  const expectedLines = ['foo', 'bar', 'baz', 'bat'];
+  rli.on('history', common.mustCall((history) => {
+    const expectedHistory = expectedLines.slice(0, history.length).reverse();
+    assert.deepStrictEqual(history, expectedHistory);
+  }, expectedLines.length));
+  for (const line of expectedLines) {
+    fi.emit('data', `${line}\n`);
+  }
+  rli.close();
+}
+
+// Altering the history array in the listener should not alter
+// the line being processed
+{
+  const [rli, fi] = getInterface({ terminal: true });
+  const expectedLine = 'foo';
+  rli.on('history', common.mustCall((history) => {
+    assert.strictEqual(history[0], expectedLine);
+    history.shift();
+  }));
+  rli.on('line', common.mustCall((line) => {
+    assert.strictEqual(line, expectedLine);
+    assert.strictEqual(rli.history.length, 0);
+  }));
+  fi.emit('data', `${expectedLine}\n`);
+  rli.close();
+}
+
 // Duplicate lines are removed from history when
 // `options.removeHistoryDuplicates` is `true`
 {
@@ -773,7 +846,7 @@ for (let i = 0; i < 12; i++) {
     assert.strictEqual(rli.historySize, 0);
 
     fi.emit('data', 'asdf\n');
-    assert.deepStrictEqual(rli.history, terminal ? [] : undefined);
+    assert.deepStrictEqual(rli.history, []);
     rli.close();
   }
 
@@ -783,7 +856,7 @@ for (let i = 0; i < 12; i++) {
     assert.strictEqual(rli.historySize, 30);
 
     fi.emit('data', 'asdf\n');
-    assert.deepStrictEqual(rli.history, terminal ? ['asdf'] : undefined);
+    assert.deepStrictEqual(rli.history, terminal ? ['asdf'] : []);
     rli.close();
   }
 

tools/doc/type-parser.js

@@ -4,6 +4,7 @@ const jsDocPrefix = 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/';
 
 const jsDataStructuresUrl = `${jsDocPrefix}Data_structures`;
 const jsPrimitives = {
+  array: 'Array',
   boolean: 'Boolean',
   integer: 'Number', // Not a primitive, used for clarification.
   null: 'Null',