WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

TransformStream: transform, flush und controller.enqueue

Verarbeite Eingabeblöcke mit `transform()`, gib Ergebnisse mit `controller.enqueue()` aus und leere beim regulären Schließen den Puffer mit `flush()`.

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

Syntax

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 verbindet eine Eingabeseite (writable) mit einer Ausgabeseite (readable). Dem Konstruktor kannst du ein transformer-Objekt übergeben. Die nächsten beiden optionalen Argumente bestimmen die Warteschlangenstrategien für die Schreib- und die Leseseite, in dieser Reihenfolge. Die Web Streams API ist kein Bestandteil von ECMAScript 2024; prüfe die Unterstützung in deiner Zielumgebung.

transform(chunk, controller) läuft für jeden Eingabeblock, sobald er verarbeitet werden kann. Rufe controller.enqueue(chunk) auf dem übergebenen TransformStreamDefaultController entsprechend oft auf, um keinen, einen oder mehrere Ausgabeblöcke zu erzeugen. Der Rückgabewert des Callbacks ist keine Ausgabe. Ohne transform() werden die Blöcke unverändert weitergereicht.

Das optionale flush(controller) läuft beim regulären Schließen der Schreibseite, nachdem alle Eingabeblöcke erfolgreich verarbeitet wurden. Es kann gepufferte Reste ausgeben, bevor die API die Leseseite schließt; es ist kein Aufräum-Callback beim Abbruch oder bei der Stornierung. Die API wartet auf ein von einem der beiden Callbacks zurückgegebenes Promise. Eine ausgelöste Ausnahme oder ein abgelehntes Promise versetzt den Stream in einen Fehlerzustand. Binde daher asynchrone Arbeit in das zurückgegebene Promise ein.

enqueue() übergibt einen Block an die Leseseite, gibt undefined zurück und löst TypeError aus, wenn die Leseseite keine Blöcke mehr annimmt. Die Methode wartet nicht auf einen Abnehmer. Rückstau (Backpressure) kann die Verarbeitung weiterer Schreibvorgänge verzögern, begrenzt die Anzahl der enqueue()-Aufrufe in einem Callback aber nicht strikt. Verbinde einen Abnehmer, bevor du auf den Abschluss der Schreibvorgänge wartest.

Beispiele

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

Ergebnis

[[1,2],[3]]

Standardmäßig leitet `pipeThrough()` das reguläre Schließen der Quelle an die Schreibseite der Transformation weiter, während `pipeTo()` die Ausgabe laufend abnimmt. `transform()` gibt das Paar `[1,2]` aus, `flush()` das übrige Element als `[3]`.

Zugehörige Lektionen

  • JavaScript · Lektion 4 · Fortgeschritten · Version: 4

Quellen