joyent/node — pull request #8209 by jeromew (2014-08-20 12:22:40+00:00)
Title: clarify the 'close' event

After a discussion with @jonathanong and @dougwilson related to the raw-body module, we realized that maybe the documentation for the "close" event is not correct on node.js documentation.

This PR proposes to start a discussion on the meaning of the 'close' event or accept the definition given by @jonathanong which seem to be more in line with what is done in stream modules on npm.

The current definition seem to imply that the close event is only related to the closing of an underlying ressource, meaning that we could receive and 'end' event after the 'close' event if the underlying resource has been close but we still have some data in the internal buffers.

The current definition is also silent on the case when there are many underlying resources (for example many file descriptors). Should we have many 'close' event or just one ?

added to that, it seems that a dest.'close' event is also used to unpipe automatically a destination in https://github.com/joyent/node/blob/master/lib/_stream_readable.js#L564 which probably makes sense but seem to be far fetched if 'close' is only related to underlying ressources of the Readable part of a stream.

I don't know if they are all interested in this thread but their stream knowledge could be very beneficial if they can share their experience working with streams: @dominictarr, @substack, @chrisdickinson