Streams API
Experimental: Esta é uma tecnologia experimental
Verifique a tabela de compatibilidade entre Navegadores cuidadosamente antes de usar essa funcionalidade em produção.
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 aWritableStream
, the underlying sink is given a correspondingWritableStreamDefaultController
instance to manipulate.
Related stream APIs and operations
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 aReadableStream
in thebody
property of itsRequestInit
dictionary. ThisRequest
could then be passed to aWindowOrWorkerGlobalScope.fetch()
to commence fetching the stream. Body
-
The response
Body
returned by a successful fetch request is exposed by default as aReadableStream
, and can have a reader attached to it, etc.
ByteStream-related interfaces
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