ReadableStream

Konstruktor

ReadableStream()

Erstellt und gibt ein lesbares Stream-Objekt aus den gegebenen Handlern zurück.

Instanzeigenschaften

ReadableStream.locked Schreibgeschützt

Gibt einen Boolean-Wert zurück, der angibt, ob der lesbare Stream an einen Leser gebunden ist oder nicht.

Statische Methoden

ReadableStream.from() Experimentell

Gibt ReadableStream von einem bereitgestellten Iterable oder asynchronen Iterable-Objekt zurück, wie z.B. ein Array, ein Set, ein asynchroner Generator usw.

Instanzmethoden

ReadableStream.cancel()

Gibt ein Promise zurück, das aufgelöst wird, wenn der Stream abgebrochen wird. Durch Aufrufen dieser Methode signalisiert ein Konsument das Desinteresse am Stream. Das übergebene reason-Argument wird an die zugrunde liegende Quelle übergeben, die es möglicherweise verwendet oder nicht.

ReadableStream.getReader()

Erstellt einen Leser und bindet den Stream an ihn. Solange der Stream gebunden ist, kann kein anderer Leser erworben werden, bis dieser freigegeben wird.

ReadableStream.pipeThrough()

Bietet eine kaskadierbare Möglichkeit, den aktuellen Stream durch einen Transform-Stream oder ein anderes schreibbares/lesbares Paar zu leiten.

ReadableStream.pipeTo()

Leitet den aktuellen ReadableStream zu einem gegebenen WritableStream und gibt ein Promise zurück, das erfüllt wird, wenn der Leitungsprozess erfolgreich abgeschlossen ist, oder abgelehnt wird, wenn Fehler aufgetreten sind.

ReadableStream.tee()

Die tee-Methode tees diesen lesbaren Stream und gibt ein zwei-elementiges Array zurück, das die beiden resultierenden Verzweigungen als neue ReadableStream-Instanzen enthält. Jeder dieser Streams erhält die gleichen eingehenden Daten.

Asynchrone Iteration

ReadableStream implementiert das asynchrone Iterierprotokoll. Dies ermöglicht die asynchrone Iteration über die Chunks in einem Stream unter Verwendung der for await...of-Syntax:

const stream = new ReadableStream(getSomeSource());

for await (const chunk of stream) {
  // Do something with each 'chunk'
}

Der asynchrone Iterator konsumiert den Stream, bis er keine Daten mehr aufweist oder anderweitig beendet wird. Die Schleife kann aufgrund eines break-, throw- oder return-Statements auch vorzeitig beendet werden.

Während der Iteration wird der Stream gesperrt, um zu verhindern, dass andere Konsumenten einen Leser erwerben (der Versuch, über einen bereits gesperrten Stream zu iterieren, führt zu einem TypeError). Diese Sperre wird freigegeben, wenn die Schleife endet.

Standardmäßig wird der Stream auch bei Verlassen der Schleife abgebrochen, sodass er nicht mehr verwendet werden kann. Um den Stream nach dem Verlassen der Schleife weiterzuverwenden, übergeben Sie { preventCancel: true } an die values()-Methode des Streams:

for await (const chunk of stream.values({ preventCancel: true })) {
  // Do something with 'chunk'
  break;
}
// Acquire a reader for the stream and continue reading ...

Beispiele

Fetch-Stream

Im folgenden Beispiel wird eine künstliche Response erstellt, um HTML-Fragmente, die von einer anderen Ressource abgerufen wurden, zum Browser zu streamen.

Es demonstriert die Nutzung eines ReadableStream in Kombination mit einer Uint8Array.

fetch("https://www.example.org")
  .then((response) => response.body)
  .then((rb) => {
    const reader = rb.getReader();

    return new ReadableStream({
      start(controller) {
        // The following function handles each data chunk
        function push() {
          // "done" is a Boolean and value a "Uint8Array"
          reader.read().then(({ done, value }) => {
            // If there is no more data to read
            if (done) {
              console.log("done", done);
              controller.close();
              return;
            }
            // Get the data and send it to the browser via the controller
            controller.enqueue(value);
            // Check chunks by logging to the console
            console.log(done, value);
            push();
          });
        }

        push();
      },
    });
  })
  .then((stream) =>
    // Respond with our stream
    new Response(stream, { headers: { "Content-Type": "text/html" } }).text(),
  )
  .then((result) => {
    // Do things with result
    console.log(result);
  });

Konvertieren eines Iterators oder asynchronen Iterators in einen Stream

Die statische Methode from() kann einen Iterator, wie z.B. eine Array oder Map, oder einen (async) iterator in einen lesbaren Stream umwandeln:

const myReadableStream = ReadableStream.from(iteratorOrAsyncIterator);

In Browsern, die die from()-Methode nicht unterstützen, können Sie stattdessen Ihren eigenen benutzerdefinierten lesbaren Stream erstellen, um dasselbe Ergebnis zu erzielen:

function iteratorToStream(iterator) {
  return new ReadableStream({
    async pull(controller) {
      const { value, done } = await iterator.next();

      if (value) {
        controller.enqueue(value);
      }
      if (done) {
        controller.close();
      }
    },
  });
}

Asynchrone Iteration eines Streams mit for await...of

Dieses Beispiel zeigt, wie Sie die fetch()-Antwort mit einer for await...of-Schleife verarbeiten können, um die eingehenden Chunks zu durchlaufen.

const response = await fetch("https://www.example.org");
let total = 0;

// Iterate response.body (a ReadableStream) asynchronously
for await (const chunk of response.body) {
  // Do something with each chunk
  // Here we just accumulate the size of the response.
  total += chunk.length;
}

// Do something with the total
console.log(total);

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Streams API Konzepte
• Verwendung von lesbaren Streams
• Verwendung von lesbaren Byte-Streams
• Web-streams-polyfill