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
- WritableStream: WritableStream() constructor
- WritableStreamDefaultWriter
- WritableStreamDefaultWriter: close() method
- WritableStream: close() method
- WritableStream: abort() method
- WritableStreamDefaultController: signal property
- WritableStreamDefaultController: error() method
- WHATWG Streams Standard — The underlying sink API