Lee archivos de forma eficiente en Node.js con el módulo fs

Kevin van Zonneveld

Cofundador · Ámsterdam, Países Bajos · Mostrar bio

Leer el contenido de los archivos es una tarea fundamental en muchas aplicaciones de Node.js. El módulo integrado fs ofrece métodos potentes y flexibles para manejar las operaciones con archivos de forma eficiente. Veamos cómo leer archivos de manera efectiva con la moderna API de promesas, los métodos de callback más antiguos, los enfoques síncronos y los streams para archivos grandes.

Introducción a la lectura de archivos en Node.js

Node.js ofrece el módulo fs (sistema de archivos), que te permite interactuar con el sistema de archivos directamente desde tu código. Ya sea que leas archivos de configuración, proceses subidas de usuarios, analices registros o manejes grandes conjuntos de datos, entender cómo leer archivos de forma eficiente es clave para crear aplicaciones robustas y con buen rendimiento.

Entender el módulo fs

El módulo fs forma parte de la API principal de Node.js y no requiere ninguna instalación externa. Puedes acceder a su funcionalidad con CommonJS o con la moderna sintaxis de importación de ESM.

// CommonJS style import (older style)
const fs = require('fs')
const fsPromises = require('fs').promises

// ESM style import (modern style)
import * as fs from 'node:fs' // Access callback-based and sync functions
import { promises as fsPromises } from 'node:fs' // Access the Promises API

// Or import specific promise-based functions directly (recommended)
import { readFile, open } from 'node:fs/promises'
import { createReadStream } from 'node:fs' // Streams perform asynchronous I/O

Recomendamos usar la API de promesas (node:fs/promises) para el desarrollo nuevo por sus ventajas con async/await.

Leer archivos de forma asíncrona con la API de promesas (recomendado)

La API fs/promises es el estándar moderno para las operaciones asíncronas con archivos en Node.js. Se integra a la perfección con async/await, lo que produce un código más limpio y legible, y un manejo de errores más sencillo que con callbacks.

import { readFile } from 'node:fs/promises'

async function readFileExample() {
  try {
    // Specify 'utf8' encoding to get a string; otherwise, a Buffer is returned.
    const data = await readFile('example.txt', 'utf8')
    console.log('File contents (promises):', data)
  } catch (err) {
    // Handles errors like file not found or permission issues
    console.error('Error reading file:', err)
  }
}

readFileExample()

Este enfoque responde directamente a la pregunta: «¿Cómo leo archivos de forma asíncrona en Node.js?».

Para leer varios archivos de forma concurrente, Promise.all() resulta eficiente:

import { readFile } from 'node:fs/promises'

async function readMultipleFiles() {
  const filesToRead = ['file1.txt', 'file2.txt']
  try {
    const results = await Promise.all(filesToRead.map((file) => readFile(file, 'utf8')))
    console.log('File 1:', results[0])
    console.log('File 2:', results[1])
  } catch (err) {
    console.error('Error reading multiple files:', err)
  }
}

readMultipleFiles()

Leer archivos de forma asíncrona con fs.readFile() (API de callbacks)

Antes de la API de promesas, las operaciones asíncronas usaban callbacks. Aunque funciona, esto puede derivar en código anidado («callback hell») y en un manejo de errores más complejo.

const fs = require('fs') // Using CommonJS for this example

fs.readFile('example.txt', 'utf8', (err, data) => {
  if (err) {
    console.error('Error reading file (callback):', err)
    return
  }
  console.log('File contents (callback):', data)
})

Lectura síncrona de archivos con fs.readFileSync()

Los métodos síncronos bloquean el event loop de Node.js hasta que la operación termina. Esto puede ser aceptable en scripts simples o durante la inicialización de la aplicación (por ejemplo, al cargar configuración esencial), pero debería evitarse en aplicaciones de servidor que atienden peticiones concurrentes, ya que afecta gravemente al rendimiento.

const fsSync = require('fs') // Using CommonJS for clarity

try {
  const data = fsSync.readFileSync('example.txt', 'utf8')
  console.log('File contents (sync):', data)
} catch (err) {
  console.error('Error reading file synchronously:', err)
}

Manejar archivos grandes de forma eficiente con streams

Cuando trabajas con archivos demasiado grandes para caber cómodamente en memoria, los streams son la solución. Los streams leen los datos en fragmentos manejables, lo que te permite procesarlos poco a poco sin un alto consumo de memoria.

import { createReadStream } from 'node:fs'

// Create a readable stream
const stream = createReadStream('largefile.txt', { encoding: 'utf8' })

// Event handler for incoming data chunks
stream.on('data', (chunk) => {
  console.log(`Received ${Buffer.byteLength(chunk, 'utf8')} bytes of data.`)
  // Process the chunk here (e.g., parse, transform, write elsewhere)
})

// Event handler for the end of the stream
stream.on('end', () => {
  console.log('Finished reading the file.')
})

// Crucial: Event handler for errors during streaming
stream.on('error', (err) => {
  console.error('Stream error:', err)
  // Clean up the stream resources if an error occurs
  stream.destroy()
})

También puedes hacer pipe desde streams de lectura hacia streams de escritura para transferir datos de forma eficiente, como leer de un archivo y escribir en la consola o en otro archivo:

import { createReadStream } from 'node:fs'

const readable = createReadStream('input.txt')
const writable = process.stdout // Example: writing to console

// Handle errors on the source stream
readable.on('error', (err) => {
  console.error('Source stream error:', err)
  readable.destroy()
  // Do not close process.stdout; the application may still need to write to it.
})

// Handle errors on the destination stream or during the pipe operation
writable.on('error', (err) => {
  console.error('Destination stream or pipe error:', err)
  readable.destroy() // Stop reading if writing fails
})

// Pipe data from readable to writable
readable.pipe(writable)

Usar streams responde de forma efectiva a la pregunta: «¿Cuáles son las buenas prácticas para manejar archivos grandes en Node.js?».

Usar FileHandle para operaciones avanzadas

Para un control más fino, como leer partes concretas de un archivo, escribir en posiciones específicas o realizar varias operaciones sin abrir y cerrar el archivo repetidamente, la API FileHandle (mediante fs/promises) es muy potente. Proporciona un objeto que representa un descriptor de archivo abierto.

import { open } from 'node:fs/promises'

async function readWithFileHandle() {
  let fileHandle = null // Declare outside try for access in finally
  try {
    // Open the file for reading ('r')
    fileHandle = await open('example.txt', 'r')

    // Read the entire file content using the handle
    const content = await fileHandle.readFile({ encoding: 'utf8' })
    console.log('File content (FileHandle):', content)

    // Example: Read the first 10 bytes
    const buffer = Buffer.alloc(10)
    const { bytesRead } = await fileHandle.read(buffer, 0, 10, 0) // buffer, offset, length, position
    console.log(`Read ${bytesRead} bytes: ${buffer.toString()}`)
  } catch (err) {
    console.error('Error using FileHandle:', err)
  } finally {
    // Crucial: Always close the file handle to release system resources
    if (fileHandle) {
      await fileHandle.close()
      console.log('File handle closed.')
    }
  }
}

readWithFileHandle()

Manejo de errores y buenas prácticas

Un manejo de errores robusto es esencial cuando trabajas con el sistema de archivos.

• Promesas (async/await): Usa bloques try...catch para gestionar los errores de forma limpia.
• Callbacks: Comprueba siempre el primer argumento err del callback.
• Streams: Implementa escuchadores del evento error en todos los streams que participan en un pipeline. Asegúrate de liberar los recursos (destroy(), close()) en caso de error.
• File Handles: Usa try...catch...finally para garantizar que se llame a fileHandle.close().
• Permisos: Asegúrate de que tu proceso de Node.js tenga los permisos de lectura necesarios para los archivos de destino.
• Comprobaciones de existencia: Considera comprobar si un archivo existe (por ejemplo, con fsPromises.access) antes de intentar leerlo, aunque a menudo es mejor manejar el error ENOENT (archivo no encontrado) directamente en el bloque catch.

Consideraciones de rendimiento

Elegir el método adecuado influye notablemente en el rendimiento y en el uso de recursos:

• Streams: Los mejores para archivos grandes por su mínimo consumo de memoria. Ideales para procesar datos de forma secuencial.
• API de promesas (readFile): Adecuada para archivos pequeños y medianos en los que cargar todo el contenido en memoria es aceptable. Ofrece un buen equilibrio entre rendimiento y facilidad de uso con async/await.
• API síncrona (readFileSync): El mayor rendimiento potencial para una única lectura si el bloqueo es aceptable (scripts, inicialización), pero desastrosa para cargas de trabajo de servidor concurrentes.
• FileHandle: Puede ser más eficiente que llamadas repetidas a readFile si se necesitan varias operaciones (lecturas, escrituras, estadísticas) sobre el mismo archivo, ya que mantiene abierto el descriptor de archivo. Añade una ligera sobrecarga en lecturas únicas.
• Concurrencia: Usa Promise.all con readFile para leer de forma concurrente varios archivos pequeños, pero ten en cuenta los límites del sistema operativo sobre los descriptores de archivo abiertos.

Casos de uso y ejemplos reales

La lectura eficiente de archivos es fundamental para:

• Cargar la configuración de la aplicación (por ejemplo, .env, config.json).
• Procesar subidas de usuarios en aplicaciones web.
• Analizar archivos de registro grandes o conjuntos de datos CSV.
• Transmitir datos de video o audio.
• Leer recursos HTML/CSS/JS o archivos de plantilla.

En Transloadit aprovechamos ampliamente las técnicas eficientes de manejo de archivos. Por ejemplo, nuestro Robot 🤖 /file/read puede leer el contenido de los archivos de forma eficiente como parte de una Assembly de procesamiento más amplia. Ten en cuenta que este Robot en concreto acepta actualmente archivos de menos de 500 KB.

Conclusión y recursos adicionales

Node.js ofrece un módulo fs versátil para leer archivos. En aplicaciones modernas, prioriza la API asíncrona y no bloqueante fs/promises con async/await. Usa streams para archivos grandes y así gestionar la memoria de forma efectiva. Reserva los métodos síncronos para casos concretos, como scripts simples o código de inicialización. Un manejo de errores adecuado es crucial sea cual sea el método elegido.

Para conocer todos los detalles, consulta la documentación oficial del sistema de archivos de Node.js⁠.

Si tu aplicación implica flujos de trabajo complejos de procesamiento, encoding o manipulación de archivos, considera explorar herramientas y servicios diseñados para estas tareas, como el SDK de Node.js de Transloadit.