From f7af915d52a8eca8d8515c6602bf511db1b55f02 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Wed, 1 Jul 2015 12:52:47 -0700 Subject: [PATCH] doc: two minor stream doc improvements per: https://github.com/joyent/node/issues/14596 1. document that a runtime error will occur if you attempt to unshift after the end event 2. document that calling read after the end event will return null and will not trigger a runtime error Reviewed-By: James M Snell PR-URL: https://github.com/joyent/node/pull/25635 --- doc/api/stream.markdown | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/doc/api/stream.markdown b/doc/api/stream.markdown index 8434a4333c2..dfc9a6d32d4 100644 --- a/doc/api/stream.markdown +++ b/doc/api/stream.markdown @@ -228,7 +228,7 @@ returns it. If there is no data available, then it will return If you pass in a `size` argument, then it will return that many bytes. If `size` bytes are not available, then it will return `null`, -unless we've ended, in which case it will return the data remaining +unless we've ended, in which case it will return the data remaining in the buffer. If you do not specify a `size` argument, then it will return all the @@ -251,6 +251,9 @@ readable.on('readable', function() { If this method returns a data chunk, then it will also trigger the emission of a [`'data'` event][]. +Note that calling `readable.read([size])` after the `end` event has been +triggered will return `null`. No runtime error will be raised. + #### readable.setEncoding(encoding) * `encoding` {String} The encoding to use. @@ -422,6 +425,9 @@ parser, which needs to "un-consume" some data that it has optimistically pulled out of the source, so that the stream can be passed on to some other party. +Note that `stream.unshift(chunk)` cannot be called after the `end` event +has been triggered; a runtime error will be raised. + If you find that you must often call `stream.unshift(chunk)` in your programs, consider implementing a [Transform][] stream instead. (See API for Stream Implementors, below.)