Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

ReadableStream.pipeThrough(): transformar um fluxo

pipeThrough() encaminha os dados do fluxo para o lado writable de um par fornecido e devolve imediatamente o respetivo lado readable. Permite encadear transformações com propagação de contrapressão; não devolve uma promise de conclusão.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

source.pipeThrough({ writable, readable }, { preventClose, preventAbort, preventCancel, signal })

ReadableStream.pipeThrough() é um método de instância definido por WHATWG Streams, não por ECMAScript. Aceita um TransformStream ou um par { writable, readable }: liga a origem a writable e devolve exatamente readable, não uma Promise. No caso de um par arbitrário, o método não liga por si só os dois lados.

O piping bloqueia a origem e o writable de destino durante a operação; se algum deles já estiver bloqueado, é lançado sincronamente um TypeError. Uma cadeia que utiliza TransformStream propaga a contrapressão. Consome o resultado: sem consumidor, a transformação pode ficar bloqueada. Em contrapartida, pipeTo() devolve uma promise que indica a conclusão do piping.

As opções aplicam-se à ligação da origem a writable. Por predefinição, o fecho da origem fecha o destino, um erro da origem interrompe o destino e um erro do destino cancela a origem. preventClose, preventAbort e preventCancel desativam, respetivamente, estes comportamentos; todas têm o valor predefinido false. signal permite interromper a operação, sujeito a essas opções. Observa os erros ao consumir o resultado; pipeThrough() não expõe a sua promise interna de piping.

O exemplo duplica dois blocos e aguarda pelo pipeTo() final. Verifica a disponibilidade das API no navegador de destino; a presença de Node 24 num repositório não comprova o suporte nos navegadores.

Exemplos

async function main() {
  const source = new ReadableStream({
    start(controller) {
      controller.enqueue(2);
      controller.enqueue(4);
      controller.close();
    }
  });

  const doubled = source.pipeThrough(new TransformStream({
    transform(chunk, controller) {
      controller.enqueue(chunk * 2);
    }
  }));

  const values = [];
  await doubled.pipeTo(new WritableStream({
    write(chunk) {
      values.push(chunk);
    }
  }));
  console.log(JSON.stringify(values));
}

main().catch(console.error);

Resultado

[4,8]

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes