diff --git a/doc/api/stream.md b/doc/api/stream.md index 9f233cd325132f..86286906b7f297 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -762,6 +762,9 @@ changes: description: > 'readable' is always emitted in the next tick after .push() is called + - version: REPLACEME + pr-url: https://github.com/nodejs/node/pull/18994 + description: Using 'readable' requires calling .read(). --> The `'readable'` event is emitted when there is data available to be read from @@ -770,10 +773,16 @@ cause some amount of data to be read into an internal buffer. ```javascript const readable = getReadableStreamSomehow(); -readable.on('readable', () => { +readable.on('readable', function() { // there is some data to read now + let data; + + while (data = this.read()) { + console.log(data); + } }); ``` + The `'readable'` event will also be emitted once the end of the stream data has been reached but before the `'end'` event is emitted. @@ -806,6 +815,10 @@ In general, the `readable.pipe()` and `'data'` event mechanisms are easier to understand than the `'readable'` event. However, handling `'readable'` might result in increased throughput. +If both `'readable'` and [`'data'`][] are used at the same time, `'readable'` +takes precedence in controlling the flow, i.e. `'data'` will be emitted +only when [`stream.read()`][stream-read] is called. + ##### readable.destroy([error]) * Returns: {this} @@ -1016,6 +1033,9 @@ getReadableStreamSomehow() }); ``` +The `readable.resume()` method has no effect if there is a `'readable'` +event listener. + ##### readable.setEncoding(encoding)