fs y fs/promises

node:fs y node:fs/promises leen, escriben y transmiten archivos en disco: APIs de promesas para trabajo asíncrono, streams para escalabilidad y flags explícitas para lecturas y escrituras sensibles a la seguridad.

Receta

import { readFile, writeFile, mkdir } from 'node:fs/promises';
import { createReadStream } from 'node:fs';
 
await mkdir('data', { recursive: true });
await writeFile('data/out.json', JSON.stringify({ ok: true }));
const text = await readFile('data/out.json', 'utf8');

Cuándo usarlo:

• Cargar configuración al inicio (JSON pequeño)
• Transmitir exportación CSV a respuesta HTTP
• Escribir archivos temporales cargados antes del escaneo de virus
• Rotar archivos de registro a disco en workers

Ejemplo de trabajo

import { open, writeFile, rename } from 'node:fs/promises';
import { createReadStream } from 'node:fs';
import { pipeline } from 'node:stream/promises';
import { createGzip } from 'node:zlib';
import { createWriteStream } from 'node:fs';
 
async function atomicWrite(path: string, data: string): Promise<void> {
  const tmp = `${path}.tmp`;
  await writeFile(tmp, data, { encoding: 'utf8', mode: 0o600 });
  await rename(tmp, path);
}
 
async function tailBytes(path: string, max: number): Promise<Buffer> {
  const handle = await open(path, 'r');
  try {
    const stat = await handle.stat();
    const size = stat.size;
    const start = Math.max(0, size - max);
    const len = size - start;
    const buf = Buffer.alloc(len);
    await handle.read(buf, 0, len, start);
    return buf;
  } finally {
    await handle.close();
  }
}
 
await pipeline(createReadStream('large.log'), createGzip(), createWriteStream('large.log.gz'));

Lo que esto demuestra:

• La escritura atómica a través de archivo temporal + renombrar reduce la corrupción por escritura parcial
• filehandle.read lee el segmento final sin cargar todo el archivo
• pipeline + createReadStream comprime registros grandes con memoria acotada
• Modo de archivo 0o600 para configuración sensible en Unix

Análisis profundo

Cómo funciona

• Pool de hilos de libuv ejecuta algunas operaciones de fs; el fs síncrono pesado aún bloquea el bucle si se usa la API síncrona.
• Descriptores de archivo - patrón open/filehandle para lecturas/escrituras posicionadas.
• Flags - 'r', 'w', 'a', 'wx' creación exclusiva - previene sobrescrituras accidentales.
• watch - fs.watch / fs.promises.watch - elimina el rebote en herramientas de desarrollo; prefiere señales de recarga explícitas en producción.

Elección de API

Notas de TypeScript

import { access, constants } from 'node:fs/promises';
 
await access('/path/to/file', constants.R_OK);

Errores comunes

• readFileSync en manejador HTTP - bloquea el bucle de eventos. Solución: fs/promises o streams.
• Recorrido de rutas - el usuario proporciona ../../etc/passwd. Solución: resolver bajo el directorio base.
• Vigilar miles de archivos - EMFILE y CPU. Solución: reducir el alcance de la vigilancia o usar una herramienta de construcción.
• UTF-8 predeterminado en archivos binarios - corrupción. Solución: omitir la codificación para Buffer.
• No cerrar los manejadores de archivos - fugas de EMFILE. Solución: try/finally con close().

Alternativas

Preguntas frecuentes

Relacionado

• path y url - unión segura de rutas
• Conceptos básicos de Streams - createReadStream
• Seguridad de Buffer - permisos de archivo
• Conceptos básicos de las API integradas - resumen

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.