¿Cómo se trabaja con el sistema de archivos en Node?

Question

Accepted Answer

El módulo integrado **`fs`** lee y escribe archivos y directorios. Ofrece tres estilos de API — **promesas** (moderno, preferido), **callbacks** (asíncrono original) y **sync** (bloqueante) — para que puedas elegir el adecuado según la situación.

## La API de promesas (recomendada)

```js
import { readFile, writeFile, mkdir, readdir } from "fs/promises";

async function work() {
  const data = await readFile("input.txt", "utf8");     // leer (utf8 → string)
  await writeFile("output.txt", "Hello");                // escribir (sobrescribe)
  await mkdir("new-dir", { recursive: true });           // crear directorios (recursive = mkdir -p)
  const files = await readdir("./");                      // listar el contenido del directorio
}
```

La API `fs/promises` funciona limpiamente con async/await — el valor por defecto moderno para la E/S de archivos.

## Variantes con callback y sync

```js
import fs from "fs";

fs.readFile("file.txt", "utf8", (err, data) => { ... }); // callback asíncrono
const data = fs.readFileSync("file.txt", "utf8");         // SYNC — ¡bloquea el event loop!
```

**Precaución:** los métodos `*Sync` **bloquean por completo el event loop** hasta que la operación termina. Están bien al arranque (cargar la configuración una sola vez) pero deben evitarse en los manejadores de solicitudes — una lectura bloqueante congela todas las solicitudes concurrentes.

## Operaciones comunes

```js
await fs.promises.appendFile("log.txt", "new line
"); // agregar al final
await fs.promises.unlink("old.txt");                    // eliminar un archivo
await fs.promises.rename("a.txt", "b.txt");             // renombrar/mover
const stats = await fs.promises.stat("file.txt");       // metadatos (tamaño, mtime)
const exists = fs.existsSync("file.txt");               // comprobar existencia
```

## Para archivos grandes: usa streams

```js
// ❌ readFile carga el archivo COMPLETO en memoria — malo para archivos enormes
const huge = await readFile("10gb.txt"); // podría agotar la memoria

// ✅ procésalo en chunks (memoria constante)
fs.createReadStream("10gb.txt").pipe(fs.createWriteStream("copy.txt"));
```

Para archivos grandes, `readFile` carga todo en memoria de una sola vez; los **streams** procesan los datos en chunks con memoria constante.

## Por qué es importante

La E/S de archivos es una capacidad central de Node para cargar configuración, registrar logs, subir/descargar archivos y construir herramientas.

Conocer los tres estilos de API — y, de forma crucial, que **los métodos sync bloquean el event loop** (evítalos en servidores) y que **los archivos grandes necesitan streams** (no `readFile`) — es esencial para escribir código de manejo de archivos que sea a la vez correcto y eficiente bajo concurrencia.

La API de promesas con async/await es el valor por defecto limpio para el uso cotidiano.