API Web Streams

[Histórico]

Versão	Mudanças
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	Adicionado 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 "web streams") define uma API para lidar com dados de streaming. É semelhante à API Streams do Node.js, mas surgiu mais tarde e se tornou 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 de streaming.
• WritableStream - Representa um destino para dados de streaming.
• TransformStream - Representa um algoritmo para transformar dados de streaming.

Exemplo ReadableStream

Este exemplo cria um ReadableStream simples que envia o timestamp performance.now() atual uma vez por 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,
} from '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	Mudanças
v18.0.0	Esta classe agora está exposta no objeto global.
v16.5.0	Adicionado em: v16.5.0

new ReadableStream([underlyingSource [, strategy]])

Adicionado em: v16.5.0

• underlyingSource <Object>

  • start <Function> 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 <Function> 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 <Function> Uma função definida pelo usuário que é chamada quando o ReadableStream é cancelado.

  • reason <any>

  • Retorna: Uma promise resolvida com undefined.

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

  • autoAllocateChunkSize <number> Usado apenas quando type é igual a 'bytes'. Quando definido com 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 através do leitor padrão ReadableStreamDefaultReader.

• 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 pedaço de dados.
  • chunk <any>
  • Retorna: <number>

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 é alternada para true enquanto houver um leitor ativo consumindo os dados do fluxo.

readableStream.cancel([reason])

Adicionado em: v16.5.0

• reason <any>
• Retorna: Uma promise fulfilled com undefined assim que o cancelamento for concluído.

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 recebe deste ReadableStream.
  • writable <WritableStream> O WritableStream para o qual os dados deste ReadableStream serão gravados.

• 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 fazem com que este ReadableStream seja cancelado.
  • preventClose <boolean> Quando true, fechar este ReadableStream não faz 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 gravados em transform.writable, possivelmente transformados, e então enviados para transform.readable. Uma vez que o pipeline é configurado, transform.readable é retornado.

Faz com que readableStream.locked seja true enquanto a operação de pipe está 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);
  // Prints: 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);
    // Prints: A
})();

readableStream.pipeTo(destination[, options])

Adicionado em: v16.5.0

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

• options <Object>

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

• Retorna: Uma promessa cumprida com undefined

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

readableStream.tee()

[Histórico]

Versão	Mudanças
v18.10.0, v16.18.0	Suporte para dividir um fluxo de bytes legível.
v16.5.0	Adicionado em: v16.5.0

• Retorna: <ReadableStream[]>

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

Faz com 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.

Faz com 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 prematuramente (via break, return ou throw), o <ReadableStream> será fechado. Para impedir 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 ser bloqueado (ou seja, não deve ter um leitor ativo existente). Durante a iteração assíncrona, o <ReadableStream> será bloqueado.

Transferindo com postMessage()

Uma instância de <ReadableStream> pode ser transferida usando um <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); // Prints: '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); // Prints: 'a', 'b', 'c'
})();

Classe: ReadableStreamDefaultReader

[Histórico]

Versão	Mudanças
v18.0.0	Esta classe agora está exposta no objeto global.
v16.5.0	Adicionado em: v16.5.0

Por padrão, chamar readableStream.getReader() sem argumentos retornará uma instância de ReadableStreamDefaultReader. O leitor padrão trata os pedaços de dados passados através do stream como valores opacos, o que permite que o <ReadableStream> trabalhe geralmente com qualquer valor JavaScript.

new ReadableStreamDefaultReader(stream)

Adicionado em: v16.5.0

• stream <ReadableStream>

Cria um novo <ReadableStreamDefaultReader> que está bloqueado para o <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 foi cancelado.

readableStreamDefaultReader.closed

Adicionado em: v16.5.0

• Tipo: <Promise> Cumprida com undefined quando o <ReadableStream> associado é fechado ou rejeitado se o stream apresentar erros ou 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 pedaço 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	Mudanças
v18.0.0	Esta classe agora está exposta no objeto global.
v16.5.0	Adicionado em: v16.5.0

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

O BYOB é uma 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 que evita 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 é bloqueado para o <ReadableStream> fornecido.

readableStreamBYOBReader.cancel([reason])

Adicionado em: v16.5.0

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

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

readableStreamBYOBReader.closed

Adicionado em: v16.5.0

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

readableStreamBYOBReader.read(view[, options])

[Histórico]

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

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

• options <Object>

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

• Retorna: Uma promise cumprida com um objeto:

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

Solicita o próximo bloco de dados do <ReadableStream> subjacente e retorna uma promise que é cumprida 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 Buffer 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 nesse 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> tem um controlador que é responsável pelo estado interno e gerenciamento da fila do stream. 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	Mudanças
v18.10.0	Suporte para lidar com uma solicitação de pull BYOB de um leitor liberado.
v16.5.0	Adicionado em: v16.5.0

Cada <ReadableStream> tem um controlador que é responsável pelo estado interno e gerenciamento da fila do stream. 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 bloco 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	Mudanças
v18.0.0	Esta classe agora é exposta no objeto global.
v16.5.0	Adicionado em: v16.5.0

Ao usar ReadableByteStreamController em fluxos orientados a bytes e ao usar o ReadableStreamBYOBReader, a propriedade readableByteStreamController.byobRequest fornece acesso a uma instância de ReadableStreamBYOBRequest que representa a solicitação de leitura atual. O objeto é usado para obter acesso ao ArrayBuffer/TypedArray que foi fornecido para a solicitação de leitura para preencher 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 bytesWritten de bytes foi escrito em readableStreamBYOBRequest.view.

readableStreamBYOBRequest.respondWithNewView(view)

Adicionado em: v16.5.0

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

Sinaliza que a solicitação foi atendida com bytes gravados em um novo Buffer, TypedArray ou DataView.

readableStreamBYOBRequest.view

Adicionado em: v16.5.0

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

Classe: WritableStream

[Histórico]

Versão	Mudanças
v18.0.0	Esta classe agora está exposta no objeto global.
v16.5.0	Adicionado 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 promessa resolvida com undefined.

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

  • chunk <any>

  • controller <WritableStreamDefaultController>

  • Retorna: Uma promessa resolvida com undefined.

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

  • Retorna: Uma promessa resolvida com undefined.

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

  • reason <any>

  • Retorna: Uma promessa resolvida 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 pedaço de dados.
  • chunk <any>
  • Retorna: <number>

writableStream.abort([reason])

Adicionado em: v16.5.0

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

Termina abruptamente o WritableStream. Todas as escritas enfileiradas serão canceladas com suas promises associadas rejeitadas.

writableStream.close()

Adicionado em: v16.5.0

• Retorna: Uma promise cumprida com undefined.

Fecha o WritableStream quando nenhuma escrita adicional é esperada.

writableStream.getWriter()

Adicionado em: v16.5.0

• Retorna: <WritableStreamDefaultWriter>

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

writableStream.locked

Adicionado em: v16.5.0

• Tipo: <boolean>

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

Transferindo com postMessage()

Uma instância de <WritableStream> pode ser transferida usando um <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	Mudanças
v18.0.0	Esta classe agora está exposta no objeto global.
v16.5.0	Adicionado em: v16.5.0

new WritableStreamDefaultWriter(stream)

Adicionado em: v16.5.0

• stream <WritableStream>

Cria um novo WritableStreamDefaultWriter que é bloqueado para o WritableStream fornecido.

writableStreamDefaultWriter.abort([reason])

Adicionado em: v16.5.0

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

Termina abruptamente o WritableStream. Todas as escritas enfileiradas serão canceladas com suas promises associadas rejeitadas.

writableStreamDefaultWriter.close()

Adicionado em: v16.5.0

• Retorna: Uma promise cumprida com undefined.

Fecha o WritableStream quando nenhuma escrita adicional é esperada.

writableStreamDefaultWriter.closed

Adicionado em: v16.5.0

• Tipo: <Promise> Cumprida com undefined quando o <WritableStream> associado é fechado ou rejeitada se o stream apresentar erros ou 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> Cumprida com undefined quando o escritor estiver 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 promise cumprida com undefined.

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

Classe: WritableStreamDefaultController

[Histórico]

Versão	Mudanças
v18.0.0	Esta classe agora está exposta no objeto global.
v16.5.0	Adicionado 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 ao processar os dados do WritableStream. Quando chamado, o <WritableStream> será abortado, com as gravações pendentes atualmente canceladas.

writableStreamDefaultController.signal

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

Classe: TransformStream

[Histórico]

Versão	Mudanças
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 são conectados de tal forma que os dados escritos no 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 promessa cumprida com undefined

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

  • chunk <any>

  • controller <TransformStreamDefaultController>

  • Retorna: Uma promessa cumprida com undefined.

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

  • controller <TransformStreamDefaultController>

  • Retorna: Uma promessa 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 trecho 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 trecho 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 um <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	Mudanças
v18.0.0	Esta classe agora está exposta no objeto global.
v16.5.0	Adicionado 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>

Acrescenta 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 ocorreu um erro 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	Mudanças
v18.0.0	Esta classe agora está exposta no objeto global.
v16.5.0	Adicionado 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 está exposta no objeto global.
v16.5.0	Adicionado 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 está exposta no objeto global.
v16.6.0	Adicionado em: v16.6.0

new TextEncoderStream()

Adicionado em: v16.6.0

Cria uma nova instância de TextEncoderStream.

textEncoderStream.encoding

Adicionado em: v16.6.0

• Tipo: <string>

A codificação suportada pela instância de 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	Mudanças
v18.0.0	Esta classe agora é exposta no objeto global.
v16.6.0	Adicionado em: v16.6.0

new TextDecoderStream([encoding[, options]])

Adicionado em: v16.6.0

• encoding <string> Identifica o encoding que esta instância de TextDecoder suporta. Padrão: 'utf-8'.
• options <Object>
  • fatal <boolean> true se falhas de decodificação forem 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 é usada apenas quando encoding é 'utf-8', 'utf-16be' ou 'utf-16le'. Padrão: false.

Cria uma nova instância de TextDecoderStream.

textDecoderStream.encoding

Adicionado em: v16.6.0

• Tipo: <string>

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

textDecoderStream.fatal

Adicionado em: v16.6.0

• Tipo: <boolean>

O valor será true se erros de decodificação resultarem no lançamento de um TypeError.

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	Mudanças
v18.0.0	Esta classe agora está exposta no objeto global.
v17.0.0	Adicionado em: v17.0.0

new CompressionStream(format)

[Histórico]

Versão	Mudanças
v21.2.0, v20.12.0	format agora aceita o valor deflate-raw.
v17.0.0	Adicionado em: v17.0.0

• format <string> Um de '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	Mudanças
v18.0.0	Esta classe agora está exposta no objeto global.
v17.0.0	Adicionado em: v17.0.0

new DecompressionStream(format)

[Histórico]

Versão	Mudanças
v21.2.0, v20.12.0	format agora aceita o valor deflate-raw.
v17.0.0	Adicionado em: v17.0.0

• format <string> Um de '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 utilidade

Adicionado em: v16.7.0

As funções de consumidor de utilidade fornecem opções comuns para consumir streams.

Eles são acessados 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 stream.

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}`);
// Prints: 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}`);
  // Prints: 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 stream.

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}`);
// Prints: 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}`);
  // Prints: 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 com codificação 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
});