Node.js fs/promises: Dateisystem-API mit async/await

fs/promises ist die Promise-basierte Variante des fs-Moduls von Node. Seine Funktionen (readFile, writeFile, readdir, stat, mkdir, rm, rename und die übrigen) geben ein Promise zurück, statt einen Callback zu nehmen, du wartest also mit await auf sie und fängst Fehler mit try/catch. Importier es mit require('fs/promises') oder import fs from 'fs/promises'.

import fs from 'fs/promises';

await fs.writeFile('todo.txt', 'write docs\n');
await fs.appendFile('todo.txt', 'ship it\n');

const text = await fs.readFile('todo.txt', 'utf8');
console.log(text.split('\n').filter(Boolean));

Es gibt [ 'write docs', 'ship it' ] aus: Jedes await wartet auf eine Operation, bevor die nächste Zeile läuft, das Anhängen passiert also immer nach dem ersten Schreiben. In einem ES-Modul funktioniert await auf oberster Ebene; in CommonJS packst du den Code in eine async-Funktion.

Die Funktionen, die du am häufigsten brauchst

Die Namen entsprechen der Callback-API, nur ohne Callback. Die Seiten zu readFile und writeFile behandeln diese beiden im Detail.

Einen Ordner mit readdir und stat auflisten

readdir gibt nur Namen zurück. Ruf für jeden stat auf, um seine Größe zu bekommen oder Dateien von Ordnern zu unterscheiden, oder übergib { withFileTypes: true }, um Einträge zu bekommen, die ihren Typ schon kennen.

import fs from 'fs/promises';

// Setup: a folder with two files and a subfolder
await fs.mkdir('project/src', { recursive: true });
await fs.writeFile('project/README.md', '# Demo');
await fs.writeFile('project/notes.txt', 'abc');

const names = await fs.readdir('project');
console.log(names);

for (const name of names) {
    const info = await fs.stat('project/' + name);
    console.log(name, info.isDirectory() ? 'folder' : info.size + ' bytes');
}

const entries = await fs.readdir('project', { withFileTypes: true });
console.log(entries.filter((e) => e.isFile()).map((e) => e.name));

Die Schleife gibt README.md 6 bytes, notes.txt 3 bytes und src folder aus. stat wird für einen Pfad, der nicht existiert, mit ENOENT abgelehnt und ist damit eine schnelle Existenzprüfung, wenn du auch die Details willst.

Umbenennen, verschieben und löschen

rename benennt eine Datei um und verschiebt sie auch (innerhalb desselben Laufwerks). rm löscht; für einen Ordner mit Inhalt braucht es recursive: true und force: true, damit es nicht fehlschlägt, wenn der Pfad schon weg ist.

import fs from 'fs/promises';

// Setup
await fs.mkdir('blog/drafts', { recursive: true });
await fs.writeFile('blog/drafts/post.md', 'hello');

await fs.mkdir('blog/published', { recursive: true });
await fs.rename('blog/drafts/post.md', 'blog/published/first-post.md');
console.log(await fs.readdir('blog/drafts'), await fs.readdir('blog/published'));

await fs.rm('blog/drafts', { recursive: true });
await fs.rm('blog/drafts', { recursive: true, force: true }); // already gone: no error
console.log(await fs.readdir('blog'));

Die Datei wandert unter ihrem neuen Namen von drafts nach published, und nach rm listet der Ordner blog nur noch published. Entferne force: true aus dem zweiten rm, und es wird mit ENOENT abgelehnt.

Fehler mit try/catch behandeln

Eine fehlgeschlagene Operation lehnt ihr Promise ab. Mit await wird diese Ablehnung zu einer Exception, die du wie jede andere fängst. Der code des Fehlers sagt dir, was schiefging.

import fs from 'fs/promises';

async function loadUsers() {
    try {
        const text = await fs.readFile('users.json', 'utf8');
        return JSON.parse(text);
    } catch (err) {
        if (err.code === 'ENOENT') return [];
        throw err;
    }
}

console.log(await loadUsers());

// Setup: create the file, then load again
await fs.writeFile('users.json', '[{"name":"Ada"}]');
console.log((await loadUsers())[0].name);

Der erste Aufruf findet keine Datei und gibt [] zurück; der zweite gibt Ada aus. Codes, die du kennen solltest: ENOENT (Datei existiert nicht), EEXIST (existiert schon), EISDIR (ein Ordner, wo eine Datei erwartet wurde), ENOTEMPTY (ein Ordner hat noch Inhalt) und EACCES (keine Berechtigung).

Ein Promise, auf das du weder mit await wartest noch .catch() anhängst, wird bei einem Fehler zu einer unbehandelten Ablehnung, und Node beendet sich mit einem Fehler. Warte auf jeden Aufruf oder gib sein Promise an einen Aufrufer zurück, der das tut.

Mehrere Dateien gleichzeitig mit Promise.all lesen

Eine for-Schleife mit await liest Dateien nacheinander. Wenn die Lesevorgänge nicht voneinander abhängen, starte alle und warte einmal mit Promise.all: Die Festplatte arbeitet gleichzeitig daran.

import fs from 'fs/promises';

// Setup: three small files
await fs.writeFile('a.txt', 'alpha');
await fs.writeFile('b.txt', 'beta');
await fs.writeFile('c.txt', 'gamma');

const files = ['a.txt', 'b.txt', 'c.txt'];
const contents = await Promise.all(files.map((f) => fs.readFile(f, 'utf8')));

console.log(contents);
console.log(contents.join('').length);

Promise.all behält die Reihenfolge des Eingabe-Arrays bei, das Ergebnis ist also [ 'alpha', 'beta', 'gamma' ], egal welcher Lesevorgang zuerst fertig war, und die zusammengefügte Länge ist 14. Benenn 'b.txt' im Array in 'x.txt' um, und das ganze await wird mit ENOENT abgelehnt.

Wenn du jedes Ergebnis brauchst, auch wenn manche Lesevorgänge fehlschlagen, nimm Promise.allSettled; die Seite zu Promises behandelt beide.

Häufige Fehler

Die beiden Module verwechseln. require('fs').readFile will einen Callback; require('fs/promises').readFile gibt ein Promise zurück. Die Callback-Variante ohne Callback aufzurufen, wirft The "cb" argument must be of type function.

await vergessen. const text = fs.readFile(...) ist ein ausstehendes Promise, und text.split wirft text.split is not a function.

Parallele Schreibvorgänge in dieselbe Datei. Promise.all mit mehreren Schreibvorgängen auf denselben Pfad kann vermischten Inhalt hinterlassen. Führ diese nacheinander aus.