Add .destroy to Readable and Writable prototypes

[mafintosh]

This is an attempt to implement #124. Basically it adds .destroy to the Readable and Writable prototypes. These prototypes forwards the call to ._destroy(cb) the first time destroy is called. If destroy is called twice the second call is ignored.

This allows you prematurely end a stream more easily. As an example here is a file reader

var createFileStream = function (fd) {
  var rs = new stream.Readable()

  rs._destroy = function (cb) {
    fs.close(fd, cb)
  }

  rs._read = function (size) {
    var buf = new Buffer(size)
    fs.read(fd, buf, 0, size, null, function (err, len) {
      if (err) {
        rs.emit('error', err)
        return rs.destroy()
      }
      rs.push(buf.slice(0, len))
    })
  }

  return rs
}

Calling rs.destroy() will now close the file descriptor and emit close when the close is done.

[chrisdickinson]

Sort of tempted to say "may as well specially implement destroy on Duplex" just to avoid adding another case of the parent class having intimate knowledge of its subclass.

[mafintosh]

yea i think thats good idea. will update the pr

[sonewman]

It's almost a shame we couldn't add this to the base stream class somehow since they are both doing pretty much the same thing.

Better still if there was a base StreamState that all states inherited from, although that would restrict people from calling _destroy() directly, however that might not be such a bad thing...

[chrisdickinson]

Curious: is the omission of .destroy from Readable#pipe/on{error,close} intentional?

[mafintosh]

@chrisdickinson I forgot about that :) I'll add it.

[sonewman]

What do you think about adding it to the construction also? e.g.:

var readable = new stream.Readable({
  destroy() {
    // burn down the house
  }
});

[calvinmetcalf]

Shouldn't this be against the main io repo or is this just for discussion?

[yoshuawuyts]

What steps must be taken to get this into core? I'd be keen to see it land since right now .destroy() lives in a weird "you should probably implement it, but it's not part of Node core yet" state.

[calvinmetcalf]

open pull request on this repo https://github.com/nodejs/node

[calvinmetcalf]

I'm going to close this, an issue is where we probably want to continue this discussion.