This is a work in progress, documenting some design decisions that were made and that were non-obvious enough that we feel the need to explain them. We'll probably be adding to it as we go. If there's something you feel belongs here, please file an issue or pull request and we'll add it!
The idea of cancelling a readable stream is that it should behave as a "loss of interest": the consumer cancelling the stream expects nobody will read from it further, and that the stream should be treated in the same way as if it had closed naturally. Thus, cancellation immediately moves the stream into a "closed" state, which has the same properties as if the stream had closed itself. This gives the most consistent view of the stream to the outside world.
On the other hand, it may be important for the consumer performing the cancellation to be notified whether the cancellation succeeds or fails. To handle this, you can simply use the promise returned from .cancel():
readableStream.cancel().then(
() => console.log("Cancellation successful!"),
err => console.error("Cancellation failed!", err)
);There are only two types of streams: readable and writable streams. pipeTo is for piping between them.
For the concept of something with a writable end and a readable end, we have "duplex streams." Duplex streams are really just containers for a pair of streams, one writable and one readable, stored in the properties writable and readable respectively.
Some duplex streams will be transform streams, wherein the two streams are entangled, so that writing to the writable side affects what can be read from the readable side. This could be a very direct entanglement, of the sort produced by the TransformStream class, or something more indirect, such as the relationship between stdin and stdout.
pipeThrough is for piping into the writable half of the entangled streams and out the readable side. That is,
src.pipeThrough(through).pipeTo(dest);is really just sugar for:
src.pipeTo(through.writable);
through.readable.pipeTo(dest);