ReadableStreamBYOBReader

The ReadableStreamBYOBReader interface of Azion Runtime: its constructor, the closed property, and the methods that read a byte stream into a buffer you supply.

Last updated

View as Markdown Agent setup

The ReadableStreamBYOBReader interface is part of the Streams API of Azion Runtime. It reads a byte stream into a buffer that you supply, without copying the data. Use it to move data from sources that deliver it as a series of anonymous bytes, such as files. BYOB stands for “Bring Your Own Buffer”. For more information, refer to ReadableStreamBYOBReader on MDN Web Docs.

Constructor

The ReadableStreamBYOBReader() constructor creates and returns a reader for the stream you pass to it:

new ReadableStreamBYOBReader(stream)

You can also create the reader from the stream: call getReader() on a ReadableStream and set mode: 'byob' in its options. The examples on this page create the stream as a byte stream, with type: 'bytes' in its handlers.

Properties

PropertyTypeDescription
closedPromiseFulfills when the stream closes. Rejects when the stream throws an error or when the reader releases its lock. Use it to run code when the stream ends.

Methods

MethodDescription
reader.cancel(reason)Returns a promise that resolves when the stream is canceled. A call signals that the consumer has lost interest in the stream. The underlying source receives reason and can use it or ignore it.
reader.read(view)Takes a view that the stream writes data into, such as a Uint8Array. Returns a promise that resolves with the next chunk of the stream, or rejects when the stream is closed or has an error.
reader.releaseLock()Releases the lock of the reader on the stream.

Examples

This handler constructs a byte stream that holds 5 bytes, creates a BYOB reader with getReader(), and reads the stream into an 8-byte buffer. It returns the class name of the reader and the result of read():

JavaScript
01export default {
02 async fetch(request, env, ctx) {
03 const stream = new ReadableStream({
04 type: 'bytes',
05 start(controller) {
06 controller.enqueue(new Uint8Array([1, 2, 3, 4, 5]));
07 controller.close();
08 },
09 });
10 const reader = stream.getReader({ mode: 'byob' });
11 const { value, done } = await reader.read(new Uint8Array(new ArrayBuffer(8)));
12 return Response.json({
13 ctor: reader.constructor.name,
14 done,
15 bytes: Array.from(value),
16 byteLength: value.byteLength,
17 });
18 },
19};

The function returns these values. The returned view holds the 5 bytes the stream wrote, not the full 8 bytes of the buffer:

JSON
01{
02 "ctor": "ReadableStreamBYOBReader",
03 "done": false,
04 "bytes": [
05 1,
06 2,
07 3,
08 4,
09 5
10 ],
11 "byteLength": 5
12}

To read a stream chunk by chunk into one buffer, call read() again from the result of each read, with a view of the part of the buffer that is still empty. In this sample, stream is a byte stream of 10 bytes and buffer holds 4,000 bytes:

JavaScript
01const stream = new ReadableStream({ type: 'bytes', start(c) { c.enqueue(new Uint8Array(10).fill(7)); c.close(); } });
02const reader = stream.getReader({ mode: "byob" });
03let buffer = new ArrayBuffer(4000);
04
05readStream(reader);
06
07function readStream(reader) {
08 let bytesReceived = 0;
09 let offset = 0;
10
11 while (offset < buffer.byteLength) {
12 // read() returns a promise that resolves when a value has been received
13 reader.read(new Uint8Array(buffer, offset, buffer.byteLength - offset))
14 .then(function processBytes({ done, value }) {
15 // Result objects contain two properties:
16 // done - true if the stream has already given all its data.
17 // value - some data. Always undefined when done is true.
18
19 if (done) {
20 // There is no more data in the stream
21 return;
22 }
23
24 buffer = value.buffer;
25 offset += value.byteLength;
26 bytesReceived += value.byteLength;
27
28 // Read some more, and call this function again
29 return reader.read(new Uint8Array(buffer, offset, buffer.byteLength - offset)).then(processBytes);
30 });
31 }
32}
ReadableStream

The stream that a BYOB reader reads, and how to construct a byte stream.

ReadableStreamDefaultReader

The reader that getReader() returns when you pass no mode.

Response

A response whose body stream a reader can consume.

Web APIs

The other Web APIs that Azion Runtime supports.