fs/promises w Node.js: system plików z async/await

fs/promises to wersja modułu fs w Node oparta na promise. Jego funkcje (readFile, writeFile, readdir, stat, mkdir, rm, rename i pozostałe) zwracają promise zamiast przyjmować callback, więc czekasz na nie przez await, a błędy łapiesz przez try/catch. Zaimportuj go przez require('fs/promises') albo 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));

Wypisuje [ 'write docs', 'ship it' ]: każde await czeka na jedną operację, zanim wykona się następna linia, więc dopisanie zawsze następuje po pierwszym zapisie. W module ES await działa na najwyższym poziomie; w CommonJS opakuj kod w funkcję async.

Funkcje, których będziesz używać najczęściej

Nazwy są takie jak w API z callbackami, tylko bez callbacku. Strony o readFile i writeFile opisują te dwie dokładnie.

Listowanie folderu przez readdir i stat

readdir zwraca tylko nazwy. Wywołaj stat dla każdej, żeby poznać rozmiar albo odróżnić pliki od folderów, albo przekaż { withFileTypes: true }, żeby dostać wpisy, które już znają swój typ.

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));

Pętla wypisuje README.md 6 bytes, notes.txt 3 bytes i src folder. stat odrzuca z ENOENT dla ścieżki, która nie istnieje, więc to szybkie sprawdzenie istnienia, gdy chcesz też poznać szczegóły.

Zmiana nazwy, przenoszenie i usuwanie

rename zarówno zmienia nazwę, jak i przenosi plik (w obrębie tego samego dysku). rm usuwa; dla folderu z zawartością potrzebuje recursive: true, a force: true, żeby nie zawieść, gdy ścieżki już nie ma.

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'));

Plik przenosi się z drafts do published pod nową nazwą, a po rm folder blog zawiera tylko published. Usuń force: true z drugiego rm, a odrzuci z ENOENT.

Obsługa błędów przez try/catch

Nieudana operacja odrzuca swój promise. Z await to odrzucenie staje się wyjątkiem, który łapiesz jak każdy inny. code błędu mówi, co poszło nie tak.

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);

Pierwsze wywołanie nie znajduje pliku i zwraca []; drugie wypisuje Ada. Kody, które warto znać: ENOENT (nie ma takiego pliku), EEXIST (już istnieje), EISDIR (folder tam, gdzie oczekiwano pliku), ENOTEMPTY (folder nadal ma zawartość) i EACCES (brak uprawnień).

Promise, na który nie czekasz przez await i nie dodasz .catch(), przy błędzie staje się nieobsłużonym odrzuceniem, a Node kończy działanie z błędem. Czekaj na każde wywołanie albo zwracaj jego promise do kodu, który to robi.

Czytanie kilku plików naraz przez Promise.all

Pętla for z await czyta pliki jeden po drugim. Gdy odczyty od siebie nie zależą, uruchom wszystkie i poczekaj raz przez Promise.all: dysk pracuje nad nimi równocześnie.

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 zachowuje kolejność tablicy wejściowej, więc wynik to [ 'alpha', 'beta', 'gamma' ] niezależnie od tego, który odczyt skończył się pierwszy, a łączna długość to 14. Zmień w tablicy 'b.txt' na 'x.txt', a całe await odrzuci z ENOENT.

Jeśli potrzebujesz każdego wyniku, nawet gdy niektóre odczyty się nie udadzą, użyj Promise.allSettled; strona o promise opisuje oba.

Częste błędy

Mylenie dwóch modułów. require('fs').readFile oczekuje callbacku; require('fs/promises').readFile zwraca promise. Wywołanie wersji z callbackiem bez callbacku rzuca The "cb" argument must be of type function.

Zapominanie o await. const text = fs.readFile(...) to oczekujący promise, a text.split rzuca text.split is not a function.

Równoległe zapisy do jednego pliku. Promise.all z kilkoma zapisami do tej samej ścieżki może zostawić wymieszaną zawartość. Wykonuj je po kolei.