doc: stream.compose documentation improvement #40861
Conversation
Made it more clear that it should be used with Duplex streams (e.g. transforms) and that its functionality should not be confused with `stream.Duplex.from({writable, readable})`.
nodejs-github-bot
added
doc
| are destroyed, including the outer `Duplex` stream. | ||
| Combines two or more `Duplex` streams (e.g. transforms) into a `Duplex` | ||
| stream that writes to the first stream and reads from the last. Each provided | ||
| stream is piped into the next, using `stream.pipeline`. If any of the streams |
There was a problem hiding this comment.
| stream is piped into the next, using `stream.pipeline`. If any of the streams | |
| stream is piped into the next, using `stream.pipeline()`. If any of the streams |
| stream is piped into the next, using `stream.pipeline`. If any of the streams | ||
| error then all are destroyed, including the outer `Duplex` stream. | ||
|
|
||
| It should not be confused with `stream.Duplex.from({writable, readable})` |
There was a problem hiding this comment.
| It should not be confused with `stream.Duplex.from({writable, readable})` | |
| It should not be confused with `stream.Duplex.from()` |
|
|
||
| It should not be confused with `stream.Duplex.from({writable, readable})` | ||
| which can combine a write-only stream with a read-only stream to create a | ||
| `Duplex` (where the streams doesn't get piped). |
There was a problem hiding this comment.
| `Duplex` (where the streams doesn't get piped). | |
| `Duplex` (where the streams don't get piped). |
| error then all are destroyed, including the outer `Duplex` stream. | ||
|
|
||
| It should not be confused with `stream.Duplex.from({writable, readable})` | ||
| which can combine a write-only stream with a read-only stream to create a |
There was a problem hiding this comment.
This comparison to stream.Duplex.from() can be generalized because it's not necessarily about "write-only" or "read-only" (which are terms that are not used in existing docs) as in having only a writable or readable side. Rather, it's about whether to use those sides.
So for this paragraph I suggest:
Use other utilities when the streams are not
Duplexor when connecting them is not desirable. For example, to instead create aDuplexstream from a writable stream and a readable stream without piping one into the other, usestream.Duplex.from().
In addition, can we move it down by one paragraph? Because describing the difference between stream.compose() and stream.pipeline() is IMO more important than describing the difference between stream.compose() and stream.Duplex.from(). And the first paragraph already mentions stream.pipeline() so that question is brought up first.
stream.Duplex.from({writable, readable})My first pull request ever, resolves #40812