WritableStream.close() — Methode · JavaScript-Referenz

Signatur

WritableStream.prototype.close()

Beschreibung

Die Methode close() beendet einen WritableStream ordnungsgemäß. Der Stream nimmt danach keine weiteren Chunks mehr an. Alle Chunks, die schon in der Warteschlange stehen, werden zuerst noch an die zugrunde liegende Senke (underlying sink) übergeben. Erst danach ruft der Stream die close()-Methode der Senke auf, falls sie eine hat.

Man verwendet stream.close(), wenn man direkt auf den Stream zugreift und gerade kein Writer den Stream sperrt. Das ist zum Beispiel der Fall, nachdem man mit writer.releaseLock() die Sperre wieder freigegeben hat. Ist der Stream gesperrt (stream.locked === true), muss man stattdessen WritableStreamDefaultWriter.close() auf dem aktiven Writer aufrufen.

Anders als abort() verwirft close() keine Daten. Die Methode ist also der „saubere“ Weg, einen Stream zu beenden. Das zurückgegebene Promise wird erst erfüllt, wenn alle Daten geschrieben sind und die Senke fertig geschlossen ist. Sollen zum Beispiel Dateien oder Netzwerkverbindungen sauber abgeschlossen werden, lohnt es sich deshalb, das Promise mit await abzuwarten.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald alle Chunks verarbeitet sind und die Senke geschlossen ist. Es wird mit einem TypeError abgelehnt, wenn der Stream gesperrt ist, schon geschlossen ist oder gerade geschlossen wird. Befindet sich der Stream in einem Fehlerzustand oder schlägt das Schließen der Senke fehl, wird es mit dem entsprechenden Fehler abgelehnt.

Beispiele

Stream nach dem Schreiben direkt schließen

// als ES-Modul ausführen (Top-Level-await)
const chunks = [];

const stream = new WritableStream({
  write(chunk) {
    chunks.push(chunk);
  },
  close() {
    console.log('Senke geschlossen:', chunks.join(' '));
  }
});

const writer = stream.getWriter();
await writer.write('Hallo');
await writer.write('Welt');

// Sperre freigeben, sonst schlägt stream.close() fehl
writer.releaseLock();

await stream.close();
console.log('Stream geschlossen');

Senke geschlossen: Hallo Welt Stream geschlossen

Fehler bei gesperrtem Stream – stattdessen writer.close() verwenden

const stream = new WritableStream({
  write(chunk) { console.log('Empfangen:', chunk); }
});

const writer = stream.getWriter();
console.log('gesperrt:', stream.locked);

try {
  await stream.close();
} catch (err) {
  console.log('Fehler:', err.name);
}

// Richtig: über den aktiven Writer schließen
await writer.write('letzter Chunk');
await writer.close();
console.log('über Writer geschlossen');

gesperrt: true Fehler: TypeError Empfangen: letzter Chunk über Writer geschlossen

Asynchrones Aufräumen der Senke abwarten

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

const logStream = new WritableStream({
  async write(line) {
    await sleep(50); // simuliert langsames Schreiben
    console.log('geschrieben:', line);
  },
  async close() {
    await sleep(100); // z. B. Puffer leeren, Verbindung trennen
    console.log('Ressourcen freigegeben');
  }
});

const writer = logStream.getWriter();
writer.write('Zeile 1');
writer.write('Zeile 2');
await writer.ready;
writer.releaseLock();

// close() wartet, bis beide Zeilen und das Aufräumen fertig sind
await logStream.close();
console.log('alles erledigt');

geschrieben: Zeile 1 geschrieben: Zeile 2 Ressourcen freigegeben alles erledigt

// Wichtig · Fallstricke

Gesperrter Stream: Solange ein Writer aktiv ist (stream.locked === true), lehnt stream.close() sofort mit einem TypeError ab. Dann muss man writer.close() verwenden oder vorher writer.releaseLock() aufrufen.
Doppeltes Schließen: Ruft man close() auf einem Stream auf, der schon geschlossen ist oder gerade geschlossen wird, gibt es ebenfalls einen TypeError. Nach close() sind auch keine weiteren write()-Aufrufe mehr möglich.
close() und abort(): close() schreibt alle Daten in der Warteschlange fertig. abort() dagegen verwirft sie und versetzt den Stream in einen Fehlerzustand.
Promise nicht ignorieren: Fehler aus der close()-Methode der Senke kommen nur über das zurückgegebene Promise an. Deshalb immer await oder .catch() verwenden, sonst bleiben Fehler unbemerkt (unhandled rejection).
Kompatibilität: Wird von allen modernen Browsern unterstützt (Chrome/Edge 81+, Safari 14.1+, Firefox 100+). In Node.js ist die Methode ab Version 18 global verfügbar, ab 16.5 über stream/web.

Siehe auch

WritableStream.abort() WritableStream.getWriter() WebSocketStream.close() MediaStream.clone() ReadableStream.cancel()