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

CKTIS / JavaScript

TransformStream: transform, flush e controller.enqueue

Processa blocos de entrada com `transform()`, emite resultados com `controller.enqueue()` e esvazia o buffer com `flush()` no fecho normal.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

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

// Optional transformer methods:
transform(chunk, controller)
flush(controller)

// Output from either method:
controller.enqueue(chunk)

TransformStream liga um lado de entrada (writable) a um lado de saída (readable). O construtor aceita um objeto transformer opcional. Os dois argumentos opcionais seguintes definem as estratégias de fila para os lados de escrita e de leitura, por esta ordem. Faz parte da API Web Streams, não do ECMAScript 2024; verifica se o ambiente de execução de destino o suporta.

transform(chunk, controller) é chamada para cada bloco de entrada quando este está pronto a ser processado. Para emitir zero, um ou vários blocos de saída, chama controller.enqueue(chunk) o número correspondente de vezes no TransformStreamDefaultController recebido. O valor devolvido pela função não é um bloco de saída. Sem transform(), os blocos passam sem alterações.

A função opcional flush(controller) é chamada no fecho normal do lado de escrita, depois de todos os blocos de entrada terem sido processados com sucesso. Pode emitir o que ficou no buffer antes de a API fechar o lado de leitura; não é uma função de limpeza em caso de cancelamento ou interrupção. A API aguarda a promessa devolvida por qualquer uma das funções. Uma exceção ou uma promessa rejeitada coloca o fluxo em estado de erro, por isso inclui o trabalho assíncrono na promessa que devolves.

enqueue() entrega um bloco ao lado de leitura, devolve undefined e lança TypeError se esse lado já não aceitar blocos. Não espera por um consumidor. A contrapressão pode atrasar o processamento de escritas posteriores, mas não impõe um limite rígido ao número de chamadas a enqueue() na mesma função. Liga um consumidor antes de esperares pela conclusão das escritas.

Exemplos

(async () => {
  const input = new ReadableStream({
    start(sourceController) {
      for (const value of [1, 2, 3]) sourceController.enqueue(value);
      sourceController.close();
    },
  });

  let pending = [];
  const pairs = new TransformStream({
    transform(chunk, controller) {
      pending.push(chunk);
      if (pending.length === 2) {
        controller.enqueue(pending);
        pending = [];
      }
    },
    flush(controller) {
      if (pending.length > 0) controller.enqueue(pending);
    },
  });

  const output = [];
  await input.pipeThrough(pairs).pipeTo(new WritableStream({
    write(chunk) {
      output.push(chunk);
    },
  }));
  console.log(JSON.stringify(output));
})().catch((error) => console.error(error));

Resultado

[[1,2],[3]]

Por predefinição, `pipeThrough()` propaga o fecho normal da origem para o lado de escrita da transformação, enquanto `pipeTo()` consome a saída à medida que chega. `transform()` emite o par `[1,2]` e `flush()` emite o elemento restante como `[3]`.

Lições relacionadas

  • JavaScript · Lição 4 · Avançado · Versão: 4

Fontes