WritableStreamDefaultWriter.desiredSize — Eigenschaft · JavaScript-Referenz

Signatur

get WritableStreamDefaultWriter.prototype.desiredSize

Beschreibung

Die schreibgeschützte Eigenschaft desiredSize eines WritableStreamDefaultWriter liefert die Differenz zwischen dem High Water Mark der Warteschlangenstrategie und der aktuellen Gesamtgröße der Chunks in der internen Warteschlange. Sie zeigt also, wie viele Daten der Stream noch gern annehmen würde, bevor er überlastet ist.

Die Einheit hängt von der verwendeten Warteschlangenstrategie ab: Bei CountQueuingStrategy (Standard, highWaterMark: 1) wird in Chunks gezählt, bei ByteLengthQueuingStrategy in Bytes. Ein Chunk bleibt so lange in der Warteschlange, bis die write()-Methode der zugrunde liegenden Senke (Sink) abgeschlossen ist. Solange er noch verarbeitet wird, zählt er also weiterhin mit.

Mögliche Werte:

positive Zahl: Es ist noch Platz frei, weiteres Schreiben ist unbedenklich.
0 oder negativ: Die Warteschlange ist voll oder läuft über. Du solltest auf writer.ready warten. Nach dem Schließen des Streams ist der Wert immer 0.
null: Der Stream ist fehlerhaft oder wird gerade abgebrochen (Zustand errored oder erroring).

Meistens reicht es, auf await writer.ready zu warten. Die Eigenschaft desiredSize ist nützlich, wenn du selbst entscheiden willst, wie viele Daten du auf einmal schreibst, zum Beispiel beim Stückeln großer Puffer oder für Diagnose und Logging.

Rückgabewert

Typ

number | null

Beschreibung

Freie Kapazität der internen Warteschlange (highWaterMark minus Warteschlangengröße). Der Wert kann negativ sein, ist nach dem Schließen 0 und bei einem fehlerhaften oder abbrechenden Stream null.

Beispiele

Füllstand der Warteschlange beobachten

// Langsame Senke: jeder Schreibvorgang dauert 100 ms
const stream = new WritableStream(
  {
    write: (chunk) => new Promise((resolve) => setTimeout(resolve, 100)),
  },
  new CountQueuingStrategy({ highWaterMark: 3 })
);

const writer = stream.getWriter();
console.log(writer.desiredSize); // leere Warteschlange

writer.write('a');
console.log(writer.desiredSize);
writer.write('b');
writer.write('c');
console.log(writer.desiredSize); // voll
writer.write('d');
console.log(writer.desiredSize); // übervoll

3 2 0 -1

Gegendruck beachten beim Schreiben vieler Chunks

const log = [];
const stream = new WritableStream(
  {
    async write(chunk) {
      await new Promise((r) => setTimeout(r, 20)); // z. B. Netzwerk/Datei
      log.push(chunk);
    },
  },
  new CountQueuingStrategy({ highWaterMark: 2 })
);

const writeAll = async (items) => {
  const writer = stream.getWriter();
  for (const item of items) {
    if (writer.desiredSize <= 0) {
      console.log(`Warteschlange voll (desiredSize=${writer.desiredSize}), warte …`);
      await writer.ready; // wird erfüllt, sobald wieder Platz ist
    }
    writer.write(item);
  }
  await writer.close();
};

await writeAll([1, 2, 3, 4]);
console.log(log);

Warteschlange voll (desiredSize=0), warte … Warteschlange voll (desiredSize=0), warte … [1, 2, 3, 4]

Werte nach close(), abort() und releaseLock()

// Geschlossener Stream → 0
const s1 = new WritableStream({ write() {} });
const w1 = s1.getWriter();
console.log(w1.desiredSize); // Standard-highWaterMark ist 1
await w1.close();
console.log(w1.desiredSize);

// Abgebrochener Stream → null
const s2 = new WritableStream({ write() {} });
const w2 = s2.getWriter();
w2.abort(new Error('Abbruch'));
console.log(w2.desiredSize);

// Nach releaseLock() → TypeError
w1.releaseLock();
try {
  w1.desiredSize;
} catch (err) {
  console.log(err.name);
}

1 0 null TypeError

// Wichtig · Fallstricke

Wenn du die Eigenschaft nach writer.releaseLock() liest, wird ein TypeError geworfen, denn der Writer ist dann nicht mehr an den Stream gebunden.
null und 0 sind verschiedene Werte. Die Prüfung if (!writer.desiredSize) behandelt beide gleich. Nutze besser === null, um Fehlerzustände zu erkennen.
write() nimmt Daten auch dann an, wenn desiredSize negativ ist. Der Gegendruck ist nur ein Hinweis. Wer ihn übergeht, riskiert, dass der Speicherverbrauch unbegrenzt wächst.
Die Einheit ist die der Warteschlangenstrategie (Chunks oder Bytes). Bei eigener size()-Funktion bestimmt deren Rückgabewert die Einheit.
Ein Chunk zählt so lange zur Warteschlange, bis das Promise der Sink-Methode write() erfüllt ist. Er zählt also auch mit, während er noch verarbeitet wird.
Kompatibilität: Chrome 59+, Edge 79+, Firefox 100+, Safari 14.1+, Node.js 18+ (global, vorher über stream/web). Auch in Web Workern verfügbar.

Siehe auch

WritableStreamDefaultWriter WritableStreamDefaultWriter.ready WritableStreamDefaultWriter.prototype.write() WritableStreamDefaultWriter.prototype.close() WritableStreamDefaultWriter.prototype.releaseLock() WritableStream CountQueuingStrategy ByteLengthQueuingStrategy ReadableStreamDefaultController.desiredSize