fs/promises no Node.js: arquivos com async/await

fs/promises é a versão baseada em promises do módulo fs do Node. As funções dele (readFile, writeFile, readdir, stat, mkdir, rm, rename e as demais) retornam uma promise em vez de receber um callback, então você dá await nelas e trata erros com try/catch. Importe com require('fs/promises') ou 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));

Ele imprime [ 'write docs', 'ship it' ]: cada await espera uma operação antes de a próxima linha rodar, então o append sempre acontece depois da primeira escrita. Em um ES module o await funciona no nível superior; em CommonJS, coloque o código dentro de uma função async.

As funções que você mais vai usar

Os nomes são os mesmos da API de callbacks, sem o callback. As páginas de readFile e writeFile cobrem essas duas em detalhe.

Listar uma pasta com readdir e stat

readdir retorna só os nomes. Chame stat em cada um para pegar o tamanho ou diferenciar arquivos de pastas, ou passe { withFileTypes: true } para receber entradas que já sabem o próprio tipo.

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

O loop imprime README.md 6 bytes, notes.txt 3 bytes e src folder. stat rejeita com ENOENT para um caminho que não existe, o que faz dele uma verificação rápida de existência quando você também quer os detalhes.

Renomear, mover e apagar

rename tanto renomeia quanto move um arquivo (dentro do mesmo disco). rm apaga; ele precisa de recursive: true para uma pasta com conteúdo, e de force: true para não falhar quando o caminho já não existe.

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

O arquivo sai de drafts para published com o nome novo, e depois do rm a pasta blog lista só published. Tire o force: true do segundo rm e ele rejeita com ENOENT.

Tratar erros com try/catch

Uma operação que falha rejeita a promise. Com await, essa rejeição vira uma exceção que você captura como qualquer outra. O code do erro diz o que deu errado.

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

A primeira chamada não encontra arquivo e retorna []; a segunda imprime Ada. Códigos para conhecer: ENOENT (arquivo não existe), EEXIST (já existe), EISDIR (uma pasta onde se esperava um arquivo), ENOTEMPTY (a pasta ainda tem conteúdo) e EACCES (sem permissão).

Uma promise em que você não dá await nem .catch() vira uma unhandled rejection quando falha, e o Node termina com erro. Dê await em toda chamada, ou retorne a promise para quem chamou e vai dar await.

Ler vários arquivos de uma vez com Promise.all

Um loop for com await lê os arquivos um depois do outro. Quando as leituras não dependem umas das outras, inicie todas e espere uma vez com Promise.all: o disco trabalha nelas ao mesmo tempo.

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 mantém a ordem do array de entrada, então o resultado é [ 'alpha', 'beta', 'gamma' ] independentemente de qual leitura terminou primeiro, e o tamanho juntado é 14. Troque 'b.txt' no array por 'x.txt' e o await inteiro rejeita com ENOENT.

Se você precisa de todos os resultados mesmo quando algumas leituras falham, use Promise.allSettled; a página de promises cobre os dois.

Erros comuns

Confundir os dois módulos. require('fs').readFile quer um callback; require('fs/promises').readFile retorna uma promise. Chamar a versão de callback sem callback lança The "cb" argument must be of type function.

Esquecer o await. const text = fs.readFile(...) é uma promise pendente, e text.split lança text.split is not a function.

Escritas em paralelo no mesmo arquivo. Promise.all com várias escritas no mesmo caminho pode deixar o conteúdo misturado. Rode essas em sequência.