1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki 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 `'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 the stream, up to the configured high water mark (`state.highWaterMark`). Effectively,
`'readable'` event indicates that the stream has new information. If data is it indicates that the stream has new information within the buffer. If data is available
available, [`stream.read()`][stream-read] will return that data. 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 ```js
const readable = getReadableStreamSomehow(); const readable = getReadableStreamSomehow();
@ -1553,13 +1555,14 @@ readable.on('end', () => {
}); });
``` ```
Each call to `readable.read()` returns a chunk of data, or `null`. The chunks Each call to `readable.read()` returns a chunk of data or `null`, signifying
are not concatenated. A `while` loop is necessary to consume all data that there's no more data to read at that moment. These chunks aren't automatically
currently in the buffer. When reading a large file `.read()` may return `null`, concatenated. Because a single `read()` call does not return all the data, using
having consumed all buffered content so far, but there is still more data to a while loop may be necessary to continuously read chunks until all data is retrieved.
come not yet buffered. In this case a new `'readable'` event will be emitted When reading a large file, `.read()` might return `null` temporarily, indicating
when there is more data in the buffer. Finally the `'end'` event will be that it has consumed all buffered content but there may be more data yet to be
emitted when there is no more data to come. 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 Therefore to read a file's whole contents from a `readable`, it is necessary
to collect chunks across multiple `'readable'` events: to collect chunks across multiple `'readable'` events: