From d2e54e5d0c3c632db4e7160928a79b1557f1105b Mon Sep 17 00:00:00 2001 From: Vincent Weevers Date: Sat, 25 Sep 2021 10:07:15 +0200 Subject: [PATCH] doc: reorder stream 'readable' paragraphs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes: https://github.com/nodejs/node/issues/40136 PR-URL: https://github.com/nodejs/node/pull/40212 Reviewed-By: Robert Nagy Reviewed-By: Matteo Collina Reviewed-By: Tobias Nießen Reviewed-By: James M Snell Reviewed-By: Colin Ihrig Reviewed-By: Anto Aravinth --- doc/api/stream.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/api/stream.md b/doc/api/stream.md index 9f4bc4516372f9..a1513dac0c0796 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -960,8 +960,9 @@ changes: --> The `'readable'` event is emitted when there is data available to be read from -the stream. In some cases, attaching a listener for the `'readable'` event will -cause some amount of data to be read into an internal buffer. +the stream or when the end of the stream has been reached. Effectively, the +`'readable'` event indicates that the stream has new information. If data is +available, [`stream.read()`][stream-read] will return that data. ```js const readable = getReadableStreamSomehow(); @@ -975,14 +976,10 @@ readable.on('readable', function() { }); ``` -The `'readable'` event will also be emitted once the end of the stream data -has been reached but before the `'end'` event is emitted. - -Effectively, the `'readable'` event indicates that the stream has new -information: either new data is available or the end of the stream has been -reached. In the former case, [`stream.read()`][stream-read] will return the -available data. In the latter case, [`stream.read()`][stream-read] will return -`null`. For instance, in the following example, `foo.txt` is an empty file: +If the end of the stream has been reached, calling +[`stream.read()`][stream-read] will return `null` and trigger the `'end'` +event. This is also true if there never was any data to be read. For instance, +in the following example, `foo.txt` is an empty file: ```js const fs = require('fs'); @@ -1003,6 +1000,9 @@ readable: null end ``` +In some cases, attaching a listener for the `'readable'` event will cause some +amount of data to be read into an internal buffer. + 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.