skip to content

In Node.js, how does for await...of over a stream.Readable differ from an async 'data' handler, and what does an early break do to the stream?

level: middleimportance: should knowfreq 55%

answer

  1. who waits for whom
  2. pull one chunk, then await
  3. errors thrown into the loop
  4. break destroys; destroyOnReturn opts out

basics

~20 s

for await reads one chunk, waits for the loop body, then reads the next, and throws stream errors into the loop; a 'data' handler's promise is ignored. An early break destroys the stream unless you use readable.iterator({ destroyOnReturn: false }).

solid answer

~40 s

`EventEmitter` ignores the promise an async `'data'` listener returns, so a flowing stream keeps emitting chunks while earlier ones are still being processed, and by default a rejection becomes an unhandled rejection. `for await (const chunk of readable)` uses the paused-mode `read()` path: it takes one chunk, runs the loop body to completion, then asks for the next, so processing is sequential and a slow body slows the reading. A stream `'error'` is thrown out of the loop, so `try/catch` handles it. If the loop ends early with `break`, `return` or `throw`, Node destroys the stream, which closes a file descriptor or socket. To keep it alive, iterate `readable.iterator({ destroyOnReturn: false })`, which Node 24 marked stable.

code

javascript · 13 lines
javascript
import { createReadStream } from 'node:fs';

const stream = createReadStream('./app.log');
let bytes = 0;
try {
  for await (const chunk of stream) {
    bytes += chunk.length;        // chunk is a Buffer of up to 64 KiB
    if (bytes > 1_000_000) break; // leaving the loop destroys the stream
  }
} catch (err) {
  console.error('read failed:', err.code); // e.g. ENOENT if the file is missing
}
console.log(bytes, stream.destroyed); // stream.destroyed is true after the loop

go deeper

for a junior

Know that for await reads a stream one chunk at a time and that leaving the loop early closes the stream.

for a middle

Explain why an async 'data' handler does not wait, how the iterator pulls with read(), how errors surface, and what destroyOnReturn changes.

for a senior

Spot the production symptoms of async 'data' handlers, such as out-of-order writes and crashes from unhandled rejections, and replace them with for await or a pipeline.

for a principal

Make for await or pipeline the default consumption pattern in code review, and reserve event-based consumption for code that measurably needs it.

## Two ways to consume chunks asynchronously A **Readable** is a Node stream you consume. Most real consumers do asynchronous work per chunk: write it to a queue, parse it, store it. There are two common ways to wire that up, and they behave very differently. | | `readable.on('data', async (chunk) => ...)` | `for await (const chunk of readable)` | |---|---|---| | Reading mode | flowing (push) | paused (pull via `read()`) | | Waits for your async work? | **no**; the returned promise is ignored | **yes**; next chunk is read after the body finishes | | Order of completion | may overlap and finish out of order | strictly sequential | | Stream `'error'` | needs a separate `'error'` listener | thrown out of the loop; `try/catch` works | | Throw inside your code | an **unhandled rejection** | propagates out of the loop and destroys the stream | | Early exit | `removeListener` does not pause the stream | `break` / `return` / `throw` **destroys** the stream | ## Why an async 'data' handler does not wait `'data'` is an ordinary `EventEmitter` event. The emitter calls each listener and moves on; it does not look at the return value. With an `async` listener: - the stream keeps emitting the next chunks while the previous `await` is still pending, so several handlers run concurrently and can finish in any order; - a thrown error becomes a rejected promise nobody handles, and in Node 24 the default `--unhandled-rejections=throw` mode turns that into a crash unless an `unhandledRejection` handler exists; - calling `pause()` inside the handler and `resume()` after the `await` restores ordering, but that is exactly the bookkeeping `for await` does for you. ## What for await does under the hood A Readable implements `Symbol.asyncIterator`. The iterator: 1. listens for `'readable'` and calls `read()` to take one chunk; 2. yields it to the loop body and waits until the body has finished; 3. repeats, waiting for the next `'readable'` when `read()` returns `null`; 4. finishes when the stream ends, or throws the stream's error into the loop. Because chunks are pulled only as fast as the body finishes, a slow body naturally slows the reading; how that ties into the stream's buffering thresholds is covered in the backpressure lesson. Chunks are whatever the stream produces: for `fs.createReadStream()` with no options that is a `Buffer` of up to 64 KiB, not a line. To iterate lines, use `node:readline` over the stream, which has its own caveats. ## What an early exit does The docs are explicit: if the loop terminates with `break`, `return` or `throw`, the stream is **destroyed**. For a file stream that closes the file descriptor; for a socket it closes the connection. That is usually what you want, because an abandoned stream would otherwise hold its resource open. When you want to read a header and hand the rest of the stream to someone else, use the explicit iterator: ```js for await (const chunk of readable.iterator({ destroyOnReturn: false })) { header = chunk; break; // the stream stays open } // readable can be iterated again or piped elsewhere ``` - `readable.iterator()` has existed since v16.3.0 and was marked stable in v24.0.0. - `destroyOnReturn` defaults to `true`, which matches plain `for await`. ## Common mistakes in code review 1. An `async` `'data'` listener doing a network write per chunk, with no `pause()`: writes overlap, arrive out of order, and one failure crashes the process. 2. A `for await` loop with an `'error'` listener added "just in case", while the errors thrown out of the loop go uncaught because nothing wraps it in `try/catch`. 3. A `break` after reading a header, followed by an attempt to pipe the rest of the same stream: it is already destroyed. 4. Iterating a byte stream and assuming each chunk is one record or one line. Node also offers helper methods built on the same iterator, such as `readable.map()`, `readable.filter()` and `readable.toArray()`, but in Node 24 they are still marked experimental, so plain `for await` remains the stable default. ## Practical rules - Prefer `for await` (or a pipeline) over an async `'data'` handler in service code; it gives ordering and error handling for free. - Do not attach a `'data'` listener to a stream you also iterate; pick one consumption style per stream. - Wrap the loop in `try/catch`, not an `'error'` listener, to handle stream failures. - Expect `break` to close the resource; reach for `destroyOnReturn: false` only when the stream must outlive the loop.

  • Can you add a 'data' listener for metrics while a for await loop consumes the same stream?
    You should not. The docs say to choose one consumption style per stream. The iterator pulls with `'readable'` and `read()`, and a `'readable'` listener takes control of the flow, so once the loop runs, the extra `'data'` listener only sees chunks as the loop reads them, and chunks it saw before the loop started never reach the loop. Count bytes inside the loop body, or insert a pass-through stage in a pipeline instead.
  • What happens if the loop body throws while iterating a Readable?
    The throw leaves the loop, which counts as an early exit: the iterator's cleanup runs and the stream is destroyed, closing its resource. The error then propagates to the surrounding `try/catch` or to the caller like any other exception, rather than becoming an unhandled rejection as it would inside an async `'data'` listener.

  • An async 'data' handler makes the stream wait for each promise.
  • Breaking out of for await leaves the file open for reuse.
  • Stream errors in a for await loop need an 'error' listener, not try/catch.
  • for await over fs.createReadStream() yields one line per iteration.
  • readable.iterator() is an alias of the default iterator with no options.

Assumes Node.js 24: async iteration of a Readable has been stable since v11.14.0, and readable.iterator() with destroyOnReturn was marked stable in v24.0.0.