doc: clarify Readable paused/flowing!==object mode #22619
Conversation
nodejs-github-bot
added
doc
doc/api/stream.md
Outdated
| * `readable.readableFlowing = true` | ||
| * `readable.readableFlowing == null` | ||
| * `readable.readableFlowing == false` | ||
| * `readable.readableFlowing == true` |
There was a problem hiding this comment.
Maybe switching to === makes sense, given the “flexible” nature of normal JS equality comparisons?
There was a problem hiding this comment.
Thanks for your quick review and positive feedback! This change is fine with me --- since I don't know the internals, I didn't want to assume. I will update momentarily. Edit Changed in 432fe1225b1ac8d4812f572357c9dfc0e4582291
BridgeAR
added
the
author ready
doc/api/stream.md
Outdated
|
|
||
| When `readable.readableFlowing` is `null`, no mechanism for consuming the | ||
| streams data is provided so the stream will not generate its data. While in this | ||
| state, attaching a listener for the `'data'` event, calling the | ||
| stream's data is provided. Therefore, the stream will not generate data. |
There was a problem hiding this comment.
Nit: two spaces before 'Therefore'.
There was a problem hiding this comment.
Good catch - will fix along with the change in response to your comment below.
doc/api/stream.md
Outdated
| @@ -661,19 +664,19 @@ pass.unpipe(writable); | |||
|
|
|||
| pass.on('data', (chunk) => { console.log(chunk.toString()); }); | |||
| pass.write('ok'); // will not emit 'data' | |||
| pass.resume(); // must be called to make 'data' being emitted | |||
| pass.resume(); // must be called to make 'data' be emitted | |||
There was a problem hiding this comment.
Hm, wdyt of: 'must be called to make stream emit data'?
There was a problem hiding this comment.
Can do. However, I have a concern about implying determinism. What about "now the stream can emit 'data' events"? Correct me if I am wrong, but I think calling resume() does not mean that a data event will necessarily be emitted, depending on the state of the stream.
There was a problem hiding this comment.
It will be emitted after resume if there is data in the stream and we have just added it there via the above write call. Therefore it should be fine with being deterministic here.
There was a problem hiding this comment.
Rebased, and both of your changes applied, in 0bb51b0. Thanks!
- 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
- 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 <anna@addaleax.net> Reviewed-By: Denys Otrishko <shishugi@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
|
Landed in 4f70ecc (with some exra spaces deleted). |
- 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 <anna@addaleax.net> Reviewed-By: Denys Otrishko <shishugi@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
- 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 <anna@addaleax.net> Reviewed-By: Denys Otrishko <shishugi@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Clarify that a
Readablestream'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
Checklist