WritableStreamDefaultWriter.ready — Eigenschaft · JavaScript-Referenz

Signatur

get WritableStreamDefaultWriter.prototype.ready

Beschreibung

Die schreibgeschützte Eigenschaft ready eines WritableStreamDefaultWriter gibt ein Promise<undefined> zurück. Es wird erfüllt, sobald die gewünschte Größe der internen Warteschlange (writer.desiredSize) von null oder negativ auf einen positiven Wert steigt. Das zeigt an, dass der Stream keinen Gegendruck (Backpressure) mehr ausübt und wieder Daten annehmen kann.

Nutze ready in Schreibschleifen, bevor du writer.write() aufrufst: await writer.ready sorgt dafür, dass der Produzent nicht schneller schreibt, als die Senke (z. B. Netzwerk, Datei, Encoder) verarbeiten kann. So wächst der Speicherbedarf nicht unbegrenzt. Ist sofort Platz, ist das Promise schon erfüllt und das await kostet praktisch nichts.

Das Promise kann sich ändern: Entsteht Backpressure, ersetzt der Writer ready durch ein neues, noch ausstehendes Promise. Frag die Eigenschaft deshalb bei jedem Schleifendurchlauf neu ab und speichere sie nicht einmalig in einer Variablen. Gerät der Stream in einen Fehlerzustand oder wird die Sperre des Writers aufgehoben (releaseLock()), wird ready abgelehnt.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald desiredSize positiv ist. Es wird abgelehnt, wenn der Stream fehlerhaft ist, abgebrochen wurde oder der Writer seine Sperre freigibt.

Beispiele

Backpressure in einer Schreibschleife beachten

const stream = new WritableStream(
  {
    write(chunk) {
      // Langsame Senke simulieren
      return new Promise((resolve) => setTimeout(() => {
        console.log('geschrieben:', chunk);
        resolve();
      }, 100));
    }
  },
  new CountQueuingStrategy({ highWaterMark: 2 })
);

const writer = stream.getWriter();

const produce = async () => {
  for (const item of ['a', 'b', 'c', 'd']) {
    await writer.ready; // warten, bis wieder Platz ist
    writer.write(item).catch(console.error);
  }
  await writer.ready;
  await writer.close();
  console.log('fertig');
};

produce();

geschrieben: a geschrieben: b geschrieben: c geschrieben: d fertig

desiredSize und ready gemeinsam beobachten

const stream = new WritableStream(
  { write: () => new Promise((r) => setTimeout(r, 50)) },
  { highWaterMark: 1 }
);
const writer = stream.getWriter();

console.log('vorher:', writer.desiredSize); // 1
writer.write('x');
console.log('nach write:', writer.desiredSize); // 0 -> Backpressure

await writer.ready;
console.log('wieder bereit:', writer.desiredSize); // 1

vorher: 1 nach write: 0 wieder bereit: 1

Ablehnung bei Fehler oder releaseLock abfangen

const stream = new WritableStream({
  write() {
    throw new Error('Senke defekt');
  }
});
const writer = stream.getWriter();

writer.write('daten').catch(() => {});

try {
  await writer.closed; // wird durch den Fehler abgelehnt
} catch (err) {
  console.log('Stream-Fehler:', err.message);
}

writer.ready.catch((err) => console.log('ready abgelehnt:', err.message));

Stream-Fehler: Senke defekt ready abgelehnt: Senke defekt

// Wichtig · Fallstricke

Nicht zwischenspeichern: ready kann bei jeder Änderung des Backpressure-Zustands ein neues Promise liefern. Lies writer.ready deshalb vor jedem write() neu aus.
await writer.ready ist keine Pflicht: write() reiht Daten auch unter Backpressure ein. Wer ready weglässt, riskiert aber eine unbegrenzt wachsende Warteschlange und hohen Speicherverbrauch.
Nach releaseLock() wird ready mit einem TypeError abgelehnt. Unbehandelte Ablehnungen erzeugen Warnungen vom Typ „unhandled rejection“.
Im Fehlerzustand wird ready mit dem gespeicherten Fehler abgelehnt. Nutze für Fehlerbehandlung und Abschluss zusätzlich writer.closed.
Kompatibilität: Streams API in Chrome, Edge, Firefox (ab 100) und Safari verfügbar. In Node.js unter stream/web und ab Version 18 global.

Siehe auch

WritableStreamDefaultWriter WritableStreamDefaultWriter.desiredSize WritableStreamDefaultWriter.prototype.write() WritableStreamDefaultWriter.closed WritableStreamDefaultWriter.prototype.releaseLock() WritableStream.prototype.getWriter()