Streams API

Experimental: Esta é uma tecnologia experimental
Verifique a tabela de compatibilidade entre Navegadores cuidadosamente antes de usar essa funcionalidade em produção.

A API Streams permite que o JavaScript acesse programaticamente fluxos de dados recebidos pela rede e os processe conforme desejado pelo desenvolvedor.

Conceitos e Uso

O streaming envolve a divisão de um recurso que você deseja receber pela rede em pequenos blocos e, em seguida, processa esses blocos aos poucos. Isso é algo que os navegadores fazem de qualquer maneira ao receber recursos para serem exibidos em páginas da web — o buffer de vídeos e mais está gradualmente disponível para reprodução, e às vezes você verá imagens sendo exibidas gradualmente conforme mais é carregado.

Mas isto nunca esteve disponível para JavaScript antes. Anteriormente, se quiséssemos processar um recurso de algum tipo (seja ele um vídeo, ou um arquivo de texto, etc.), Teríamos que baixar o arquivo inteiro, espera até que seja desserializado em um formato adequado, então processa todo o lote após ser totalmente recebido.

Com o Streams disponível para JavaScript, tudo isso muda - agora você pode começar a processar dados brutos com JavaScript bit a bit assim que estiverem disponíveis no lado do cliente, sem a necessidade de gerar um buffer, string ou blob.

Também há mais vantagens - você pode detectar quando os fluxos começam ou terminam, encadeia os fluxos juntos, trata os erros e cancela os fluxos quando necessário e reage à velocidade em que o fluxo está sendo lido.

O uso básico de Streams gira em torno de tornar as respostas disponíveis como streams. Por exemplo, a resposta Body retornada com sucesso de uma fetch request pode ser exposta como um ReadableStream, e você pode lê-lo usando um leitor criado com ReadableStream.getReader(), cancela-lo com ReadableStream.cancel(), etc.

Usos mais complicados envolvem a criação de seu próprio fluxo usando o contrutor ReadableStream(), por exemplo para processar dados dentro de um service worker.

Você também pode gravar dados em streams usando WritableStream.

Nota: Você pode encontrar muito mais detalhes sobre a teoria e prática de streams em nossos artigos — Streams API concepts, Using readable streams, e Using writable streams.

Stream interfaces

Readable streams

ReadableStream

Represents a readable stream of data. It can be used to handle response streams of the Fetch API, or developer-defined streams (e.g. a custom ReadableStream() constructor).

ReadableStreamDefaultReader

Represents a default reader that can be used to read stream data supplied from a network (e.g. a fetch request).

ReadableStreamDefaultController

Represents a controller allowing control of a ReadableStream's state and internal queue. Default controllers are for streams that are not byte streams.

Writable streams

WritableStream

Provides a standard abstraction for writing streaming data to a destination, known as a sink. This object comes with built-in backpressure and queuing.

WritableStreamDefaultWriter

Represents a default writable stream writer that can be used to write chunks of data to a writable stream.

WritableStreamDefaultController

Represents a controller allowing control of a WritableStream's state. When constructing a WritableStream, the underlying sink is given a corresponding WritableStreamDefaultController instance to manipulate.

ByteLengthQueuingStrategy

Provides a built-in byte length queuing strategy that can be used when constructing streams.

CountQueuingStrategy

Provides a built-in chunk counting queuing strategy that can be used when constructing streams.

Extensions to other APIs

Request

When a new Request object is constructed, you can pass it a ReadableStream in the body property of its RequestInit dictionary. This Request could then be passed to a WindowOrWorkerGlobalScope.fetch() to commence fetching the stream.

Body

The response Body returned by a successful fetch request is exposed by default as a ReadableStream, and can have a reader attached to it, etc.

Aviso: Important: these are not implemented anywhere as yet, and questions have been raised as to whether the spec details are in a finished enough state for them to be implemented. This may change over time.

ReadableStreamBYOBReader

Represents a BYOB ("bring your own buffer") reader that can be used to read stream data supplied by the developer (e.g. a custom ReadableStream() constructor).

ReadableByteStreamController

Represents a controller allowing control of a ReadableStream's state and internal queue. Byte stream controllers are for byte streams.

ReadableStreamBYOBRequest

Represents a pull into request in a ReadableByteStreamController.

Examples

We have created a directory of examples to go along with the Streams API documentation — see mdn/dom-examples/streams. The examples are as follows:

  • Simple stream pump: This example shows how to consume a ReadableStream and pass its data to another.
  • Grayscale a PNG: This example shows how a ReadableStream of a PNG can be turned into grayscale.
  • Simple random stream: This example shows how to use a custom stream to generate random strings, enqueue them as chunks, and then read them back out again.
  • Simple tee example: This example extends the Simple random stream example, showing how a stream can be teed and both resulting streams can be read independently.
  • Simple writer: This example shows how to to write to a writable stream, then decode the stream and write the contents to the UI.
  • Unpack chunks of a PNG: This example shows how pipeThrough() can be used to transform a ReadableStream into a stream of other data types by transforming a data of a PNG file into a stream of PNG chunks.

Examples from other developers:

Especificações

Specification
Streams Standard
# rs-class
Streams Standard
# ws-class

Compatibilidade com navegadores

api.ReadableStream

BCD tables only load in the browser

api.WritableStream

BCD tables only load in the browser

See also