CKTIS / JavaScript
WritableStream-Senke: start, write, close und abort
Vier optionale Methoden der Senke legen fest, wie ein beschreibbarer Stream sein Ziel vorbereitet, Datenblöcke schreibt, den Schreibvorgang abschließt oder nach einem Abbruch aufräumt.
Version: ECMAScript 2024 and the current web platform; runtime support varies
Syntax
new WritableStream()
new WritableStream(underlyingSink)
new WritableStream(underlyingSink, queuingStrategy)
// Optional methods on underlyingSink:
const underlyingSink = {
start(controller) { /* initialize the destination */ },
write(chunk, controller) { /* write one chunk */ },
close() { /* finalize successful output */ },
abort(reason) { /* clean up after an abort request */ },
};WritableStream gehört zur Web Streams API, nicht zu ECMAScript 2024; die Verfügbarkeit hängt von der Laufzeitumgebung ab. Das erste optionale Konstruktorargument underlyingSink ist ein Objekt mit Methoden, die der Stream aufruft. Das zweite optionale Argument queuingStrategy legt fest, wie die Warteschlangengröße für den Rückstau (Backpressure) gemessen wird.
start(controller) läuft einmal bei der Konstruktion. Eine synchrone Ausnahme lässt die Konstruktion fehlschlagen; ein abgelehntes Promise versetzt den angelegten Stream in den Fehlerzustand. Erst nach erfolgreicher Initialisierung gelangen Datenblöcke zur Senke. write(chunk, controller) verarbeitet jeweils einen Block in der Reihenfolge der Schreibanforderungen. Gib für den tatsächlichen asynchronen Schreibvorgang ein Promise zurück, damit der Stream darauf warten und Fehler weitergeben kann.
close() erhält keine Argumente. Nach einer Schließanforderung läuft die Methode erst, wenn alle angenommenen Schreibvorgänge erfolgreich waren. Leere hier die Puffer der Senke und gib Ressourcen frei. abort(reason) räumt nach einer Abbruchanforderung auf; der Grund kann ein beliebiger JavaScript-Wert sein. Noch nicht begonnene Schreibvorgänge werden abgelehnt, laufende aber nicht automatisch gestoppt und abgeschlossene nicht rückgängig gemacht. Beide Methoden können Promises zurückgeben; abort wird nicht bei jedem Fehler oder nach dem Schließen aufgerufen.
start und write erhalten denselben WritableStreamDefaultController. Mit controller.signal kann ein laufender Vorgang auf eine Abbruchanforderung reagieren, sofern er Abbruch unterstützt. controller.error(error) meldet einen Streamfehler; das ist keine Abbruchanforderung und ersetzt die Aufräumarbeiten nicht.
Der Produzent ruft getWriter() auf und sperrt den Stream damit für genau einen Writer. Behandle die Promises von writer.write(), writer.close() und writer.abort(); direkte Aufrufe von stream.close() und stream.abort() liefern bei gesperrtem Stream abgelehnte Promises. writer.releaseLock() hebt die Sperre auf, ohne den Stream zu beenden.
Beispiele
(async () => {
const log = [];
const reason = new Error("stop");
async function run(label, shouldAbort) {
const stream = new WritableStream({
start() {
log.push(`${label}: start`);
},
async write(chunk) {
await Promise.resolve();
log.push(`${label}: write ${chunk}`);
},
close() {
log.push(`${label}: close`);
},
abort(received) {
log.push(`${label}: abort (${received === reason})`);
},
});
const writer = stream.getWriter();
try {
await writer.write("A");
if (shouldAbort) {
await writer.abort(reason);
} else {
await writer.close();
}
} finally {
writer.releaseLock();
}
}
await run("normal", false);
await run("interrupted", true);
console.log(log.join("\n"));
})().catch(console.error);Ergebnis
normal: start normal: write A normal: close interrupted: start interrupted: write A interrupted: abort (true)
Das Beispiel verwendet zwei separate Streams. Beide schreiben `A` vollständig; der erste wird geschlossen, der zweite abgebrochen. `true` zeigt, dass die Senke genau dasselbe `Error`-Objekt erhalten hat.
Zugehörige Lektionen
- JavaScript · Lektion 4 · Fortgeschritten · Version: 4
Quellen
- WritableStream: WritableStream() constructor
- WritableStreamDefaultWriter
- WritableStreamDefaultWriter: close() method
- WritableStream: close() method
- WritableStream: abort() method
- WritableStreamDefaultController: signal property
- WritableStreamDefaultController: error() method
- WHATWG Streams Standard — The underlying sink API