fs/promises в Node.js: работа с файлами через async/await

fs/promises это версия модуля fs в Node на промисах. Его функции (readFile, writeFile, readdir, stat, mkdir, rm, rename и остальные) возвращают промис, а не принимают callback, поэтому вы ждёте их через await и ловите ошибки через try/catch. Импортируйте его через require('fs/promises') или 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));

Программа выводит [ 'write docs', 'ship it' ]: каждый await ждёт одну операцию, прежде чем выполнится следующая строка, поэтому дописывание всегда происходит после первой записи. В ES-модуле await работает на верхнем уровне; в CommonJS оберните код в функцию async.

Функции, которые нужны чаще всего

Имена совпадают с API на callback'ах, только без callback'а. Две из них подробно разобраны на страницах readFile и writeFile.

Содержимое папки через readdir и stat

readdir возвращает только имена. Вызовите stat для каждого, чтобы узнать размер или отличить файлы от папок, или передайте { withFileTypes: true }, чтобы получить записи, которые уже знают свой тип.

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

Цикл выводит README.md 6 bytes, notes.txt 3 bytes и src folder. Для несуществующего пути stat отклоняется с ENOENT, поэтому он годится как быстрая проверка существования, когда заодно нужны подробности.

Переименование, перемещение и удаление

rename и переименовывает, и перемещает файл (в пределах одного диска). rm удаляет; для непустой папки ему нужен recursive: true, а force: true, чтобы не падать, если пути уже нет.

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

Файл переезжает из drafts в published под новым именем, а после rm в папке blog остаётся только published. Уберите force: true из второго rm, и он отклонится с ENOENT.

Ошибки через try/catch

Неудачная операция отклоняет свой промис. С await это отклонение становится исключением, которое ловится как любое другое. Поле code у ошибки говорит, что пошло не так.

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

Первый вызов не находит файла и возвращает []; второй выводит Ada. Коды, которые стоит знать: ENOENT (нет такого файла), EEXIST (уже существует), EISDIR (папка там, где ожидался файл), ENOTEMPTY (в папке ещё что-то есть) и EACCES (нет прав).

Промис, который вы не ждёте через await и не обрабатываете через .catch(), при ошибке становится необработанным отклонением, и Node завершается с ошибкой. Ждите каждый вызов или возвращайте его промис вызывающему коду, который его дождётся.

Чтение нескольких файлов сразу через Promise.all

Цикл for с await читает файлы один за другим. Когда чтения не зависят друг от друга, запустите их все и подождите один раз через Promise.all: диск будет работать над ними одновременно.

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 сохраняет порядок входного массива, поэтому результат будет [ 'alpha', 'beta', 'gamma' ], какое бы чтение ни закончилось первым, а длина склеенной строки равна 14. Замените в массиве 'b.txt' на 'x.txt', и весь await отклонится с ENOENT.

Если нужны все результаты, даже когда часть чтений не удалась, используйте Promise.allSettled; оба метода описаны на странице про промисы.

Частые ошибки

Путаница между двумя модулями. require('fs').readFile ждёт callback; require('fs/promises').readFile возвращает промис. Вызов версии на callback'ах без callback'а выбрасывает The "cb" argument must be of type function.

Забытый await. const text = fs.readFile(...) это промис в ожидании, и text.split выбрасывает text.split is not a function.

Параллельная запись в один файл. Promise.all с несколькими записями в один путь может оставить перемешанное содержимое. Выполняйте их последовательно.