ReadableStream: tee()-Methode

Hinweis: Dieses Feature ist verfügbar in Web Workers.

Die tee()-Methode der ReadableStream-Schnittstelle teilt den aktuellen lesbaren Stream und gibt ein Array mit zwei Elementen zurück, das die beiden resultierenden Zweige als neue ReadableStream-Instanzen enthält.

Dies ist nützlich, um zwei Lesern zu ermöglichen, einen Stream nacheinander oder gleichzeitig, vielleicht mit unterschiedlichen Geschwindigkeiten, zu lesen. Zum Beispiel könnte dies in einem ServiceWorker nützlich sein, wenn Sie eine Antwort vom Server abrufen und sie an den Browser streamen, aber auch an den ServiceWorker-Cache streamen möchten. Da ein Antwortkörper nicht mehr als einmal konsumiert werden kann, benötigen Sie zwei Kopien, um dies zu tun.

Ein geteilter Stream signalisiert teilweisen Rückstau mit der Rate des schnelleren Verbrauchers der beiden ReadableStream-Zweige, und ungelesene Daten werden intern im langsamer konsumierten ReadableStream ohne Begrenzung oder Rückstau im Puffer gespeichert. Das heißt, wenn beide Zweige ein ungelesenes Element in ihrer internen Warteschlange haben, dann wird die interne Warteschlange des Controllers des ursprünglichen ReadableStream beginnen sich zu füllen, und sobald seine desiredSize ≤ 0 oder die des Byte-Stream-Controllers desiredSize ≤ 0, wird der Controller aufhören, pull(controller) auf der an ReadableStream() übergebenen zugrundeliegenden Quelle aufzurufen. Wenn nur ein Zweig konsumiert wird, wird der gesamte Körper im Speicher gespeichert. Daher sollten Sie die eingebaute tee() nicht verwenden, um sehr große Streams parallel mit unterschiedlichen Geschwindigkeiten zu lesen. Suchen Sie stattdessen nach einer Implementierung, die den Rückstau vollständig an die Geschwindigkeit des langsamer konsumierten Zweiges anpasst.

Um den Stream abzubrechen, müssen Sie dann beide resultierenden Zweige abbrechen. Das Teilen eines Streams wird ihn generell für die Dauer sperren, um zu verhindern, dass andere Leser ihn sperren.

Syntax

js
tee()

Parameter

Keine.

Rückgabewert

Ein Array, das zwei ReadableStream-Instanzen enthält.

Ausnahmen

TypeError

Wird ausgelöst, wenn der Quellstream kein ReadableStream ist.

Beispiele

Im folgenden einfachen Beispiel wird ein zuvor erstellter Stream geteilt und dann werden beide resultierenden Streams (enthalten in zwei Mitgliedern eines generierten Arrays) an eine Funktion übergeben, die die Daten aus den beiden Streams liest und die Chunks jedes Streams nacheinander an verschiedenen Teilen der Benutzeroberfläche ausgibt. Siehe einfaches Tee-Beispiel für den vollständigen Code.

js
function teeStream() {
  const teedOff = stream.tee();
  fetchStream(teedOff[0], list2);
  fetchStream(teedOff[1], list3);
}

function fetchStream(stream, list) {
  const reader = stream.getReader();
  let charsReceived = 0;

  // read() returns a promise that resolves
  // when a value has been received
  reader.read().then(function processText({ done, value }) {
    // Result objects contain two properties:
    // done  - true if the stream has already given you all its data.
    // value - some data. Always undefined when done is true.
    if (done) {
      console.log("Stream complete");
      return;
    }

    // value for fetch streams is a Uint8Array
    charsReceived += value.length;
    const chunk = value;
    let listItem = document.createElement("li");
    listItem.textContent = `Read ${charsReceived} characters so far. Current chunk = ${chunk}`;
    list.appendChild(listItem);

    // Read some more, and call this function again
    return reader.read().then(processText);
  });
}

Spezifikationen

Specification
Streams Standard
# ref-for-rs-tee②

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch