new WritableStreamDefaultWriter() — Methode · JavaScript-Referenz

Signatur

new WritableStreamDefaultWriter(stream)

Beschreibung

Der Konstruktor new WritableStreamDefaultWriter(stream) erzeugt einen Writer für einen WritableStream. Dabei wird der Stream gesperrt (stream.locked === true): Solange der Writer aktiv ist, kann kein anderer Writer auf denselben Stream schreiben. So bleiben Reihenfolge und Konsistenz der geschriebenen Chunks gewährleistet.

In der Praxis ruft man den Konstruktor selten direkt auf. Üblich ist stream.getWriter(), das intern genau diesen Konstruktor verwendet und dasselbe Ergebnis liefert. Der direkte Aufruf ist gleichwertig und kann für mehr Lesbarkeit sorgen oder beim Schreiben eigener Hilfsbibliotheken nützlich sein.

Über den Writer schreibt man mit write(), beendet den Stream sauber mit close(), bricht mit abort() ab und gibt die Sperre mit releaseLock() wieder frei. Für Gegendruck (Backpressure) sorgen die Eigenschaften ready (Promise) und desiredSize.

Parameter

Name	Typ	Default	Beschreibung
$stream Pflicht	WritableStream		Der `WritableStream`, in den geschrieben werden soll. Er darf noch nicht gesperrt sein.

Rückgabewert

Typ

WritableStreamDefaultWriter

Beschreibung

Eine neue Writer-Instanz, die den übergebenen Stream exklusiv sperrt.

Beispiele

Writer direkt per Konstruktor erzeugen

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

const writer = new WritableStreamDefaultWriter(stream);
console.log('Gesperrt:', stream.locked);

await writer.write('Hallo');
await writer.write('Welt');
await writer.close();

Gesperrt: true Empfangen: Hallo Empfangen: Welt Stream geschlossen

Backpressure beachten mit writer.ready

const stream = new WritableStream(
  {
    async write(chunk) {
      // langsame Senke simulieren
      await new Promise((r) => setTimeout(r, 100));
      console.log('Geschrieben:', chunk);
    }
  },
  new CountQueuingStrategy({ highWaterMark: 2 })
);

const writer = new WritableStreamDefaultWriter(stream);

for (const zeile of ['a', 'b', 'c', 'd']) {
  await writer.ready; // warten, bis die Warteschlange wieder Platz hat
  writer.write(zeile);
}
await writer.close();

Geschrieben: a Geschrieben: b Geschrieben: c Geschrieben: d

Text als Bytes schreiben und Sperre freigeben

const chunks = [];
const stream = new WritableStream({
  write(chunk) { chunks.push(chunk); }
});

const writer = new WritableStreamDefaultWriter(stream);
const encoder = new TextEncoder();

await writer.write(encoder.encode('Log-Eintrag 1'));
writer.releaseLock();

console.log('Gesperrt nach releaseLock:', stream.locked);

// Ein neuer Writer kann nun übernehmen
const writer2 = stream.getWriter();
await writer2.write(encoder.encode('Log-Eintrag 2'));
await writer2.close();
console.log('Anzahl Chunks:', chunks.length);

Gesperrt nach releaseLock: false Anzahl Chunks: 2

Fehler bei bereits gesperrtem Stream

const stream = new WritableStream();
const ersterWriter = stream.getWriter();

try {
  new WritableStreamDefaultWriter(stream);
} catch (err) {
  console.log(err.name);
}

TypeError

// Wichtig · Fallstricke

TypeError: Wird geworfen, wenn stream kein WritableStream ist oder bereits gesperrt ist (stream.locked === true).
Ohne Aufruf von releaseLock() bleibt der Stream dauerhaft gesperrt – auch pipeTo() auf diesen Stream schlägt dann fehl.
Ein nicht abgewartetes write() kann abgelehnt werden (z. B. bei Fehlern in der Senke); unbehandelte Rejections vermeiden, indem man await nutzt oder writer.closed überwacht.
releaseLock() während ausstehender Schreibvorgänge lässt diese Promises mit einem TypeError ablehnen.
Kompatibilität: In Chrome, Edge, Firefox (ab 100) und Safari verfügbar; in Node.js global ab Version 18, davor über require('node:stream/web'). Beispiele mit Top-Level-await benötigen ein ES-Modul oder eine async-Funktion.

Siehe auch

WritableStreamDefaultWriter WritableStream WritableStream.prototype.getWriter() WritableStreamDefaultWriter.prototype.write() WritableStreamDefaultWriter.prototype.close() WritableStreamDefaultWriter.prototype.releaseLock() WritableStreamDefaultWriter.ready ReadableStreamDefaultReader