ReadableStream BYOBReader

Background

BYOB is an abbreviation of bring your own buffer. A ReadableStreamBYOBReader allows reading into a developer-supplied buffer, thus minimizing copies.

An instance of ReadableStreamBYOBReader is functionally identical to ReadableStreamDefaultReader with the exception of the read method.

A ReadableStreamBYOBReader is not instantiated via its constructor. Rather, it is retrieved from a ReadableStream:

const { readable, writable } = new TransformStream();
const reader = readable.getReader({ mode: 'byob' });

---

Methods

• read(bufferArrayBufferView) : Promise<ReadableStreamBYOBReadResult>

  • Returns a promise with the next available chunk of data read into a passed-in buffer.

• readAtLeast(minBytes, bufferArrayBufferView) : Promise<ReadableStreamBYOBReadResult>

  • Returns a promise with the next available chunk of data read into a passed-in buffer. The promise will not resolve until at least minBytes have been read.

---

Common issues

Warning

read provides no control over the minimum number of bytes that should be read into the buffer. Even if you allocate a 1 MiB buffer, the kernel is perfectly within its rights to fulfill this read with a single byte, whether or not an EOF immediately follows.

In practice, the Workers team has found that read typically fills only 1% of the provided buffer.

readAtLeast is a non-standard extension to the Streams API which allows users to specify that at least minBytes bytes must be read into the buffer before resolving the read.

---

Related resources

• Streams
• Background about BYOB readers in the Streams API WHATWG specification ↗

Was this helpful?

What did you like?

Accurate

Easy to understand

Solved my problem

Helped me decide to use the product

Other

What went wrong?

Hard to understand

Incorrect information

Missing the information

Other

Thank you for helping improve Cloudflare's documentation!