Skip to content

Commit 620db54

Browse files
committed
doc: clarify mutable Web Stream chunk reuse
Document when a mutable chunk can be reused after writer.write() fulfills, and prohibit mutation while the write is pending. Explain copying in byte mode, reference passing in object mode, and preservation of bytes retained by a Duplex readable side. Signed-off-by: seungwoo <zoozoo1302@gmail.com>
1 parent 3ca2ce1 commit 620db54

1 file changed

Lines changed: 15 additions & 0 deletions

File tree

‎doc/api/stream.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3339,6 +3339,14 @@ changes:
33393339
* `streamWritable` {stream.Writable}
33403340
* Returns: {WritableStream}
33413341

3342+
For streams not operating in object mode, a mutable {Buffer}, {TypedArray},
3343+
{DataView}, {ArrayBuffer}, or {SharedArrayBuffer} passed to the returned stream's
3344+
writer can be reused after the promise returned by `writer.write()` is
3345+
fulfilled. Do not modify the chunk or its underlying bytes while that promise
3346+
is pending. The adapter may copy the chunk, so the underlying Node.js stream is
3347+
not guaranteed to receive the same object. Chunks written to streams operating
3348+
in object mode are passed by reference without copying.
3349+
33423350
### `stream.Duplex.from(src)`
33433351

33443352
<!-- YAML
@@ -3507,6 +3515,12 @@ changes:
35073515
* `readable` {ReadableStream}
35083516
* `writable` {WritableStream}
35093517

3518+
The `writable` stream has the same mutable chunk reuse behavior as
3519+
[`stream.Writable.toWeb()`][]. For streams not operating in writable object mode,
3520+
reusing the chunk after `writer.write()` is fulfilled does not modify bytes
3521+
retained by the Node.js stream's readable side. The adapter may copy chunks
3522+
before passing them to the Node.js stream.
3523+
35103524
```mjs
35113525
import { Duplex } from 'node:stream';
35123526

@@ -5088,6 +5102,7 @@ contain multi-byte characters.
50885102
[`readable.push('')`]: #readablepush
50895103
[`readable.setEncoding()`]: #readablesetencodingencoding
50905104
[`stream.Readable.from()`]: #streamreadablefromiterable-options
5105+
[`stream.Writable.toWeb()`]: #streamwritabletowebstreamwritable
50915106
[`stream.addAbortSignal()`]: #streamaddabortsignalsignal-stream
50925107
[`stream.compose(...streams)`]: #streamcomposestreams
50935108
[`stream.cork()`]: #writablecork

0 commit comments

Comments
 (0)