ReadableByteStreamController.error() — Methode · JavaScript-Referenz

Signatur

ReadableByteStreamController.prototype.error(errorReason)

Beschreibung

Mit error() meldet die zugrunde liegende Quelle eines lesbaren Byte-Streams (new ReadableStream({ type: 'bytes', … })), dass ein nicht behebbarer Fehler aufgetreten ist, etwa ein Netzwerkabbruch, eine ungültige Prüfsumme oder eine Zeitüberschreitung. Der Controller wird in start(), pull() oder cancel() übergeben. Man kann ihn aber auch speichern und später aufrufen, zum Beispiel aus einem Timer oder einem Event-Handler.

Nach dem Aufruf wechselt der Stream sofort in den Zustand errored:

Die interne Warteschlange wird verworfen. Bereits mit enqueue() eingereihte, aber noch nicht gelesene Bytes gehen verloren.
Offene und künftige read()-Aufrufe (bei Standard- und BYOB-Readern) werden mit errorReason abgelehnt.
Das Promise reader.closed wird mit demselben Grund abgelehnt.
Ein offener byobRequest wird ungültig, danach sind weder respond() noch enqueue() möglich.
Über pipeTo() oder pipeThrough() verbundene Ziele werden standardmäßig ebenfalls abgebrochen.

Im Unterschied dazu beendet close() den Stream regulär: Die Daten in der Warteschlange können noch gelesen werden. error() ist dagegen ein harter Abbruch. cancel() kommt von der Verbraucherseite, error() dagegen von der Erzeugerseite.

Parameter

Name	Typ	Default	Beschreibung
$errorReason	any	undefined	Grund für den Fehler. Mit diesem Wert werden alle folgenden Lesevorgänge abgelehnt. Meist ein `Error`- oder `DOMException`-Objekt, möglich ist aber jeder Wert.

Rückgabewert

Typ

void

Beschreibung

Gibt undefined zurück.

Beispiele

Stream beim Start mit Fehler abbrechen

const stream = new ReadableStream({
  type: 'bytes',
  start(controller) {
    controller.enqueue(new Uint8Array([1, 2, 3]));
    // Die Warteschlange wird verworfen, die Bytes 1–3 gehen verloren
    controller.error(new Error('Quelle nicht verfügbar'));
  }
});

const reader = stream.getReader();
try {
  await reader.read();
} catch (err) {
  console.log('Lesefehler:', err.message);
}

Lesefehler: Quelle nicht verfügbar

BYOB-Quelle bricht bei ungültigen Daten ab

const data = new Uint8Array(10).fill(7);
let offset = 0;

const stream = new ReadableStream({
  type: 'bytes',
  pull(controller) {
    const request = controller.byobRequest;
    if (offset >= 6) {
      // Beispielhafte Prüfung schlägt fehl -> Stream hart abbrechen
      controller.error(new RangeError('Prüfsumme ungültig'));
      return;
    }
    const view = request.view;
    const n = Math.min(3, view.byteLength);
    view.set(data.subarray(offset, offset + n));
    offset += n;
    request.respond(n);
  }
});

const reader = stream.getReader({ mode: 'byob' });
let buffer = new ArrayBuffer(8);

try {
  while (true) {
    const { value, done } = await reader.read(new Uint8Array(buffer));
    if (done) break;
    console.log(`${value.byteLength} Bytes gelesen`);
    buffer = value.buffer; // übertragenen Puffer weiterverwenden
  }
} catch (err) {
  console.log(`Abbruch: ${err.name}: ${err.message}`);
}

3 Bytes gelesen 3 Bytes gelesen Abbruch: RangeError: Prüfsumme ungültig

Zeitüberschreitung über gespeicherten Controller

let timer;

const stream = new ReadableStream({
  type: 'bytes',
  start(controller) {
    // Kommen nach 1 s keine Daten, wird der Stream abgebrochen
    timer = setTimeout(() => {
      controller.error(
        new DOMException('Keine Daten innerhalb von 1 s', 'TimeoutError')
      );
    }, 1000);
  },
  cancel() {
    clearTimeout(timer);
  }
});

const reader = stream.getReader();
reader.closed.catch((err) => console.log(err.name, '-', err.message));

TimeoutError - Keine Daten innerhalb von 1 s

Siehe auch

ReadableByteStreamController.close() ReadableByteStreamController.enqueue() ReadableStreamDefaultController.error() WritableStreamDefaultController.error() ReadableStream.getReader()