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

CKTIS / JavaScript

Destino de WritableStream: start, write, close e abort

Quatro métodos opcionais definem como um fluxo de escrita prepara o destino, escreve blocos, termina normalmente ou liberta recursos após uma interrupção.

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

Sintaxe

new WritableStream()
new WritableStream(underlyingSink)
new WritableStream(underlyingSink, queuingStrategy)

// Optional methods on underlyingSink:
const underlyingSink = {
  start(controller) { /* initialize the destination */ },
  write(chunk, controller) { /* write one chunk */ },
  close() { /* finalize successful output */ },
  abort(reason) { /* clean up after an abort request */ },
};

WritableStream faz parte da API Web Streams, não do ECMAScript 2024; a disponibilidade depende do ambiente de execução. underlyingSink, o primeiro argumento opcional do construtor, é um objeto cujos métodos são chamados pelo fluxo. O segundo argumento opcional, queuingStrategy, define como se mede o tamanho da fila para regular o ritmo de escrita (backpressure).

start(controller) é executado uma vez durante a construção. Uma exceção síncrona faz falhar a construção; uma promessa rejeitada coloca o fluxo criado em estado de erro. O fluxo aguarda que a inicialização termine com sucesso antes de entregar blocos ao destino. write(chunk, controller) trata um bloco de cada vez, pela ordem de envio. Devolve uma promessa que represente a escrita assíncrona efetiva, para que o fluxo possa aguardá-la e propagar falhas.

close() não recebe argumentos. Após um pedido de fecho, só é chamado depois de todas as escritas aceites terminarem com sucesso. Usa-o para esvaziar os buffers do destino e libertar recursos. abort(reason) faz a limpeza após um pedido de interrupção; o motivo pode ser qualquer valor JavaScript. As escritas que ainda não começaram são rejeitadas, mas uma operação em curso não é parada automaticamente e as escritas concluídas não são desfeitas. Ambos os métodos podem devolver promessas; não assumas que abort é chamado em todos os erros ou depois do fecho.

start e write recebem o mesmo WritableStreamDefaultController. controller.signal permite que uma operação em curso reaja a um pedido de interrupção, se suportar cancelamento. controller.error(error) assinala uma falha do fluxo; não é um pedido de interrupção nem substitui a limpeza.

O produtor chama getWriter(), que bloqueia o fluxo para uso por um só escritor. Trata as promessas de writer.write(), writer.close() e writer.abort(); as chamadas diretas a stream.close() e stream.abort() devolvem promessas rejeitadas enquanto o fluxo estiver bloqueado. writer.releaseLock() liberta o bloqueio sem terminar o fluxo.

Exemplos

(async () => {
  const log = [];
  const reason = new Error("stop");

  async function run(label, shouldAbort) {
    const stream = new WritableStream({
      start() {
        log.push(`${label}: start`);
      },
      async write(chunk) {
        await Promise.resolve();
        log.push(`${label}: write ${chunk}`);
      },
      close() {
        log.push(`${label}: close`);
      },
      abort(received) {
        log.push(`${label}: abort (${received === reason})`);
      },
    });

    const writer = stream.getWriter();
    try {
      await writer.write("A");
      if (shouldAbort) {
        await writer.abort(reason);
      } else {
        await writer.close();
      }
    } finally {
      writer.releaseLock();
    }
  }

  await run("normal", false);
  await run("interrupted", true);
  console.log(log.join("\n"));
})().catch(console.error);

Resultado

normal: start
normal: write A
normal: close
interrupted: start
interrupted: write A
interrupted: abort (true)

O exemplo usa dois fluxos distintos. Ambos acabam de escrever `A`; o primeiro fecha normalmente e o segundo é interrompido. `true` indica que o destino recebeu exatamente o mesmo objeto `Error`.

Lições relacionadas

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

Fontes