[streams] [WIP] Putting a chunk back in the readable stream queue (#275)

See #3, and especially the real-world use case in the [MSE spec](https://w3c.github.io/media-source/#sourcebuffer-stream-append-loop), step 9.

This doesn't contain any spec updates yet, just prototype in the reference implementation---including some fairly-exhaustive tests. Suggestions for more tests welcome!

Thoughts:

- putBack was a name thrown around in #3. It's better than Node's "unshift", certainly. The Wikipedia [double-ended queue](https://en.wikipedia.org/wiki/Double-ended_queue) article is entirely unhelpful (and we're using `read()` instead of `dequeue()` anyway). One idea that I came up with and am starting to like is `rs.unRead(chunk)`. (Or should it be `unread`, no capital-R?) I might go with that if nobody objects or comes up with something better.

- It might be nice to let the underlying source provide some sort of hook that gets called upon putBack. This could allow things like: causing any array buffers that are putBack to be transferred (see discussion in #3), or validating that all chunks in a stream stay the same type. I am hesitant to add this until someone explicitly asks for it though. Anyone want to convince me it's a really good idea, or shall we leave it for later?

- Unlike `enqueue`, right now `putBack` does not return any backpressure-indicating value. We could easily add it, but I am not sure it should be the consumers responsibility to worry about whether they're putting back too much data? putBack is supposed to be a pretty rare, out-of-band occurrence, and not part of the normal backpressure negotation protocol.
You can view, comment on, or merge this pull request online at:

  https://github.com/whatwg/streams/pull/275

-- Commit Summary --

  * First draft of putBack

-- File Changes --

    M reference-implementation/lib/exclusive-stream-reader.js (18)
    M reference-implementation/lib/queue-with-sizes.js (11)
    M reference-implementation/lib/readable-stream-abstract-ops.js (38)
    M reference-implementation/lib/readable-stream.js (16)
    M reference-implementation/test/bad-underlying-sources.js (101)
    M reference-implementation/test/brand-checks.js (6)
    M reference-implementation/test/exclusive-stream-reader.js (8)
    M reference-implementation/test/readable-stream.js (100)

-- Patch Links --

https://github.com/whatwg/streams/pull/275.patch
https://github.com/whatwg/streams/pull/275.diff

---
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/streams/pull/275