Skip to content

doc: improve stream.compose documentation clarity #61975

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
turanalmammadov wants to merge 1 commit into
base: main
Choose a base branch
from
Open

doc: improve stream.compose documentation clarity #61975

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 13 additions & 5 deletions doc/api/stream.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2981,6 +2981,11 @@ first stream and reads from the last. Each provided stream is piped into
the next, using `stream.pipeline`. If any of the streams error then all
are destroyed, including the outer `Duplex` stream.

When composing multiple streams, all must be `Duplex` streams (e.g. transforms).
Each stream is piped to the next: the first receives writes, the last provides
reads. When combining a write-only stream with a read-only stream (without
piping them), use [`stream.Duplex.from({ writable, readable })`][] instead.

Because `stream.compose` returns a new stream that in turn can (and
should) be piped into other streams, it enables composition. In contrast,
when passing streams to `stream.pipeline`, typically the first stream is
Expand Down Expand Up @@ -3014,15 +3019,17 @@ console.log(res); // prints 'HELLOWORLD'
```

`stream.compose` can be used to convert async iterables, generators and
functions into streams.
functions into streams. The resulting streams are `Duplex` instances with
configurable `readable` and `writable` options; when only one side is used,
they are described as "readable Duplex" or "writable Duplex" accordingly.

* `AsyncIterable` converts into a readable `Duplex`. Cannot yield
`null`.
* `AsyncIterable` converts into a readable `Duplex` (readable side only).
Cannot yield `null`.
* `AsyncGeneratorFunction` converts into a readable/writable transform `Duplex`.
Must take a source `AsyncIterable` as first parameter. Cannot yield
`null`.
* `AsyncFunction` converts into a writable `Duplex`. Must return
either `null` or `undefined`.
* `AsyncFunction` converts into a writable `Duplex` (writable side only).
Must return either `null` or `undefined`.

```mjs
import { compose } from 'node:stream';
Expand Down Expand Up @@ -5016,6 +5023,7 @@ contain multi-byte characters.
[`stream.Readable.from()`]: #streamreadablefromiterable-options
[`stream.addAbortSignal()`]: #streamaddabortsignalsignal-stream
[`stream.compose(...streams)`]: #streamcomposestreams
[`stream.Duplex.from({ writable, readable })`]: #streamduplexfromsrc
[`stream.cork()`]: #writablecork
[`stream.duplexPair()`]: #streamduplexpairoptions
[`stream.finished()`]: #streamfinishedstream-options-callback
Expand Down