diff --git a/doc/api/fs.md b/doc/api/fs.md index 9cb84007b3b815..d3421a0ff01bc9 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -400,7 +400,7 @@ added: reached, whichever comes first. **Default:** read until EOF. * `chunkSize` {number} Size in bytes of the buffer allocated for each read operation. **Default:** `131072` (128 KB). -* Returns: {AsyncIterable\} +* Returns: {AsyncIterable} whose chunks fulfill with {Uint8Array\[]} Return the file contents as an async iterable using the [`node:stream/iter`][] pull model. Reads are performed in `chunkSize`-byte @@ -475,7 +475,7 @@ added: iterator. **Default:** read until EOF. * `chunkSize` {number} Size in bytes of the buffer allocated for each read operation. **Default:** `131072` (128 KB). -* Returns: {Iterable\} +* Returns: {Iterable} whose chunks return {Uint8Array\[]} Synchronous counterpart of [`filehandle.pull()`][]. Returns a sync iterable that reads the file using synchronous I/O on the main thread. Reads are @@ -9330,7 +9330,7 @@ the file contents. [`minimatch`]: https://github.com/isaacs/minimatch [`node:stream/iter`]: stream_iter.md [`statfs.bsize`]: #statfsbsize -[`stream/iter pipeTo()`]: stream_iter.md#pipetosource-transforms-writer +[`stream/iter pipeTo()`]: stream_iter.md#pipetosource-transforms-writer-options [`stream/iter pull()`]: stream_iter.md#pullsource-transforms-options [`stream/iter pullSync()`]: stream_iter.md#pullsyncsource-transforms [`util.promisify()`]: util.md#utilpromisifyoriginal diff --git a/doc/api/stream_iter.md b/doc/api/stream_iter.md index 0641246d9f013a..b7af639c2a9768 100644 --- a/doc/api/stream_iter.md +++ b/doc/api/stream_iter.md @@ -2,7 +2,7 @@ -> Stability: 1 - Experimental +> Stability: 1 - Experimental – Enable this API with the [`--experimental-stream-iter`][] CLI flag. @@ -10,15 +10,12 @@ The `node:stream/iter` module provides a streaming API built on iterables rather than the event-driven `Readable`/`Writable`/`Transform` class hierarchy, or the Web Streams `ReadableStream`/`WritableStream`/`TransformStream` interfaces. -This module is available only when the `--experimental-stream-iter` CLI flag -is enabled. - -Streams are represented as `AsyncIterable` (async) or -`Iterable` (sync). There are no base classes to extend -- any +Streams are represented as {AsyncIterable} (async) or {Iterable} (sync). There +are no base classes to extend -- any object implementing the iterable protocol can participate. Transforms are plain functions or objects with a `transform` method. -Data flows in **batches** (`Uint8Array[]` per iteration) to amortize the cost +Data flows in **batches** ({Uint8Array\[]} per iteration) to amortize the cost of async operations. ```mjs @@ -85,15 +82,15 @@ run().catch(console.error); ### Byte streams -All data in this API is represented as `Uint8Array` bytes. Strings +All data in this API is represented as {Uint8Array} bytes. Strings are automatically UTF-8 encoded when passed to `from()`, `push()`, or `pipeTo()`. This removes ambiguity around encodings and enables zero-copy transfers between streams and native code. ### Batching -Each iteration yields a **batch** -- an array of `Uint8Array` chunks -(`Uint8Array[]`). Batching amortizes the cost of `await` and Promise creation +Each iteration yields a **batch** -- an {Array} of {Uint8Array} chunks +({Uint8Array\[]}). Batching amortizes the cost of `await` and {Promise} creation across multiple chunks. A consumer that processes one chunk at a time can simply iterate the inner array: @@ -121,7 +118,7 @@ Transforms come in two forms: * **Stateless** -- a function `(chunks, options) => result` called once per batch. Receives `Uint8Array[]` (or `null` as the flush signal) and an - `options` object. Returns `Uint8Array[]`, `null`, or an iterable of chunks. + `options` object. Returns {Uint8Array\[]|null|Iterable}. * **Stateful** -- an object `{ transform(source, options) }` where `transform` is a generator (sync or async) that receives the entire upstream iterable @@ -527,11 +524,11 @@ added: * `input` {string|ArrayBuffer|ArrayBufferView|Iterable|AsyncIterable|Object} Must not be `null` or `undefined`. -* Returns: {AsyncIterable\} +* Returns: {AsyncIterable} whose chunks fulfill with {Uint8Array\[]}. Create an async byte stream from the given input. Strings are UTF-8 encoded. `ArrayBuffer` and `ArrayBufferView` values are wrapped as `Uint8Array`. Arrays -and iterables are recursively flattened and normalized. +and iterables in `input` are recursively flattened and normalized. Objects implementing `Symbol.for('Stream.toAsyncStreamable')` or `Symbol.for('Stream.toStreamable')` are converted via those protocols. The @@ -568,7 +565,7 @@ added: * `input` {string|ArrayBuffer|ArrayBufferView|Iterable|Object} Must not be `null` or `undefined`. -* Returns: {Iterable\} +* Returns: {Iterable} whose chunks return {Uint8Array\[]} Synchronous version of [`from()`][]. Returns a sync iterable. Cannot accept async iterables or promises. Objects implementing @@ -680,7 +677,7 @@ added: * `...transforms` {Function|Object} Zero or more transforms to apply. * `options` {Object} * `signal` {AbortSignal} Abort the pipeline. -* Returns: {AsyncIterable\} +* Returns: {AsyncIterable} whose chunks fulfill with {Uint8Array\[]} Create a lazy async pipeline. Data is not read from `source` until the returned iterable is consumed. Transforms are applied in order. @@ -750,7 +747,7 @@ added: * `source` {Iterable} The sync data source. * `...transforms` {Function|Object} Zero or more sync transforms. -* Returns: {Iterable\} +* Returns: {Iterable} whose chunks return {Uint8Array\[]} Synchronous version of [`pull()`][]. All transforms must be synchronous. @@ -773,8 +770,8 @@ added: `'drop-oldest'`, or `'drop-newest'`. **Default:** `'strict'`. * `signal` {AbortSignal} Abort the stream. * Returns: {Object} - * `writer` {PushWriter} The writer side. - * `readable` {AsyncIterable\} The readable side. + * `writer` {Writable} The writer side. + * `readable` {AsyncIterable} whose chunks fulfill with {Uint8Array\[]} Create a push stream with backpressure. The writer pushes data in; the readable side is consumed as an async iterable. @@ -851,8 +848,7 @@ the other channel's readable. Each channel has: * `writer` — a \[Writer interface]\[] object for sending data to the peer. -* `readable` — an `AsyncIterable` for reading data from - the peer. +* `readable` — an {AsyncIterable} for reading data from the peer. * `close()` — close this end of the channel (idempotent). * `[Symbol.asyncDispose]()` — async dispose support for `await using`. @@ -907,7 +903,7 @@ added: - v25.9.0 --> -* `source` {AsyncIterable\|Iterable\} +* `source` {AsyncIterable|Iterable} whose chunks must be {Uint8Array\[]} * `options` {Object} * `signal` {AbortSignal} * `limit` {number} Maximum number of bytes to consume. If the total bytes @@ -923,7 +919,7 @@ added: - v25.9.0 --> -* `source` {AsyncIterable\|Iterable\} +* `source` {AsyncIterable|Iterable} whose chunks must be {Uint8Array\[]} * `options` {Object} * `signal` {AbortSignal} * `limit` {number} Maximum number of bytes to consume. If the total bytes @@ -939,7 +935,7 @@ added: - v25.9.0 --> -* `source` {Iterable\} +* `source` {Iterable} whose chunks must be {Uint8Array\[]} * `options` {Object} * `limit` {number} Maximum number of bytes to consume. If the total bytes collected exceeds limit, an `ERR_OUT_OF_RANGE` error is thrown @@ -954,7 +950,7 @@ added: - v25.9.0 --> -* `source` {Iterable\} +* `source` {Iterable} whose chunks must be {Uint8Array\[]} * `options` {Object} * `limit` {number} Maximum number of bytes to consume. If the total bytes collected exceeds limit, an `ERR_OUT_OF_RANGE` error is thrown @@ -969,7 +965,7 @@ added: - v25.9.0 --> -* `source` {AsyncIterable\|Iterable\} +* `source` {AsyncIterable|Iterable} whose chunks must be {Uint8Array\[]} * `options` {Object} * `signal` {AbortSignal} * `limit` {number} Maximum number of bytes to consume. If the total bytes @@ -1003,7 +999,7 @@ added: - v25.9.0 --> -* `source` {Iterable\} +* `source` {Iterable} whose chunks must be {Uint8Array\[]} * `options` {Object} * `limit` {number} Maximum number of bytes to consume. If the total bytes collected exceeds limit, an `ERR_OUT_OF_RANGE` error is thrown @@ -1018,7 +1014,7 @@ added: - v25.9.0 --> -* `source` {AsyncIterable\|Iterable\} +* `source` {AsyncIterable|Iterable} whose chunks must be {Uint8Array\[]} * `options` {Object} * `encoding` {string} Text encoding. **Default:** `'utf-8'`. * `signal` {AbortSignal} @@ -1051,7 +1047,7 @@ added: - v25.9.0 --> -* `source` {Iterable\} +* `source` {Iterable} whose chunks must be {Uint8Array\[]} * `options` {Object} * `encoding` {string} **Default:** `'utf-8'`. * `limit` {number} Maximum number of bytes to consume. If the total bytes @@ -1125,10 +1121,10 @@ added: - v25.9.0 --> -* `...sources` {AsyncIterable\|Iterable\} Two or more iterables. +* `...sources` {AsyncIterable|Iterable} whose chunks must be {Uint8Array\[]} * `options` {Object} * `signal` {AbortSignal} -* Returns: {AsyncIterable\} +* Returns: {AsyncIterable} whose chunks fulfill with {Uint8Array\[]} Merge multiple async iterables by yielding batches in temporal order (whichever source produces data first). All sources are consumed @@ -1220,8 +1216,8 @@ added: `'drop-newest'`. **Default:** `'strict'`. * `signal` {AbortSignal} * Returns: {Object} - * `writer` {BroadcastWriter} - * `broadcast` {Broadcast} + * `writer` {Writable} + * `broadcast` {BroadcastChannel} Create a push-model multi-consumer broadcast channel. A single writer pushes data to multiple consumers. Each consumer has an independent cursor into a @@ -1298,7 +1294,7 @@ The number of active consumers. * `...transforms` {Function|Object} * `options` {Object} * `signal` {AbortSignal} -* Returns: {AsyncIterable\} +* Returns: {AsyncIterable} whose chunks fulfill with {Uint8Array\[]} Create a new consumer. Each consumer receives all data written to the broadcast from the point of subscription onward. Optional transforms are @@ -1315,11 +1311,11 @@ added: - v25.9.0 --> -* `input` {AsyncIterable|Iterable|Broadcastable} +* `input` {AsyncIterable|Iterable|BroadcastChannel} * `options` {Object} Same as `broadcast()`. * Returns: {Object} `{ writer, broadcast }` -Create a {Broadcast} from an existing source. The source is consumed +Create a {BroadcastChannel} from an existing source. The source is consumed automatically and pushed to all subscribers. ### `share(source[, options])` @@ -1373,6 +1369,21 @@ async function run() { run().catch(console.error); ``` +### Class: `Share` + +#### Static method: `Share.from(input[, options])` + + + +* `input` {AsyncIterable|Shareable} +* `options` {Object} Same as `share()`. +* Returns: {Share} + +Create a {Share} from an existing source. + #### `share.bufferSize` * {number} @@ -1396,7 +1407,7 @@ The number of active consumers. * `...transforms` {Function|Object} * `options` {Object} * `signal` {AbortSignal} -* Returns: {AsyncIterable\} +* Returns: {AsyncIterable} whose chunks fulfill with {Uint8Array\[]} Create a new consumer of the shared source. @@ -1404,18 +1415,17 @@ Create a new consumer of the shared source. Alias for `share.cancel()`. -### `Share.from(input[, options])` +### Interface: `Shareable` - +#### `sharable[Symbol.for('Stream.shareProtocol')]` -* `input` {AsyncIterable|Shareable} -* `options` {Object} Same as `share()`. -* Returns: {Share} +* {Function} that returns a {Share}. -Create a {Share} from an existing source. +### Interface: `SyncShareable` + +#### `sharable[Symbol.for('Stream.shareSyncProtocol')]` + +* {Function} that returns a {SyncShare}. ### `shareSync(source[, options])` @@ -1433,7 +1443,9 @@ added: Synchronous version of [`share()`][]. -### `SyncShare.fromSync(input[, options])` +### Class: `SyncShare` + +#### Static method: `SyncShare.fromSync(input[, options])`