Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Streams and readline

The readline/promises module

Reference for node:readline/promises: await rl.question(), abort a prompt with an AbortSignal, build a Readline for batched cursor actions, and avoid common pitfalls.

node:readline/promises is the promise flavor of readline. Its createInterface() returns an interface whose rl.question() returns a promise, so a sequence of prompts reads like ordinary top-level code: const name = await rl.question("Name? "). No nested callbacks are needed.

The module also exports Readline, a helper that queues cursor and screen actions (cursorTo, clearLine, and so on) and sends them to a stream in one commit(). Everything else, including events and async iteration, behaves as in the callback-based module.

NODE
import 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("Your name? ");
console.log(`Hello, ${answer}`);
rl.close();

Try it

Node.js A scripted conversation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Cancelling a prompt with AbortSignal

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
import readline from "node:readline/promises";

readline.createInterface(options): readline.Interface
rl.question(query: string, options?: { signal?: AbortSignal }): Promise<string>
new readline.Readline(stream: Writable, options?: { autoCommit?: boolean })
Name Description
options.input The readable stream to read from (required). Often process.stdin.
options.output The writable stream the prompt is written to. Optional.
options.terminal Treat the output as a TTY and enable line editing. Defaults to output.isTTY.
options.crlfDelay Milliseconds to wait for \n after \r. Use Infinity for CRLF input.
options.signal An AbortSignal that closes the interface when aborted.
query Text written before waiting for the answer.

Returns: question() resolves with the entered line, without the line break.

Errors and edge cases:

  • Aborting the signal passed to question() rejects with an AbortError whose code is ABORT_ERR. The interface stays usable.
  • Calling question() after rl.close() rejects with ERR_USE_AFTER_CLOSE.

Usage notes

  • The promise API and the callback API are separate modules. Do not mix readline/promises question() with the callback style on the same interface.
  • A single interface can ask many questions in sequence. Create one per input stream and close it when done, otherwise the process stays alive waiting for input.
  • Input that arrives before a question is asked is not kept for that question. For fully scripted input, prefer async iteration of lines.
  • Readline is a batching tool: queue rl.cursorTo(0).clearLine(0), then call commit() once. It is handy for progress displays; see readline.cursorTo() and clearLine().
  • The promise module is stable since Node.js 17.