API de Streams da Web

[Histórico]

Versão	Alterações
v21.0.0	Não mais experimental.
v18.0.0	O uso desta API não emite mais um aviso de tempo de execução.
v16.5.0	Adicionada em: v16.5.0

[Estável: 2 - Estável]

Estável: 2 Estabilidade: 2 - Estável

Uma implementação do Padrão WHATWG Streams.

Visão geral

O Padrão WHATWG Streams (ou "streams da web") define uma API para lidar com dados em streaming. É semelhante à API Streams do Node.js, mas surgiu posteriormente e tornou-se a API "padrão" para streaming de dados em muitos ambientes JavaScript.

Existem três tipos principais de objetos:

• ReadableStream - Representa uma fonte de dados em streaming.
• WritableStream - Representa um destino para dados em streaming.
• TransformStream - Representa um algoritmo para transformar dados em streaming.

Exemplo ReadableStream

Este exemplo cria um ReadableStream simples que envia o timestamp atual performance.now() a cada segundo para sempre. Um iterável assíncrono é usado para ler os dados do stream.

ESM

import { ReadableStream } from 'node:stream/web'

import { setInterval as every } from 'node:timers/promises'

import { performance } from 'node:perf_hooks'

const SECOND = 1000

const stream = new ReadableStream({
  async start(controller) {
    for await (const _ of every(SECOND)) controller.enqueue(performance.now())
  },
})

for await (const value of stream) console.log(value)

CJS

const { ReadableStream } = require('node:stream/web')

const { setInterval: every } = require('node:timers/promises')

const { performance } = require('node:perf_hooks')

const SECOND = 1000

const stream = new ReadableStream({
  async start(controller) {
    for await (const _ of every(SECOND)) controller.enqueue(performance.now())
  },
})

;(async () => {
  for await (const value of stream) console.log(value)
})()

API

Classe: ReadableStream

[Histórico]

Versão	Alterações
v18.0.0	Esta classe agora é exposta no objeto global.
v16.5.0	Adicionada em: v16.5.0

new ReadableStream([underlyingSource [, strategy]])

Adicionado em: v16.5.0

• underlyingSource <Objeto>

  • start <Função> Uma função definida pelo usuário que é invocada imediatamente quando o ReadableStream é criado.

  • controller <ReadableStreamDefaultController> | <ReadableByteStreamController>

  • Retorna: undefined ou uma promise resolvida com undefined.

  • pull <Função> Uma função definida pelo usuário que é chamada repetidamente quando a fila interna do ReadableStream não está cheia. A operação pode ser síncrona ou assíncrona. Se assíncrona, a função não será chamada novamente até que a promise retornada anteriormente seja resolvida.

  • controller <ReadableStreamDefaultController> | <ReadableByteStreamController>

  • Retorna: Uma promise resolvida com undefined.

  • cancel <Função> Uma função definida pelo usuário que é chamada quando o ReadableStream é cancelado.

  • reason <qualquer>

  • Retorna: Uma promise resolvida com undefined.

  • type <string> Deve ser 'bytes' ou undefined.

  • autoAllocateChunkSize <número> Usado apenas quando type é igual a 'bytes'. Quando definido para um valor diferente de zero, um buffer de visualização é alocado automaticamente para ReadableByteStreamController.byobRequest. Quando não definido, deve-se usar as filas internas do stream para transferir dados via leitor padrão ReadableStreamDefaultReader.

• strategy <Objeto>

  • highWaterMark <número> O tamanho máximo da fila interna antes que a contrapressão seja aplicada.
  • size <Função> Uma função definida pelo usuário usada para identificar o tamanho de cada bloco de dados.
  • chunk <qualquer>
  • Retorna: <número>

readableStream.locked

Adicionado em: v16.5.0

• Tipo: <boolean> Definido como true se houver um leitor ativo para este <ReadableStream>.

A propriedade readableStream.locked é false por padrão e muda para true enquanto houver um leitor ativo consumindo os dados do stream.

readableStream.cancel([reason])

Adicionado em: v16.5.0

• reason <any>
• Retorna: Uma promessa cumprida com undefined assim que a operação de cancelamento for concluída.

readableStream.getReader([options])

Adicionado em: v16.5.0

• options <Object>

  • mode <string> 'byob' ou undefined

• Retorna: <ReadableStreamDefaultReader> | <ReadableStreamBYOBReader>

ESM

import { ReadableStream } from 'node:stream/web'

const stream = new ReadableStream()

const reader = stream.getReader()

console.log(await reader.read())

CJS

const { ReadableStream } = require('node:stream/web')

const stream = new ReadableStream()

const reader = stream.getReader()

reader.read().then(console.log)

Faz com que readableStream.locked seja true.

readableStream.pipeThrough(transform[, options])

Adicionado em: v16.5.0

• transform <Object>

  • readable <ReadableStream> O ReadableStream para o qual transform.writable enviará os dados potencialmente modificados que ele recebe deste ReadableStream.
  • writable <WritableStream> O WritableStream para o qual os dados deste ReadableStream serão escritos.

• options <Object>

  • preventAbort <boolean> Quando true, erros neste ReadableStream não farão com que transform.writable seja abortado.
  • preventCancel <boolean> Quando true, erros no destino transform.writable não farão com que este ReadableStream seja cancelado.
  • preventClose <boolean> Quando true, fechar este ReadableStream não fará com que transform.writable seja fechado.
  • signal <AbortSignal> Permite que a transferência de dados seja cancelada usando um <AbortController>.

• Retorna: <ReadableStream> De transform.readable.

Conecta este <ReadableStream> ao par de <ReadableStream> e <WritableStream> fornecido no argumento transform de forma que os dados deste <ReadableStream> sejam escritos em transform.writable, possivelmente transformados, e então enviados para transform.readable. Assim que o pipeline for configurado, transform.readable será retornado.

Faz com que readableStream.locked seja true enquanto a operação de pipe estiver ativa.

ESM

import { ReadableStream, TransformStream } from 'node:stream/web'

const stream = new ReadableStream({
  start(controller) {
    controller.enqueue('a')
  },
})

const transform = new TransformStream({
  transform(chunk, controller) {
    controller.enqueue(chunk.toUpperCase())
  },
})

const transformedStream = stream.pipeThrough(transform)

for await (const chunk of transformedStream) console.log(chunk)
// Imprime: A

CJS

const { ReadableStream, TransformStream } = require('node:stream/web')

const stream = new ReadableStream({
  start(controller) {
    controller.enqueue('a')
  },
})

const transform = new TransformStream({
  transform(chunk, controller) {
    controller.enqueue(chunk.toUpperCase())
  },
})

const transformedStream = stream.pipeThrough(transform)

;(async () => {
  for await (const chunk of transformedStream) console.log(chunk)
  // Imprime: A
})()

readableStream.pipeTo(destination[, options])

Adicionado em: v16.5.0

• destination <WritableStream> Um <WritableStream> para o qual os dados deste ReadableStream serão escritos.

• options <Object>

  • preventAbort <boolean> Quando true, erros neste ReadableStream não causarão a interrupção de destination.
  • preventCancel <boolean> Quando true, erros em destination não causarão o cancelamento deste ReadableStream.
  • preventClose <boolean> Quando true, o fechamento deste ReadableStream não causará o fechamento de destination.
  • signal <AbortSignal> Permite que a transferência de dados seja cancelada usando um <AbortController>.

• Retorna: Uma promise resolvida com undefined

Causa que readableStream.locked seja true enquanto a operação de pipe estiver ativa.

readableStream.tee()

[Histórico]

Versão	Alterações
v18.10.0, v16.18.0	Suporte a ramificação de um fluxo de bytes legível.
v16.5.0	Adicionada em: v16.5.0

• Retorna: <ReadableStream[]>

Retorna um par de novas instâncias <ReadableStream> para as quais os dados deste ReadableStream serão encaminhados. Cada um receberá os mesmos dados.

Causa que readableStream.locked seja true.

readableStream.values([options])

Adicionado em: v16.5.0

• options <Object>
  • preventCancel <boolean> Quando true, impede que o <ReadableStream> seja fechado quando o iterador assíncrono termina abruptamente. Padrão: false.

Cria e retorna um iterador assíncrono utilizável para consumir os dados deste ReadableStream.

Causa que readableStream.locked seja true enquanto o iterador assíncrono estiver ativo.

import { Buffer } from 'node:buffer'

const stream = new ReadableStream(getSomeSource())

for await (const chunk of stream.values({ preventCancel: true })) console.log(Buffer.from(chunk).toString())

Iteração Assíncrona

O objeto <ReadableStream> suporta o protocolo de iterador assíncrono usando a sintaxe for await.

import { Buffer } from 'node:buffer'

const stream = new ReadableStream(getSomeSource())

for await (const chunk of stream) console.log(Buffer.from(chunk).toString())

O iterador assíncrono consumirá o <ReadableStream> até que ele termine.

Por padrão, se o iterador assíncrono sair mais cedo (via break, return ou throw), o <ReadableStream> será fechado. Para evitar o fechamento automático do <ReadableStream>, use o método readableStream.values() para adquirir o iterador assíncrono e defina a opção preventCancel como true.

O <ReadableStream> não deve estar bloqueado (isto é, não deve ter um leitor ativo existente). Durante a iteração assíncrona, o <ReadableStream> estará bloqueado.

Transferindo com postMessage()

Uma instância <ReadableStream> pode ser transferida usando uma <MessagePort>.

const stream = new ReadableStream(getReadableSourceSomehow())

const { port1, port2 } = new MessageChannel()

port1.onmessage = ({ data }) => {
  data
    .getReader()
    .read()
    .then(chunk => {
      console.log(chunk)
    })
}

port2.postMessage(stream, [stream])

ReadableStream.from(iterable)

Adicionado em: v20.6.0

• iterable <Iterable> Objeto implementando o protocolo iterável Symbol.asyncIterator ou Symbol.iterator.

Um método utilitário que cria um novo <ReadableStream> a partir de um iterável.

ESM

import { ReadableStream } from 'node:stream/web'

async function* asyncIterableGenerator() {
  yield 'a'
  yield 'b'
  yield 'c'
}

const stream = ReadableStream.from(asyncIterableGenerator())

for await (const chunk of stream) console.log(chunk) // Imprime: 'a', 'b', 'c'

CJS

const { ReadableStream } = require('node:stream/web')

async function* asyncIterableGenerator() {
  yield 'a'
  yield 'b'
  yield 'c'
}

;(async () => {
  const stream = ReadableStream.from(asyncIterableGenerator())

  for await (const chunk of stream) console.log(chunk) // Imprime: 'a', 'b', 'c'
})()

Classe: ReadableStreamDefaultReader

[Histórico]

Versão	Alterações
v18.0.0	Esta classe agora é exposta no objeto global.
v16.5.0	Adicionada em: v16.5.0

Por padrão, chamar readableStream.getReader() sem argumentos retornará uma instância de ReadableStreamDefaultReader. O leitor padrão trata os blocos de dados passados pelo stream como valores opacos, o que permite que o <ReadableStream> funcione com praticamente qualquer valor JavaScript.

new ReadableStreamDefaultReader(stream)

Adicionado em: v16.5.0

• stream <ReadableStream>

Cria um novo <ReadableStreamDefaultReader> que está bloqueado no <ReadableStream> fornecido.

readableStreamDefaultReader.cancel([reason])

Adicionado em: v16.5.0

• reason <any>
• Retorna: Uma promise resolvida com undefined.

Cancela o <ReadableStream> e retorna uma promise que é resolvida quando o stream subjacente for cancelado.

readableStreamDefaultReader.closed

Adicionado em: v16.5.0

• Tipo: <Promise> Resolvido com undefined quando o <ReadableStream> associado é fechado ou rejeitado se o stream apresentar erros ou se o bloqueio do leitor for liberado antes que o stream termine de fechar.

readableStreamDefaultReader.read()

Adicionado em: v16.5.0

• Retorna: Uma promise resolvida com um objeto:
  • value <any>
  • done <boolean>

Solicita o próximo bloco de dados do <ReadableStream> subjacente e retorna uma promise que é resolvida com os dados assim que estiverem disponíveis.

readableStreamDefaultReader.releaseLock()

Adicionado em: v16.5.0

Libera o bloqueio deste leitor no <ReadableStream> subjacente.

Classe: ReadableStreamBYOBReader

[Histórico]

Versão	Alterações
v18.0.0	Esta classe agora é exposta no objeto global.
v16.5.0	Adicionada em: v16.5.0

O ReadableStreamBYOBReader é um consumidor alternativo para <ReadableStream>s orientados a bytes (aqueles criados com underlyingSource.type definido como 'bytes' quando o ReadableStream foi criado).

O BYOB é a abreviação de "bring your own buffer" (traga seu próprio buffer). Este é um padrão que permite uma leitura mais eficiente de dados orientados a bytes, evitando cópias desnecessárias.

import { open } from 'node:fs/promises'

import { ReadableStream } from 'node:stream/web'

import { Buffer } from 'node:buffer'

class Source {
  type = 'bytes'
  autoAllocateChunkSize = 1024

  async start(controller) {
    this.file = await open(new URL(import.meta.url))
    this.controller = controller
  }

  async pull(controller) {
    const view = controller.byobRequest?.view
    const { bytesRead } = await this.file.read({
      buffer: view,
      offset: view.byteOffset,
      length: view.byteLength,
    })

    if (bytesRead === 0) {
      await this.file.close()
      this.controller.close()
    }
    controller.byobRequest.respond(bytesRead)
  }
}

const stream = new ReadableStream(new Source())

async function read(stream) {
  const reader = stream.getReader({ mode: 'byob' })

  const chunks = []
  let result
  do {
    result = await reader.read(Buffer.alloc(100))
    if (result.value !== undefined) chunks.push(Buffer.from(result.value))
  } while (!result.done)

  return Buffer.concat(chunks)
}

const data = await read(stream)
console.log(Buffer.from(data).toString())

new ReadableStreamBYOBReader(stream)

Adicionado em: v16.5.0

• stream <ReadableStream>

Cria um novo ReadableStreamBYOBReader que está bloqueado no <ReadableStream> fornecido.

readableStreamBYOBReader.cancel([reason])

Adicionado em: v16.5.0

• reason <any>
• Retorna: Uma promise resolvida com undefined.

Cancela o <ReadableStream> e retorna uma promise que é resolvida quando o stream subjacente for cancelado.

readableStreamBYOBReader.closed

Adicionado em: v16.5.0

• Tipo: <Promise> Resolvido com undefined quando o <ReadableStream> associado é fechado ou rejeitado se o stream apresentar erros ou se o bloqueio do leitor for liberado antes do stream finalizar o fechamento.

readableStreamBYOBReader.read(view[, options])

[Histórico]

Versão	Alterações
v21.7.0, v20.17.0	Adicionada a opção min.
v16.5.0	Adicionada em: v16.5.0

• view <Buffer> | <TypedArray> | <DataView>

• options <Object>

  • min <number> Quando definido, a promise retornada só será resolvida assim que estiver disponível o número min de elementos. Quando não definido, a promise é resolvida quando pelo menos um elemento estiver disponível.

• Retorna: Uma promise resolvida com um objeto:

  • value <TypedArray> | <DataView>
  • done <boolean>

Solicita o próximo bloco de dados do <ReadableStream> subjacente e retorna uma promise que é resolvida com os dados assim que estiverem disponíveis.

Não passe uma instância de objeto <Buffer> agrupada para este método. Objetos Buffer agrupados são criados usando Buffer.allocUnsafe(), ou Buffer.from(), ou são frequentemente retornados por vários retornos de chamada do módulo node:fs. Esses tipos de Buffers usam um objeto <ArrayBuffer> subjacente compartilhado que contém todos os dados de todas as instâncias de Buffer agrupadas. Quando um Buffer, <TypedArray>, ou <DataView> é passado para readableStreamBYOBReader.read(), o ArrayBuffer subjacente da view é desanexado, invalidando todas as views existentes que possam existir naquele ArrayBuffer. Isso pode ter consequências desastrosas para sua aplicação.

readableStreamBYOBReader.releaseLock()

Adicionado em: v16.5.0

Libera o bloqueio deste leitor no <ReadableStream> subjacente.

Classe: ReadableStreamDefaultController

Adicionado em: v16.5.0

Cada <ReadableStream> possui um controlador responsável pelo estado interno e gerenciamento da fila do fluxo. O ReadableStreamDefaultController é a implementação de controlador padrão para ReadableStreams que não são orientados a bytes.

readableStreamDefaultController.close()

Adicionado em: v16.5.0

Fecha o <ReadableStream> ao qual este controlador está associado.

readableStreamDefaultController.desiredSize

Adicionado em: v16.5.0

• Tipo: <number>

Retorna a quantidade de dados restantes para preencher a fila do <ReadableStream>.

readableStreamDefaultController.enqueue([chunk])

Adicionado em: v16.5.0

• chunk <any>

Anexa um novo bloco de dados à fila do <ReadableStream>.

readableStreamDefaultController.error([error])

Adicionado em: v16.5.0

• error <any>

Sinaliza um erro que faz com que o <ReadableStream> apresente um erro e feche.

Classe: ReadableByteStreamController

[Histórico]

Versão	Alterações
v18.10.0	Suporte ao tratamento de uma solicitação de pull BYOB de um leitor liberado.
v16.5.0	Adicionada em: v16.5.0

Cada <ReadableStream> possui um controlador responsável pelo estado interno e gerenciamento da fila do fluxo. O ReadableByteStreamController é para ReadableStreams orientados a bytes.

readableByteStreamController.byobRequest

Adicionado em: v16.5.0

• Tipo: <ReadableStreamBYOBRequest>

readableByteStreamController.close()

Adicionado em: v16.5.0

Fecha o <ReadableStream> ao qual este controlador está associado.

readableByteStreamController.desiredSize

Adicionado em: v16.5.0

• Tipo: <number>

Retorna a quantidade de dados restantes para preencher a fila do <ReadableStream>.

readableByteStreamController.enqueue(chunk)

Adicionado em: v16.5.0

• chunk: <Buffer> | <TypedArray> | <DataView>

Anexa um novo pedaço de dados à fila do <ReadableStream>.

readableByteStreamController.error([error])

Adicionado em: v16.5.0

• error <any>

Sinaliza um erro que faz com que o <ReadableStream> apresente um erro e feche.

Classe: ReadableStreamBYOBRequest

[Histórico]

Versão	Alterações
v18.0.0	Esta classe agora é exposta no objeto global.
v16.5.0	Adicionada em: v16.5.0

Quando se utiliza ReadableByteStreamController em fluxos orientados a bytes, e quando se utiliza o ReadableStreamBYOBReader, a propriedade readableByteStreamController.byobRequest fornece acesso a uma instância ReadableStreamBYOBRequest que representa o pedido de leitura atual. O objeto é usado para obter acesso ao ArrayBuffer/TypedArray que foi fornecido para o pedido de leitura a ser preenchido, e fornece métodos para sinalizar que os dados foram fornecidos.

readableStreamBYOBRequest.respond(bytesWritten)

Adicionado em: v16.5.0

• bytesWritten <number>

Sinaliza que um número de bytesWritten bytes foi escrito para readableStreamBYOBRequest.view.

readableStreamBYOBRequest.respondWithNewView(view)

Adicionado em: v16.5.0

• view <Buffer> | <TypedArray> | <DataView>

Sinaliza que o pedido foi atendido com bytes escritos em um novo Buffer, TypedArray ou DataView.

readableStreamBYOBRequest.view

Adicionado em: v16.5.0

• Tipo: <Buffer> | <TypedArray> | <DataView>

Classe: WritableStream

[Histórico]

Versão	Alterações
v18.0.0	Esta classe agora é exposta no objeto global.
v16.5.0	Adicionada em: v16.5.0

O WritableStream é um destino para o qual os dados do fluxo são enviados.

import { WritableStream } from 'node:stream/web'

const stream = new WritableStream({
  write(chunk) {
    console.log(chunk)
  },
})

await stream.getWriter().write('Hello World')

new WritableStream([underlyingSink[, strategy]])

Adicionado em: v16.5.0

• underlyingSink <Object>

  • start <Function> Uma função definida pelo usuário que é invocada imediatamente quando o WritableStream é criado.

  • controller <WritableStreamDefaultController>

  • Retorna: undefined ou uma promise cumprida com undefined.

  • write <Function> Uma função definida pelo usuário que é invocada quando um bloco de dados foi escrito no WritableStream.

  • chunk <any>

  • controller <WritableStreamDefaultController>

  • Retorna: Uma promise cumprida com undefined.

  • close <Function> Uma função definida pelo usuário que é chamada quando o WritableStream é fechado.

  • Retorna: Uma promise cumprida com undefined.

  • abort <Function> Uma função definida pelo usuário que é chamada para fechar abruptamente o WritableStream.

  • reason <any>

  • Retorna: Uma promise cumprida com undefined.

  • type <any> A opção type é reservada para uso futuro e deve ser indefinida.

• strategy <Object>

  • highWaterMark <number> O tamanho máximo da fila interna antes que a contrapressão seja aplicada.
  • size <Function> Uma função definida pelo usuário usada para identificar o tamanho de cada bloco de dados.
  • chunk <any>
  • Retorna: <number>

writableStream.abort([reason])

Adicionado em: v16.5.0

• reason <any>
• Retorna: Uma promise resolvida com undefined.

Termina abruptamente o WritableStream. Todas as escritas na fila serão canceladas e suas promises associadas rejeitadas.

writableStream.close()

Adicionado em: v16.5.0

• Retorna: Uma promise resolvida com undefined.

Fecha o WritableStream quando não forem esperadas escritas adicionais.

writableStream.getWriter()

Adicionado em: v16.5.0

• Retorna: <WritableStreamDefaultWriter>

Cria e retorna uma nova instância de escritor que pode ser usada para escrever dados no WritableStream.

writableStream.locked

Adicionado em: v16.5.0

• Tipo: <boolean>

A propriedade writableStream.locked é false por padrão e muda para true enquanto houver um escritor ativo conectado a este WritableStream.

Transferindo com postMessage()

Uma instância <WritableStream> pode ser transferida usando uma <MessagePort>.

const stream = new WritableStream(getWritableSinkSomehow())

const { port1, port2 } = new MessageChannel()

port1.onmessage = ({ data }) => {
  data.getWriter().write('hello')
}

port2.postMessage(stream, [stream])

Classe: WritableStreamDefaultWriter

[Histórico]

Versão	Alterações
v18.0.0	Esta classe agora é exposta no objeto global.
v16.5.0	Adicionada em: v16.5.0

new WritableStreamDefaultWriter(stream)

Adicionado em: v16.5.0

• stream <WritableStream>

Cria um novo WritableStreamDefaultWriter que está bloqueado no WritableStream fornecido.

writableStreamDefaultWriter.abort([reason])

Adicionado em: v16.5.0

• reason <any>
• Retorna: Uma promise resolvida com undefined.

Termina abruptamente o WritableStream. Todas as escritas na fila serão canceladas e suas promises associadas rejeitadas.

writableStreamDefaultWriter.close()

Adicionado em: v16.5.0

• Retorna: Uma promessa resolvida com undefined.

Fecha o WritableStream quando não são esperadas gravações adicionais.

writableStreamDefaultWriter.closed

Adicionado em: v16.5.0

• Tipo: <Promise> Resolvido com undefined quando o <WritableStream> associado é fechado ou rejeitado se o stream apresentar erros ou se o bloqueio do escritor for liberado antes que o stream termine de fechar.

writableStreamDefaultWriter.desiredSize

Adicionado em: v16.5.0

• Tipo: <number>

A quantidade de dados necessária para preencher a fila do <WritableStream>.

writableStreamDefaultWriter.ready

Adicionado em: v16.5.0

• Tipo: <Promise> Resolvido com undefined quando o escritor está pronto para ser usado.

writableStreamDefaultWriter.releaseLock()

Adicionado em: v16.5.0

Libera o bloqueio deste escritor no <ReadableStream> subjacente.

writableStreamDefaultWriter.write([chunk])

Adicionado em: v16.5.0

• chunk: <any>
• Retorna: Uma promessa resolvida com undefined.

Anexa um novo bloco de dados à fila do <WritableStream>.

Classe: WritableStreamDefaultController

[Histórico]

Versão	Alterações
v18.0.0	Esta classe agora é exposta no objeto global.
v16.5.0	Adicionada em: v16.5.0

O WritableStreamDefaultController gerencia o estado interno do <WritableStream>.

writableStreamDefaultController.error([error])

Adicionado em: v16.5.0

• error <any>

Chamado pelo código do usuário para sinalizar que ocorreu um erro durante o processamento dos dados do WritableStream. Quando chamado, o <WritableStream> será abortado, com as gravações pendentes atualmente canceladas.

writableStreamDefaultController.signal

• Tipo: <AbortSignal> Um AbortSignal que pode ser usado para cancelar operações pendentes de escrita ou fechamento quando um <WritableStream> é abortado.

Classe: TransformStream

[Histórico]

Versão	Alterações
v18.0.0	Esta classe agora é exposta no objeto global.
v16.5.0	Adicionado em: v16.5.0

Um TransformStream consiste em um <ReadableStream> e um <WritableStream> que estão conectados de forma que os dados escritos para o WritableStream são recebidos e potencialmente transformados, antes de serem enviados para a fila do ReadableStream.

import { TransformStream } from 'node:stream/web'

const transform = new TransformStream({
  transform(chunk, controller) {
    controller.enqueue(chunk.toUpperCase())
  },
})

await Promise.all([transform.writable.getWriter().write('A'), transform.readable.getReader().read()])

new TransformStream([transformer[, writableStrategy[, readableStrategy]]])

Adicionado em: v16.5.0

• transformer <Object>

  • start <Function> Uma função definida pelo usuário que é invocada imediatamente quando o TransformStream é criado.

  • controller <TransformStreamDefaultController>

  • Retorna: undefined ou uma promise cumprida com undefined

  • transform <Function> Uma função definida pelo usuário que recebe e potencialmente modifica um bloco de dados escrito para transformStream.writable, antes de encaminhá-lo para transformStream.readable.

  • chunk <any>

  • controller <TransformStreamDefaultController>

  • Retorna: Uma promise cumprida com undefined.

  • flush <Function> Uma função definida pelo usuário que é chamada imediatamente antes do lado gravável do TransformStream ser fechado, sinalizando o fim do processo de transformação.

  • controller <TransformStreamDefaultController>

  • Retorna: Uma promise cumprida com undefined.

  • readableType <any> a opção readableType é reservada para uso futuro e deve ser undefined.

  • writableType <any> a opção writableType é reservada para uso futuro e deve ser undefined.

• writableStrategy <Object>

  • highWaterMark <number> O tamanho máximo da fila interna antes que a contrapressão seja aplicada.
  • size <Function> Uma função definida pelo usuário usada para identificar o tamanho de cada bloco de dados.
  • chunk <any>
  • Retorna: <number>

• readableStrategy <Object>

  • highWaterMark <number> O tamanho máximo da fila interna antes que a contrapressão seja aplicada.
  • size <Function> Uma função definida pelo usuário usada para identificar o tamanho de cada bloco de dados.
  • chunk <any>
  • Retorna: <number>

transformStream.readable

Adicionado em: v16.5.0

• Tipo: <ReadableStream>

transformStream.writable

Adicionado em: v16.5.0

• Tipo: <WritableStream>

Transferindo com postMessage()

Uma instância de <TransformStream> pode ser transferida usando uma <MessagePort>.

const stream = new TransformStream()

const { port1, port2 } = new MessageChannel()

port1.onmessage = ({ data }) => {
  const { writable, readable } = data
  // ...
}

port2.postMessage(stream, [stream])

Classe: TransformStreamDefaultController

[Histórico]

Versão	Alterações
v18.0.0	Esta classe agora é exposta no objeto global.
v16.5.0	Adicionada em: v16.5.0

O TransformStreamDefaultController gerencia o estado interno do TransformStream.

transformStreamDefaultController.desiredSize

Adicionado em: v16.5.0

• Tipo: <number>

A quantidade de dados necessária para preencher a fila do lado legível.

transformStreamDefaultController.enqueue([chunk])

Adicionado em: v16.5.0

• chunk <any>

Anexa um bloco de dados à fila do lado legível.

transformStreamDefaultController.error([reason])

Adicionado em: v16.5.0

• reason <any>

Sinaliza para os lados legível e gravável que um erro ocorreu durante o processamento dos dados de transformação, fazendo com que ambos os lados sejam fechados abruptamente.

transformStreamDefaultController.terminate()

Adicionado em: v16.5.0

Fecha o lado legível do transporte e faz com que o lado gravável seja fechado abruptamente com um erro.

Classe: ByteLengthQueuingStrategy

[Histórico]

Versão	Alterações
v18.0.0	Esta classe agora é exposta no objeto global.
v16.5.0	Adicionada em: v16.5.0

new ByteLengthQueuingStrategy(init)

Adicionado em: v16.5.0

• init <Object>
  • highWaterMark <number>

byteLengthQueuingStrategy.highWaterMark

Adicionado em: v16.5.0

• Tipo: <number>

byteLengthQueuingStrategy.size

Adicionado em: v16.5.0

• Tipo: <Function>
  • chunk <any>
  • Retorna: <number>

Classe: CountQueuingStrategy

[Histórico]

Versão	Alterações
v18.0.0	Esta classe agora é exposta no objeto global.
v16.5.0	Adicionada em: v16.5.0

new CountQueuingStrategy(init)

Adicionado em: v16.5.0

• init <Object>
  • highWaterMark <number>

countQueuingStrategy.highWaterMark

Adicionado em: v16.5.0

• Tipo: <number>

countQueuingStrategy.size

Adicionado em: v16.5.0

• Tipo: <Function>
  • chunk <any>
  • Retorna: <number>

Classe: TextEncoderStream

[Histórico]

Versão	Alterações
v18.0.0	Esta classe agora é exposta no objeto global.
v16.6.0	Adicionada em: v16.6.0

new TextEncoderStream()

Adicionado em: v16.6.0

Cria uma nova instância TextEncoderStream.

textEncoderStream.encoding

Adicionado em: v16.6.0

• Tipo: <string>

A codificação suportada pela instância TextEncoderStream.

textEncoderStream.readable

Adicionado em: v16.6.0

• Tipo: <ReadableStream>

textEncoderStream.writable

Adicionado em: v16.6.0

• Tipo: <WritableStream>

Classe: TextDecoderStream

[Histórico]

Versão	Alterações
v18.0.0	Esta classe agora é exposta no objeto global.
v16.6.0	Adicionada em: v16.6.0

new TextDecoderStream([encoding[, options]])

Adicionado em: v16.6.0

• encoding <string> Identifica a codificação que esta instância TextDecoder suporta. Padrão: 'utf-8'.
• options <Object>
  • fatal <boolean> true se falhas de decodificação são fatais.
  • ignoreBOM <boolean> Quando true, o TextDecoderStream incluirá a marca de ordem de bytes no resultado decodificado. Quando false, a marca de ordem de bytes será removida da saída. Esta opção só é usada quando encoding é 'utf-8', 'utf-16be' ou 'utf-16le'. Padrão: false.

Cria uma nova instância TextDecoderStream.

textDecoderStream.encoding

Adicionado em: v16.6.0

• Tipo: <string>

A codificação suportada pela instância TextDecoderStream.

textDecoderStream.fatal

Adicionado em: v16.6.0

• Tipo: <boolean>

O valor será true se erros de decodificação resultarem em um TypeError sendo lançado.

textDecoderStream.ignoreBOM

Adicionado em: v16.6.0

• Tipo: <boolean>

O valor será true se o resultado da decodificação incluir a marca de ordem de bytes.

textDecoderStream.readable

Adicionado em: v16.6.0

• Tipo: <ReadableStream>

textDecoderStream.writable

Adicionado em: v16.6.0

• Tipo: <WritableStream>

Classe: CompressionStream

[Histórico]

Versão	Alterações
v18.0.0	Esta classe agora é exposta no objeto global.
v17.0.0	Adicionada em: v17.0.0

new CompressionStream(format)

[Histórico]

Versão	Alterações
v21.2.0, v20.12.0	format agora aceita o valor deflate-raw.
v17.0.0	Adicionada em: v17.0.0

• format <string> Um dos seguintes: 'deflate', 'deflate-raw', ou 'gzip'.

compressionStream.readable

Adicionado em: v17.0.0

• Tipo: <ReadableStream>

compressionStream.writable

Adicionado em: v17.0.0

• Tipo: <WritableStream>

Classe: DecompressionStream

[Histórico]

Versão	Alterações
v18.0.0	Esta classe agora é exposta no objeto global.
v17.0.0	Adicionada em: v17.0.0

new DecompressionStream(format)

[Histórico]

Versão	Alterações
v21.2.0, v20.12.0	format agora aceita o valor deflate-raw.
v17.0.0	Adicionada em: v17.0.0

• format <string> Um dos seguintes: 'deflate', 'deflate-raw', ou 'gzip'.

decompressionStream.readable

Adicionado em: v17.0.0

• Tipo: <ReadableStream>

decompressionStream.writable

Adicionado em: v17.0.0

• Tipo: <WritableStream>

Consumidores de Utilitários

Adicionado em: v16.7.0

As funções consumidoras de utilitários fornecem opções comuns para consumir fluxos.

Elas são acessadas usando:

ESM

import { arrayBuffer, blob, buffer, json, text } from 'node:stream/consumers'

CJS

const { arrayBuffer, blob, buffer, json, text } = require('node:stream/consumers')

streamConsumers.arrayBuffer(stream)

Adicionado em: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Retorna: <Promise> Cumpre com um ArrayBuffer contendo o conteúdo completo do fluxo.

ESM

import { arrayBuffer } from 'node:stream/consumers'
import { Readable } from 'node:stream'
import { TextEncoder } from 'node:util'

const encoder = new TextEncoder()
const dataArray = encoder.encode('hello world from consumers!')

const readable = Readable.from(dataArray)
const data = await arrayBuffer(readable)
console.log(`from readable: ${data.byteLength}`)
// Imprime: from readable: 76

CJS

const { arrayBuffer } = require('node:stream/consumers')
const { Readable } = require('node:stream')
const { TextEncoder } = require('node:util')

const encoder = new TextEncoder()
const dataArray = encoder.encode('hello world from consumers!')
const readable = Readable.from(dataArray)
arrayBuffer(readable).then(data => {
  console.log(`from readable: ${data.byteLength}`)
  // Imprime: from readable: 76
})

streamConsumers.blob(stream)

Adicionado em: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Retorna: <Promise> Cumpre com um <Blob> contendo o conteúdo completo do fluxo.

ESM

import { blob } from 'node:stream/consumers'

const dataBlob = new Blob(['hello world from consumers!'])

const readable = dataBlob.stream()
const data = await blob(readable)
console.log(`from readable: ${data.size}`)
// Imprime: from readable: 27

CJS

const { blob } = require('node:stream/consumers')

const dataBlob = new Blob(['hello world from consumers!'])

const readable = dataBlob.stream()
blob(readable).then(data => {
  console.log(`from readable: ${data.size}`)
  // Imprime: from readable: 27
})

streamConsumers.buffer(stream)

Adicionado em: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Retorna: <Promise> Cumpre com um <Buffer> contendo o conteúdo completo do stream.

ESM

import { buffer } from 'node:stream/consumers'
import { Readable } from 'node:stream'
import { Buffer } from 'node:buffer'

const dataBuffer = Buffer.from('hello world from consumers!')

const readable = Readable.from(dataBuffer)
const data = await buffer(readable)
console.log(`from readable: ${data.length}`)
// Imprime: from readable: 27

CJS

const { buffer } = require('node:stream/consumers')
const { Readable } = require('node:stream')
const { Buffer } = require('node:buffer')

const dataBuffer = Buffer.from('hello world from consumers!')

const readable = Readable.from(dataBuffer)
buffer(readable).then(data => {
  console.log(`from readable: ${data.length}`)
  // Imprime: from readable: 27
})

streamConsumers.json(stream)

Adicionado em: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Retorna: <Promise> Cumpre com o conteúdo do stream analisado como uma string codificada em UTF-8 que é então passada por JSON.parse().

ESM

import { json } from 'node:stream/consumers'
import { Readable } from 'node:stream'

const items = Array.from(
  {
    length: 100,
  },
  () => ({
    message: 'hello world from consumers!',
  })
)

const readable = Readable.from(JSON.stringify(items))
const data = await json(readable)
console.log(`from readable: ${data.length}`)
// Imprime: from readable: 100

CJS

const { json } = require('node:stream/consumers')
const { Readable } = require('node:stream')

const items = Array.from(
  {
    length: 100,
  },
  () => ({
    message: 'hello world from consumers!',
  })
)

const readable = Readable.from(JSON.stringify(items))
json(readable).then(data => {
  console.log(`from readable: ${data.length}`)
  // Imprime: from readable: 100
})

streamConsumers.text(stream)

Adicionado em: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Retorna: <Promise> Cumpre com o conteúdo do stream analisado como uma string codificada em UTF-8.

ESM

import { text } from 'node:stream/consumers'
import { Readable } from 'node:stream'

const readable = Readable.from('Hello world from consumers!')
const data = await text(readable)
console.log(`from readable: ${data.length}`)
// Imprime: from readable: 27

CJS

const { text } = require('node:stream/consumers')
const { Readable } = require('node:stream')

const readable = Readable.from('Hello world from consumers!')
text(readable).then(data => {
  console.log(`from readable: ${data.length}`)
  // Imprime: from readable: 27
})