Re: [streams] Merge ReadableByteStream into ReadableStream (#430)

Here's a draft of the commit log:

----

Merge ReadableByteStream into ReadableStream

Background

We originally designed the ReadableByteStream which includes extended features to handle bytes as a separate class from the ReadableStream which handles a stream of general objects.

While designing the details of ReadableByteStream (see #361), we noticed that we could simplify the ReadableStream and ReadableByteStream by moving variables and logic for handling queuing into their controller class (see #379). This turned out to be also clarifying which part of the logic is representing semantic requirement of readable streams and which part of that is implementing helper logic for easing development of underlying sources.

After the above refactoring, we also noticed that ReadableStream and ReadableByteStream share most of their code. So, we attempted to merge the ReadableByteStream into the ReadableStream.

Change summary

The new ReadableStream has two reader getter methods when BYOB reading is available. Availability of BYOB reading is determined by whether or not the underlying source passed to the ReadableStream had BYOB pulling functionality. This is indicated by the "byob" parameter of the ReadableStream constructor.

The two readers are named the default reader and BYOB reader. The default reader's read() method takes no argument. The resulting promise of the read() method will be fulfilled by a generated chunk. The BYOB reader's read() method takes one argument. It must be an ArrayBufferView. The ReadableStream will fill the passed ArrayBufferView and fulfills the returned promise with it. The ArrayBufferView might be transferred several times.

When the byob parameter is false, the underlying source is given a ReadableStreamDefaultController on start() method call. This class provides methods to enqueue a new chunk and know the status of the queue. Its queuing strategy is configured by the parameters passed to the ReadableStream's constructor. The underlying source can subscribe to events on which chunks are drained from the queue by implementing the "pull" method on it. Only the getReader() method will be available on the ReadableStream.

When the byob parameter is false, the underlying source is given a ReadableStreamBYOBController on start() method call. In addition to the functionalities of the ReadableStreamDefaultController, this controller provides a getter named byobRequest() which exposes the oldest outstanding BYOB reading request into which the underlying source can put bytes directly (see #423). Both the getReader() and the getBYOBReader() method will be available on the ReadableStream.

The ReadableStreamBYOBController can be configured to convert read requests from a default reader into BYOB read request by allocating a buffer and exposing it at the byobRequest getter automatically. This ease implementation of a reactive underlying source.

Changes included in this commit

In addition to the major changes as described above, this commit includes bunch of design / logic / aesthetic changes as follows:

- remove auto release feature from the ReadableByteStream
- rename Byob to BYOB
- move TransferArrayBuffer to helpers.js
- make the default highWaterMark of the byte source version to 0
- port the functionality that the start method can delay pulling by returning a pending Promise to the ReadableStreamBYOBController
- implement `[[disturbed]]` feature to the byte handling logic
- port highWaterMark mechanism to ReadableByteStreamController
- changes on semantics of the controller methods (see #424)
  - make controller.close() and controller.enqueue() fail when the stream is not in the readable state
  - make controller.enqueue() throw a predefined TypeError, not the stored error
  - as a result test/pipe-to-options.js, readable-streams/general.js and test/readable-stream-templated.js have been updated
- rename ReadableStreamController to ReadableStreamDefaultController
- rename ReadableStreamReader to ReadableStreamDefaultReader
- rename ReadableByteStreamController to ReadableStreamBYOBController
- read(view) now checks view.byteLength before setting [[disturbed]]

---
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/streams/pull/430#issuecomment-201305295