fs/promises in Node.js: il file system con async/await

fs/promises è la versione a promise del modulo fs di Node. Le sue funzioni (readFile, writeFile, readdir, stat, mkdir, rm, rename e le altre) restituiscono una promise invece di ricevere una callback, quindi fai await e gestisci gli errori con try/catch. Importalo con require('fs/promises') o 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));

Stampa [ 'write docs', 'ship it' ]: ogni await aspetta un'operazione prima che venga eseguita la riga successiva, quindi l'append avviene sempre dopo la prima scrittura. In un modulo ES await funziona al livello principale; in CommonJS, metti il codice dentro una funzione async.

Le funzioni che userai di più

I nomi sono quelli dell'API a callback, senza la callback. Le pagine su readFile e writeFile trattano queste due nel dettaglio.

Elencare una cartella con readdir e stat

readdir restituisce solo i nomi. Chiama stat su ognuno per sapere la dimensione o distinguere file e cartelle, oppure passa { withFileTypes: true } per avere voci che conoscono già il loro 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));

Il ciclo stampa README.md 6 bytes, notes.txt 3 bytes e src folder. stat viene rifiutata con ENOENT per un path che non esiste, quindi è un controllo di esistenza rapido quando ti servono anche i dettagli.

Rinominare, spostare ed eliminare

rename rinomina e sposta un file (sullo stesso disco). rm elimina; serve recursive: true per una cartella con dei contenuti, e force: true per non fallire quando il path non c'è già più.

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

Il file passa da drafts a published con il nuovo nome, e dopo rm la cartella blog contiene solo published. Togli force: true dal secondo rm e la promise viene rifiutata con ENOENT.

Gestire gli errori con try/catch

Un'operazione che fallisce rifiuta la sua promise. Con await quel rifiuto diventa un'eccezione da intercettare come tutte le altre. Il code dell'errore ti dice cosa è andato storto.

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

La prima chiamata non trova il file e restituisce []; la seconda stampa Ada. I codici da conoscere: ENOENT (file inesistente), EEXIST (esiste già), EISDIR (una cartella dove ci si aspettava un file), ENOTEMPTY (una cartella ha ancora dei contenuti) ed EACCES (permesso negato).

Una promise su cui non fai await e senza .catch() diventa un unhandled rejection quando fallisce, e Node termina con un errore. Fai await di ogni chiamata, oppure restituisci la promise a un chiamante che lo faccia.

Leggere più file insieme con Promise.all

Un ciclo for con await legge i file uno dopo l'altro. Quando le letture non dipendono l'una dall'altra, avviale tutte e aspetta una volta sola con Promise.all: il disco ci lavora in contemporanea.

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 mantiene l'ordine dell'array di partenza, quindi il risultato è [ 'alpha', 'beta', 'gamma' ] indipendentemente da quale lettura è finita prima, e la lunghezza unita è 14. Rinomina 'b.txt' in 'x.txt' nell'array e tutto l'await viene rifiutato con ENOENT.

Se ti servono tutti i risultati anche quando alcune letture falliscono, usa Promise.allSettled; la pagina sulle promise le spiega entrambe.

Errori comuni

Confondere i due moduli. require('fs').readFile vuole una callback; require('fs/promises').readFile restituisce una promise. Chiamare la versione a callback senza callback lancia The "cb" argument must be of type function.

Dimenticare await. const text = fs.readFile(...) è una promise in sospeso, e text.split lancia text.split is not a function.

Scritture parallele sullo stesso file. Promise.all con più scritture sullo stesso path può lasciare contenuti mescolati. Eseguile in sequenza.