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?
answer
- who waits for whom
- pull one chunk, then await
- errors thrown into the loop
- break destroys; destroyOnReturn opts out
basics
~20 sfor 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 linesimport { 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 loopgo deeper
Know that for await reads a stream one chunk at a time and that leaving the loop early closes the stream.
Explain why an async 'data' handler does not wait, how the iterator pulls with read(), how errors surface, and what destroyOnReturn changes.
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.
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.