Abschnitt 7 · Lektion 5
Streams verbinden
Ein Protokoll soll Zeile für Zeile in ein anderes Format und das Ergebnis in eine neue Datei. Das
sind drei Streams. Einer liest, einer formt um, einer schreibt, und jeder davon kann scheitern. Wer
sie von Hand aneinanderhängt, muss an jedem einzelnen auf Fehler hören und selbst herausfinden, wann
alles durch ist. pipeline nimmt einem beides ab.
import { writeFileSync, createReadStream, createWriteStream, readFileSync } from "node:fs";
import { Transform } from "node:stream";
import { pipeline } from "node:stream/promises";
writeFileSync("quelle.txt", "erste zeile\nzweite zeile\n");
const grossschreiben = new Transform({
transform(stueck, kodierung, weiter) {
weiter(null, stueck.toString("utf8").toUpperCase());
},
});
await pipeline(
createReadStream("quelle.txt", { encoding: "utf8" }),
grossschreiben,
createWriteStream("ziel.txt"),
);
console.log(readFileSync("ziel.txt", "utf8").trim()); Aus den zwei kleingeschriebenen Zeilen in quelle.txt wird eine ziel.txt mit ERSTE ZEILE und
ZWEITE ZEILE. Keine der drei Stufen weiß dabei von den anderen.
pipeline aus node:stream/promises nimmt beliebig viele Streams entgegen. Zuerst einen lesbaren,
dann null oder mehr Transform-Streams, zuletzt einen schreibbaren. Es verbindet sie, wartet, bis
alles durch ist, und gibt dir ein Promise zurück, das du mit await abholst.
Ein Transform bekommt in seiner kleinsten Form eine Funktion transform mit drei Parametern. Das
sind das Stück, seine Kodierung und ein weiter, das du aufrufst, wenn du fertig bist. Der erste
Parameter von weiter ist ein Fehler, der zweite das Ergebnis. Fehler zuerst also, wie bei den
Callbacks in Abschnitt 6.
Warum nicht .pipe()
In älterem Code steht oft .pipe(). Das funktioniert und ist kürzer. Es hat aber ein Problem, das
man erst im Fehlerfall sieht.
import { writeFileSync, createReadStream, createWriteStream } from "node:fs";
import { Transform } from "node:stream";
import { pipeline } from "node:stream/promises";
writeFileSync("quelle.txt", "erste zeile\n");
const kaputt = new Transform({
transform(stueck, kodierung, weiter) {
weiter(new Error("Umformung fehlgeschlagen"));
},
});
const ziel = createWriteStream("ziel.txt");
try {
await pipeline(createReadStream("quelle.txt"), kaputt, ziel);
} catch (fehler) {
console.log(`abgebrochen: ${fehler.message}`);
}
console.log(`Ziel aufgeräumt: ${ziel.destroyed}`); Der Transform-Stream scheitert. pipeline wirft, du fängst es, und der schreibbare Stream ist
danach geschlossen, samt Dateihandle. Die Datei ziel.txt liegt trotzdem da, leer oder halb
geschrieben. Wegräumen musst du sie selbst.
import { writeFileSync, createReadStream, createWriteStream } from "node:fs";
import { Transform } from "node:stream";
writeFileSync("quelle.txt", "erste zeile\n");
const kaputt = new Transform({
transform(stueck, kodierung, weiter) {
weiter(new Error("Umformung fehlgeschlagen"));
},
});
const ziel = createWriteStream("ziel.txt");
createReadStream("quelle.txt").pipe(kaputt).pipe(ziel);
kaputt.on("error", (fehler) => {
console.log(`abgebrochen: ${fehler.message}`);
console.log(`Ziel aufgeräumt: ${ziel.destroyed}`);
}); Derselbe Fehler mit .pipe() statt pipeline, und der schreibbare Stream lebt weiter. Das
Dateihandle bleibt offen, bis der Prozess endet.
Bei einem Skript merkt das niemand. Auf einem Server, der das pro Anfrage macht, sammeln sich diese
Dateihandles. Irgendwann steht im Protokoll EMFILE: too many open files. Die Fehlersuche danach
ist eine der unangenehmeren, denn die Meldung taucht an einer ganz anderen Stelle auf als die
Ursache.
Dazu reicht .pipe() Fehler nicht weiter. Jeder Stream der Kette braucht sein eigenes
on("error", ...). Sonst beendet ein error ohne Listener den Prozess wie in Lektion 7.3.
Ich nehme deshalb überall pipeline, auch da, wo nichts schiefgehen kann.
Gegendruck
Der Empfänger ist oft langsamer als der Sender. Wenn du eine Datei von der SSD liest und über eine langsame Netzwerkverbindung schreibst, ist das der Normalfall.
Ein Stream regelt das selbst. Ist der Puffer des schreibbaren Streams voll, meldet er das, und der lesbare pausiert. Sobald wieder Platz ist, geht es weiter. Das nennt sich Gegendruck (englisch backpressure).
Wie das im Einzelnen funktioniert, ist gar nicht so wichtig. Wichtiger ist, was passiert, wenn man es selbst nachbaut und dabei vergisst. Dann läuft der Puffer voll, und der Speicherverbrauch steigt. Am Ende liegt doch wieder die ganze Datei im Arbeitsspeicher, also das, wovor der Stream dich bewahren sollte.
Wo dir das überall begegnet
Das Muster steckt an vielen Stellen, an denen man es nicht sofort vermutet.
Eine Datei komprimieren heißt createReadStream, createGzip aus node:zlib und
createWriteStream hintereinander. Ein Datei-Upload ist ein lesbarer Stream aus der Anfrage in
einen schreibbaren auf die Platte. Und die Antwort eines HTTP-Servers ist selbst ein schreibbarer
Stream, in den du eine große Datei direkt hineinleiten kannst, ohne sie vorher ganz in den Speicher
zu laden.
express.static in Abschnitt 9 erledigt das für dich, und zwar mit createReadStream.
Im Reiter Praxis bringt eine Kette aus drei Streams ein Protokoll in ein neues Format.
Zum Mitnehmen
pipeline verbindet einen lesbaren Stream über Transform-Streams mit einem schreibbaren und schließt bei einem Fehler alle. Mit .pipe() bleibt der schreibbare offen, den Gegendruck regeln beide von selbst.
Jetzt du
Basis Konto, kostenlosZu dieser Lektion gehört eine Aufgabe. Du schreibst den Code selbst, und nach jedem Lauf sagt dir eine Prüfliste, was schon stimmt.
Dafür brauchst du das Basis Konto. Es kostet nichts, und ein Passwort gibt es auch nicht.
In diesem Kurs läuft dein Code auf einem Server. Dafür hat das Basis Konto 1 Stunde im Monat, mehr Zeit gibt es mit dem Premium Konto.
Was in dieser Lektion steckt
-
Artikel mit 3 Beispielen zum Ausprobieren
Steht hier, ohne Konto lesbar.
-
Aufgabe, dein Code läuft auf einem Server
Öffnet sich mit dem Basis Konto.