Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

Destinazione di WritableStream: start, write, close e abort

Quattro metodi facoltativi definiscono come uno stream scrivibile prepara la destinazione, scrive i blocchi, termina normalmente o libera risorse dopo un’interruzione.

Versione: ECMAScript 2024 and the current web platform; runtime support varies

Sintassi

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 appartiene alla Web Streams API, non a ECMAScript 2024; la disponibilità dipende dall’ambiente di esecuzione. underlyingSink, il primo argomento facoltativo del costruttore, è un oggetto i cui metodi vengono invocati dallo stream. Il secondo argomento facoltativo, queuingStrategy, definisce come misurare la dimensione della coda per la contropressione (backpressure).

start(controller) viene eseguito una volta durante la costruzione. Un’eccezione sincrona fa fallire la costruzione; una promessa rigettata porta lo stream creato in stato di errore. Lo stream attende il successo dell’inizializzazione prima di consegnare blocchi alla destinazione. write(chunk, controller) gestisce un blocco alla volta, nell’ordine di invio. Restituisci una promessa che rappresenti l’effettiva scrittura asincrona, così lo stream può attenderla e propagare gli errori.

close() non riceve argomenti. Dopo una richiesta di chiusura, viene chiamato solo quando tutte le scritture accettate sono riuscite. Usalo per svuotare i buffer della destinazione e liberare risorse. abort(reason) esegue la pulizia dopo una richiesta di interruzione; il motivo può essere qualsiasi valore JavaScript. Le scritture non ancora iniziate vengono rigettate, ma un’operazione in corso non si arresta automaticamente e le scritture completate non vengono annullate. Entrambi i metodi possono restituire promesse; non dare per scontato che abort venga chiamato a ogni errore o dopo la chiusura.

start e write ricevono lo stesso WritableStreamDefaultController. controller.signal consente a un’operazione in corso di reagire a una richiesta di interruzione, se supporta l’annullamento. controller.error(error) segnala un errore dello stream; non costituisce una richiesta di interruzione e non sostituisce la pulizia.

Il produttore chiama getWriter(), che riserva lo stream a un solo writer. Gestisci le promesse di writer.write(), writer.close() e writer.abort(); le chiamate dirette a stream.close() e stream.abort() restituiscono promesse rigettate finché lo stream è bloccato. writer.releaseLock() rilascia il blocco senza terminare lo stream.

Esempi

(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);

Risultato

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

L’esempio usa due stream distinti. Entrambi finiscono di scrivere `A`; il primo si chiude e il secondo viene interrotto. `true` indica che la destinazione ha ricevuto esattamente lo stesso oggetto `Error`.

Lezioni correlate

  • JavaScript · Lezione 4 · Avanzato · Versione: 4

Fonti