Skip to content

Commit a3e3ae0

Browse files
cxw42targos
authored andcommitted
doc: clarify Readable paused/flowing!==object mode
- Clarify that a `Readable` stream's reading mode (paused vs. flowing) is independent of its object mode (object vs. non-object). I am relatively new to Node streams, and was briefly confused while reading the docs by the two uses of the word "mode". - Copyediting: add missing apostrophes; minor grammatical changes PR-URL: #22619 Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Denys Otrishko <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]> Reviewed-By: Trivikram Kamat <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Matteo Collina <[email protected]>
1 parent 56e654a commit a3e3ae0

File tree

1 file changed

+23
-19
lines changed

1 file changed

+23
-19
lines changed

doc/api/stream.md

+23-19
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@ buffer that can be retrieved using `writable.writableBuffer` or
7070
`readable.readableBuffer`, respectively.
7171

7272
The amount of data potentially buffered depends on the `highWaterMark` option
73-
passed into the streams constructor. For normal streams, the `highWaterMark`
73+
passed into the stream's constructor. For normal streams, the `highWaterMark`
7474
option specifies a [total number of bytes][hwm-gotcha]. For streams operating
7575
in object mode, the `highWaterMark` specifies a total number of objects.
7676

@@ -576,15 +576,18 @@ Examples of `Readable` streams include:
576576
All [`Readable`][] streams implement the interface defined by the
577577
`stream.Readable` class.
578578

579-
#### Two Modes
579+
#### Two Reading Modes
580580

581-
`Readable` streams effectively operate in one of two modes: flowing and paused.
581+
`Readable` streams effectively operate in one of two modes: flowing and
582+
paused. These modes are separate from [object mode][object-mode].
583+
A [`Readable`][] stream can be in object mode or not, regardless of whether
584+
it is in flowing mode or paused mode.
582585

583-
When in flowing mode, data is read from the underlying system automatically
586+
* In flowing mode, data is read from the underlying system automatically
584587
and provided to an application as quickly as possible using events via the
585588
[`EventEmitter`][] interface.
586589

587-
In paused mode, the [`stream.read()`][stream-read] method must be called
590+
* In paused mode, the [`stream.read()`][stream-read] method must be called
588591
explicitly to read chunks of data from the stream.
589592

590593
All [`Readable`][] streams begin in paused mode but can be switched to flowing
@@ -633,22 +636,22 @@ within the `Readable` stream implementation.
633636
Specifically, at any given point in time, every `Readable` is in one of three
634637
possible states:
635638

636-
* `readable.readableFlowing = null`
637-
* `readable.readableFlowing = false`
638-
* `readable.readableFlowing = true`
639+
* `readable.readableFlowing === null`
640+
* `readable.readableFlowing === false`
641+
* `readable.readableFlowing === true`
639642

640643
When `readable.readableFlowing` is `null`, no mechanism for consuming the
641-
streams data is provided so the stream will not generate its data. While in this
642-
state, attaching a listener for the `'data'` event, calling the
644+
stream's data is provided. Therefore, the stream will not generate data.
645+
While in this state, attaching a listener for the `'data'` event, calling the
643646
`readable.pipe()` method, or calling the `readable.resume()` method will switch
644-
`readable.readableFlowing` to `true`, causing the `Readable` to begin
645-
actively emitting events as data is generated.
647+
`readable.readableFlowing` to `true`, causing the `Readable` to begin actively
648+
emitting events as data is generated.
646649

647650
Calling `readable.pause()`, `readable.unpipe()`, or receiving backpressure
648651
will cause the `readable.readableFlowing` to be set as `false`,
649652
temporarily halting the flowing of events but *not* halting the generation of
650653
data. While in this state, attaching a listener for the `'data'` event
651-
would not cause `readable.readableFlowing` to switch to `true`.
654+
will not switch `readable.readableFlowing` to `true`.
652655

653656
```js
654657
const { PassThrough, Writable } = require('stream');
@@ -660,20 +663,20 @@ pass.unpipe(writable);
660663
// readableFlowing is now false
661664

662665
pass.on('data', (chunk) => { console.log(chunk.toString()); });
663-
pass.write('ok'); // will not emit 'data'
664-
pass.resume(); // must be called to make 'data' being emitted
666+
pass.write('ok'); // will not emit 'data'
667+
pass.resume(); // must be called to make stream emit 'data'
665668
```
666669

667670
While `readable.readableFlowing` is `false`, data may be accumulating
668-
within the streams internal buffer.
671+
within the stream's internal buffer.
669672

670-
#### Choose One
673+
#### Choose One API Style
671674

672675
The `Readable` stream API evolved across multiple Node.js versions and provides
673676
multiple methods of consuming stream data. In general, developers should choose
674677
*one* of the methods of consuming data and *should never* use multiple methods
675678
to consume data from a single stream. Specifically, using a combination
676-
of `on('data')`, `on('readable')`, `pipe()` or async iterators could
679+
of `on('data')`, `on('readable')`, `pipe()`, or async iterators could
677680
lead to unintuitive behavior.
678681

679682
Use of the `readable.pipe()` method is recommended for most users as it has been
@@ -832,7 +835,7 @@ In general, the `readable.pipe()` and `'data'` event mechanisms are easier to
832835
understand than the `'readable'` event. However, handling `'readable'` might
833836
result in increased throughput.
834837

835-
If both `'readable'` and [`'data'`][] are used at the same time, `'readable'`
838+
If both `'readable'` and [`'data'`][] are used at the same time, `'readable'`
836839
takes precedence in controlling the flow, i.e. `'data'` will be emitted
837840
only when [`stream.read()`][stream-read] is called. The
838841
`readableFlowing` property would become `false`.
@@ -2469,3 +2472,4 @@ contain multi-byte characters.
24692472
[readable-destroy]: #stream_readable_destroy_error
24702473
[writable-_destroy]: #stream_writable_destroy_err_callback
24712474
[writable-destroy]: #stream_writable_destroy_error
2475+
[object-mode]: #stream_object_mode

0 commit comments

Comments
 (0)