Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Streams and readline

Node.js readline async iterator (for await over lines)

Reference for iterating a readline Interface with for await...of in Node.js: reading input line by line, crlfDelay, early exit, and the pitfalls of late listeners.

A readline.Interface is an async iterable. for await (const line of rl) hands you one line at a time, without the trailing newline, and the loop ends when the input ends. It is the simplest and safest way to process a text file or piped input line by line, because the loop body can await things and the stream is paused while it does.

The iterator is backed by the line event, but it buffers lines for you, so a slow loop body never loses data. Pair it with fs.createReadStream() for files or process.stdin for piped input.

NODE
import readline from "node:readline";

const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
for await (const line of rl) {
  console.log(line.toUpperCase());
}

Try it

Node.js Counting words per line

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 Stopping early and async work in the loop

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
rl[Symbol.asyncIterator](): AsyncIterator<string>

Using for await (const line of rl) calls it for you. With readline/promises the interface is iterable in the same way.

Name Description
line Each yielded value is one input line as a string, with the line terminator removed.

Returns: an async iterator that finishes when the interface emits close (the input ended or rl.close() was called).

Errors and edge cases:

  • An error event on the input stream makes the iteration reject, so wrap the loop in try/catch.
  • Leaving the loop early (break, return, or a thrown error) closes the interface, which also stops reading the input.
  • A final line without a trailing newline is still delivered. An empty last line (input ends with \n) is not delivered as an extra empty string.

Usage notes

  • Set crlfDelay: Infinity when the input may contain Windows line endings. Otherwise a \r and \n that arrive in different chunks can be counted as two line breaks, which yields a blank line between every line.
  • Add the loop right after creating the interface. If you await something else first, lines can be emitted before the iterator exists, and those lines are lost. This is the most common bug with rl.on("line") mixed with async code, and it applies to the iterator too.
  • The loop applies backpressure. While your body awaits, no further line events pile up in memory beyond the internal buffer, so you can process multi-gigabyte files in constant memory.
  • Use events.once(rl, "close") instead if you only need to know when the input ended, not each line.
  • The iterator is available since Node.js 11.4; the readline/promises module arrived in Node.js 17.