chore: add byob stream reference documentation

Author: Jake Champion

documentation/docs/globals/ReadableByteStreamController/prototype/byobRequest.md

@@ -0,0 +1,17 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# byobRequest
+
+The **`byobRequest`** read-only property of the `ReadableByteStreamController` interface returns the current BYOB request, or `null` if there are no pending requests.
+
+An underlying byte source should check this property, and use it to write data to the stream if it exists (rather than using `ReadableByteStreamController.enqueue()`).
+This will result in an efficient zero-byte transfer of the data to the consumer.
+
+## Value
+
+A `ReadableStreamBYOBRequest` object instance, or `null`.

documentation/docs/globals/ReadableByteStreamController/prototype/close.md

@@ -0,0 +1,34 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# close()
+
+The **`close()`** method of the `ReadableByteStreamController` interface closes the associated stream.
+
+This might be called by the underlying source when its data source has been exhausted/completed.
+
+> **Note:** Readers will still be able to read any previously-enqueued chunks from the stream, but once those are read, the stream will become closed.
+> However if there is an outstanding and partially written `byobRequest` when `close()` is called, the stream will be errored.
+
+## Syntax
+
+```js
+close()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+`undefined`.
+
+### Exceptions
+
+- `TypeError`
+  - : Thrown if the source object is not a `ReadableByteStreamController`, it is already closed, or the stream is not readable for some other reason.

documentation/docs/globals/ReadableByteStreamController/prototype/desiredSize.md

@@ -0,0 +1,21 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# desiredSize
+
+The **`desiredSize`** read-only property of the`ReadableByteStreamController` interface returns the number of bytes required to fill the stream's internal queue to its "desired size".
+
+The value is used by the stream to indicate a preferred flow rate to the underlying source.
+Sources that support throttling or pausing their inflow of data (not all do!) should control the inflow such that `desiredSize` of the stream buffer is kept positive and as close to zero as possible.
+
+The `desiredSize` is used to apply backpressure from downstream consumers.
+
+## Value
+
+An integer. Note that this can be negative if the queue is over-full.
+
+The value will be `null` if the stream has errored and `0` if it is closed.

documentation/docs/globals/ReadableByteStreamController/prototype/enqueue.md

@@ -0,0 +1,33 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# enqueue()
+
+The **`enqueue()`** method of the `ReadableByteStreamController` interface enqueues a given chunk on the associated readable byte stream (the chunk is copied into the stream's internal queues).
+
+This should only be used to transfer data to the queue when `byobRequest` is `null`.
+
+## Syntax
+
+```js
+enqueue(chunk)
+```
+
+### Parameters
+
+- `chunk`
+  - : The chunk to enqueue.
+
+### Return value
+
+`undefined`.
+
+### Exceptions
+
+- `TypeError`
+  - : Thrown if the source object is not a `ReadableByteStreamController`, or the stream cannot be read for some other reason, or the chunk is not an object, or the chunk's internal array buffer is non-existent, zero-length, or detached.
+    It is also thrown if the stream has been closed.

documentation/docs/globals/ReadableByteStreamController/prototype/error.md

@@ -0,0 +1,34 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# error()
+
+The **`error()`** method of the `ReadableByteStreamController` interface causes any future interactions with the associated stream to error with the specified reason.
+
+This is commonly called by an underlying source to surface an error from the interface where it gets its data (such as a file-read or socket error).
+It can also be called from elsewhere to trigger a stream error, for example if another part of the system that the stream relies on fails.
+
+## Syntax
+
+```js
+error(errorObject)
+```
+
+### Parameters
+
+- `errorObject`
+  - : Any object that you want future interactions to fail with.
+
+### Return value
+
+`undefined`
+
+### Exceptions
+
+- `TypeError`
+  - : Thrown if the source object is not a `ReadableByteStreamController`, or the stream is not readable for some other reason.
+

documentation/docs/globals/ReadableStreamBYOBReader/ReadableStreamBYOBReader.md

@@ -0,0 +1,33 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# ReadableStreamBYOBReader()
+
+The **`ReadableStreamBYOBReader()`** constructor creates and returns a `ReadableStreamBYOBReader` object instance.
+
+> **Note:** You generally wouldn't use this constructor manually;
+> instead, you'd use the `ReadableStream.getReader()` method with the argument `"byob"`.
+
+## Syntax
+
+```js
+new ReadableStreamBYOBReader(stream)
+```
+
+### Parameters
+
+- `stream`
+  - : The `ReadableStream` to be read.
+
+### Return value
+
+An instance of the `ReadableStreamBYOBReader` object.
+
+### Exceptions
+
+- `TypeError`
+  - : Thrown if the supplied `stream` parameter is not a `ReadableStream`, or it is already locked for reading by another reader, or its stream controller is not a `ReadableByteStreamController`.

documentation/docs/globals/ReadableStreamBYOBReader/prototype/cancel.md

@@ -0,0 +1,34 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# cancel()
+
+The **`cancel()`** method of the `ReadableStreamBYOBReader` interface returns a `Promise` that resolves when the stream is canceled.
+Calling this method signals a loss of interest in the stream by a consumer.
+
+> **Note:** If the reader is active, the `cancel()` method behaves the same as that for the associated stream (`ReadableStream.cancel()`).
+
+## Syntax
+
+```js
+cancel()
+cancel(reason)
+```
+
+### Parameters
+
+- `reason` __optional__
+  - : A human-readable reason for the cancellation. The underlying source may or may not use it.
+
+### Return value
+
+A `Promise`, which fulfills with the value given in the `reason` parameter.
+
+### Exceptions
+
+- `TypeError`
+  - : The source object is not a `ReadableStreamBYOBReader`, or the stream has no owner.

documentation/docs/globals/ReadableStreamBYOBReader/prototype/closed.md

@@ -0,0 +1,16 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# closed
+
+The **`closed`** read-only property of the `ReadableStreamBYOBReader` interface returns a `Promise` that fulfills when the stream closes, or rejects if the stream throws an error or the reader's lock is released.
+
+This property enables you to write code that responds to an end to the streaming process.
+
+## Value
+
+A `Promise`.

documentation/docs/globals/ReadableStreamBYOBReader/prototype/read.md

@@ -0,0 +1,73 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# read()
+
+The **`read()`** method of the `ReadableStreamBYOBReader` interface is used to read data into a view on a user-supplied buffer from an associated readable byte stream.
+A request for data will be satisfied from the stream's internal queues if there is any data present.
+If the stream queues are empty, the request may be supplied as a zero-copy transfer from the underlying byte source.
+
+The method takes as an argument a view on a buffer that supplied data is to be read into, and returns a `Promise`.
+The promise fulfills with an object that has properties `value` and `done` when data comes available, or if the stream is cancelled.
+If the stream is errored, the promise will be rejected with the relevant error object.
+
+If a chunk of data is supplied, the `value` property will contain a new view.
+This will be a view over the same buffer/backing memory (and of the same type) as the original `view` passed to the `read()` method, now populated with the new chunk of data.
+Note that once the promise fulfills, the original `view` passed to the method will be detached and no longer usable.
+The promise will fulfill with a `value: undefined` if the stream has been cancelled.
+In this case the backing memory region of `view` is discarded and not returned to the caller (all previously read data in the view's buffer is lost).
+
+The `done` property indicates whether or not more data is expected.
+The value is set `true` if the stream is closed or cancelled, and `false` otherwise.
+
+## Syntax
+
+```js
+read(view)
+```
+
+### Parameters
+
+- `view`
+  - : The view that data is to be read into.
+
+### Return value
+
+A `Promise`, which fulfills/rejects with a result depending on the state of the stream.
+
+The following are possible:
+
+- If a chunk is available and the stream is still active, the promise fulfills with an object of the form:
+
+  ```
+  { value: theChunk, done: false }
+  ```
+
+  `theChunk` is a view containing the new data.
+  This is a view of the same type and over the same backing memory as the `view` passed to the `read()` method.
+  The original `view` will be detached and no longer usable.
+
+- If the stream is closed, the promise fulfills with an object of the form (where `theChunk` has the same properties as above):
+
+  ```
+  { value: theChunk, done: true }
+  ```
+
+- If the stream is cancelled, the promise fulfills with an object of the form:
+
+  ```
+  { value: undefined, done: true }
+  ```
+
+  In this case the backing memory is discarded.
+
+- If the stream throws an error, the promise rejects with the relevant error.
+
+### Exceptions
+
+- `TypeError`
+  - : The source object is not a `ReadableStreamBYOBReader`, the stream has no owner, the view is not an object or has become detached, the view's length is 0, or `ReadableStreamBYOBReader.releaseLock()` is called (when there's is a pending read request).

documentation/docs/globals/ReadableStreamBYOBReader/prototype/releaseLock.md

@@ -0,0 +1,35 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# releaseLock()
+
+The **`releaseLock()`** method of the `ReadableStreamBYOBReader` interface releases the reader's lock on the stream.
+After the lock is released, the reader is no longer active.
+
+The reader will appear errored if the associated stream is errored when the lock is released; otherwise, the reader will appear closed.
+
+If the reader's lock is released while it still has pending read requests then the promises returned by the reader's `ReadableStreamBYOBReader.read()` method are immediately rejected with a `TypeError`.
+Unread chunks remain in the stream's internal queue and can be read later by acquiring a new reader.
+
+## Syntax
+
+```js
+releaseLock()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+`undefined`.
+
+### Exceptions
+
+- `TypeError`
+  - : Thrown if the source object is not a `ReadableStreamBYOBReader`.