# ReadableStreamBYOBReader

A interface `ReadableStreamBYOBReader` faz parte da Streams API do Azion Runtime. Ela lê um stream de bytes para um buffer que você fornece, sem copiar os dados. Use-a para transferir dados de fontes que os entregam como uma série de bytes anônimos, como arquivos. BYOB significa "Bring Your Own Buffer" (traga o seu próprio buffer). Para mais informações, consulte [ReadableStreamBYOBReader](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamBYOBReader) na MDN Web Docs.

---

## Construtor

O construtor [`ReadableStreamBYOBReader()`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamBYOBReader/ReadableStreamBYOBReader) cria e retorna um reader para o stream que você passa para ele:

```javascript
new ReadableStreamBYOBReader(stream)
```

Você também pode criar o reader a partir do stream: chame `getReader()` em um [ReadableStream](/pt-br/documentacao/devtools/runtime/api-reference/readable-stream/) e defina `mode: 'byob'` nas opções. Os exemplos desta página criam o stream como um stream de bytes, com `type: 'bytes'` nos handlers.

---

## Propriedades

| Propriedade                                                                                  | Tipo    | Descrição                                                                                                                                                                   |
| -------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`closed`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamBYOBReader/closed) | Promise | É cumprida quando o stream é encerrado. É rejeitada quando o stream lança um erro ou quando o reader libera o bloqueio. Use-a para executar código quando o stream termina. |

---

## Métodos

| Método                                                                                                          | Descrição                                                                                                                                                                                                 |
| --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`reader.cancel(reason)`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamBYOBReader/cancel)     | Retorna uma promise que resolve quando o stream é cancelado. Uma chamada sinaliza que o consumidor perdeu o interesse no stream. A fonte subjacente recebe `reason` e pode usá-lo ou ignorá-lo.           |
| [`reader.read(view)`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamBYOBReader/read)           | Recebe uma view na qual o stream escreve os dados, como um `Uint8Array`. Retorna uma promise que resolve com o próximo chunk do stream, ou que é rejeitada quando o stream está encerrado ou tem um erro. |
| [`reader.releaseLock()`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamBYOBReader/releaseLock) | Libera o bloqueio do reader sobre o stream.                                                                                                                                                               |

---

## Exemplos

Este handler constrói um stream de bytes que contém 5 bytes, cria um BYOB reader com `getReader()` e lê o stream para um buffer de 8 bytes. Ele retorna o nome da classe do reader e o resultado de `read()`:

```javascript
export default {
  async fetch(request, env, ctx) {
    const stream = new ReadableStream({
      type: 'bytes',
      start(controller) {
        controller.enqueue(new Uint8Array([1, 2, 3, 4, 5]));
        controller.close();
      },
    });
    const reader = stream.getReader({ mode: 'byob' });
    const { value, done } = await reader.read(new Uint8Array(new ArrayBuffer(8)));
    return Response.json({
      ctor: reader.constructor.name,
      done,
      bytes: Array.from(value),
      byteLength: value.byteLength,
    });
  },
};
```

A function retorna estes valores. A view retornada contém os 5 bytes que o stream escreveu, e não os 8 bytes completos do buffer:

```json
{
 "ctor": "ReadableStreamBYOBReader",
 "done": false,
 "bytes": [
  1,
  2,
  3,
  4,
  5
 ],
 "byteLength": 5
}
```

Para ler um stream chunk por chunk para um único buffer, chame `read()` de novo a partir do resultado de cada leitura, com uma view da parte do buffer que ainda está vazia. Neste exemplo, `stream` é um stream de bytes de 10 bytes e `buffer` comporta 4.000 bytes:

```javascript
const stream = new ReadableStream({ type: 'bytes', start(c) { c.enqueue(new Uint8Array(10).fill(7)); c.close(); } });
const reader = stream.getReader({ mode: "byob" });
let buffer = new ArrayBuffer(4000);

readStream(reader);

function readStream(reader) {
  let bytesReceived = 0;
  let offset = 0;

  while (offset < buffer.byteLength) {
    // read() returns a promise that resolves when a value has been received
    reader.read(new Uint8Array(buffer, offset, buffer.byteLength - offset))
      .then(function processBytes({ done, value }) {
        // Result objects contain two properties:
        // done  - true if the stream has already given all its data.
        // value - some data. Always undefined when done is true.

        if (done) {
          // There is no more data in the stream
          return;
        }

        buffer = value.buffer;
        offset += value.byteLength;
        bytesReceived += value.byteLength;

        // Read some more, and call this function again
        return reader.read(new Uint8Array(buffer, offset, buffer.byteLength - offset)).then(processBytes);
      });
  }
}
```

---

## Recursos relacionados

- [ReadableStream](/pt-br/documentacao/devtools/runtime/api-reference/readable-stream.md): O stream que um BYOB reader lê, e como construir um stream de bytes.
- [ReadableStreamDefaultReader](/pt-br/documentacao/devtools/runtime/api-reference/readable-default-reader.md): O reader que `getReader()` retorna quando você não passa um modo.
- [Response](/pt-br/documentacao/devtools/runtime/api-reference/response.md): Uma resposta cujo stream `body` um reader pode consumir.
- [Web APIs](/pt-br/documentacao/devtools/runtime/api-reference/javascript.md): As outras Web APIs que o Azion Runtime suporta.