fs/promises Node.js : système de fichiers avec async/await

fs/promises est la version à promesses du module fs de Node. Ses fonctions (readFile, writeFile, readdir, stat, mkdir, rm, rename et les autres) renvoient une promesse au lieu de prendre un callback, donc vous les attendez avec await et interceptez les erreurs avec try/catch. Importez-le avec 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));

Le programme affiche [ 'write docs', 'ship it' ] : chaque await attend la fin d'une opération avant que la ligne suivante s'exécute, donc l'ajout se fait toujours après la première écriture. Dans un module ES, await fonctionne au niveau supérieur ; en CommonJS, placez le code dans une fonction async.

Les fonctions les plus utilisées

Les noms sont ceux de l'API à callbacks, sans le callback. Les pages readFile et writeFile détaillent ces deux-là.

Lister un dossier avec readdir et stat

readdir ne renvoie que des noms. Appelez stat sur chacun pour obtenir sa taille ou distinguer fichiers et dossiers, ou passez { withFileTypes: true } pour obtenir des entrées qui connaissent déjà leur type.

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

La boucle affiche README.md 6 bytes, notes.txt 3 bytes et src folder. stat rejette avec ENOENT pour un chemin qui n'existe pas, ce qui en fait un test d'existence rapide quand vous voulez aussi les détails.

Renommer, déplacer et supprimer

rename renomme et déplace un fichier (sur le même disque). rm supprime ; il lui faut recursive: true pour un dossier non vide, et force: true pour ne pas échouer quand le chemin a déjà disparu.

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

Le fichier passe de drafts à published sous son nouveau nom, et après rm le dossier blog ne contient plus que published. Retirez force: true du second rm et il rejette avec ENOENT.

Gérer les erreurs avec try/catch

Une opération qui échoue rejette sa promesse. Avec await, ce rejet devient une exception que vous interceptez comme n'importe quelle autre. Le code de l'erreur indique ce qui s'est mal passé.

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

Le premier appel ne trouve pas le fichier et renvoie [] ; le second affiche Ada. Les codes à connaître : ENOENT (fichier inexistant), EEXIST (existe déjà), EISDIR (un dossier là où un fichier était attendu), ENOTEMPTY (un dossier contient encore des éléments) et EACCES (permission refusée).

Une promesse que vous n'attendez pas avec await et sans .catch() devient un rejet non géré si elle échoue, et Node se termine avec une erreur. Attendez chaque appel, ou renvoyez sa promesse à un appelant qui le fait.

Lire plusieurs fichiers à la fois avec Promise.all

Une boucle for avec await lit les fichiers l'un après l'autre. Quand les lectures ne dépendent pas les unes des autres, lancez-les toutes et attendez une seule fois avec Promise.all : le disque les traite en même temps.

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 conserve l'ordre du tableau d'entrée, donc le résultat est [ 'alpha', 'beta', 'gamma' ] quelle que soit la lecture terminée en premier, et la longueur concaténée est 14. Renommez 'b.txt' en 'x.txt' dans le tableau et tout l'await rejette avec ENOENT.

Si vous avez besoin de chaque résultat même quand certaines lectures échouent, utilisez Promise.allSettled ; la page sur les promesses couvre les deux.

Erreurs fréquentes

Confondre les deux modules. require('fs').readFile attend un callback ; require('fs/promises').readFile renvoie une promesse. Appeler la version à callback sans callback lève The "cb" argument must be of type function.

Oublier await. const text = fs.readFile(...) est une promesse en attente, et text.split lève text.split is not a function.

Écrire en parallèle dans un même fichier. Promise.all avec plusieurs écritures sur le même chemin peut laisser un contenu mélangé. Exécutez-les à la suite.