From 0b020089d960905fce949d3c245d36b61a8eb290 Mon Sep 17 00:00:00 2001 From: Aviv Keller <38299977+RedYetiDev@users.noreply.github.com> Date: Sat, 8 Jun 2024 11:52:46 -0400 Subject: [PATCH] doc: define more cases for stream event emissions PR-URL: https://github.com/nodejs/node/pull/53317 Reviewed-By: Matteo Collina Reviewed-By: Luigi Pinca --- doc/api/stream.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/doc/api/stream.md b/doc/api/stream.md index 42885b48c74..f7566858ee5 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -1282,9 +1282,11 @@ changes: --> The `'readable'` event is emitted when there is data available to be read from -the stream or when the end of the stream has been reached. Effectively, the -`'readable'` event indicates that the stream has new information. If data is -available, [`stream.read()`][stream-read] will return that data. +the stream, up to the configured high water mark (`state.highWaterMark`). Effectively, +it indicates that the stream has new information within the buffer. If data is available +within this buffer, [`stream.read()`][stream-read] can be called to retrieve that data. +Additionally, the `'readable'` event may also be emitted when the end of the stream has been +reached. ```js const readable = getReadableStreamSomehow(); @@ -1553,13 +1555,14 @@ readable.on('end', () => { }); ``` -Each call to `readable.read()` returns a chunk of data, or `null`. The chunks -are not concatenated. A `while` loop is necessary to consume all data -currently in the buffer. When reading a large file `.read()` may return `null`, -having consumed all buffered content so far, but there is still more data to -come not yet buffered. In this case a new `'readable'` event will be emitted -when there is more data in the buffer. Finally the `'end'` event will be -emitted when there is no more data to come. +Each call to `readable.read()` returns a chunk of data or `null`, signifying +that there's no more data to read at that moment. These chunks aren't automatically +concatenated. Because a single `read()` call does not return all the data, using +a while loop may be necessary to continuously read chunks until all data is retrieved. +When reading a large file, `.read()` might return `null` temporarily, indicating +that it has consumed all buffered content but there may be more data yet to be +buffered. In such cases, a new `'readable'` event is emitted once there's more +data in the buffer, and the `'end'` event signifies the end of data transmission. Therefore to read a file's whole contents from a `readable`, it is necessary to collect chunks across multiple `'readable'` events: