fs/promises en Node.js: archivos con async/await

fs/promises es la versión basada en promesas del módulo fs de Node. Sus funciones (readFile, writeFile, readdir, stat, mkdir, rm, rename y el resto) devuelven una promesa en lugar de recibir un callback, así que las esperas con await y capturas los errores con try/catch. Impórtalo 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));

Imprime [ 'write docs', 'ship it' ]: cada await espera a que termine una operación antes de que se ejecute la siguiente línea, así que el append siempre ocurre después de la primera escritura. En un ES module await funciona en el nivel superior; en CommonJS, envuelve el código en una función async.

Las funciones que más vas a usar

Los nombres coinciden con la API de callbacks, sin el callback. Las páginas de readFile y writeFile cubren esas dos en detalle.

Listar una carpeta con readdir y stat

readdir solo devuelve nombres. Llama a stat sobre cada uno para obtener su tamaño o distinguir archivos de carpetas, o pasa { withFileTypes: true } para obtener entradas que ya conocen su 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));

El bucle imprime README.md 6 bytes, notes.txt 3 bytes y src folder. stat se rechaza con ENOENT para una ruta que no existe, lo que lo convierte en una comprobación rápida de existencia cuando además quieres los detalles.

Renombrar, mover y borrar

rename sirve para renombrar y para mover un archivo (dentro de la misma unidad). rm borra; necesita recursive: true para una carpeta con contenido, y force: true para no fallar cuando la ruta ya no 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'));

El archivo pasa de drafts a published con su nuevo nombre, y después de rm la carpeta blog solo lista published. Quita force: true del segundo rm y se rechaza con ENOENT.

Manejar errores con try/catch

Una operación que falla rechaza su promesa. Con await, ese rechazo se convierte en una excepción que capturas como cualquier otra. El code del error te dice qué salió mal.

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 primera llamada no encuentra el archivo y devuelve []; la segunda imprime Ada. Códigos que conviene conocer: ENOENT (no existe el archivo), EEXIST (ya existe), EISDIR (una carpeta donde se esperaba un archivo), ENOTEMPTY (una carpeta aún tiene contenido) y EACCES (sin permisos).

Una promesa a la que no haces await ni .catch() se convierte en un unhandled rejection cuando falla, y Node termina con un error. Haz await de cada llamada, o devuelve su promesa a quien sí lo haga.

Leer varios archivos a la vez con Promise.all

Un bucle for con await lee los archivos uno detrás de otro. Cuando las lecturas no dependen entre sí, lánzalas todas y espera una sola vez con Promise.all: el disco trabaja en todas a la vez.

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 el orden del array de entrada, así que el resultado es [ 'alpha', 'beta', 'gamma' ] sin importar qué lectura terminó primero, y la longitud unida es 14. Cambia 'b.txt' por 'x.txt' en el array y todo el await se rechaza con ENOENT.

Si necesitas todos los resultados aunque fallen algunas lecturas, usa Promise.allSettled; la página de promesas cubre los dos.

Errores comunes

Confundir los dos módulos. require('fs').readFile espera un callback; require('fs/promises').readFile devuelve una promesa. Llamar a la versión con callback sin callback lanza The "cb" argument must be of type function.

Olvidar await. const text = fs.readFile(...) es una promesa pendiente, y text.split lanza text.split is not a function.

Escrituras en paralelo sobre un archivo. Promise.all con varias escrituras a la misma ruta puede dejar el contenido mezclado. Ejecútalas en secuencia.