Commit d9182d0
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -1278,9 +1278,11 @@ changes: | |||
| 1278 | 1278 | --> | |
| 1279 | 1279 | ||
| 1280 | 1280 | The `'readable'` event is emitted when there is data available to be read from | |
| 1281 | - the stream or when the end of the stream has been reached. Effectively, the | ||
| 1282 | - `'readable'` event indicates that the stream has new information. If data is | ||
| 1283 | - available, [`stream.read()`][stream-read] will return that data. | ||
| 1281 | + the stream, up to the configured high water mark (`state.highWaterMark`). Effectively, | ||
| 1282 | + it indicates that the stream has new information within the buffer. If data is available | ||
| 1283 | + within this buffer, [`stream.read()`][stream-read] can be called to retrieve that data. | ||
| 1284 | + Additionally, the `'readable'` event may also be emitted when the end of the stream has been | ||
| 1285 | + reached. | ||
| 1284 | 1286 | ||
| 1285 | 1287 | ```js | |
| 1286 | 1288 | const readable = getReadableStreamSomehow(); | |
@@ -1549,13 +1551,14 @@ readable.on('end', () => { | |||
| 1549 | 1551 | }); | |
| 1550 | 1552 | ``` | |
| 1551 | 1553 | ||
| 1552 | - Each call to `readable.read()` returns a chunk of data, or `null`. The chunks | ||
| 1553 | - are not concatenated. A `while` loop is necessary to consume all data | ||
| 1554 | - currently in the buffer. When reading a large file `.read()` may return `null`, | ||
| 1555 | - having consumed all buffered content so far, but there is still more data to | ||
| 1556 | - come not yet buffered. In this case a new `'readable'` event will be emitted | ||
| 1557 | - when there is more data in the buffer. Finally the `'end'` event will be | ||
| 1558 | - emitted when there is no more data to come. | ||
| 1554 | + Each call to `readable.read()` returns a chunk of data or `null`, signifying | ||
| 1555 | + that there's no more data to read at that moment. These chunks aren't automatically | ||
| 1556 | + concatenated. Because a single `read()` call does not return all the data, using | ||
| 1557 | + a while loop may be necessary to continuously read chunks until all data is retrieved. | ||
| 1558 | + When reading a large file, `.read()` might return `null` temporarily, indicating | ||
| 1559 | + that it has consumed all buffered content but there may be more data yet to be | ||
| 1560 | + buffered. In such cases, a new `'readable'` event is emitted once there's more | ||
| 1561 | + data in the buffer, and the `'end'` event signifies the end of data transmission. | ||
| 1559 | 1562 | ||
| 1560 | 1563 | Therefore to read a file's whole contents from a `readable`, it is necessary | |
| 1561 | 1564 | to collect chunks across multiple `'readable'` events: | |
0 commit comments