diff --git a/doc/api/stream.md b/doc/api/stream.md index ba298cb4756ea9..35b23a966fff2d 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -618,6 +618,12 @@ instance, when the `readable.resume()` method is called without a listener attached to the `'data'` event, or when a `'data'` event handler is removed from the stream. +Adding a [`'readable'`][] event handler automatically make the stream to +stop flowing, and the data to be consumed via +[`readable.read()`][stream-read]. If the [`'readable'`] event handler is +removed, then the stream will start flowing again if there is a +[`'data'`][] event handler. + #### Three States The "two modes" of operation for a `Readable` stream are a simplified @@ -666,12 +672,15 @@ within the streams internal buffer. The `Readable` stream API evolved across multiple Node.js versions and provides multiple methods of consuming stream data. In general, developers should choose *one* of the methods of consuming data and *should never* use multiple methods -to consume data from a single stream. +to consume data from a single stream. Specifically, using a combination +of `on('data')`, `on('readable')`, `pipe()` or async iterators could +lead to unintuitive behavior. Use of the `readable.pipe()` method is recommended for most users as it has been implemented to provide the easiest way of consuming stream data. Developers that require more fine-grained control over the transfer and generation of data can -use the [`EventEmitter`][] and `readable.pause()`/`readable.resume()` APIs. +use the [`EventEmitter`][] and `readable.on('readable')`/`readable.read()` +or the `readable.pause()`/`readable.resume()` APIs. #### Class: stream.Readable