mirrors/nodejs
mirrors/nodejs
0
0
Fork 0
mirror of https://github.com/nodejs/node.git synced 2024-11-21 13:09:21 +01:00
Code Issues Releases Activity

doc: define more cases for stream event emissions

Browse Source 
PR-URL: https://github.com/nodejs/node/pull/53317
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
This commit is contained in:
Aviv Keller 2024-06-08 11:52:46 -04:00 committed by GitHub
parent 50695e5de1
commit 0b020089d9
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 13 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
doc/api/stream.md
View File

@ -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: