@@ -70,7 +70,7 @@ buffer that can be retrieved using `writable.writableBuffer` or
70
70
` readable.readableBuffer ` , respectively.
71
71
72
72
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 `
74
74
option specifies a [ total number of bytes] [ hwm-gotcha ] . For streams operating
75
75
in object mode, the ` highWaterMark ` specifies a total number of objects.
76
76
@@ -576,15 +576,18 @@ Examples of `Readable` streams include:
576
576
All [ ` Readable ` ] [ ] streams implement the interface defined by the
577
577
` stream.Readable ` class.
578
578
579
- #### Two Modes
579
+ #### Two Reading Modes
580
580
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.
582
585
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
584
587
and provided to an application as quickly as possible using events via the
585
588
[ ` EventEmitter ` ] [ ] interface.
586
589
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
588
591
explicitly to read chunks of data from the stream.
589
592
590
593
All [ ` Readable ` ] [ ] streams begin in paused mode but can be switched to flowing
@@ -633,22 +636,22 @@ within the `Readable` stream implementation.
633
636
Specifically, at any given point in time, every ` Readable ` is in one of three
634
637
possible states:
635
638
636
- * ` readable.readableFlowing = null `
637
- * ` readable.readableFlowing = false `
638
- * ` readable.readableFlowing = true `
639
+ * ` readable.readableFlowing === null `
640
+ * ` readable.readableFlowing === false `
641
+ * ` readable.readableFlowing === true `
639
642
640
643
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
643
646
` 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.
646
649
647
650
Calling ` readable.pause() ` , ` readable.unpipe() ` , or receiving backpressure
648
651
will cause the ` readable.readableFlowing ` to be set as ` false ` ,
649
652
temporarily halting the flowing of events but * not* halting the generation of
650
653
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 ` .
652
655
653
656
``` js
654
657
const { PassThrough , Writable } = require (' stream' );
@@ -660,20 +663,20 @@ pass.unpipe(writable);
660
663
// readableFlowing is now false
661
664
662
665
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'
665
668
```
666
669
667
670
While ` readable.readableFlowing ` is ` false ` , data may be accumulating
668
- within the streams internal buffer.
671
+ within the stream's internal buffer.
669
672
670
- #### Choose One
673
+ #### Choose One API Style
671
674
672
675
The ` Readable ` stream API evolved across multiple Node.js versions and provides
673
676
multiple methods of consuming stream data. In general, developers should choose
674
677
* one* of the methods of consuming data and * should never* use multiple methods
675
678
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
677
680
lead to unintuitive behavior.
678
681
679
682
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
832
835
understand than the ` 'readable' ` event. However, handling ` 'readable' ` might
833
836
result in increased throughput.
834
837
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' `
836
839
takes precedence in controlling the flow, i.e. ` 'data' ` will be emitted
837
840
only when [ ` stream.read() ` ] [ stream-read ] is called. The
838
841
` readableFlowing ` property would become ` false ` .
@@ -2469,3 +2472,4 @@ contain multi-byte characters.
2469
2472
[ readable-destroy ] : #stream_readable_destroy_error
2470
2473
[ writable-_destroy ] : #stream_writable_destroy_err_callback
2471
2474
[ writable-destroy ] : #stream_writable_destroy_error
2475
+ [ object-mode ] : #stream_object_mode
0 commit comments