Skip to content

Commit

Permalink
doc: reorder stream 'readable' paragraphs
Browse files Browse the repository at this point in the history
Fixes: #40136

PR-URL: #40212
Reviewed-By: Robert Nagy <ronagy@icloud.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Anto Aravinth <anto.aravinth.cse@gmail.com>
  • Loading branch information
vweevers authored and targos committed Oct 4, 2021
1 parent 555af5b commit d2e54e5
Showing 1 changed file with 10 additions and 10 deletions.
20 changes: 10 additions & 10 deletions doc/api/stream.md
Original file line number Diff line number Diff line change
Expand Up @@ -960,8 +960,9 @@ changes:
-->

The `'readable'` event is emitted when there is data available to be read from
the stream. In some cases, attaching a listener for the `'readable'` event will
cause some amount of data to be read into an internal buffer.
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.

```js
const readable = getReadableStreamSomehow();
Expand All @@ -975,14 +976,10 @@ readable.on('readable', function() {
});
```

The `'readable'` event will also be emitted once the end of the stream data
has been reached but before the `'end'` event is emitted.

Effectively, the `'readable'` event indicates that the stream has new
information: either new data is available or the end of the stream has been
reached. In the former case, [`stream.read()`][stream-read] will return the
available data. In the latter case, [`stream.read()`][stream-read] will return
`null`. For instance, in the following example, `foo.txt` is an empty file:
If the end of the stream has been reached, calling
[`stream.read()`][stream-read] will return `null` and trigger the `'end'`
event. This is also true if there never was any data to be read. For instance,
in the following example, `foo.txt` is an empty file:

```js
const fs = require('fs');
Expand All @@ -1003,6 +1000,9 @@ readable: null
end
```

In some cases, attaching a listener for the `'readable'` event will cause some
amount of data to be read into an internal buffer.

In general, the `readable.pipe()` and `'data'` event mechanisms are easier to
understand than the `'readable'` event. However, handling `'readable'` might
result in increased throughput.
Expand Down

0 comments on commit d2e54e5

Please sign in to comment.