Surprising behavior in stream.read(n) when stream ends #7273
Description
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.