new CountQueuingStrategy() — Methode · JavaScript-Referenz

Signatur

new CountQueuingStrategy({ highWaterMark })

Beschreibung

Der Konstruktor CountQueuingStrategy() erzeugt eine Strategie, mit der ein ReadableStream, WritableStream oder TransformStream seine interne Warteschlange und den Gegendruck (Backpressure) steuert. Jeder eingereihte Chunk zählt dabei als 1, egal ob es ein Objekt, ein String oder ein großes Array ist.

Das zentrale Element ist highWaterMark: Sobald die Anzahl der Chunks in der Warteschlange diesen Wert erreicht, wird controller.desiredSize bzw. writer.desiredSize null oder negativ. Die Quelle sollte dann pausieren, bis wieder Platz frei ist. Bei einem ReadableStream wird pull() nicht mehr aufgerufen, bei einem WritableStream wartet writer.ready.

Die Strategie eignet sich vor allem für Objekt-Streams, bei denen jeder Chunk eine logische Einheit ist, etwa Datensätze, Log-Einträge oder Nachrichten. Wenn die Größe in Bytes zählen soll, nimmt man stattdessen ByteLengthQueuingStrategy.

Parameter

Name	Typ	Default	Beschreibung
$options Pflicht	Object		Konfigurationsobjekt mit der Eigenschaft `highWaterMark`.
$options.highWaterMark Pflicht	number		Wie viele Chunks höchstens in der internen Warteschlange liegen dürfen, bevor Gegendruck entsteht. Muss eine nicht-negative Zahl sein (auch `0` oder `Infinity` sind erlaubt).

Beispiele

Instanz erstellen und Eigenschaften lesen

const strategy = new CountQueuingStrategy({ highWaterMark: 3 });

console.log(strategy.highWaterMark);
console.log(strategy.size('beliebiger Chunk'));
console.log(strategy.size(new Uint8Array(1024)));

3 1 1

ReadableStream mit begrenzter Warteschlange

let counter = 0;

const stream = new ReadableStream({
  pull(controller) {
    counter++;
    console.log(`pull #${counter}, desiredSize: ${controller.desiredSize}`);
    controller.enqueue({ id: counter });
    if (counter === 5) controller.close();
  }
}, new CountQueuingStrategy({ highWaterMark: 2 }));

// Ohne Leser füllt der Stream nur bis zu 2 Chunks vor
setTimeout(async () => {
  for await (const item of stream) {
    console.log('gelesen:', item.id);
  }
}, 100);

pull #1, desiredSize: 2 pull #2, desiredSize: 1 ... (danach erst beim Lesen weitere pull-Aufrufe)

WritableStream mit Gegendruck respektieren

const sink = new WritableStream({
  async write(record) {
    // langsames Speichern simulieren
    await new Promise((r) => setTimeout(r, 50));
    console.log('gespeichert:', record.name);
  }
}, new CountQueuingStrategy({ highWaterMark: 2 }));

const writer = sink.getWriter();
const records = ['Anna', 'Ben', 'Clara', 'David'].map((name) => ({ name }));

for (const record of records) {
  await writer.ready; // wartet, solange die Warteschlange voll ist
  writer.write(record);
}
await writer.close();
console.log('fertig');

gespeichert: Anna gespeichert: Ben gespeichert: Clara gespeichert: David fertig

// Wichtig · Fallstricke

Fehlt highWaterMark oder wird kein Objekt übergeben, wirft der Konstruktor einen TypeError. Ein negativer Wert oder NaN führt spätestens beim Erzeugen des Streams zu einem RangeError.
Gegendruck ist nur ein Signal. controller.enqueue() und writer.write() nehmen auch über dem Limit weitere Chunks an. Der Code muss desiredSize bzw. writer.ready selbst prüfen.
Ohne Angabe einer Strategie verwenden Streams standardmäßig eine Zählstrategie mit highWaterMark: 1 (bei TransformStream auf der lesbaren Seite: 0).
Statt einer Instanz kann man auch ein einfaches Objekt wie { highWaterMark: 3, size: () => 1 } übergeben. CountQueuingStrategy ist aber lesbarer und teilt sich intern die size-Funktion.
Nicht verwendbar für Byte-Streams (type: 'bytes'): Dort ist keine size-Funktion erlaubt.
Unterstützt in Chrome 52+, Firefox 65+, Safari 10.1+, Deno und Node.js (global ab v18, vorher über stream/web).

Siehe auch

new ByteLengthQueuingStrategy() new CSSTranslate() new CompressionStream() new ContentIndexEvent() new CSSMathNegate()