joyent/node — pull request #3785 by dominictarr (2012-07-27 18:41:45+00:00)
Title: stream: notify user of to pipe state via 'unpipe' event.

this does not change the semantics of any of the current `Stream` methods or events,
but makes only a _tiny_ two line change, which gives the user a lot more power.

firstly, by emitting pipe's internal cleanup function to the `dest` it gives the option of disconnecting the stream.

secondly, by emitting source.emit('unpipe', dest) it allows the source to know when the pipe is disconnected.

this would allow users to do things like

```` js
requestThatMayFail
.on('pipe', function (source, unpipe) {
requestThatMayFail.unpipe = unpipe
})
.on('error', function (){
requestThatMayFail.unpipe()
})

stream
.pipe(requestThatMayFail)
stream
.pipe(aVeryReliableStream)

```

Also, it would become possible to notify the upstream pipeline that the pipe has ended,
which could be necessary for long pipelines.
(such was the intention of: https://github.com/joyent/node/pull/3759 ) but with out changing any semantics.