Skip to content

Commit 3b83f91

Browse files
Trottdanielleadams
authored andcommitted
doc: clarify recommendations in stream.md
PR-URL: #42555 Reviewed-By: Mestery <[email protected]> Reviewed-By: Tierney Cyren <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Akhil Marsonya <[email protected]>
1 parent 519f912 commit 3b83f91

File tree

1 file changed

+6
-7
lines changed

1 file changed

+6
-7
lines changed

doc/api/stream.md

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -546,8 +546,8 @@ The `writable.uncork()` method flushes all data buffered since
546546
[`stream.cork()`][] was called.
547547

548548
When using [`writable.cork()`][] and `writable.uncork()` to manage the buffering
549-
of writes to a stream, it is recommended that calls to `writable.uncork()` be
550-
deferred using `process.nextTick()`. Doing so allows batching of all
549+
of writes to a stream, defer calls to `writable.uncork()` using
550+
`process.nextTick()`. Doing so allows batching of all
551551
`writable.write()` calls that occur within a given Node.js event loop phase.
552552

553553
```js
@@ -701,7 +701,7 @@ stop until the [`'drain'`][] event is emitted.
701701
While a stream is not draining, calls to `write()` will buffer `chunk`, and
702702
return false. Once all currently buffered chunks are drained (accepted for
703703
delivery by the operating system), the `'drain'` event will be emitted.
704-
It is recommended that once `write()` returns false, no more chunks be written
704+
Once `write()` returns false, do not write more chunks
705705
until the `'drain'` event is emitted. While calling `write()` on a stream that
706706
is not draining is allowed, Node.js will buffer all written chunks until
707707
maximum memory usage occurs, at which point it will abort unconditionally.
@@ -861,10 +861,9 @@ to consume data from a single stream. Specifically, using a combination
861861
of `on('data')`, `on('readable')`, `pipe()`, or async iterators could
862862
lead to unintuitive behavior.
863863

864-
Use of the `readable.pipe()` method is recommended for most users as it has been
865-
implemented to provide the easiest way of consuming stream data. Developers that
866-
require more fine-grained control over the transfer and generation of data can
867-
use the [`EventEmitter`][] and `readable.on('readable')`/`readable.read()`
864+
`readable.pipe()` provides the easiest way to consume stream data. Developers
865+
that require more fine-grained control over the transfer and generation of data
866+
can use the [`EventEmitter`][] and `readable.on('readable')`/`readable.read()`
868867
or the `readable.pause()`/`readable.resume()` APIs.
869868

870869
#### Class: `stream.Readable`

0 commit comments

Comments
 (0)