Signatur
Beschreibung
Die schreibgeschützte Eigenschaft desiredSize zeigt, wie viel Platz die Warteschlange des zugehörigen ReadableStream (also transformStream.readable) noch hat, bevor ihre Obergrenze erreicht ist. Der Wert wird so berechnet: highWaterMark der readableStrategy minus die Gesamtgröße aller Chunks, die schon eingereiht, aber noch nicht gelesen wurden. Wie groß ein einzelner Chunk zählt, bestimmt die Funktion size() der Strategie. Ohne eigene Strategie zählt jeder Chunk als 1.
Der Wert ist Teil des Rückstau-Mechanismus (Backpressure) der Streams-API. Ist desiredSize größer als 0, kann die Transformation weitere Daten liefern. Ist der Wert 0 oder negativ, ist die Warteschlange voll oder überfüllt. Der TransformStream hält dann neue Schreibvorgänge auf der beschreibbaren Seite an, bis ein Leser Daten abholt.
Nützlich ist die Eigenschaft vor allem, um Transformationen zu überwachen und Fehler zu suchen. Sie hilft auch bei Transformationen, die aus einem Eingabe-Chunk viele Ausgabe-Chunks machen, etwa beim Zerlegen oder Dekomprimieren. Dort erkennt man daran, ob der Verbraucher nicht mehr hinterherkommt. Wichtig: controller.enqueue() beachtet den Rückstau nicht selbst. Es reiht immer ein, auch wenn desiredSize negativ ist.
Mögliche Werte:
- positive Zahl: Es ist noch Platz frei.
0oder negativ: Die Warteschlange ist voll bzw. überfüllt. Außerdem ist der Wert0, wenn die lesbare Seite geschlossen ist.null: Der Stream ist fehlerhaft, zum Beispiel nachcontroller.error().
Rückgabewert
readableStrategy (Chunks oder Bytes). Der Wert kann negativ sein. Ist der Stream geschlossen, ist er 0; ist der Stream fehlerhaft, ist er null.Beispiele
Freien Platz vor und nach enqueue() beobachten
// Die lesbare Seite darf bis zu 3 Chunks puffern
const ts = new TransformStream({
transform(chunk, controller) {
const vorher = controller.desiredSize;
controller.enqueue(chunk.toUpperCase());
console.log(`${chunk}: vorher ${vorher}, nachher ${controller.desiredSize}`);
}
}, undefined, { highWaterMark: 3 });
const writer = ts.writable.getWriter();
// Kein Leser aktiv: die Chunks bleiben in der Warteschlange
await writer.write('a');
await writer.write('b');
await writer.write('c');Byte-basierte Strategie: desiredSize wird negativ
const ts = new TransformStream({
transform(chunk, controller) {
controller.enqueue(chunk);
const frei = controller.desiredSize;
if (frei <= 0) {
console.warn(`Rückstau! Überlauf: ${-frei} Bytes`);
} else {
console.log(`Noch ${frei} Bytes frei`);
}
}
}, undefined, new ByteLengthQueuingStrategy({ highWaterMark: 16 }));
const writer = ts.writable.getWriter();
await writer.write(new Uint8Array(10));
await writer.write(new Uint8Array(10));null nach einem Fehler
const ts = new TransformStream({
transform(chunk, controller) {
if (typeof chunk !== 'string') {
controller.error(new TypeError('Nur Strings erlaubt'));
console.log('desiredSize nach error():', controller.desiredSize);
return;
}
controller.enqueue(chunk);
}
});
const writer = ts.writable.getWriter();
try {
await writer.write(42);
} catch (err) {
console.log('Schreiben fehlgeschlagen:', err.message);
}