# ReadableStream A interface `ReadableStream` faz parte da Streams API do Azion Runtime. Ela lê um stream de dados um chunk de cada vez, como os dados em bytes do corpo de uma resposta. A [Fetch API](/pt-br/documentacao/devtools/runtime/api-reference/fetch/) fornece uma instância específica de `ReadableStream`: a propriedade `body` de um objeto [Response](/pt-br/documentacao/devtools/runtime/api-reference/response/). Para mais informações, consulte [ReadableStream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) na MDN Web Docs. --- ## Construtor O construtor [`ReadableStream()`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream/ReadableStream) cria e retorna um objeto readable stream a partir dos handlers que você passa para ele: ```javascript new ReadableStream(handlers) ``` O objeto `handlers` aceita um método `start(controller)` e um método `cancel(reason)`. Em `start()`, `controller.enqueue()` adiciona um chunk ao stream e `controller.close()` encerra o stream. O método `cancel()` recebe o motivo passado para `stream.cancel()`. Os chunks não se limitam a bytes: um stream que você constrói pode carregar strings ou números. Para criar um stream de bytes, adicione `type: 'bytes'` ao objeto `handlers`. A seção [Exemplo](#exemplo) mostra um stream construído dessa forma. --- ## Propriedades | Propriedade | Tipo | Descrição | | ---------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ | | [`locked`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream/locked) | Boolean | `true` enquanto um reader mantém o stream. É `false` antes de `getReader()` e depois que o reader chama `releaseLock()`. | --- ## Métodos | Método | Descrição | | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`stream.cancel(reason)`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream/cancel) | Retorna uma promise que resolve quando o stream é cancelado. Uma chamada sinaliza que o consumidor perdeu o interesse no stream. O handler `cancel()` do stream recebe `reason` e pode usá-lo ou ignorá-lo. | | [`stream.getReader()`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream/getReader) | Cria um reader e bloqueia o stream para ele. Enquanto o stream está bloqueado, você não consegue obter outro reader até que o primeiro seja liberado. Para os métodos do reader, consulte [ReadableStreamDefaultReader](/pt-br/documentacao/devtools/runtime/api-reference/readable-default-reader/). | | [`stream.pipeThrough(transform)`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream/pipeThrough) | Canaliza o stream por um transform stream, ou por qualquer outro par de um writable stream e um readable stream, e retorna o lado readable. A chamada é encadeável. | | [`stream.pipeTo(destination)`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream/pipeTo) | Canaliza o stream para um `WritableStream`. Retorna uma promise que é cumprida quando a canalização termina, ou que é rejeitada quando ocorre um erro. | | [`stream.tee()`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream/tee) | Divide o stream em duas ramificações e as retorna como um array de duas instâncias de `ReadableStream`. Cada ramificação recebe os mesmos chunks. | `ReadableStream` também implementa o [protocolo iterável assíncrono](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols), então um loop [for await...of](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of) lê os chunks de um stream em ordem. --- ## Exemplo Este handler constrói um stream de dois chunks, lê o stream com um reader, libera o reader e retorna o valor de `locked` em cada etapa com os três resultados de `read()`: ```javascript export default { async fetch(request, env, ctx) { const stream = new ReadableStream({ start(controller) { controller.enqueue('a'); controller.enqueue('b'); controller.close(); }, }); const lockedBefore = stream.locked; const reader = stream.getReader(); const lockedAfter = stream.locked; const r1 = await reader.read(); const r2 = await reader.read(); const r3 = await reader.read(); reader.releaseLock(); return Response.json({ lockedBefore, lockedAfter, reads: [r1, r2, r3], lockedAfterRelease: stream.locked, }); }, }; ``` A function retorna estes valores. O terceiro `read()` informa `done` como `true` depois que o stream é encerrado, e `"[undefined]"` marca o `value` dele, que é `undefined`: ```json { "lockedBefore": false, "lockedAfter": true, "reads": [ { "value": "a", "done": false }, { "value": "b", "done": false }, { "value": "[undefined]", "done": true } ], "lockedAfterRelease": false } ``` --- ## Recursos relacionados - [Response](/pt-br/documentacao/devtools/runtime/api-reference/response.md): O objeto de resposta cuja propriedade `body` é um `ReadableStream`. - [ReadableStreamDefaultReader](/pt-br/documentacao/devtools/runtime/api-reference/readable-default-reader.md): O reader que `getReader()` bloqueia para um stream, e os métodos dele. - [ReadableStreamBYOBReader](/pt-br/documentacao/devtools/runtime/api-reference/readable-byob-reader.md): O reader que lê um stream de bytes para um buffer que você fornece. - [Web APIs](/pt-br/documentacao/devtools/runtime/api-reference/javascript.md): As outras Web APIs que o Azion Runtime suporta.