Surprising behavior in stream.read(n) when stream ends

[sorccu]

It seems that when a stream ends, and it still has unread data in its buffers, a final readable event gets emitted, and stream.read(n) where n > unread.length happily returns the remaining bytes even though it normally wouldn't.

Example of said behavior:

var fs = require('fs')
var out = fs.createReadStream(__filename)

out.on('readable', function() {
  console.log('readable', out.read(10000))
})

out.on('end', function() {
  console.log('end')
})

(note that the file is considerably smaller than requested 10000 bytes)

Produces:

readable null
readable <Buffer 76 61 72 20 66 73 20 3d 20 72 65 71 75 69 72 65 28 27 66 73 27 29 0a 76 61 72 20 6f 75 74 20 3d 20 66 73 2e 63 72 65 61 74 65 52 65 61 64 53 74 72 65 61 ...>
end

(i.e. just before ending, it returned what it had, instead of the requested amount)

This behavior is surprising because the documentation lets you believe that stream.read(n) can only ever return the requested amount of bytes:

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.

I was able to dig a removed explanation for this behavior, and I'm not necessarily questioning the validity of it, but it seems very odd and confusing that none of this is documented and even the useful comment has been removed.

[indutny]

cc @tjfontaine

[adrianblynch]

@sorccu - Out of interest, what would you expect to see logged to the console?

readable null
end

[sorccu]

Same as now, I suppose. It's just that the docs fail to mention anything about this case and you're left to figure it out on your own. If you blindly rely on the current docs you're likely to have a bug in your code.

[Burstaholic]

Yeah, this basically seems like a documentation issue. I wouldn't expect the data to simply be lost.

[jasnell]

@sorccu ... interested in helping out with a PR? :-)

[plafer]

Can I take this one?

[sorccu]

Sure!

On Sunday, June 28, 2015, Philippe Laferriere notifications@github.com
wrote:

Can I take this one?

—
Reply to this email directly or view it on GitHub
#7273 (comment).