Signatur
Beschreibung
Die Eigenschaft fatal zeigt, in welchem Fehlermodus ein TextDecoderStream arbeitet. Festgelegt wird der Wert einmalig beim Erzeugen über die Option fatal im Konstruktor new TextDecoderStream(label, { fatal }). Wird die Option weggelassen, ist der Wert false.
Bei false (Ersetzungsmodus) setzt der Decoder für jede ungültige Byte-Folge das Ersatzzeichen U+FFFD (�) ein und dekodiert weiter. Bei true (fataler Modus) bricht der Decoder bei der ersten ungültigen Folge mit einem TypeError ab. Dadurch geht der Stream in den Fehlerzustand über: sowohl die lesbare als auch die beschreibbare Seite gelten dann als fehlerhaft, und ein laufendes pipeThrough() bzw. reader.read() wird mit diesem Fehler abgelehnt.
Die Eigenschaft ist nützlich, wenn eine Bibliothek einen fremden Decoder-Stream bekommt und prüfen will, ob damit strikt validiert wird. Das ist zum Beispiel bei Protokollen, Prüfsummen oder beim Import von Nutzerdaten wichtig, bei denen stillschweigend ersetzte Zeichen zu Datenverfälschung führen würden.
Rückgabewert
true, wenn der Decoder im fatalen Fehlermodus arbeitet (ungültige Bytes lösen einen TypeError aus), sonst false (ungültige Bytes werden durch U+FFFD ersetzt).Beispiele
Fehlermodus abfragen
const lenient = new TextDecoderStream();
const strict = new TextDecoderStream('utf-8', { fatal: true });
console.log(lenient.fatal);
console.log(strict.fatal);Strikte UTF-8-Validierung beim Laden einer Datei
const loadStrictText = async (url) => {
const response = await fetch(url);
const decoder = new TextDecoderStream('utf-8', { fatal: true });
const reader = response.body.pipeThrough(decoder).getReader();
let text = '';
try {
while (true) {
const { value, done } = await reader.read();
if (done) break;
text += value;
}
return text;
} catch (err) {
// Bei fatal === true landet ungültiges UTF-8 hier
console.error(`Ungültige Kodierung (fatal=${decoder.fatal}):`, err.name);
throw err;
}
};
loadStrictText('/daten/import.csv').catch(() => {});Ersetzungsmodus und fataler Modus im Vergleich
const invalidBytes = new Uint8Array([0x48, 0x69, 0xff, 0x21]); // "Hi", ungültiges Byte, "!"
const decodeWith = async (fatal) => {
const decoder = new TextDecoderStream('utf-8', { fatal });
const source = new ReadableStream({
start(controller) {
controller.enqueue(invalidBytes);
controller.close();
}
});
try {
let result = '';
for await (const chunk of source.pipeThrough(decoder)) result += chunk;
return `fatal=${decoder.fatal}: ${result}`;
} catch (err) {
return `fatal=${decoder.fatal}: ${err.name}`;
}
};
console.log(await decodeWith(false));
console.log(await decodeWith(true));// Wichtig · Fallstricke
- Schreibgeschützt: Eine Zuweisung wie
decoder.fatal = truehat keine Wirkung (im Strict Mode gibt es einenTypeError). Der Modus lässt sich nur über den Konstruktor festlegen. - Stream ist danach unbrauchbar: Im fatalen Modus bleibt der gesamte Stream nach dem ersten Dekodierfehler im Fehlerzustand. Er lässt sich nicht fortsetzen. Für einen neuen Versuch braucht es eine neue Instanz.
- Späte Fehler: Eine unvollständige Mehrbyte-Folge am Ende des Streams wird erst beim Schließen (Flush) erkannt. Der Fehler kommt dann ganz am Schluss, nicht schon beim betroffenen Chunk.
- Sicherheit: Der Ersetzungsmodus (
false) kann manipulierte oder beschädigte Daten verschleiern. Bei Validierung, Signaturprüfung oder Parsern solltefatal: truegesetzt werden. - Kompatibilität:
TextDecoderStreamist erst seit Firefox 105 (2022) in allen großen Browsern verfügbar. Vor dem Einsatz bei Bedarf mit'TextDecoderStream' in globalThisprüfen.