Add examples for stopping pipes

[domenic]

Closes #1055.

---

Preview | Diff

[ricea]

lgtm

[ricea]

Having two sentences inside "()" looks a little odd to me. I think you could just omit the "()" characters here without changing the meaning too much. If you like. I don't have really strong feelings about it.

[domenic]

Eh, on balance I like it, as a way of deemphasizing these sentences. I'll keep it. Thanks for weighing in though.

[domenic]

FYI folks might be interested in the discussion I'm having over in whatwg/dom#881 on making this pattern less terrible.

[domenic]

Hmm, or we could do something entirely on the Streams side. For example:

const controller = new AbortController();
readable1.pipeTo(writable, { preventAbort: true, signal: controller.signal });

// ... some time later ...
controller.abort();

// Start the new pipe, when ready:
readable2.pipeTo(writable, { waitForPrevious: true });

with the same semantics. (That would require storing the previous pipe promise while it is not settled, but that seems OK.)

I don't think we could make waitForPrevious the default; my intuition is that that would transform too many error cases into stalled cases. But maybe it'd work...