Readline#

Stability: 2 - Stable

Source Code: lib/readline.js

The node:readline module provides an interface for reading data from a Readable stream (such as process.stdin) one line at a time.

To use the promise-based APIs:

import * as readline from 'node:readline/promises';const readline = require('node:readline/promises');

To use the callback and sync APIs:

import * as readline from 'node:readline';const readline = require('node:readline');

The following simple example illustrates the basic use of the node:readline module.

import * as readline from 'node:readline/promises';
import { stdin as input, stdout as output } from 'node:process';

const rl = readline.createInterface({ input, output });

const answer = await rl.question('What do you think of Node.js? ');

console.log(`Thank you for your valuable feedback: ${answer}`);

rl.close();const readline = require('node:readline');
const { stdin: input, stdout: output } = require('node:process');

const rl = readline.createInterface({ input, output });

rl.question('What do you think of Node.js? ', (answer) => {
  // TODO: Log the answer in a database
  console.log(`Thank you for your valuable feedback: ${answer}`);

  rl.close();
});

Once this code is invoked, the Node.js application will not terminate until the readline.Interface is closed because the interface waits for data to be received on the input stream.

Class: InterfaceConstructor#

Added in: v0.1.104

Instances of the InterfaceConstructor class are constructed using the readlinePromises.createInterface() or readline.createInterface() method. Every instance is associated with a single input Readable stream and a single output Writable stream. The output stream is used to print prompts for user input that arrives on, and is read from, the input stream.

Event: 'close'#

Added in: v0.1.98

The 'close' event is emitted when one of the following occur:

  • The rl.close() method is called and the InterfaceConstructor instance has relinquished control over the input and output streams;
  • The input stream receives its 'end' event;
  • The input stream receives Ctrl+D to signal end-of-transmission (EOT);
  • The input stream receives Ctrl+C to signal SIGINT and there is no 'SIGINT' event listener registered on the InterfaceConstructor instance.

The listener function is called without passing any arguments.

The InterfaceConstructor instance is finished once the 'close' event is emitted.

Event: 'line'#

Added in: v0.1.98

The 'line' event is emitted whenever the input stream receives an end-of-line input (\n, \r, or \r\n). This usually occurs when the user presses Enter or Return.

The 'line' event is also emitted if new data has been read from a stream and that stream ends without a final end-of-line marker.

The listener function is called with a string containing the single line of received input.

rl.on('line', (input) => {
  console.log(`Received: ${input}`);
});

Event: 'history'#

Added in: v15.8.0, v14.18.0

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.

rl.on('history', (history) => {
  console.log(`Received: ${history}`);
});

Event: 'pause'#

Added in: v0.7.5

The 'pause' event is emitted when one of the following occur:

  • The input stream is paused.
  • The input stream is not paused and receives the 'SIGCONT' event. (See events 'SIGTSTP' and 'SIGCONT'.)

The listener function is called without passing any arguments.

rl.on('pause', () => {
  console.log('Readline paused.');
});

Event: 'resume'#

Added in: v0.7.5

The 'resume' event is emitted whenever the input stream is resumed.

The listener function is called without passing any arguments.

rl.on('resume', () => {
  console.log('Readline resumed.');
});

Event: 'SIGCONT'