TextDecoderStream.writable — Eigenschaft · JavaScript-Referenz

Signatur

TextDecoderStream.writable

Beschreibung

Die schreibgeschützte Eigenschaft writable eines TextDecoderStream ist die Eingabeseite des Transform-Streams. In diesen WritableStream schreibt man Binärdaten als ArrayBuffer, TypedArray (z. B. Uint8Array) oder DataView. Der Stream dekodiert sie in der beim Konstruktor angegebenen Kodierung (Standard: utf-8) und gibt die Zeichenketten über readable aus.

Meist greift man nicht direkt auf writable zu, sondern verbindet einen Byte-Stream per pipeThrough() mit dem ganzen TextDecoderStream – dabei wird intern genau diese Eigenschaft genutzt. Direkt verwendet man writable, wenn Daten manuell über einen WritableStreamDefaultWriter eingespeist werden sollen, etwa aus WebSocket-Nachrichten, einem Serial-Port oder selbst erzeugten Puffern.

Der große Vorteil gegenüber einem einfachen TextDecoder: Mehrbyte-Zeichen, die über Chunk-Grenzen hinweg geteilt sind, werden korrekt zusammengesetzt. Erst beim Schließen des Writers (close()) werden verbleibende, unvollständige Bytes verarbeitet – je nach fatal-Option als Ersatzzeichen U+FFFD oder als Fehler.

Rückgabewert

Typ

WritableStream<BufferSource>

Beschreibung

Der WritableStream, der Binär-Chunks entgegennimmt. Es wird bei jedem Zugriff dieselbe Instanz zurückgegeben.

Beispiele

Manuell Bytes schreiben und Text lesen

const decoder = new TextDecoderStream('utf-8');
const writer = decoder.writable.getWriter();
const reader = decoder.readable.getReader();

// „Grüße“ in UTF-8, das „ü“ (0xC3 0xBC) ist auf zwei Chunks verteilt
writer.write(new Uint8Array([0x47, 0x72, 0xC3]));
writer.write(new Uint8Array([0xBC, 0xC3, 0x9F, 0x65]));
writer.close();

let text = '';
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  text += value;
}
console.log(text);

Grüße

Fetch-Antwort per pipeTo in writable leiten

const decoder = new TextDecoderStream();

// Bytes explizit in die writable-Seite pumpen
const response = await fetch('/daten.txt');
const pipePromise = response.body.pipeTo(decoder.writable);

for await (const chunk of decoder.readable) {
  console.log('Textstück:', chunk.length, 'Zeichen');
}
await pipePromise;

Textstück: 65536 Zeichen Textstück: 1234 Zeichen

Serial-Port-Daten dekodieren (Web Serial API)

const port = await navigator.serial.requestPort();
await port.open({ baudRate: 9600 });

const decoder = new TextDecoderStream();
// Port-Bytes fließen in decoder.writable
const closed = port.readable.pipeTo(decoder.writable);
const reader = decoder.readable.getReader();

const { value } = await reader.read();
console.log('Empfangen:', value);

Empfangen: OK\r\n

Sperrstatus prüfen

const decoder = new TextDecoderStream();
console.log(decoder.writable.locked);
const writer = decoder.writable.getWriter();
console.log(decoder.writable.locked);
writer.releaseLock();
console.log(decoder.writable.locked);

false true false

// Wichtig · Fallstricke

Keine Strings schreiben: writer.write('text') führt zu einem TypeError und versetzt den Stream in den Fehlerzustand. Erlaubt sind nur ArrayBuffer, TypedArray und DataView.
SharedArrayBuffer: Chunks, die auf einem SharedArrayBuffer basieren, werden abgelehnt – vorher in einen normalen Puffer kopieren.
Sperre: Solange ein Writer aktiv ist oder ein pipeTo() läuft, ist writable.locked true; ein zweites getWriter() wirft einen Fehler.
Schließen nicht vergessen: Ohne writer.close() endet readable nie, und am Ende abgeschnittene Mehrbyte-Sequenzen werden nicht ausgegeben.
Backpressure: Bei großen Datenmengen await writer.ready vor jedem write() beachten; lesen Sie readable nicht aus, staut sich der Puffer.
Fehlerverhalten: Mit { fatal: true } führen ungültige Bytes zu einem Abbruch beider Seiten mit TypeError.
Kompatibilität: Firefox unterstützt TextDecoderStream erst ab Version 105; in Node.js ist es seit 18 global verfügbar (vorher über stream/web).

Siehe auch

DecompressionStream.readable TextDecoderStream.readable TextDecoderStream.fatal TextDecoderStream.encoding TextDecoderStream.ignoreBOM