Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

Destination d’un WritableStream : start, write, close et abort

Quatre méthodes facultatives définissent comment un flux inscriptible prépare sa destination, écrit des fragments, termine normalement ou libère ses ressources après une interruption.

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

Syntaxe

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 fait partie de l’API Web Streams, pas d’ECMAScript 2024 ; sa disponibilité dépend de l’environnement d’exécution. underlyingSink, le premier argument facultatif du constructeur, est un objet dont le flux appelle les méthodes. Le second argument facultatif, queuingStrategy, définit comment mesurer la taille de la file pour la régulation du débit (backpressure).

start(controller) s’exécute une fois pendant la construction. Une exception synchrone fait échouer la construction ; une promesse rejetée met le flux créé en état d’erreur. Le flux attend la réussite de l’initialisation avant de transmettre des fragments à la destination. write(chunk, controller) traite un fragment à la fois, dans l’ordre de soumission. Renvoyez une promesse qui représente l’écriture asynchrone effective pour que le flux puisse l’attendre et propager les erreurs.

close() ne reçoit aucun argument. Après une demande de fermeture, cette méthode n’est appelée que si toutes les écritures acceptées ont réussi. Elle permet de vider les tampons de la destination et de libérer les ressources. abort(reason) effectue le nettoyage après une demande d’interruption ; le motif peut être n’importe quelle valeur JavaScript. Les écritures non commencées sont rejetées, mais une opération en cours n’est pas arrêtée automatiquement et les écritures déjà terminées ne sont pas annulées. Les deux méthodes peuvent renvoyer des promesses ; ne supposez pas que abort est appelée pour toute erreur ou après la fermeture.

start et write reçoivent le même WritableStreamDefaultController. controller.signal permet à une opération en cours de réagir à une demande d’interruption si elle prend en charge l’annulation. controller.error(error) signale une défaillance du flux ; ce n’est pas une demande d’interruption et cela ne remplace pas le nettoyage.

Le producteur appelle getWriter(), qui verrouille le flux pour un seul objet d’écriture. Traitez les promesses de writer.write(), writer.close() et writer.abort() ; les appels directs à stream.close() et stream.abort() renvoient des promesses rejetées tant que le flux est verrouillé. writer.releaseLock() libère le verrou sans mettre fin au flux.

Exemples

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

Résultat

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

L’exemple utilise deux flux distincts. Les deux terminent l’écriture de `A` ; le premier se ferme et le second est interrompu. `true` indique que la destination a reçu exactement le même objet `Error`.

Leçons associées

  • JavaScript · Leçon 4 · Avancé · Version : 4

Sources