TransformStreamDefaultController.enqueue() — Methode · JavaScript-Referenz

Signatur

TransformStreamDefaultController.prototype.enqueue(chunk)

Beschreibung

enqueue() ist das zentrale Werkzeug innerhalb der transform()- und flush()-Callbacks eines TransformStream. Jeder Chunk, der auf der beschreibbaren Seite ankommt, kann verarbeitet und anschließend über controller.enqueue() an die lesbare Seite weitergegeben werden. So entstehen Pipelines, die Daten umwandeln, filtern oder aufteilen – etwa Text in Großbuchstaben umwandeln, Zeilen aufspalten oder JSON parsen.

Die Anzahl der Aufrufe ist frei: Ein Eingangs-Chunk kann keinen (Filtern), genau einen (Abbilden) oder mehrere Ausgangs-Chunks (Aufteilen) erzeugen. Im flush()-Callback lassen sich außerdem gepufferte Restdaten ausgeben, bevor der Stream geschlossen wird.

Die Methode wirkt synchron und wartet nicht auf den Konsumenten. Den Füllstand der lesbaren Warteschlange kann man über controller.desiredSize prüfen; der Rückstau (Backpressure) wird aber automatisch an die beschreibbare Seite weitergegeben, sodass transform() erst wieder aufgerufen wird, wenn Platz ist.

Parameter

Name	Typ	Default	Beschreibung
$chunk Pflicht	any		Das Datenstück, das eingereiht werden soll. Beliebiger Typ, z. B. `string`, `Uint8Array` oder ein Objekt – abhängig davon, was die Konsumenten erwarten.

Beispiele

Text in Großbuchstaben umwandeln

const upperCase = new TransformStream({
  transform(chunk, controller) {
    controller.enqueue(chunk.toUpperCase());
  }
});

const source = ReadableStream.from(['hallo ', 'welt']);
const reader = source.pipeThrough(upperCase).getReader();

let result = '';
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  result += value;
}
console.log(result);

HALLO WELT

Zeilen aufteilen und Rest im flush() ausgeben

const lineSplitter = () => {
  let buffer = '';
  return new TransformStream({
    transform(chunk, controller) {
      buffer += chunk;
      const lines = buffer.split('\n');
      buffer = lines.pop(); // unvollständige Zeile behalten
      for (const line of lines) controller.enqueue(line);
    },
    flush(controller) {
      if (buffer) controller.enqueue(buffer);
    }
  });
};

const response = await fetch('/log.txt');
const lines = response.body
  .pipeThrough(new TextDecoderStream())
  .pipeThrough(lineSplitter());

for await (const line of lines) {
  console.log('Zeile:', line);
}

Zeile: ... (eine Ausgabe pro Zeile der Datei)

Filtern: nur gerade Zahlen weiterreichen

const evenOnly = new TransformStream({
  transform(n, controller) {
    if (n % 2 === 0) controller.enqueue(n);
    // ungerade Zahlen werden einfach nicht eingereiht
  }
});

const out = [];
for await (const n of ReadableStream.from([1, 2, 3, 4, 5, 6]).pipeThrough(evenOnly)) {
  out.push(n);
}
console.log(out);

[2, 4, 6]

// Wichtig · Fallstricke

Wirft einen TypeError, wenn die lesbare Seite bereits geschlossen oder fehlerhaft ist bzw. nach controller.terminate() aufgerufen wird. Bei Abbruch durch den Konsumenten (cancel()) kann ein späteres enqueue() ebenfalls scheitern – ggf. in try/catch absichern.
enqueue() gibt kein Promise zurück; wer Backpressure bewusst steuern will, gibt aus transform() ein Promise zurück oder prüft controller.desiredSize.
Objekte werden per Referenz weitergereicht, nicht kopiert – nachträgliche Änderungen am Chunk sind für den Konsumenten sichtbar.
for await...of über ReadableStream sowie ReadableStream.from() sind neuer als die Streams-API selbst (Safari erst seit Kurzem); für ältere Umgebungen getReader() verwenden.

Siehe auch

TransformStreamDefaultController.error() TransformStreamDefaultController.terminate() ReadableStreamDefaultController.enqueue() ReadableStreamDefaultController.close() ReadableStreamDefaultController.error()