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.
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
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.
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
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
errorevent on the input stream makes the iteration reject, so wrap the loop intry/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: Infinitywhen the input may contain Windows line endings. Otherwise a\rand\nthat 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
awaitsomething else first, lines can be emitted before the iterator exists, and those lines are lost. This is the most common bug withrl.on("line")mixed with async code, and it applies to the iterator too. - The loop applies backpressure. While your body awaits, no further
lineevents 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/promisesmodule arrived in Node.js 17.