Sistema de archivos

[Estable: 2 - Estable]

Estable: 2 Estabilidad: 2 - Estable

Código fuente: lib/fs.js

El módulo node:fs permite interactuar con el sistema de archivos de una manera modelada en las funciones POSIX estándar.

Para usar las API basadas en promesas:

ESM

import * as fs from 'node:fs/promises'

CJS

const fs = require('node:fs/promises')

Para usar las API de devolución de llamada y síncronas:

ESM

import * as fs from 'node:fs'

CJS

const fs = require('node:fs')

Todas las operaciones del sistema de archivos tienen formas síncronas, de devolución de llamada y basadas en promesas, y se puede acceder a ellas utilizando tanto la sintaxis CommonJS como los módulos ES6 (ESM).

Ejemplo de promesa

Las operaciones basadas en promesas devuelven una promesa que se cumple cuando la operación asíncrona se completa.

ESM

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

try {
  await unlink('/tmp/hello')
  console.log('se eliminó correctamente /tmp/hello')
} catch (error) {
  console.error('hubo un error:', error.message)
}

CJS

const { unlink } = require('node:fs/promises')

;(async function (path) {
  try {
    await unlink(path)
    console.log(`se eliminó correctamente ${path}`)
  } catch (error) {
    console.error('hubo un error:', error.message)
  }
})('/tmp/hello')

Ejemplo de Callback

La forma de callback toma una función de callback de finalización como su último argumento e invoca la operación de forma asíncrona. Los argumentos pasados al callback de finalización dependen del método, pero el primer argumento siempre está reservado para una excepción. Si la operación se completa con éxito, entonces el primer argumento es null o undefined.

ESM

import { unlink } from 'node:fs'

unlink('/tmp/hello', err => {
  if (err) throw err
  console.log('eliminado correctamente /tmp/hello')
})

CJS

const { unlink } = require('node:fs')

unlink('/tmp/hello', err => {
  if (err) throw err
  console.log('eliminado correctamente /tmp/hello')
})

Las versiones basadas en callbacks de las APIs del módulo node:fs son preferibles al uso de las APIs de promesas cuando se requiere el máximo rendimiento (tanto en términos de tiempo de ejecución como de asignación de memoria).

Ejemplo Síncrono

Las APIs síncronas bloquean el bucle de eventos de Node.js y la posterior ejecución de JavaScript hasta que la operación se completa. Las excepciones se lanzan inmediatamente y pueden ser manejadas usando try…catch, o se puede permitir que se propaguen.

ESM

import { unlinkSync } from 'node:fs'

try {
  unlinkSync('/tmp/hello')
  console.log('eliminado correctamente /tmp/hello')
} catch (err) {
  // manejar el error
}

CJS

const { unlinkSync } = require('node:fs')

try {
  unlinkSync('/tmp/hello')
  console.log('eliminado correctamente /tmp/hello')
} catch (err) {
  // manejar el error
}

API de Promesas

[Historia]

Versión	Cambios
v14.0.0	Expuesto como require('fs/promises').
v11.14.0, v10.17.0	Esta API ya no es experimental.
v10.1.0	La API es accesible solo a través de require('fs').promises.
v10.0.0	Añadido en: v10.0.0

La API fs/promises proporciona métodos asíncronos del sistema de archivos que devuelven promesas.

Las API de promesas utilizan el grupo de hilos subyacente de Node.js para realizar operaciones del sistema de archivos fuera del hilo del bucle de eventos. Estas operaciones no están sincronizadas ni son seguras para subprocesos. Se debe tener cuidado al realizar múltiples modificaciones concurrentes en el mismo archivo o puede producirse corrupción de datos.

Clase: FileHandle

Añadido en: v10.0.0

Un objeto <FileHandle> es un envoltorio de objeto para un descriptor de archivo numérico.

Las instancias del objeto <FileHandle> son creadas por el método fsPromises.open().

Todos los objetos <FileHandle> son <EventEmitter>s.

Si un <FileHandle> no se cierra usando el método filehandle.close(), intentará cerrar automáticamente el descriptor de archivo y emitirá una advertencia de proceso, ayudando a prevenir fugas de memoria. Por favor, no confíe en este comportamiento porque puede ser poco fiable y el archivo puede no cerrarse. En su lugar, cierre siempre explícitamente los <FileHandle>s. Node.js puede cambiar este comportamiento en el futuro.

Evento: 'close'

Agregado en: v15.4.0

El evento 'close' se emite cuando el <FileHandle> se ha cerrado y ya no se puede usar.

filehandle.appendFile(data[, options])

[Historial]

Versión	Cambios
v21.1.0, v20.10.0	Ahora se admite la opción flush.
v15.14.0, v14.18.0	El argumento data admite AsyncIterable, Iterable y Stream.
v14.0.0	El parámetro data ya no forzará las entradas no admitidas a cadenas.
v10.0.0	Agregado en: v10.0.0

• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>

• options <Object> | <string>

  • encoding <string> | <null> Predeterminado: 'utf8'
  • flush <boolean> Si es true, el descriptor de archivo subyacente se vacía antes de cerrarlo. Predeterminado: false.

• Devuelve: <Promise> Se cumple con undefined tras el éxito.

Alias de filehandle.writeFile().

Cuando se opera con controladores de archivos, el modo no se puede cambiar con respecto a lo que se estableció con fsPromises.open(). Por lo tanto, esto es equivalente a filehandle.writeFile().

filehandle.chmod(mode)

Agregado en: v10.0.0

• mode <integer> la máscara de bits del modo de archivo.
• Devuelve: <Promise> Se cumple con undefined tras el éxito.

Modifica los permisos del archivo. Véase chmod(2).

filehandle.chown(uid, gid)

Agregado en: v10.0.0

• uid <integer> El nuevo id de usuario del propietario del archivo.
• gid <integer> El nuevo id de grupo del grupo del archivo.
• Devuelve: <Promise> Se cumple con undefined tras el éxito.

Cambia la propiedad del archivo. Un envoltorio para chown(2).

filehandle.close()

Agregado en: v10.0.0

• Devuelve: <Promise> Se cumple con undefined al tener éxito.

Cierra el identificador de archivo después de esperar a que se complete cualquier operación pendiente en el identificador.

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

let filehandle
try {
  filehandle = await open('thefile.txt', 'r')
} finally {
  await filehandle?.close()
}

filehandle.createReadStream([options])

Agregado en: v16.11.0

• options <Objeto>

  • encoding <string> Predeterminado: null
  • autoClose <boolean> Predeterminado: true
  • emitClose <boolean> Predeterminado: true
  • start <entero>
  • end <entero> Predeterminado: Infinity
  • highWaterMark <entero> Predeterminado: 64 * 1024
  • signal <AbortSignal> | <undefined> Predeterminado: undefined

• Devuelve: <fs.ReadStream>

options puede incluir valores de start y end para leer un rango de bytes del archivo en lugar de todo el archivo. Tanto start como end son inclusivos y comienzan a contar en 0, los valores permitidos están en el rango [0, Number.MAX_SAFE_INTEGER]. Si se omite start o es undefined, filehandle.createReadStream() lee secuencialmente desde la posición actual del archivo. La encoding puede ser cualquiera de las aceptadas por <Buffer>.

Si FileHandle apunta a un dispositivo de caracteres que solo admite lecturas de bloqueo (como un teclado o una tarjeta de sonido), las operaciones de lectura no finalizan hasta que haya datos disponibles. Esto puede evitar que el proceso salga y que la secuencia se cierre de forma natural.

De forma predeterminada, la secuencia emitirá un evento 'close' después de que haya sido destruida. Establezca la opción emitClose en false para cambiar este comportamiento.

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

const fd = await open('/dev/input/event0')
// Crea un flujo desde algún dispositivo de caracteres.
const stream = fd.createReadStream()
setTimeout(() => {
  stream.close() // Esto podría no cerrar el flujo.
  // Marca artificialmente el final de la secuencia, como si el recurso subyacente
  // hubiera indicado el fin de archivo por sí mismo, permite que se cierre la secuencia.
  // Esto no cancela las operaciones de lectura pendientes, y si hay una
  // operación de este tipo, es posible que el proceso aún no pueda salir
  // correctamente hasta que termine.
  stream.push(null)
  stream.read(0)
}, 100)

Si autoClose es falso, entonces el descriptor de archivo no se cerrará, incluso si hay un error. Es responsabilidad de la aplicación cerrarlo y asegurarse de que no haya fugas de descriptores de archivos. Si autoClose está establecido en verdadero (comportamiento predeterminado), en 'error' o 'end' el descriptor de archivo se cerrará automáticamente.

Un ejemplo para leer los últimos 10 bytes de un archivo que tiene una longitud de 100 bytes:

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

const fd = await open('sample.txt')
fd.createReadStream({ start: 90, end: 99 })

filehandle.createWriteStream([options])

[Historial]

Versión	Cambios
v21.0.0, v20.10.0	Ahora se admite la opción flush.
v16.11.0	Añadido en: v16.11.0

• options <Object>

  • encoding <string> Predeterminado: 'utf8'
  • autoClose <boolean> Predeterminado: true
  • emitClose <boolean> Predeterminado: true
  • start <integer>
  • highWaterMark <number> Predeterminado: 16384
  • flush <boolean> Si es true, el descriptor de archivo subyacente se vacía antes de cerrarlo. Predeterminado: false.

• Devuelve: <fs.WriteStream>

options también puede incluir una opción start para permitir la escritura de datos en alguna posición posterior al inicio del archivo, los valores permitidos están en el rango [0, Number.MAX_SAFE_INTEGER]. La modificación de un archivo en lugar de su sustitución puede requerir que la opción flags de open se establezca en r+ en lugar del valor predeterminado r. La encoding puede ser cualquiera de las aceptadas por <Buffer>.

Si autoClose se establece en true (comportamiento predeterminado) en 'error' o 'finish' el descriptor de archivo se cerrará automáticamente. Si autoClose es false, entonces el descriptor de archivo no se cerrará, incluso si hay un error. Es responsabilidad de la aplicación cerrarlo y asegurarse de que no haya fugas de descriptores de archivos.

De forma predeterminada, el stream emitirá un evento 'close' después de que se haya destruido. Establezca la opción emitClose en false para cambiar este comportamiento.

filehandle.datasync()

Agregado en: v10.0.0

• Devuelve: <Promise> Se cumple con undefined al tener éxito.

Fuerza todas las operaciones de E/S actualmente en cola asociadas con el archivo al estado de finalización de E/S sincronizada del sistema operativo. Consulta la documentación POSIX fdatasync(2) para obtener detalles.

A diferencia de filehandle.sync, este método no descarga los metadatos modificados.

filehandle.fd

Agregado en: v10.0.0

• <number> El descriptor de archivo numérico administrado por el objeto <FileHandle>.

filehandle.read(buffer, offset, length, position)

[Historial]

Versión	Cambios
v21.0.0	Acepta valores bigint como position.
v10.0.0	Agregado en: v10.0.0

• buffer <Buffer> | <TypedArray> | <DataView> Un búfer que se llenará con los datos del archivo leídos.
• offset <integer> La ubicación en el búfer en la que se empezará a rellenar. Predeterminado: 0
• length <integer> El número de bytes que se leerán. Predeterminado: buffer.byteLength - offset
• position <integer> | <bigint> | <null> La ubicación desde donde empezar a leer los datos del archivo. Si es null o -1, los datos se leerán desde la posición actual del archivo y la posición se actualizará. Si position es un entero no negativo, la posición actual del archivo permanecerá sin cambios. Predeterminado: null
• Devuelve: <Promise> Se cumple al tener éxito con un objeto con dos propiedades:
  • bytesRead <integer> El número de bytes leídos
  • buffer <Buffer> | <TypedArray> | <DataView> Una referencia al argumento buffer pasado.

Lee los datos del archivo y los almacena en el búfer dado.

Si el archivo no se modifica simultáneamente, se alcanza el final del archivo cuando el número de bytes leídos es cero.

filehandle.read([options])

[Historial]

Versión	Cambios
v21.0.0	Acepta valores bigint como position.
v13.11.0, v12.17.0	Añadido en: v13.11.0, v12.17.0

• options <Objeto>

  • buffer <Buffer> | <TypedArray> | <DataView> Un búfer que se llenará con los datos del archivo leídos. Predeterminado: Buffer.alloc(16384)
  • offset <entero> La ubicación en el búfer en la que comenzar a llenar. Predeterminado: 0
  • length <entero> El número de bytes a leer. Predeterminado: buffer.byteLength - offset
  • position <entero> | <bigint> | <null> La ubicación donde comenzar a leer datos del archivo. Si es null o -1, los datos se leerán desde la posición actual del archivo y la posición se actualizará. Si position es un entero no negativo, la posición actual del archivo permanecerá sin cambios. Predeterminado: null

• Devuelve: <Promesa> Se cumple con éxito con un objeto con dos propiedades:

  • bytesRead <entero> El número de bytes leídos
  • buffer <Buffer> | <TypedArray> | <DataView> Una referencia al argumento buffer pasado.

Lee datos del archivo y los almacena en el búfer dado.

Si el archivo no se modifica simultáneamente, se llega al final del archivo cuando el número de bytes leídos es cero.

filehandle.read(buffer[, options])

[Historial]

Versión	Cambios
v21.0.0	Acepta valores bigint como position.
v18.2.0, v16.17.0	Añadido en: v18.2.0, v16.17.0

• buffer <Buffer> | <TypedArray> | <DataView> Un búfer que se llenará con los datos del archivo leídos.

• options <Object>

  • offset <integer> La ubicación en el búfer donde se debe comenzar a llenar. Predeterminado: 0
  • length <integer> El número de bytes a leer. Predeterminado: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> La ubicación desde donde se debe comenzar a leer datos del archivo. Si es null o -1, los datos se leerán desde la posición actual del archivo y la posición se actualizará. Si position es un entero no negativo, la posición actual del archivo permanecerá sin cambios. Predeterminado:: null

• Devuelve: <Promise> Se cumple con éxito con un objeto con dos propiedades:

  • bytesRead <integer> El número de bytes leídos.
  • buffer <Buffer> | <TypedArray> | <DataView> Una referencia al argumento buffer pasado.

Lee datos del archivo y los almacena en el búfer dado.

Si el archivo no se modifica simultáneamente, se alcanza el final del archivo cuando el número de bytes leídos es cero.

filehandle.readableWebStream([options])

[Historial]

Versión	Cambios
v20.0.0, v18.17.0	Se añadió la opción para crear un stream de 'bytes'.
v17.0.0	Añadido en: v17.0.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

• options <Objeto>

  • type <cadena> | <indefinido> Indica si se debe abrir un stream normal o un stream 'bytes'. Predeterminado: undefined

• Devuelve: <ReadableStream>

Devuelve un ReadableStream que puede utilizarse para leer los datos de los archivos.

Se lanzará un error si este método se llama más de una vez o si se llama después de que el FileHandle esté cerrado o en proceso de cierre.

ESM

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

const file = await open('./some/file/to/read')

for await (const chunk of file.readableWebStream()) console.log(chunk)

await file.close()

CJS

const { open } = require('node:fs/promises')

;(async () => {
  const file = await open('./some/file/to/read')

  for await (const chunk of file.readableWebStream()) console.log(chunk)

  await file.close()
})()

Si bien ReadableStream leerá el archivo hasta su finalización, no cerrará FileHandle automáticamente. El código de usuario debe llamar al método fileHandle.close().

filehandle.readFile(options)

Agregado en: v10.0.0

• options <Objeto> | <cadena>

  • encoding <cadena> | <null> Predeterminado: null
  • signal <AbortSignal> permite abortar un readFile en progreso

• Devuelve: <Promise> Se cumple tras una lectura exitosa con el contenido del archivo. Si no se especifica ninguna codificación (utilizando options.encoding), los datos se devuelven como un objeto <Buffer>. De lo contrario, los datos serán una cadena.

Lee de forma asíncrona todo el contenido de un archivo.

Si options es una cadena, especifica la encoding.

El <FileHandle> tiene que soportar la lectura.

Si se realizan una o más llamadas a filehandle.read() en un descriptor de archivo y luego se realiza una llamada a filehandle.readFile(), los datos se leerán desde la posición actual hasta el final del archivo. No siempre se lee desde el principio del archivo.

filehandle.readLines([opciones])

Agregado en: v18.11.0

• opciones <Objeto>

  • encoding <cadena> Predeterminado: null
  • autoClose <booleano> Predeterminado: true
  • emitClose <booleano> Predeterminado: true
  • start <entero>
  • end <entero> Predeterminado: Infinity
  • highWaterMark <entero> Predeterminado: 64 * 1024

• Devuelve: <readline.InterfaceConstructor>

Método de conveniencia para crear una interfaz readline y transmitir sobre el archivo. Consulte filehandle.createReadStream() para las opciones.

ESM

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

const file = await open('./some/file/to/read')

for await (const line of file.readLines()) {
  console.log(line)
}

CJS

const { open } = require('node:fs/promises')

;(async () => {
  const file = await open('./some/file/to/read')

  for await (const line of file.readLines()) {
    console.log(line)
  }
})()

filehandle.readv(buffers[, position])

Agregado en: v13.13.0, v12.17.0

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <integer> | <null> El desplazamiento desde el inicio del archivo desde donde se deben leer los datos. Si position no es un number, los datos se leerán desde la posición actual. Predeterminado: null
• Devuelve: <Promise> Se cumple con éxito un objeto que contiene dos propiedades:
  • bytesRead <integer> la cantidad de bytes leídos
  • buffers <Buffer[]> | <TypedArray[]> | <DataView[]> propiedad que contiene una referencia a la entrada buffers.

Lee de un archivo y escribe en un array de <ArrayBufferView>s

filehandle.stat([options])

[Historial]

Versión	Cambios
v10.5.0	Acepta un objeto options adicional para especificar si los valores numéricos devueltos deben ser bigint.
v10.0.0	Añadido en: v10.0.0

• options <Objeto>

  • bigint <booleano> Indica si los valores numéricos en el objeto <fs.Stats> devuelto deben ser bigint. Predeterminado: false.

• Devuelve: <Promise> Se cumple con un <fs.Stats> para el archivo.

filehandle.sync()

Añadido en: v10.0.0

• Devuelve: <Promise> Se cumple con undefined si la operación es exitosa.

Solicita que todos los datos del descriptor de archivo abierto se vacíen en el dispositivo de almacenamiento. La implementación específica es específica del sistema operativo y del dispositivo. Consulte la documentación de POSIX fsync(2) para obtener más detalles.

filehandle.truncate(len)

Agregado en: v10.0.0

• len <integer> Predeterminado: 0
• Devuelve: <Promise> Se cumple con undefined al tener éxito.

Trunca el archivo.

Si el archivo era más grande que len bytes, solo los primeros len bytes se conservarán en el archivo.

El siguiente ejemplo conserva solo los primeros cuatro bytes del archivo:

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

let filehandle = null
try {
  filehandle = await open('temp.txt', 'r+')
  await filehandle.truncate(4)
} finally {
  await filehandle?.close()
}

Si el archivo previamente era más corto que len bytes, se extiende, y la parte extendida se rellena con bytes nulos ('\0'):

Si len es negativo, se usará 0.

filehandle.utimes(atime, mtime)

Agregado en: v10.0.0

• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• Devuelve: <Promise>

Cambia las marcas de tiempo del sistema de archivos del objeto referenciado por el <FileHandle> y luego cumple la promesa sin argumentos al tener éxito.

filehandle.write(buffer, offset[, length[, position]])

[Historial]

Versión	Cambios
v14.0.0	El parámetro buffer ya no forzará la conversión de entradas no admitidas a buffers.
v10.0.0	Añadido en: v10.0.0

• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer> La posición de inicio dentro de buffer donde comienza la escritura de los datos.
• length <integer> El número de bytes de buffer que se van a escribir. Predeterminado: buffer.byteLength - offset
• position <integer> | <null> El desplazamiento desde el principio del archivo donde se deben escribir los datos de buffer. Si position no es un número, los datos se escribirán en la posición actual. Consulte la documentación de POSIX pwrite(2) para obtener más detalles. Predeterminado: null
• Devuelve: <Promise>

Escribe buffer en el archivo.

La promesa se cumple con un objeto que contiene dos propiedades:

• bytesWritten <integer> el número de bytes escritos
• buffer <Buffer> | <TypedArray> | <DataView> una referencia al buffer escrito.

No es seguro usar filehandle.write() varias veces en el mismo archivo sin esperar a que la promesa se cumpla (o se rechace). Para este escenario, utilice filehandle.createWriteStream().

En Linux, las escrituras posicionales no funcionan cuando el archivo se abre en modo de anexión. El kernel ignora el argumento de posición y siempre anexa los datos al final del archivo.

filehandle.write(buffer[, options])

Agregado en: v18.3.0, v16.17.0

• buffer <Buffer> | <TypedArray> | <DataView>

• options <Object>

  • offset <integer> Predeterminado: 0
  • length <integer> Predeterminado: buffer.byteLength - offset
  • position <integer> Predeterminado: null

• Devuelve: <Promise>

Escribe buffer en el archivo.

Similar a la función filehandle.write anterior, esta versión toma un objeto options opcional. Si no se especifica ningún objeto options, se utilizarán por defecto los valores anteriores.

filehandle.write(string[, position[, encoding]])

[Historial]

Versión	Cambios
v14.0.0	El parámetro string ya no forzará la entrada no admitida a cadenas.
v10.0.0	Añadido en: v10.0.0

• string <string>
• position <integer> | <null> El desplazamiento desde el principio del archivo donde se deben escribir los datos de string. Si position no es un number, los datos se escribirán en la posición actual. Consulte la documentación de POSIX pwrite(2) para obtener más detalles. Predeterminado: null
• encoding <string> La codificación de cadena esperada. Predeterminado: 'utf8'
• Devuelve: <Promise>

Escribe string en el archivo. Si string no es una cadena, la promesa se rechaza con un error.

La promesa se cumple con un objeto que contiene dos propiedades:

• bytesWritten <integer> el número de bytes escritos
• buffer <string> una referencia a la string escrita.

No es seguro usar filehandle.write() varias veces en el mismo archivo sin esperar a que se cumpla (o se rechace) la promesa. Para este escenario, utilice filehandle.createWriteStream().

En Linux, las escrituras posicionales no funcionan cuando el archivo se abre en modo de anexar. El kernel ignora el argumento de posición y siempre agrega los datos al final del archivo.

filehandle.writeFile(data, options)

[Historial]

Versión	Cambios
v15.14.0, v14.18.0	El argumento data admite AsyncIterable, Iterable y Stream.
v14.0.0	El parámetro data ya no coaccionará entradas no admitidas a strings.
v10.0.0	Añadido en: v10.0.0

• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>

• options <Object> | <string>

  • encoding <string> | <null> La codificación de caracteres esperada cuando data es un string. Predeterminado: 'utf8'

• Devuelve: <Promise>

Escribe datos de forma asíncrona en un archivo, reemplazando el archivo si ya existe. data puede ser un string, un buffer, un objeto <AsyncIterable> o un objeto <Iterable>. La promesa se cumple sin argumentos tras el éxito.

Si options es un string, entonces especifica la encoding.

El <FileHandle> tiene que ser compatible con la escritura.

No es seguro usar filehandle.writeFile() varias veces en el mismo archivo sin esperar a que la promesa se cumpla (o se rechace).

Si se realizan una o más llamadas a filehandle.write() en un manejador de archivo y luego se realiza una llamada a filehandle.writeFile(), los datos se escribirán desde la posición actual hasta el final del archivo. No siempre escribe desde el principio del archivo.

filehandle.writev(buffers[, position])

Agregado en: v12.9.0

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <integer> | <null> El desplazamiento desde el inicio del archivo donde se deben escribir los datos de buffers. Si position no es un number, los datos se escribirán en la posición actual. Predeterminado: null
• Devuelve: <Promise>

Escribe un array de <ArrayBufferView>s en el archivo.

La promesa se cumple con un objeto que contiene dos propiedades:

• bytesWritten <integer> la cantidad de bytes escritos
• buffers <Buffer[]> | <TypedArray[]> | <DataView[]> una referencia a la entrada buffers.

No es seguro llamar a writev() varias veces en el mismo archivo sin esperar a que la promesa se cumpla (o se rechace).

En Linux, las escrituras posicionales no funcionan cuando el archivo se abre en modo de anexión. El kernel ignora el argumento de posición y siempre agrega los datos al final del archivo.

filehandle[Symbol.asyncDispose]()

Añadido en: v20.4.0, v18.18.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

Un alias para filehandle.close().

fsPromises.access(path[, mode])

Añadido en: v10.0.0

• path <string> | <Buffer> | <URL>
• mode <integer> Predeterminado: fs.constants.F_OK
• Devuelve: <Promise> Se cumple con undefined si tiene éxito.

Prueba los permisos de un usuario para el archivo o directorio especificado por path. El argumento mode es un entero opcional que especifica las comprobaciones de accesibilidad que se realizarán. mode debe ser el valor fs.constants.F_OK o una máscara que consiste en el OR bit a bit de cualquiera de fs.constants.R_OK, fs.constants.W_OK y fs.constants.X_OK (por ejemplo, fs.constants.W_OK | fs.constants.R_OK). Consulte Constantes de acceso a archivos para conocer los valores posibles de mode.

Si la comprobación de accesibilidad se realiza correctamente, la promesa se cumple sin ningún valor. Si falla alguna de las comprobaciones de accesibilidad, la promesa se rechaza con un objeto <Error>. El siguiente ejemplo comprueba si el proceso actual puede leer y escribir el archivo /etc/passwd.

import { access, constants } from 'node:fs/promises'

try {
  await access('/etc/passwd', constants.R_OK | constants.W_OK)
  console.log('can access')
} catch {
  console.error('cannot access')
}

No se recomienda usar fsPromises.access() para comprobar la accesibilidad de un archivo antes de llamar a fsPromises.open(). Hacerlo introduce una condición de carrera, ya que otros procesos pueden cambiar el estado del archivo entre las dos llamadas. En cambio, el código del usuario debería abrir/leer/escribir el archivo directamente y gestionar el error que se produce si el archivo no es accesible.

fsPromises.appendFile(path, data[, options])

[Historial]

Versión	Cambios
v21.1.0, v20.10.0	Ahora se admite la opción flush.
v10.0.0	Añadido en: v10.0.0

• path <string> | <Buffer> | <URL> | <FileHandle> nombre de archivo o <FileHandle>

• data <string> | <Buffer>

• options <Object> | <string>

  • encoding <string> | <null> Predeterminado: 'utf8'
  • mode <integer> Predeterminado: 0o666
  • flag <string> Consulte soporte de flags del sistema de archivos. Predeterminado: 'a'.
  • flush <boolean> Si es true, el descriptor de archivo subyacente se vacía antes de cerrarlo. Predeterminado: false.

• Devuelve: <Promise> Se cumple con undefined tras el éxito.

Añade datos de forma asíncrona a un archivo, creando el archivo si aún no existe. data puede ser una cadena o un <Buffer>.

Si options es una cadena, especifica la codificación.

La opción mode solo afecta al archivo recién creado. Consulta fs.open() para obtener más detalles.

El path se puede especificar como un <FileHandle> que se ha abierto para anexar (usando fsPromises.open()).

fsPromises.chmod(path, mode)

Agregado en: v10.0.0

• path <string> | <Buffer> | <URL>
• mode <string> | <integer>
• Devuelve: <Promise> Se cumple con undefined tras el éxito.

Cambia los permisos de un archivo.

fsPromises.chown(path, uid, gid)

Agregado en: v10.0.0

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• Devuelve: <Promise> Se cumple con undefined tras el éxito.

Cambia la propiedad de un archivo.

fsPromises.copyFile(src, dest[, mode])

[Historial]

Versión	Cambios
v14.0.0	Se cambió el argumento flags a mode y se impuso una validación de tipo más estricta.
v10.0.0	Agregado en: v10.0.0

• src <string> | <Buffer> | <URL> nombre de archivo de origen a copiar

• dest <string> | <Buffer> | <URL> nombre de archivo de destino de la operación de copia

• mode <integer> Modificadores opcionales que especifican el comportamiento de la operación de copia. Es posible crear una máscara que consista en la operación OR bit a bit de dos o más valores (p. ej. fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE) Predeterminado: 0.

  • fs.constants.COPYFILE_EXCL: La operación de copia fallará si dest ya existe.
  • fs.constants.COPYFILE_FICLONE: La operación de copia intentará crear un reflink de copia en escritura. Si la plataforma no admite la copia en escritura, se utiliza un mecanismo de copia de respaldo.
  • fs.constants.COPYFILE_FICLONE_FORCE: La operación de copia intentará crear un reflink de copia en escritura. Si la plataforma no admite la copia en escritura, la operación fallará.

• Devuelve: <Promise> Se cumple con undefined al finalizar con éxito.

Copia asíncronamente src a dest. De forma predeterminada, dest se sobrescribe si ya existe.

No se ofrecen garantías sobre la atomicidad de la operación de copia. Si se produce un error después de que se haya abierto el archivo de destino para su escritura, se intentará eliminar el destino.

import { copyFile, constants } from 'node:fs/promises'

try {
  await copyFile('source.txt', 'destination.txt')
  console.log('source.txt fue copiado a destination.txt')
} catch {
  console.error('El archivo no se pudo copiar')
}

// Al usar COPYFILE_EXCL, la operación fallará si destination.txt existe.
try {
  await copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL)
  console.log('source.txt fue copiado a destination.txt')
} catch {
  console.error('El archivo no se pudo copiar')
}

fsPromises.cp(src, dest[, options])

[Historial]

Versión	Cambios
v22.3.0	Esta API ya no es experimental.
v20.1.0, v18.17.0	Acepta una opción adicional mode para especificar el comportamiento de copia como el argumento mode de fs.copyFile().
v17.6.0, v16.15.0	Acepta una opción adicional verbatimSymlinks para especificar si se debe realizar la resolución de ruta para los enlaces simbólicos.
v16.7.0	Añadido en: v16.7.0

• src <string> | <URL> ruta de origen a copiar.

• dest <string> | <URL> ruta de destino a la que copiar.

• options <Object>

  • dereference <boolean> desreferenciar enlaces simbólicos. Predeterminado: false.
  • errorOnExist <boolean> cuando force es false y el destino existe, arroja un error. Predeterminado: false.
  • filter <Function> Función para filtrar archivos/directorios copiados. Devuelve true para copiar el elemento, false para ignorarlo. Al ignorar un directorio, todo su contenido también se omitirá. También puede devolver una Promise que se resuelve en true o false Predeterminado: undefined.
  • src <string> ruta de origen a copiar.
  • dest <string> ruta de destino a la que copiar.
  • Devuelve: <boolean> | <Promise> Un valor que se puede convertir a boolean o una Promise que se cumple con dicho valor.
  • force <boolean> sobrescribir archivo o directorio existente. La operación de copia ignorará los errores si establece esto en false y el destino existe. Utilice la opción errorOnExist para cambiar este comportamiento. Predeterminado: true.
  • mode <integer> modificadores para la operación de copia. Predeterminado: 0. Vea la bandera mode de fsPromises.copyFile().
  • preserveTimestamps <boolean> Cuando es true, se conservarán las marcas de tiempo de src. Predeterminado: false.
  • recursive <boolean> copiar directorios de forma recursiva Predeterminado: false
  • verbatimSymlinks <boolean> Cuando es true, se omitirá la resolución de ruta para los enlaces simbólicos. Predeterminado: false

• Devuelve: <Promise> Se cumple con undefined tras el éxito.

Copia asincrónicamente toda la estructura de directorios desde src hasta dest, incluyendo subdirectorios y archivos.

Al copiar un directorio a otro directorio, no se admiten globs y el comportamiento es similar a cp dir1/ dir2/.

fsPromises.glob(pattern[, options])

[Historial]

Versión	Cambios
v22.2.0	Se agregó soporte para withFileTypes como opción.
v22.0.0	Agregado en: v22.0.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

• pattern <string> | <string[]>

• options <Object>

  • cwd <string> directorio de trabajo actual. Predeterminado: process.cwd()
  • exclude <Function> Función para filtrar archivos/directorios. Devuelve true para excluir el elemento, false para incluirlo. Predeterminado: undefined.
  • withFileTypes <boolean> true si el glob debe devolver rutas como Dirents, false de lo contrario. Predeterminado: false.

• Devuelve: <AsyncIterator> Un AsyncIterator que produce las rutas de los archivos que coinciden con el patrón.

ESM

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

for await (const entry of glob('**/*.js')) console.log(entry)

CJS

const { glob } = require('node:fs/promises')

;(async () => {
  for await (const entry of glob('**/*.js')) console.log(entry)
})()

fsPromises.lchmod(path, mode)

Obsoleto desde: v10.0.0

• path <string> | <Buffer> | <URL>
• mode <integer>
• Devuelve: <Promise> Se cumple con undefined al finalizar correctamente.

Cambia los permisos en un enlace simbólico.

Este método solo se implementa en macOS.

fsPromises.lchown(path, uid, gid)

[Historial]

Versión	Cambios
v10.6.0	Esta API ya no está obsoleta.
v10.0.0	Añadido en: v10.0.0

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• Devuelve: <Promise> Se cumple con undefined al finalizar correctamente.

Cambia la propiedad en un enlace simbólico.

fsPromises.lutimes(path, atime, mtime)

Agregado en: v14.5.0, v12.19.0

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• Devuelve: <Promise> Se cumple con undefined al tener éxito.

Cambia los tiempos de acceso y modificación de un archivo de la misma manera que fsPromises.utimes(), con la diferencia de que si la ruta se refiere a un enlace simbólico, entonces el enlace no se desreferencia: en su lugar, se cambian las marcas de tiempo del propio enlace simbólico.

fsPromises.link(existingPath, newPath)

Agregado en: v10.0.0

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• Devuelve: <Promise> Se cumple con undefined al tener éxito.

Crea un nuevo enlace desde existingPath a newPath. Consulta la documentación de POSIX link(2) para obtener más detalles.

fsPromises.lstat(path[, options])

[Historial]

Versión	Cambios
v10.5.0	Acepta un objeto options adicional para especificar si los valores numéricos devueltos deben ser bigint.
v10.0.0	Agregado en: v10.0.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Indica si los valores numéricos en el objeto <fs.Stats> devuelto deben ser bigint. Predeterminado: false.

• Devuelve: <Promise> Se cumple con el objeto <fs.Stats> para el path de enlace simbólico dado.

Equivalente a fsPromises.stat() a menos que path se refiera a un enlace simbólico, en cuyo caso se realiza una estadística del propio enlace, no del archivo al que se refiere. Consulta el documento POSIX lstat(2) para obtener más detalles.

fsPromises.mkdir(path[, options])

Añadido en: v10.0.0

• path <string> | <Buffer> | <URL>

• options <Object> | <integer>

  • recursive <boolean> Predeterminado: false
  • mode <string> | <integer> No soportado en Windows. Predeterminado: 0o777.

• Devuelve: <Promise> En caso de éxito, se cumple con undefined si recursive es false, o la primera ruta de directorio creada si recursive es true.

Crea un directorio de forma asíncrona.

El argumento opcional options puede ser un entero que especifica mode (permiso y bits adhesivos), o un objeto con una propiedad mode y una propiedad recursive que indica si se deben crear directorios principales. Llamar a fsPromises.mkdir() cuando path es un directorio que existe resulta en un rechazo solo cuando recursive es falso.

ESM

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

try {
  const projectFolder = new URL('./test/project/', import.meta.url)
  const createDir = await mkdir(projectFolder, { recursive: true })

  console.log(`created ${createDir}`)
} catch (err) {
  console.error(err.message)
}

CJS

const { mkdir } = require('node:fs/promises')
const { join } = require('node:path')

async function makeDirectory() {
  const projectFolder = join(__dirname, 'test', 'project')
  const dirCreation = await mkdir(projectFolder, { recursive: true })

  console.log(dirCreation)
  return dirCreation
}

makeDirectory().catch(console.error)

fsPromises.mkdtemp(prefix[, options])

[Historial]

Versión	Cambios
v20.6.0, v18.19.0	El parámetro prefix ahora acepta buffers y URL.
v16.5.0, v14.18.0	El parámetro prefix ahora acepta una cadena vacía.
v10.0.0	Agregado en: v10.0.0

• prefix <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Predeterminado: 'utf8'

• Devuelve: <Promise> Se cumple con una cadena que contiene la ruta del sistema de archivos del directorio temporal recién creado.

Crea un directorio temporal único. Se genera un nombre de directorio único agregando seis caracteres aleatorios al final del prefix proporcionado. Debido a inconsistencias entre plataformas, evita los caracteres X al final de prefix. Algunas plataformas, especialmente las BSD, pueden devolver más de seis caracteres aleatorios y reemplazar los caracteres X al final de prefix con caracteres aleatorios.

El argumento options opcional puede ser una cadena que especifique una codificación o un objeto con una propiedad encoding que especifique la codificación de caracteres a utilizar.

import { mkdtemp } from 'node:fs/promises'
import { join } from 'node:path'
import { tmpdir } from 'node:os'

try {
  await mkdtemp(join(tmpdir(), 'foo-'))
} catch (err) {
  console.error(err)
}

El método fsPromises.mkdtemp() agregará los seis caracteres seleccionados aleatoriamente directamente a la cadena prefix. Por ejemplo, dado un directorio /tmp, si la intención es crear un directorio temporal dentro de /tmp, el prefix debe terminar con un separador de ruta específico de la plataforma (require('node:path').sep).

fsPromises.open(path, flags[, mode])

[Historial]

Versión	Cambios
v11.1.0	El argumento flags ahora es opcional y su valor predeterminado es 'r'.
v10.0.0	Agregado en: v10.0.0

• path <string> | <Buffer> | <URL>
• flags <string> | <number> Consulte el soporte de flags del sistema de archivos. Predeterminado: 'r'.
• mode <string> | <integer> Establece el modo de archivo (permiso y bits sticky) si se crea el archivo. Predeterminado: 0o666 (legible y grabable)
• Devuelve: <Promise> Se completa con un objeto <FileHandle>.

Abre un <FileHandle>.

Consulte la documentación POSIX open(2) para obtener más detalles.

Algunos caracteres (\< \> : " / \ | ? *) están reservados en Windows, como se documenta en Nombres de archivos, rutas y espacios de nombres. En NTFS, si el nombre del archivo contiene dos puntos, Node.js abrirá un flujo del sistema de archivos, como se describe en esta página de MSDN.

fsPromises.opendir(path[, options])

[Historial]

Versión	Cambios
v20.1.0, v18.17.0	Se añadió la opción recursive.
v13.1.0, v12.16.0	Se introdujo la opción bufferSize.
v12.12.0	Añadido en: v12.12.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • encoding <string> | <null> Predeterminado: 'utf8'
  • bufferSize <number> Número de entradas de directorio que se almacenan en búfer internamente al leer del directorio. Los valores más altos conducen a un mejor rendimiento pero a un mayor uso de memoria. Predeterminado: 32
  • recursive <boolean> El Dir resuelto será un <AsyncIterable> que contiene todos los sub archivos y directorios. Predeterminado: false

• Devuelve: <Promise> Se cumple con un <fs.Dir>.

Abre de forma asíncrona un directorio para el escaneo iterativo. Consulta la documentación de POSIX opendir(3) para obtener más detalles.

Crea un <fs.Dir>, que contiene todas las funciones adicionales para leer y limpiar el directorio.

La opción encoding establece la codificación para el path al abrir el directorio y las operaciones de lectura posteriores.

Ejemplo usando iteración asíncrona:

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

try {
  const dir = await opendir('./')
  for await (const dirent of dir) console.log(dirent.name)
} catch (err) {
  console.error(err)
}

Cuando se usa el iterador asíncrono, el objeto <fs.Dir> se cerrará automáticamente después de que el iterador salga.

fsPromises.readdir(path[, options])

[Historial]

Versión	Cambios
v20.1.0, v18.17.0	Se agregó la opción recursive.
v10.11.0	Se agregó la nueva opción withFileTypes.
v10.0.0	Agregado en: v10.0.0

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Predeterminado: 'utf8'
  • withFileTypes <boolean> Predeterminado: false
  • recursive <boolean> Si es true, lee el contenido de un directorio de forma recursiva. En modo recursivo, listará todos los archivos, subarchivos y directorios. Predeterminado: false.

• Devuelve: <Promise> Se cumple con un arreglo de los nombres de los archivos en el directorio excluyendo '.' y '..'.

Lee el contenido de un directorio.

El argumento opcional options puede ser una cadena que especifique una codificación, o un objeto con una propiedad encoding que especifique la codificación de caracteres que se utilizará para los nombres de archivo. Si la encoding se establece en 'buffer', los nombres de archivo devueltos se pasarán como objetos <Buffer>.

Si options.withFileTypes se establece en true, el arreglo devuelto contendrá objetos <fs.Dirent>.

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

try {
  const files = await readdir(path)
  for (const file of files) console.log(file)
} catch (err) {
  console.error(err)
}

fsPromises.readFile(path[, options])

[Historial]

Versión	Cambios
v15.2.0, v14.17.0	El argumento options puede incluir un AbortSignal para abortar una solicitud readFile en curso.
v10.0.0	Añadido en: v10.0.0

• path <string> | <Buffer> | <URL> | <FileHandle> nombre de archivo o FileHandle

• options <Object> | <string>

  • encoding <string> | <null> Predeterminado: null
  • flag <string> Véase soporte de flags del sistema de archivos. Predeterminado: 'r'.
  • signal <AbortSignal> permite abortar un readFile en curso

• Devuelve: <Promise> Se cumple con el contenido del archivo.

Lee de forma asíncrona todo el contenido de un archivo.

Si no se especifica ninguna codificación (usando options.encoding), los datos se devuelven como un objeto <Buffer>. De lo contrario, los datos serán una cadena.

Si options es una cadena, especifica la codificación.

Cuando la path es un directorio, el comportamiento de fsPromises.readFile() es específico de la plataforma. En macOS, Linux y Windows, la promesa será rechazada con un error. En FreeBSD, se devolverá una representación del contenido del directorio.

Un ejemplo de lectura de un archivo package.json ubicado en el mismo directorio del código en ejecución:

ESM

import { readFile } from 'node:fs/promises'
try {
  const filePath = new URL('./package.json', import.meta.url)
  const contents = await readFile(filePath, { encoding: 'utf8' })
  console.log(contents)
} catch (err) {
  console.error(err.message)
}

CJS

const { readFile } = require('node:fs/promises')
const { resolve } = require('node:path')
async function logFile() {
  try {
    const filePath = resolve('./package.json')
    const contents = await readFile(filePath, { encoding: 'utf8' })
    console.log(contents)
  } catch (err) {
    console.error(err.message)
  }
}
logFile()

Es posible abortar un readFile en curso usando un <AbortSignal>. Si se aborta una solicitud, la promesa devuelta se rechaza con un AbortError:

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

try {
  const controller = new AbortController()
  const { signal } = controller
  const promise = readFile(fileName, { signal })

  // Aborta la solicitud antes de que se cumpla la promesa.
  controller.abort()

  await promise
} catch (err) {
  // Cuando se aborta una solicitud, err es un AbortError
  console.error(err)
}

Abortar una solicitud en curso no aborta las solicitudes individuales del sistema operativo, sino el almacenamiento en búfer interno que realiza fs.readFile.

Cualquier <FileHandle> especificado tiene que soportar la lectura.

fsPromises.readlink(path[, options])

Agregado en: v10.0.0

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Predeterminado: 'utf8'

• Devuelve: <Promise> Se cumple con la linkString en caso de éxito.

Lee el contenido del enlace simbólico al que hace referencia path. Consulta la documentación POSIX readlink(2) para obtener más detalles. La promesa se cumple con la linkString en caso de éxito.

El argumento opcional options puede ser una cadena que especifique una codificación, o un objeto con una propiedad encoding que especifique la codificación de caracteres que se utilizará para la ruta del enlace devuelta. Si la encoding se establece en 'buffer', la ruta del enlace devuelta se pasará como un objeto <Buffer>.

fsPromises.realpath(path[, options])

Agregado en: v10.0.0

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Predeterminado: 'utf8'

• Devuelve: <Promise> Se cumple con la ruta resuelta en caso de éxito.

Determina la ubicación real de path utilizando la misma semántica que la función fs.realpath.native().

Solo se admiten las rutas que se pueden convertir a cadenas UTF8.

El argumento opcional options puede ser una cadena que especifique una codificación, o un objeto con una propiedad encoding que especifique la codificación de caracteres que se utilizará para la ruta. Si la encoding se establece en 'buffer', la ruta devuelta se pasará como un objeto <Buffer>.

En Linux, cuando Node.js está vinculado a musl libc, el sistema de archivos procfs debe montarse en /proc para que esta función funcione. Glibc no tiene esta restricción.

fsPromises.rename(oldPath, newPath)

Añadido en: v10.0.0

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• Devuelve: <Promise> Se cumple con undefined tras el éxito.

Renombra oldPath a newPath.

fsPromises.rmdir(path[, options])

[Historial]

Versión	Cambios
v16.0.0	El uso de fsPromises.rmdir(path, { recursive: true }) en un path que es un archivo ya no está permitido y resulta en un error ENOENT en Windows y un error ENOTDIR en POSIX.
v16.0.0	El uso de fsPromises.rmdir(path, { recursive: true }) en un path que no existe ya no está permitido y resulta en un error ENOENT.
v16.0.0	La opción recursive está obsoleta, usarla desencadena una advertencia de obsolescencia.
v14.14.0	La opción recursive está obsoleta, use fsPromises.rm en su lugar.
v13.3.0, v12.16.0	La opción maxBusyTries se ha renombrado a maxRetries, y su valor predeterminado es 0. La opción emfileWait se ha eliminado, y los errores EMFILE usan la misma lógica de reintento que otros errores. Ahora se admite la opción retryDelay. Ahora se reintentan los errores ENFILE.
v12.10.0	Ahora se admiten las opciones recursive, maxBusyTries y emfileWait.
v10.0.0	Añadido en: v10.0.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • maxRetries <integer> Si se encuentra un error EBUSY, EMFILE, ENFILE, ENOTEMPTY o EPERM, Node.js reintenta la operación con una espera de retroceso lineal de retryDelay milisegundos más larga en cada intento. Esta opción representa el número de reintentos. Esta opción se ignora si la opción recursive no es true. Predeterminado: 0.
  • recursive <boolean> Si es true, realiza una eliminación de directorio recursiva. En modo recursivo, las operaciones se vuelven a intentar en caso de fallo. Predeterminado: false. Obsoleto.
  • retryDelay <integer> La cantidad de tiempo en milisegundos que se debe esperar entre reintentos. Esta opción se ignora si la opción recursive no es true. Predeterminado: 100.

• Devuelve: <Promise> Se cumple con undefined tras el éxito.

Elimina el directorio identificado por path.

El uso de fsPromises.rmdir() en un archivo (no un directorio) hace que la promesa se rechace con un error ENOENT en Windows y un error ENOTDIR en POSIX.

Para obtener un comportamiento similar al comando Unix rm -rf, utilice fsPromises.rm() con las opciones { recursive: true, force: true }.

fsPromises.rm(path[, options])

Añadido en: v14.14.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • force <boolean> Cuando es true, las excepciones se ignorarán si path no existe. Predeterminado: false.
  • maxRetries <integer> Si se encuentra un error EBUSY, EMFILE, ENFILE, ENOTEMPTY o EPERM, Node.js volverá a intentar la operación con una espera de retroceso lineal de retryDelay milisegundos más en cada intento. Esta opción representa el número de reintentos. Esta opción se ignora si la opción recursive no es true. Predeterminado: 0.
  • recursive <boolean> Si es true, realiza una eliminación de directorio recursiva. En el modo recursivo, las operaciones se vuelven a intentar en caso de fallo. Predeterminado: false.
  • retryDelay <integer> La cantidad de tiempo en milisegundos que se debe esperar entre reintentos. Esta opción se ignora si la opción recursive no es true. Predeterminado: 100.

• Devuelve: <Promise> Se cumple con undefined tras el éxito.

Elimina archivos y directorios (siguiendo el modelo de la utilidad estándar POSIX rm).

fsPromises.stat(path[, options])

[Historial]

Versión	Cambios
v10.5.0	Acepta un objeto options adicional para especificar si los valores numéricos devueltos deben ser bigint.
v10.0.0	Añadido en: v10.0.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Indica si los valores numéricos en el objeto <fs.Stats> devuelto deben ser bigint. Predeterminado: false.

• Devuelve: <Promise> Se cumple con el objeto <fs.Stats> para el path dado.

fsPromises.statfs(path[, options])

Agregado en: v19.6.0, v18.15.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Indica si los valores numéricos en el objeto <fs.StatFs> devuelto deben ser bigint. Predeterminado: false.

• Devuelve: <Promise> Se cumple con el objeto <fs.StatFs> para el path dado.

fsPromises.symlink(target, path[, type])

[Historial]

Versión	Cambios
v19.0.0	Si el argumento type es null u omitido, Node.js autodectectará el tipo de target y seleccionará automáticamente dir o file.
v10.0.0	Agregado en: v10.0.0

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> | <null> Predeterminado: null
• Devuelve: <Promise> Se cumple con undefined en caso de éxito.

Crea un enlace simbólico.

El argumento type solo se utiliza en plataformas Windows y puede ser uno de 'dir', 'file' o 'junction'. Si el argumento type es null, Node.js autodectectará el tipo de target y usará 'file' o 'dir'. Si el target no existe, se utilizará 'file'. Los puntos de unión de Windows requieren que la ruta de destino sea absoluta. Cuando se usa 'junction', el argumento target se normalizará automáticamente a la ruta absoluta. Los puntos de unión en volúmenes NTFS solo pueden apuntar a directorios.

fsPromises.truncate(path[, len])

Agregado en: v10.0.0

• path <string> | <Buffer> | <URL>
• len <integer> Predeterminado: 0
• Devuelve: <Promise> Se resuelve con undefined tras el éxito.

Trunca (acorta o extiende la longitud) del contenido en path a len bytes.

fsPromises.unlink(path)

Agregado en: v10.0.0

• path <string> | <Buffer> | <URL>
• Devuelve: <Promise> Se resuelve con undefined tras el éxito.

Si path se refiere a un enlace simbólico, entonces el enlace se elimina sin afectar al archivo o directorio al que se refiere dicho enlace. Si el path se refiere a una ruta de archivo que no es un enlace simbólico, el archivo se elimina. Consulte la documentación POSIX unlink(2) para obtener más detalles.

fsPromises.utimes(path, atime, mtime)

Agregado en: v10.0.0

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• Devuelve: <Promise> Se cumple con undefined al tener éxito.

Cambia las marcas de tiempo del sistema de archivos del objeto al que hace referencia path.

Los argumentos atime y mtime siguen estas reglas:

• Los valores pueden ser números que representan el tiempo de la época de Unix, Dates o una cadena numérica como '123456789.0'.
• Si el valor no se puede convertir a un número o es NaN, Infinity o -Infinity, se generará un Error.

fsPromises.watch(filename[, options])

Agregado en: v15.9.0, v14.18.0

• filename <string> | <Buffer> | <URL>

• options <string> | <Object>

  • persistent <boolean> Indica si el proceso debe continuar ejecutándose mientras se estén vigilando archivos. Predeterminado: true.
  • recursive <boolean> Indica si se deben vigilar todos los subdirectorios, o solo el directorio actual. Esto se aplica cuando se especifica un directorio, y solo en plataformas compatibles (ver advertencias). Predeterminado: false.
  • encoding <string> Especifica la codificación de caracteres que se utilizará para el nombre de archivo pasado al listener. Predeterminado: 'utf8'.
  • signal <AbortSignal> Un <AbortSignal> usado para señalar cuándo se debe detener el observador.

• Devuelve: <AsyncIterator> de objetos con las siguientes propiedades:

  • eventType <string> El tipo de cambio
  • filename <string> | <Buffer> | <null> El nombre del archivo cambiado.

Devuelve un iterador asíncrono que observa los cambios en filename, donde filename es un archivo o un directorio.

const { watch } = require('node:fs/promises')

const ac = new AbortController()
const { signal } = ac
setTimeout(() => ac.abort(), 10000)

;(async () => {
  try {
    const watcher = watch(__filename, { signal })
    for await (const event of watcher) console.log(event)
  } catch (err) {
    if (err.name === 'AbortError') return
    throw err
  }
})()

En la mayoría de las plataformas, se emite 'rename' cada vez que un nombre de archivo aparece o desaparece en el directorio.

Todas las advertencias para fs.watch() también se aplican a fsPromises.watch().

fsPromises.writeFile(file, data[, options])

[Historial]

Versión	Cambios
v21.0.0, v20.10.0	Ahora se admite la opción flush.
v15.14.0, v14.18.0	El argumento data admite AsyncIterable, Iterable y Stream.
v15.2.0, v14.17.0	El argumento de opciones puede incluir un AbortSignal para abortar una solicitud de writeFile en curso.
v14.0.0	El parámetro data ya no forzará la entrada no admitida a cadenas.
v10.0.0	Añadido en: v10.0.0

• file <string> | <Buffer> | <URL> | <FileHandle> nombre de archivo o FileHandle

• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>

• options <Object> | <string>

  • encoding <string> | <null> Predeterminado: 'utf8'
  • mode <integer> Predeterminado: 0o666
  • flag <string> Ver soporte de flags del sistema de archivos. Predeterminado: 'w'.
  • flush <boolean> Si todos los datos se escriben correctamente en el archivo y flush es true, se utiliza filehandle.sync() para vaciar los datos. Predeterminado: false.
  • signal <AbortSignal> permite abortar una writeFile en curso

• Devuelve: <Promise> Se cumple con undefined si tiene éxito.

Escribe datos de forma asíncrona en un archivo, reemplazando el archivo si ya existe. data puede ser una cadena, un búfer, un objeto <AsyncIterable> o un objeto <Iterable>.

La opción encoding se ignora si data es un búfer.

Si options es una cadena, especifica la codificación.

La opción mode solo afecta al archivo recién creado. Consulta fs.open() para obtener más detalles.

Cualquier <FileHandle> especificado debe admitir la escritura.

No es seguro usar fsPromises.writeFile() varias veces en el mismo archivo sin esperar a que la promesa se resuelva.

De forma similar a fsPromises.readFile - fsPromises.writeFile es un método de conveniencia que realiza varias llamadas write internamente para escribir el búfer que se le pasa. Para código sensible al rendimiento, considera usar fs.createWriteStream() o filehandle.createWriteStream().

Es posible usar un <AbortSignal> para cancelar un fsPromises.writeFile(). La cancelación es de "mejor esfuerzo", y es probable que todavía se escriba una cierta cantidad de datos.

import { writeFile } from 'node:fs/promises'
import { Buffer } from 'node:buffer'

try {
  const controller = new AbortController()
  const { signal } = controller
  const data = new Uint8Array(Buffer.from('Hello Node.js'))
  const promise = writeFile('message.txt', data, { signal })

  // Abortar la solicitud antes de que se resuelva la promesa.
  controller.abort()

  await promise
} catch (err) {
  // Cuando una solicitud se aborta - err es un AbortError
  console.error(err)
}

Abortar una solicitud en curso no aborta las solicitudes individuales del sistema operativo, sino el almacenamiento en búfer interno que realiza fs.writeFile.

fsPromises.constants

Agregado en: v18.4.0, v16.17.0

• <Objeto>

Devuelve un objeto que contiene constantes de uso común para las operaciones del sistema de archivos. El objeto es el mismo que fs.constants. Consulta Constantes de FS para obtener más detalles.

API de Callback

Las API de callback realizan todas las operaciones de forma asíncrona, sin bloquear el bucle de eventos, y luego invocan una función de callback al finalizar o producirse un error.

Las API de callback utilizan el threadpool subyacente de Node.js para realizar operaciones del sistema de archivos fuera del hilo del bucle de eventos. Estas operaciones no están sincronizadas ni son seguras para subprocesos. Se debe tener cuidado al realizar múltiples modificaciones concurrentes en el mismo archivo o se puede producir una corrupción de datos.

fs.access(path[, mode], callback)

[Historial]

Versión	Cambios
v20.8.0	Las constantes fs.F_OK, fs.R_OK, fs.W_OK y fs.X_OK que estaban presentes directamente en fs están en desuso.
v18.0.0	Pasar un callback no válido al argumento callback ahora arroja ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v7.6.0	El parámetro path puede ser un objeto URL WHATWG usando el protocolo file:.
v6.3.0	Las constantes como fs.R_OK, etc., que estaban presentes directamente en fs se movieron a fs.constants como una desaprobación suave. Por lo tanto, para Node.js \< v6.3.0 utiliza fs para acceder a esas constantes, o haz algo como `(fs.constants
v0.11.15	Agregado en: v0.11.15

• path <string> | <Buffer> | <URL>
• mode <integer> Predeterminado: fs.constants.F_OK
• callback <Función>
  • err <Error>

Prueba los permisos de un usuario para el archivo o directorio especificado por path. El argumento mode es un entero opcional que especifica las comprobaciones de accesibilidad que se van a realizar. mode debe ser el valor fs.constants.F_OK o una máscara que consista en el OR bit a bit de cualquiera de fs.constants.R_OK, fs.constants.W_OK y fs.constants.X_OK (por ejemplo, fs.constants.W_OK | fs.constants.R_OK). Consulta Constantes de acceso a archivos para ver los posibles valores de mode.

El argumento final, callback, es una función de callback que se invoca con un posible argumento de error. Si alguna de las comprobaciones de accesibilidad falla, el argumento de error será un objeto Error. Los siguientes ejemplos comprueban si package.json existe y si es legible o grabable.

import { access, constants } from 'node:fs'

const file = 'package.json'

// Comprobar si el archivo existe en el directorio actual.
access(file, constants.F_OK, err => {
  console.log(`${file} ${err ? 'no existe' : 'existe'}`)
})

// Comprobar si el archivo es legible.
access(file, constants.R_OK, err => {
  console.log(`${file} ${err ? 'no es legible' : 'es legible'}`)
})

// Comprobar si el archivo es grabable.
access(file, constants.W_OK, err => {
  console.log(`${file} ${err ? 'no es grabable' : 'es grabable'}`)
})

// Comprobar si el archivo es legible y grabable.
access(file, constants.R_OK | constants.W_OK, err => {
  console.log(`${file} ${err ? 'no es' : 'es'} legible y grabable`)
})

No utilices fs.access() para comprobar la accesibilidad de un archivo antes de llamar a fs.open(), fs.readFile() o fs.writeFile(). Hacerlo introduce una condición de carrera, ya que otros procesos pueden cambiar el estado del archivo entre las dos llamadas. En su lugar, el código de usuario debe abrir/leer/escribir el archivo directamente y manejar el error que se produzca si el archivo no es accesible.

escritura (NO RECOMENDADO)

import { access, open, close } from 'node:fs'

access('myfile', err => {
  if (!err) {
    console.error('myfile ya existe')
    return
  }

  open('myfile', 'wx', (err, fd) => {
    if (err) throw err

    try {
      writeMyData(fd)
    } finally {
      close(fd, err => {
        if (err) throw err
      })
    }
  })
})

escritura (RECOMENDADO)

import { open, close } from 'node:fs'

open('myfile', 'wx', (err, fd) => {
  if (err) {
    if (err.code === 'EEXIST') {
      console.error('myfile ya existe')
      return
    }

    throw err
  }

  try {
    writeMyData(fd)
  } finally {
    close(fd, err => {
      if (err) throw err
    })
  }
})

lectura (NO RECOMENDADO)

import { access, open, close } from 'node:fs'
access('myfile', err => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile no existe')
      return
    }

    throw err
  }

  open('myfile', 'r', (err, fd) => {
    if (err) throw err

    try {
      readMyData(fd)
    } finally {
      close(fd, err => {
        if (err) throw err
      })
    }
  })
})

lectura (RECOMENDADO)

import { open, close } from 'node:fs'

open('myfile', 'r', (err, fd) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile no existe')
      return
    }

    throw err
  }

  try {
    readMyData(fd)
  } finally {
    close(fd, err => {
      if (err) throw err
    })
  }
})

Los ejemplos "no recomendados" anteriores comprueban la accesibilidad y luego usan el archivo; los ejemplos "recomendados" son mejores porque usan el archivo directamente y manejan el error, si lo hay.

En general, comprueba la accesibilidad de un archivo solo si el archivo no se va a utilizar directamente, por ejemplo, cuando su accesibilidad es una señal de otro proceso.

En Windows, las políticas de control de acceso (ACL) en un directorio pueden limitar el acceso a un archivo o directorio. Sin embargo, la función fs.access() no comprueba la ACL y, por lo tanto, puede informar de que una ruta es accesible incluso si la ACL restringe al usuario la lectura o escritura en ella.

fs.appendFile(path, data[, options], callback)

[Historial]

Versión	Cambios
v21.1.0, v20.10.0	Ahora se admite la opción flush.
v18.0.0	Pasar una devolución de llamada no válida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de desaprobación con el ID DEP0013.
v7.0.0	El objeto options pasado nunca se modificará.
v5.0.0	El parámetro file ahora puede ser un descriptor de archivo.
v0.6.7	Agregado en: v0.6.7

• path <string> | <Buffer> | <URL> | <number> nombre de archivo o descriptor de archivo

• data <string> | <Buffer>

• options <Object> | <string>

  • encoding <string> | <null> Predeterminado: 'utf8'
  • mode <integer> Predeterminado: 0o666
  • flag <string> Consulte el soporte de flags del sistema de archivos. Predeterminado: 'a'.
  • flush <boolean> Si es true, el descriptor de archivo subyacente se vacía antes de cerrarlo. Predeterminado: false.

• callback <Function>

  • err <Error>

Anexa datos de forma asíncrona a un archivo, creando el archivo si aún no existe. data puede ser una cadena o un <Buffer>.

La opción mode solo afecta al archivo recién creado. Consulte fs.open() para obtener más detalles.

import { appendFile } from 'node:fs'

appendFile('message.txt', 'datos para anexar', err => {
  if (err) throw err
  console.log('¡Los "datos para anexar" fueron anexados al archivo!')
})

Si options es una cadena, entonces especifica la codificación:

import { appendFile } from 'node:fs'

appendFile('message.txt', 'datos para anexar', 'utf8', callback)

El path se puede especificar como un descriptor de archivo numérico que se ha abierto para anexar (usando fs.open() o fs.openSync()). El descriptor de archivo no se cerrará automáticamente.

import { open, close, appendFile } from 'node:fs'

function closeFd(fd) {
  close(fd, err => {
    if (err) throw err
  })
}

open('message.txt', 'a', (err, fd) => {
  if (err) throw err

  try {
    appendFile(fd, 'datos para anexar', 'utf8', err => {
      closeFd(fd)
      if (err) throw err
    })
  } catch (err) {
    closeFd(fd)
    throw err
  }
})

fs.chmod(path, mode, callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar una devolución de llamada no válida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.6.0	El parámetro path puede ser un objeto WHATWG URL usando el protocolo file:.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de obsolescencia con ID DEP0013.
v0.1.30	Añadido en: v0.1.30

• path <string> | <Buffer> | <URL>
• mode <string> | <integer>
• callback <Function>
  • err <Error>

Cambia de forma asíncrona los permisos de un archivo. No se proporcionan argumentos a la devolución de llamada de finalización, aparte de una posible excepción.

Consulta la documentación de POSIX chmod(2) para más detalles.

import { chmod } from 'node:fs'

chmod('my_file.txt', 0o775, err => {
  if (err) throw err
  console.log('¡Los permisos para el archivo "my_file.txt" han sido cambiados!')
})

Modos de archivo

El argumento mode utilizado tanto en los métodos fs.chmod() como en fs.chmodSync() es una máscara de bits numérica creada utilizando un OR lógico de las siguientes constantes:

Constante	Octal	Descripción
fs.constants.S_IRUSR	0o400	lectura por el propietario
fs.constants.S_IWUSR	0o200	escritura por el propietario
fs.constants.S_IXUSR	0o100	ejecución/búsqueda por el propietario
fs.constants.S_IRGRP	0o40	lectura por el grupo
fs.constants.S_IWGRP	0o20	escritura por el grupo
fs.constants.S_IXGRP	0o10	ejecución/búsqueda por el grupo
fs.constants.S_IROTH	0o4	lectura por otros
fs.constants.S_IWOTH	0o2	escritura por otros
fs.constants.S_IXOTH	0o1	ejecución/búsqueda por otros

Un método más sencillo para construir el mode es utilizar una secuencia de tres dígitos octales (por ejemplo, 765). El dígito más a la izquierda (7 en el ejemplo), especifica los permisos para el propietario del archivo. El dígito del medio (6 en el ejemplo), especifica los permisos para el grupo. El dígito más a la derecha (5 en el ejemplo), especifica los permisos para otros.

Número	Descripción
7	lectura, escritura y ejecución
6	lectura y escritura
5	lectura y ejecución
4	solo lectura
3	escritura y ejecución
2	solo escritura
1	solo ejecución
0	sin permiso

Por ejemplo, el valor octal 0o765 significa:

• El propietario puede leer, escribir y ejecutar el archivo.
• El grupo puede leer y escribir el archivo.
• Otros pueden leer y ejecutar el archivo.

Cuando se utilizan números sin procesar donde se esperan modos de archivo, cualquier valor mayor que 0o777 puede resultar en comportamientos específicos de la plataforma que no son compatibles para funcionar de manera consistente. Por lo tanto, constantes como S_ISVTX, S_ISGID o S_ISUID no se exponen en fs.constants.

Advertencias: en Windows solo se puede cambiar el permiso de escritura, y la distinción entre los permisos de grupo, propietario u otros no está implementada.

fs.chown(path, uid, gid, callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar una devolución de llamada no válida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.6.0	El parámetro path puede ser un objeto WHATWG URL utilizando el protocolo file:.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de obsolescencia con el id DEP0013.
v0.1.97	Agregado en: v0.1.97

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• callback <Function>
  • err <Error>

Cambia asincrónicamente el propietario y el grupo de un archivo. No se dan argumentos aparte de una posible excepción a la devolución de llamada de finalización.

Consulte la documentación POSIX chown(2) para obtener más detalles.

fs.close(fd[, callback])

[Historial]

Versión	Cambios
v18.0.0	Pasar una callback inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v15.9.0, v14.17.0	Ahora se usa una callback por defecto si no se proporciona ninguna.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de obsolescencia con el id DEP0013.
v0.0.2	Añadido en: v0.0.2

• fd <integer>
• callback <Function>
  • err <Error>

Cierra el descriptor de archivo. No se dan argumentos a la callback de finalización, salvo una posible excepción.

Llamar a fs.close() en cualquier descriptor de archivo (fd) que esté actualmente en uso a través de cualquier otra operación fs puede llevar a un comportamiento indefinido.

Consulta la documentación POSIX close(2) para más detalles.

fs.copyFile(src, dest[, mode], callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar una devolución de llamada inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v14.0.0	Se cambió el argumento flags a mode y se impuso una validación de tipo más estricta.
v8.5.0	Añadido en: v8.5.0

• src <string> | <Buffer> | <URL> nombre de archivo fuente a copiar
• dest <string> | <Buffer> | <URL> nombre de archivo de destino de la operación de copia
• mode <integer> modificadores para la operación de copia. Predeterminado: 0.
• callback <Function>
  • err <Error>

Copia asíncronamente src a dest. Por defecto, dest se sobrescribe si ya existe. No se dan otros argumentos a la función de devolución de llamada que una posible excepción. Node.js no garantiza la atomicidad de la operación de copia. Si se produce un error después de que el archivo de destino se haya abierto para escritura, Node.js intentará eliminar el destino.

mode es un entero opcional que especifica el comportamiento de la operación de copia. Es posible crear una máscara que consiste en la operación OR bit a bit de dos o más valores (por ejemplo, fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE).

• fs.constants.COPYFILE_EXCL: La operación de copia fallará si dest ya existe.
• fs.constants.COPYFILE_FICLONE: La operación de copia intentará crear un reflink de copia sobre escritura. Si la plataforma no admite la copia sobre escritura, se utiliza un mecanismo de copia de reserva.
• fs.constants.COPYFILE_FICLONE_FORCE: La operación de copia intentará crear un reflink de copia sobre escritura. Si la plataforma no admite la copia sobre escritura, la operación fallará.

import { copyFile, constants } from 'node:fs'

function callback(err) {
  if (err) throw err
  console.log('source.txt se copió a destination.txt')
}

// destination.txt se creará o sobrescribirá por defecto.
copyFile('source.txt', 'destination.txt', callback)

// Al usar COPYFILE_EXCL, la operación fallará si destination.txt existe.
copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL, callback)

fs.cp(src, dest[, options], callback)

[Historial]

Versión	Cambios
v22.3.0	Esta API ya no es experimental.
v20.1.0, v18.17.0	Acepta una opción mode adicional para especificar el comportamiento de copia como el argumento mode de fs.copyFile().
v18.0.0	Pasar una devolución de llamada inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v17.6.0, v16.15.0	Acepta una opción verbatimSymlinks adicional para especificar si se debe realizar la resolución de rutas para los enlaces simbólicos.
v16.7.0	Añadido en: v16.7.0

• src <string> | <URL> ruta de origen para copiar.

• dest <string> | <URL> ruta de destino para copiar.

• options <Object>

  • dereference <boolean> desreferenciar enlaces simbólicos. Predeterminado: false.

  • errorOnExist <boolean> cuando force es false, y el destino existe, lanza un error. Predeterminado: false.

  • filter <Function> Función para filtrar archivos/directorios copiados. Devuelve true para copiar el elemento, false para ignorarlo. Al ignorar un directorio, todo su contenido también se omitirá. También puede devolver una Promise que se resuelve en true o false. Predeterminado: undefined.

  • src <string> ruta de origen para copiar.

  • dest <string> ruta de destino para copiar.

  • Devuelve: <boolean> | <Promise> Un valor que se puede forzar a boolean o una Promise que se cumple con dicho valor.

  • force <boolean> sobreescribir archivo o directorio existente. La operación de copia ignorará los errores si establece esto en falso y el destino existe. Use la opción errorOnExist para cambiar este comportamiento. Predeterminado: true.

  • mode <integer> modificadores para la operación de copia. Predeterminado: 0. Ver bandera mode de fs.copyFile().

  • preserveTimestamps <boolean> Cuando true se conservarán las marcas de tiempo de src. Predeterminado: false.

  • recursive <boolean> copiar directorios recursivamente. Predeterminado: false

  • verbatimSymlinks <boolean> Cuando true, se omitirá la resolución de rutas para los enlaces simbólicos. Predeterminado: false

• callback <Function>

  • err <Error>

Copia asíncronamente toda la estructura de directorios de src a dest, incluidos subdirectorios y archivos.

Al copiar un directorio a otro directorio, los comodines no son compatibles y el comportamiento es similar a cp dir1/ dir2/.

fs.createReadStream(path[, options])

[Historial]

Versión	Cambios
v16.10.0	La opción fs no necesita el método open si se proporcionó un fd.
v16.10.0	La opción fs no necesita el método close si autoClose es false.
v15.5.0	Se agregó soporte para AbortSignal.
v15.4.0	La opción fd acepta argumentos de FileHandle.
v14.0.0	Se cambió el valor predeterminado de emitClose a true.
v13.6.0, v12.17.0	Las opciones fs permiten anular la implementación de fs utilizada.
v12.10.0	Se habilitó la opción emitClose.
v11.0.0	Se imponen nuevas restricciones en start y end, lanzando errores más apropiados en los casos en que no podemos manejar razonablemente los valores de entrada.
v7.6.0	El parámetro path puede ser un objeto URL WHATWG usando el protocolo file:.
v7.0.0	El objeto options pasado nunca se modificará.
v2.3.0	El objeto options pasado puede ser una cadena ahora.
v0.1.31	Añadido en: v0.1.31

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • flags <string> Ver soporte de flags del sistema de archivos. Predeterminado: 'r'.
  • encoding <string> Predeterminado: null
  • fd <integer> | <FileHandle> Predeterminado: null
  • mode <integer> Predeterminado: 0o666
  • autoClose <boolean> Predeterminado: true
  • emitClose <boolean> Predeterminado: true
  • start <integer>
  • end <integer> Predeterminado: Infinity
  • highWaterMark <integer> Predeterminado: 64 * 1024
  • fs <Object> | <null> Predeterminado: null
  • signal <AbortSignal> | <null> Predeterminado: null

• Devuelve: <fs.ReadStream>

options puede incluir los valores start y end para leer un rango de bytes del archivo en lugar del archivo completo. Tanto start como end son inclusivos y comienzan a contar desde 0, los valores permitidos están en el rango [0, Number.MAX_SAFE_INTEGER]. Si se especifica fd y se omite o es undefined start, fs.createReadStream() lee secuencialmente desde la posición actual del archivo. La encoding puede ser cualquiera de las aceptadas por <Buffer>.

Si se especifica fd, ReadStream ignorará el argumento path y usará el descriptor de archivo especificado. Esto significa que no se emitirá ningún evento 'open'. fd debe ser de bloqueo; los fd no bloqueantes deben pasarse a <net.Socket>.

Si fd apunta a un dispositivo de caracteres que solo admite lecturas de bloqueo (como el teclado o la tarjeta de sonido), las operaciones de lectura no finalizan hasta que haya datos disponibles. Esto puede evitar que el proceso salga y que la transmisión se cierre de forma natural.

De forma predeterminada, la transmisión emitirá un evento 'close' después de que se haya destruido. Establezca la opción emitClose en false para cambiar este comportamiento.

Al proporcionar la opción fs, es posible anular las implementaciones fs correspondientes para open, read y close. Al proporcionar la opción fs, se requiere una anulación para read. Si no se proporciona fd, también se requiere una anulación para open. Si autoClose es true, también se requiere una anulación para close.

import { createReadStream } from 'node:fs'

// Crear un flujo desde algún dispositivo de caracteres.
const stream = createReadStream('/dev/input/event0')
setTimeout(() => {
  stream.close() // Esto puede no cerrar el flujo.
  // Marcar artificialmente el fin del flujo, como si el recurso subyacente hubiera
  // indicado el fin del archivo por sí mismo, permite que el flujo se cierre.
  // Esto no cancela las operaciones de lectura pendientes, y si hay una operación de este tipo,
  // el proceso puede que todavía no pueda salir correctamente
  // hasta que termine.
  stream.push(null)
  stream.read(0)
}, 100)

Si autoClose es falso, el descriptor de archivo no se cerrará, incluso si hay un error. Es responsabilidad de la aplicación cerrarlo y asegurarse de que no haya ninguna fuga de descriptor de archivo. Si autoClose se establece en true (comportamiento predeterminado), en 'error' o 'end' el descriptor de archivo se cerrará automáticamente.

mode establece el modo de archivo (permisos y bits pegajosos), pero solo si se creó el archivo.

Un ejemplo para leer los últimos 10 bytes de un archivo que tiene 100 bytes de longitud:

import { createReadStream } from 'node:fs'

createReadStream('sample.txt', { start: 90, end: 99 })

Si options es una cadena, especifica la codificación.

fs.createWriteStream(path[, options])

[Historial]

Versión	Cambios
v21.0.0, v20.10.0	Ahora se admite la opción flush.
v16.10.0	La opción fs no necesita el método open si se proporcionó un fd.
v16.10.0	La opción fs no necesita el método close si autoClose es false.
v15.5.0	Se agrega soporte para AbortSignal.
v15.4.0	La opción fd acepta argumentos de FileHandle.
v14.0.0	Se cambia el valor predeterminado de emitClose a true.
v13.6.0, v12.17.0	Las opciones fs permiten anular la implementación de fs utilizada.
v12.10.0	Se habilita la opción emitClose.
v7.6.0	El parámetro path puede ser un objeto URL WHATWG que utiliza el protocolo file:.
v7.0.0	El objeto options pasado nunca se modificará.
v5.5.0	Ahora se admite la opción autoClose.
v2.3.0	El objeto options pasado puede ser una cadena ahora.
v0.1.31	Añadido en: v0.1.31

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • flags <string> Ver soporte de indicadores del sistema de archivos. Predeterminado: 'w'.
  • encoding <string> Predeterminado: 'utf8'
  • fd <integer> | <FileHandle> Predeterminado: null
  • mode <integer> Predeterminado: 0o666
  • autoClose <boolean> Predeterminado: true
  • emitClose <boolean> Predeterminado: true
  • start <integer>
  • fs <Object> | <null> Predeterminado: null
  • signal <AbortSignal> | <null> Predeterminado: null
  • highWaterMark <number> Predeterminado: 16384
  • flush <boolean> Si es true, el descriptor de archivo subyacente se vacía antes de cerrarlo. Predeterminado: false.

• Devuelve: <fs.WriteStream>

options también puede incluir una opción start para permitir escribir datos en alguna posición después del comienzo del archivo, los valores permitidos están en el rango [0, Number.MAX_SAFE_INTEGER]. Modificar un archivo en lugar de reemplazarlo puede requerir que la opción flags se establezca en r+ en lugar del valor predeterminado w. La codificación puede ser cualquiera de las aceptadas por <Buffer>.

Si autoClose se establece en true (comportamiento predeterminado) en 'error' o 'finish', el descriptor de archivo se cerrará automáticamente. Si autoClose es false, el descriptor de archivo no se cerrará, incluso si hay un error. Es responsabilidad de la aplicación cerrarlo y asegurarse de que no haya fugas de descriptores de archivo.

De forma predeterminada, la secuencia emitirá un evento 'close' después de que se haya destruido. Establezca la opción emitClose en false para cambiar este comportamiento.

Al proporcionar la opción fs, es posible anular las implementaciones de fs correspondientes para open, write, writev y close. Anular write() sin writev() puede reducir el rendimiento, ya que se deshabilitarán algunas optimizaciones (_writev()). Al proporcionar la opción fs, se requieren anulaciones para al menos uno de write y writev. Si no se proporciona ninguna opción fd, también se requiere una anulación para open. Si autoClose es true, también se requiere una anulación para close.

Al igual que <fs.ReadStream>, si se especifica fd, <fs.WriteStream> ignorará el argumento path y utilizará el descriptor de archivo especificado. Esto significa que no se emitirá ningún evento 'open'. fd debe ser de bloqueo; los fd no bloqueantes deben pasarse a <net.Socket>.

Si options es una cadena, especifica la codificación.

fs.exists(path, callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar una devolución de llamada inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v7.6.0	El parámetro path puede ser un objeto URL WHATWG usando el protocolo file:.
v1.0.0	Obsoleto desde: v1.0.0
v0.0.2	Añadido en: v0.0.2

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto: Use fs.stat() o fs.access() en su lugar.

• path <string> | <Buffer> | <URL>
• callback <Function>
  • exists <boolean>

Comprueba si el elemento en la ruta especificada path existe o no, verificándolo con el sistema de archivos. Luego, llama al argumento callback con verdadero o falso:

import { exists } from 'node:fs'

exists('/etc/passwd', e => {
  console.log(e ? 'existe' : '¡sin passwd!')
})

Los parámetros de esta devolución de llamada no son consistentes con otras devoluciones de llamada de Node.js. Normalmente, el primer parámetro de una devolución de llamada de Node.js es un parámetro err, opcionalmente seguido de otros parámetros. La devolución de llamada fs.exists() solo tiene un parámetro booleano. Esta es una de las razones por las que se recomienda fs.access() en lugar de fs.exists().

Si path es un enlace simbólico, se sigue. Por lo tanto, si path existe pero apunta a un elemento inexistente, la devolución de llamada recibirá el valor false.

No se recomienda usar fs.exists() para comprobar la existencia de un archivo antes de llamar a fs.open(), fs.readFile() o fs.writeFile(). Hacerlo introduce una condición de carrera, ya que otros procesos pueden cambiar el estado del archivo entre las dos llamadas. En su lugar, el código del usuario debe abrir/leer/escribir el archivo directamente y manejar el error que se genera si el archivo no existe.

escritura (NO RECOMENDADO)

import { exists, open, close } from 'node:fs'

exists('myfile', e => {
  if (e) {
    console.error('myfile ya existe')
  } else {
    open('myfile', 'wx', (err, fd) => {
      if (err) throw err

      try {
        writeMyData(fd)
      } finally {
        close(fd, err => {
          if (err) throw err
        })
      }
    })
  }
})

escritura (RECOMENDADO)

import { open, close } from 'node:fs'
open('myfile', 'wx', (err, fd) => {
  if (err) {
    if (err.code === 'EEXIST') {
      console.error('myfile ya existe')
      return
    }

    throw err
  }

  try {
    writeMyData(fd)
  } finally {
    close(fd, err => {
      if (err) throw err
    })
  }
})

lectura (NO RECOMENDADO)

import { open, close, exists } from 'node:fs'

exists('myfile', e => {
  if (e) {
    open('myfile', 'r', (err, fd) => {
      if (err) throw err

      try {
        readMyData(fd)
      } finally {
        close(fd, err => {
          if (err) throw err
        })
      }
    })
  } else {
    console.error('myfile no existe')
  }
})

lectura (RECOMENDADO)

import { open, close } from 'node:fs'

open('myfile', 'r', (err, fd) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile no existe')
      return
    }

    throw err
  }

  try {
    readMyData(fd)
  } finally {
    close(fd, err => {
      if (err) throw err
    })
  }
})

Los ejemplos "no recomendados" anteriores comprueban la existencia y luego usan el archivo; los ejemplos "recomendados" son mejores porque usan el archivo directamente y manejan el error, si lo hay.

En general, compruebe la existencia de un archivo solo si el archivo no se usará directamente, por ejemplo, cuando su existencia es una señal de otro proceso.

fs.fchmod(fd, mode, callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar un callback inválido al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de deprecación con el id DEP0013.
v0.4.7	Añadido en: v0.4.7

• fd <integer>
• mode <string> | <integer>
• callback <Function>
  • err <Error>

Establece los permisos en el archivo. No se proporcionan otros argumentos además de una posible excepción al callback de finalización.

Consulte la documentación POSIX fchmod(2) para obtener más detalles.

fs.fchown(fd, uid, gid, callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar una devolución de llamada inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de deprecación con el ID DEP0013.
v0.4.7	Añadido en: v0.4.7

• fd <integer>
• uid <integer>
• gid <integer>
• callback <Function>
  • err <Error>

Establece el propietario del archivo. No se pasan otros argumentos a la devolución de llamada de finalización que una posible excepción.

Consulte la documentación POSIX fchown(2) para obtener más detalles.

fs.fdatasync(fd, callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar un callback inválido al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de deprecación con el ID DEP0013.
v0.1.96	Añadido en: v0.1.96

• fd <entero>
• callback <Función>
  • err <Error>

Fuerza todas las operaciones de E/S actualmente en cola asociadas con el archivo al estado de finalización de E/S sincronizada del sistema operativo. Consulte la documentación POSIX fdatasync(2) para obtener más detalles. No se proporcionan otros argumentos que una posible excepción a la devolución de llamada de finalización.

fs.fstat(fd[, options], callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar un callback inválido al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v10.5.0	Acepta un objeto options adicional para especificar si los valores numéricos devueltos deben ser bigint.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de deprecación con el ID DEP0013.
v0.1.95	Añadido en: v0.1.95

• fd <integer>

• options <Object>

  • bigint <boolean> Si los valores numéricos en el objeto <fs.Stats> devuelto deben ser bigint. Predeterminado: false.

• callback <Function>

  • err <Error>
  • stats <fs.Stats>

Invoca el callback con el <fs.Stats> para el descriptor de archivo.

Consulte la documentación POSIX fstat(2) para más detalles.

fs.fsync(fd, callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar un callback inválido al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de deprecación con el id DEP0013.
v0.1.96	Añadido en: v0.1.96

• fd <entero>
• callback <Función>
  • err <Error>

Solicita que todos los datos del descriptor de archivo abierto se vacíen en el dispositivo de almacenamiento. La implementación específica es específica del sistema operativo y del dispositivo. Consulte la documentación POSIX fsync(2) para obtener más detalles. No se dan otros argumentos además de una posible excepción a la devolución de llamada de finalización.

fs.ftruncate(fd[, len], callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar un callback inválido al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de deprecación con el ID DEP0013.
v0.8.6	Añadido en: v0.8.6

• fd <integer>
• len <integer> Predeterminado: 0
• callback <Function>
  • err <Error>

Trunca el descriptor de archivo. No se dan otros argumentos al callback de finalización que una posible excepción.

Vea la documentación POSIX ftruncate(2) para más detalles.

Si el archivo al que se refiere el descriptor de archivo era mayor que len bytes, solo se retendrán los primeros len bytes en el archivo.

Por ejemplo, el siguiente programa retiene solo los primeros cuatro bytes del archivo:

import { open, close, ftruncate } from 'node:fs'

function closeFd(fd) {
  close(fd, err => {
    if (err) throw err
  })
}

open('temp.txt', 'r+', (err, fd) => {
  if (err) throw err

  try {
    ftruncate(fd, 4, err => {
      closeFd(fd)
      if (err) throw err
    })
  } catch (err) {
    closeFd(fd)
    if (err) throw err
  }
})

Si el archivo anteriormente era más corto que len bytes, se extiende y la parte extendida se llena con bytes nulos ('\0'):

Si len es negativo, se usará 0.

fs.futimes(fd, atime, mtime, callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar una devolución de llamada inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de deprecación con el ID DEP0013.
v4.1.0	Las cadenas numéricas, NaN e Infinity ahora son especificadores de tiempo permitidos.
v0.4.2	Añadido en: v0.4.2

• fd <integer>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• callback <Function>
  • err <Error>

Cambia las marcas de tiempo del sistema de archivos del objeto referenciado por el descriptor de archivo suministrado. Ver fs.utimes().

fs.glob(pattern[, options], callback)

[Historial]

Versión	Cambios
v22.2.0	Se agregó soporte para withFileTypes como opción.
v22.0.0	Añadido en: v22.0.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

• pattern <string> | <string[]>

• options <Object>

  • cwd <string> directorio de trabajo actual. Predeterminado: process.cwd()
  • exclude <Function> Función para filtrar archivos/directorios. Devuelve true para excluir el elemento, false para incluirlo. Predeterminado: undefined.
  • withFileTypes <boolean> true si el glob debe devolver las rutas como Dirents, false de lo contrario. Predeterminado: false.

• callback <Function>

  • err <Error>

• Recupera los archivos que coinciden con el patrón especificado.

ESM

import { glob } from 'node:fs'

glob('**/*.js', (err, matches) => {
  if (err) throw err
  console.log(matches)
})

CJS

const { glob } = require('node:fs')

glob('**/*.js', (err, matches) => {
  if (err) throw err
  console.log(matches)
})

fs.lchmod(path, mode, callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar un callback inválido al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v16.0.0	El error devuelto puede ser un AggregateError si se devuelve más de un error.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de deprecación con el id DEP0013.
v0.4.7	Obsoleto desde: v0.4.7

• path <string> | <Buffer> | <URL>
• mode <integer>
• callback <Function>
  • err <Error> | <AggregateError>

Cambia los permisos de un enlace simbólico. No se pasan otros argumentos al callback de finalización que una posible excepción.

Este método solo está implementado en macOS.

Consulte la documentación POSIX lchmod(2) para más detalles.

fs.lchown(path, uid, gid, callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar una devolución de llamada inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v10.6.0	Esta API ya no está en desuso.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de deprecación con el id DEP0013.
v0.4.7	Deprecación solo en la documentación.

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• callback <Function>
  • err <Error>

Establece el propietario del enlace simbólico. No se dan otros argumentos además de una posible excepción a la devolución de llamada de finalización.

Consulte la documentación POSIX lchown(2) para obtener más detalles.

fs.lutimes(path, atime, mtime, callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar una devolución de llamada inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v14.5.0, v12.19.0	Añadido en: v14.5.0, v12.19.0

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• callback <Function>
  • err <Error>

Cambia los tiempos de acceso y modificación de un archivo de la misma manera que fs.utimes(), con la diferencia de que si la ruta se refiere a un enlace simbólico, entonces el enlace no se desreferencia: en su lugar, se cambian las marcas de tiempo del propio enlace simbólico.

No se dan otros argumentos que una posible excepción a la devolución de llamada de finalización.

fs.link(existingPath, newPath, callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar una función de devolución de llamada inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.6.0	Los parámetros existingPath y newPath pueden ser objetos URL WHATWG usando el protocolo file:. El soporte aún es experimental.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de deprecación con el id DEP0013.
v0.1.31	Añadido en: v0.1.31

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• callback <Function>
  • err <Error>

Crea un nuevo enlace desde existingPath a newPath. Consulte la documentación POSIX link(2) para más detalles. No se dan otros argumentos a la función de devolución de llamada de finalización que una posible excepción.

fs.lstat(path[, options], callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar un callback inválido al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v10.5.0	Acepta un objeto options adicional para especificar si los valores numéricos devueltos deben ser bigint.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.6.0	El parámetro path puede ser un objeto URL WHATWG usando el protocolo file:.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de deprecación con el ID DEP0013.
v0.1.30	Añadido en: v0.1.30

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Si los valores numéricos en el objeto <fs.Stats> devuelto deben ser bigint. Predeterminado: false.

• callback <Function>

  • err <Error>
  • stats <fs.Stats>

Recupera las <fs.Stats> para el enlace simbólico al que se refiere la ruta. El callback obtiene dos argumentos (err, stats) donde stats es un objeto <fs.Stats>. lstat() es idéntico a stat(), excepto que si path es un enlace simbólico, entonces se analiza el propio enlace, no el archivo al que se refiere.

Consulte la documentación POSIX lstat(2) para obtener más detalles.

fs.mkdir(path[, options], callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar un callback inválido al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v13.11.0, v12.17.0	En modo recursive, el callback ahora recibe la primera ruta creada como argumento.
v10.12.0	El segundo argumento ahora puede ser un objeto options con propiedades recursive y mode.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.6.0	El parámetro path puede ser un objeto URL WHATWG usando el protocolo file:.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de deprecación con el id DEP0013.
v0.1.8	Añadido en: v0.1.8

• path <string> | <Buffer> | <URL>

• options <Object> | <integer>

  • recursive <boolean> Predeterminado: false
  • mode <string> | <integer> No soportado en Windows. Predeterminado: 0o777.

• callback <Function>

  • err <Error>
  • path <string> | <undefined> Presente solo si se crea un directorio con recursive establecido en true.

Crea un directorio de forma asíncrona.

El callback recibe una posible excepción y, si recursive es true, la primera ruta de directorio creada, (err[, path]). path puede seguir siendo undefined cuando recursive es true, si no se creó ningún directorio (por ejemplo, si ya se había creado previamente).

El argumento options opcional puede ser un entero que especifica mode (permisos y bits pegajosos), o un objeto con una propiedad mode y una propiedad recursive que indica si se deben crear directorios padre. Llamar a fs.mkdir() cuando path es un directorio que existe solo resulta en un error cuando recursive es falso. Si recursive es falso y el directorio existe, se produce un error EEXIST.

import { mkdir } from 'node:fs'

// Crea ./tmp/a/apple, independientemente de si existen ./tmp y ./tmp/a.
mkdir('./tmp/a/apple', { recursive: true }, err => {
  if (err) throw err
})

En Windows, usar fs.mkdir() en el directorio raíz incluso con recursión resultará en un error:

import { mkdir } from 'node:fs'

mkdir('/', { recursive: true }, err => {
  // => [Error: EPERM: operation not permitted, mkdir 'C:\']
})

Consulte la documentación de POSIX mkdir(2) para más detalles.

fs.mkdtemp(prefix[, options], callback)

[Historial]

Versión	Cambios
v20.6.0, v18.19.0	El parámetro prefix ahora acepta búferes y URL.
v18.0.0	Pasar una devolución de llamada inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v16.5.0, v14.18.0	El parámetro prefix ahora acepta una cadena vacía.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de deprecación con el ID DEP0013.
v6.2.1	El parámetro callback ahora es opcional.
v5.10.0	Añadido en: v5.10.0

• prefix <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Predeterminado: 'utf8'

• callback <Function>

  • err <Error>
  • directory <string>

Crea un directorio temporal único.

Genera seis caracteres aleatorios que se anexarán detrás de un prefix requerido para crear un directorio temporal único. Debido a inconsistencias entre plataformas, evite caracteres X finales en prefix. Algunas plataformas, notablemente las BSD, pueden devolver más de seis caracteres aleatorios y reemplazar los caracteres X finales en prefix con caracteres aleatorios.

La ruta del directorio creado se pasa como una cadena al segundo parámetro de la devolución de llamada.

El argumento options opcional puede ser una cadena que especifique una codificación, o un objeto con una propiedad encoding que especifique la codificación de caracteres a utilizar.

import { mkdtemp } from 'node:fs'
import { join } from 'node:path'
import { tmpdir } from 'node:os'

mkdtemp(join(tmpdir(), 'foo-'), (err, directory) => {
  if (err) throw err
  console.log(directory)
  // Imprime: /tmp/foo-itXde2 o C:\Users\...\AppData\Local\Temp\foo-itXde2
})

El método fs.mkdtemp() anexará los seis caracteres seleccionados aleatoriamente directamente a la cadena prefix. Por ejemplo, dado un directorio /tmp, si la intención es crear un directorio temporal dentro de /tmp, el prefix debe terminar con un separador de ruta específico de la plataforma (require('node:path').sep).

import { tmpdir } from 'node:os'
import { mkdtemp } from 'node:fs'

// El directorio padre para el nuevo directorio temporal
const tmpDir = tmpdir()

// Este método es *INCORRECTO*:
mkdtemp(tmpDir, (err, directory) => {
  if (err) throw err
  console.log(directory)
  // Imprimirá algo similar a `/tmpabc123`.
  // Se crea un nuevo directorio temporal en la raíz del sistema de archivos
  // en lugar de *dentro* del directorio /tmp.
})

// Este método es *CORRECTO*:
import { sep } from 'node:path'
mkdtemp(`${tmpDir}${sep}`, (err, directory) => {
  if (err) throw err
  console.log(directory)
  // Imprimirá algo similar a `/tmp/abc123`.
  // Se crea un nuevo directorio temporal dentro
  // del directorio /tmp.
})

fs.open(path[, flags[, mode]], callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar una devolución de llamada inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v11.1.0	El argumento flags ahora es opcional y su valor predeterminado es 'r'.
v9.9.0	Ahora se admiten las marcas as y as+.
v7.6.0	El parámetro path puede ser un objeto URL WHATWG usando el protocolo file:.
v0.0.2	Añadido en: v0.0.2

• path <string> | <Buffer> | <URL>
• flags <string> | <number> Ver compatibilidad de marcas del sistema de archivos. Predeterminado: 'r'.
• mode <string> | <integer> Predeterminado: 0o666 (lectura y escritura)
• callback <Function>
  • err <Error>
  • fd <integer>

Apertura de archivo asincrónica. Consulte la documentación POSIX open(2) para obtener más detalles.

mode establece el modo de archivo (permisos y bits pegajosos), pero solo si se creó el archivo. En Windows, solo se puede manipular el permiso de escritura; consulte fs.chmod().

La devolución de llamada recibe dos argumentos (err, fd).

Algunos caracteres (\< \> : " / \ | ? *) están reservados en Windows como se documenta en Nombrar archivos, rutas y espacios de nombres. Bajo NTFS, si el nombre de archivo contiene dos puntos, Node.js abrirá un flujo del sistema de archivos, como se describe en esta página de MSDN.

Las funciones basadas en fs.open() también muestran este comportamiento: fs.writeFile(), fs.readFile(), etc.

fs.openAsBlob(path[, options])

Añadido en: v19.8.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

• path <string> | <Buffer> | <URL>

• options <Object>

  • type <string> Un tipo mime opcional para el blob.

• Devuelve: <Promise> Se cumple con un <Blob> si tiene éxito.

Devuelve un <Blob> cuyos datos están respaldados por el archivo dado.

El archivo no debe modificarse después de que se cree el <Blob>. Cualquier modificación provocará que la lectura de los datos del <Blob> falle con un error DOMException. Operaciones de estadísticas sincrónicas en el archivo cuando se crea el Blob, y antes de cada lectura para detectar si los datos del archivo se han modificado en el disco.

ESM

import { openAsBlob } from 'node:fs'

const blob = await openAsBlob('the.file.txt')
const ab = await blob.arrayBuffer()
blob.stream()

CJS

const { openAsBlob } = require('node:fs')

;(async () => {
  const blob = await openAsBlob('the.file.txt')
  const ab = await blob.arrayBuffer()
  blob.stream()
})()

fs.opendir(path[, options], callback)

[Historial]

Versión	Cambios
v20.1.0, v18.17.0	Se agregó la opción recursive.
v18.0.0	Pasar una devolución de llamada inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v13.1.0, v12.16.0	Se introdujo la opción bufferSize.
v12.12.0	Añadido en: v12.12.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • encoding <string> | <null> Predeterminado: 'utf8'
  • bufferSize <number> Número de entradas de directorio que se almacenan en búfer internamente al leer desde el directorio. Valores más altos conducen a un mejor rendimiento pero a un mayor uso de memoria. Predeterminado: 32
  • recursive <boolean> Predeterminado: false

• callback <Function>

  • err <Error>
  • dir <fs.Dir>

Abra un directorio de forma asíncrona. Consulte la documentación POSIX opendir(3) para obtener más detalles.

Crea un <fs.Dir>, que contiene todas las funciones adicionales para leer y limpiar el directorio.

La opción encoding establece la codificación para la ruta path al abrir el directorio y las operaciones de lectura posteriores.

fs.read(fd, buffer, offset, length, position, callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar una devolución de llamada inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v10.10.0	El parámetro buffer ahora puede ser cualquier TypedArray, o un DataView.
v7.4.0	El parámetro buffer ahora puede ser un Uint8Array.
v6.0.0	El parámetro length ahora puede ser 0.
v0.0.2	Añadido en: v0.0.2

• fd <entero>
• buffer <Buffer> | <TypedArray> | <DataView> El búfer al que se escribirán los datos.
• offset <entero> La posición en buffer donde escribir los datos.
• length <entero> El número de bytes a leer.
• position <entero> | <bigint> | <nulo> Especifica dónde comenzar a leer en el archivo. Si position es null o -1, los datos se leerán desde la posición actual del archivo y la posición del archivo se actualizará. Si position es un entero no negativo, la posición del archivo no cambiará.
• callback <Función>
  • err <Error>
  • bytesRead <entero>
  • buffer <Buffer>

Lee datos del archivo especificado por fd.

La devolución de llamada recibe los tres argumentos, (err, bytesRead, buffer).

Si el archivo no se modifica concurrentemente, se alcanza el fin de archivo cuando el número de bytes leídos es cero.

Si este método se invoca como su versión util.promisify(), devuelve una promesa para un Object con las propiedades bytesRead y buffer.

El método fs.read() lee datos del archivo especificado por el descriptor de archivo (fd). El argumento length indica el número máximo de bytes que Node.js intentará leer del kernel. Sin embargo, el número real de bytes leídos (bytesRead) puede ser menor que el length especificado por varias razones.

Por ejemplo:

• Si el archivo es más corto que el length especificado, bytesRead se establecerá en el número real de bytes leídos.
• Si el archivo encuentra EOF (Fin de Archivo) antes de que el búfer pueda llenarse, Node.js leerá todos los bytes disponibles hasta que se encuentre EOF, y el parámetro bytesRead en la devolución de llamada indicará el número real de bytes leídos, que puede ser menor que el length especificado.
• Si el archivo está en un sistema de archivos de red lento o encuentra algún otro problema durante la lectura, bytesRead puede ser menor que el length especificado.

Por lo tanto, al usar fs.read(), es importante verificar el valor bytesRead para determinar cuántos bytes se leyeron realmente del archivo. Dependiendo de la lógica de su aplicación, es posible que deba manejar los casos en que bytesRead sea menor que el length especificado, como envolviendo la llamada de lectura en un bucle si necesita una cantidad mínima de bytes.

Este comportamiento es similar a la función POSIX preadv2.

fs.read(fd[, options], callback)

[Historial]

Versión	Cambios
v13.11.0, v12.17.0	Se puede pasar un objeto de opciones para hacer que el búfer, el desplazamiento, la longitud y la posición sean opcionales.
v13.11.0, v12.17.0	Añadido en: v13.11.0, v12.17.0

• fd <integer>

• options <Object>

  • buffer <Buffer> | <TypedArray> | <DataView> Predeterminado: Buffer.alloc(16384)
  • offset <integer> Predeterminado: 0
  • length <integer> Predeterminado: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> Predeterminado: null

• callback <Function>

  • err <Error>
  • bytesRead <integer>
  • buffer <Buffer>

Similar a la función fs.read(), esta versión toma un objeto options opcional. Si no se especifica ningún objeto options, se utilizará el valor predeterminado que se muestra arriba.

fs.read(fd, buffer[, options], callback)

Añadido en: v18.2.0, v16.17.0

• fd <integer>

• buffer <Buffer> | <TypedArray> | <DataView> El búfer al que se escribirán los datos.

• options <Object>

  • offset <integer> Predeterminado: 0
  • length <integer> Predeterminado: buffer.byteLength - offset
  • position <integer> | <bigint> Predeterminado: null

• callback <Function>

  • err <Error>
  • bytesRead <integer>
  • buffer <Buffer>

Similar a la función fs.read(), esta versión toma un objeto options opcional. Si no se especifica ningún objeto options, se usará el valor predeterminado que se muestra arriba.

fs.readdir(path[, options], callback)

[Historial]

Versión	Cambios
v20.1.0, v18.17.0	Se agregó la opción recursive.
v18.0.0	Pasar una devolución de llamada inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v10.10.0	Se agregó la nueva opción withFileTypes.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.6.0	El parámetro path puede ser un objeto URL WHATWG usando el protocolo file:.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de deprecación con el id DEP0013.
v6.0.0	Se agregó el parámetro options.
v0.1.8	Añadido en: v0.1.8

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Predeterminado: 'utf8'
  • withFileTypes <boolean> Predeterminado: false
  • recursive <boolean> Si es true, lee el contenido de un directorio de forma recursiva. En modo recursivo, listará todos los archivos, subarchivos y directorios. Predeterminado: false.

• callback <Function>

  • err <Error>
  • files <string[]> | <Buffer[]> | <fs.Dirent[]>

Lee el contenido de un directorio. La devolución de llamada obtiene dos argumentos (err, files) donde files es un array de los nombres de los archivos en el directorio, excluyendo '.' y '..'.

Consulte la documentación POSIX readdir(3) para obtener más detalles.

El argumento options opcional puede ser una cadena que especifique una codificación, o un objeto con una propiedad encoding que especifique la codificación de caracteres que se utilizará para los nombres de archivo pasados a la devolución de llamada. Si encoding se establece en 'buffer', los nombres de archivo devueltos se pasarán como objetos <Buffer>.

Si options.withFileTypes se establece en true, la matriz files contendrá objetos <fs.Dirent>.

fs.readFile(path[, options], callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar un callback inválido al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v16.0.0	El error devuelto puede ser un AggregateError si se devuelve más de un error.
v15.2.0, v14.17.0	El argumento options puede incluir una señal AbortSignal para abortar una solicitud readFile en curso.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.6.0	El parámetro path puede ser un objeto URL WHATWG usando el protocolo file:.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de deprecación con el id DEP0013.
v5.1.0	El callback siempre se llamará con null como parámetro error en caso de éxito.
v5.0.0	El parámetro path ahora puede ser un descriptor de archivo.
v0.1.29	Añadido en: v0.1.29

• path <string> | <Buffer> | <URL> | <integer> nombre de archivo o descriptor de archivo

• options <Object> | <string>

  • encoding <string> | <null> Predeterminado: null
  • flag <string> Ver soporte de flags del sistema de archivos. Predeterminado: 'r'.
  • signal <AbortSignal> permite abortar una lectura de archivo en progreso

• callback <Function>

  • err <Error> | <AggregateError>
  • data <string> | <Buffer>

Lee asincrónicamente todo el contenido de un archivo.

import { readFile } from 'node:fs'

readFile('/etc/passwd', (err, data) => {
  if (err) throw err
  console.log(data)
})

El callback recibe dos argumentos (err, data), donde data es el contenido del archivo.

Si no se especifica ninguna codificación, se devuelve el búfer sin procesar.

Si options es una cadena, entonces especifica la codificación:

import { readFile } from 'node:fs'

readFile('/etc/passwd', 'utf8', callback)

Cuando la ruta es un directorio, el comportamiento de fs.readFile() y fs.readFileSync() es específico de la plataforma. En macOS, Linux y Windows, se devolverá un error. En FreeBSD, se devolverá una representación del contenido del directorio.

import { readFile } from 'node:fs'

// macOS, Linux y Windows
readFile('<directory>', (err, data) => {
  // => [Error: EISDIR: operación ilegal en un directorio, lectura <directory>]
})

//  FreeBSD
readFile('<directory>', (err, data) => {
  // => null, <data>
})

Es posible abortar una solicitud en curso usando una AbortSignal. Si se aborta una solicitud, el callback se llama con un AbortError:

import { readFile } from 'node:fs'

const controller = new AbortController()
const signal = controller.signal
readFile(fileInfo[0].name, { signal }, (err, buf) => {
  // ...
})
// Cuando quieras abortar la solicitud
controller.abort()

La función fs.readFile() almacena en búfer todo el archivo. Para minimizar los costos de memoria, cuando sea posible, prefiera la transmisión a través de fs.createReadStream().

Abortar una solicitud en curso no aborta las solicitudes individuales del sistema operativo, sino el búfer interno que realiza fs.readFile.

Descriptores de archivo

Consideraciones de rendimiento

El método fs.readFile() lee de forma asíncrona el contenido de un archivo en la memoria, un fragmento a la vez, permitiendo que el bucle de eventos gire entre cada fragmento. Esto permite que la operación de lectura tenga menos impacto en otras actividades que puedan estar utilizando el grupo de subprocesos libuv subyacente, pero significa que llevará más tiempo leer un archivo completo en la memoria.

La sobrecarga de lectura adicional puede variar ampliamente en diferentes sistemas y depende del tipo de archivo que se esté leyendo. Si el tipo de archivo no es un archivo regular (una tubería, por ejemplo) y Node.js no puede determinar el tamaño real del archivo, cada operación de lectura cargará 64 KiB de datos. Para archivos regulares, cada lectura procesará 512 KiB de datos.

Para las aplicaciones que requieren una lectura lo más rápida posible del contenido de los archivos, es mejor usar fs.read() directamente y que el código de la aplicación gestione la lectura completa del contenido del archivo.

El problema de GitHub de Node.js #25741 proporciona más información y un análisis detallado del rendimiento de fs.readFile() para múltiples tamaños de archivo en diferentes versiones de Node.js.

fs.readlink(path[, options], callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar un callback inválido al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.6.0	El parámetro path puede ser un objeto URL WHATWG usando el protocolo file:.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de deprecación con el id DEP0013.
v0.1.31	Añadido en: v0.1.31

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Predeterminado: 'utf8'

• callback <Function>

  • err <Error>
  • linkString <string> | <Buffer>

Lee el contenido del enlace simbólico al que se refiere path. El callback recibe dos argumentos (err, linkString).

Vea la documentación POSIX readlink(2) para más detalles.

El argumento options opcional puede ser una cadena que especifique una codificación, o un objeto con una propiedad encoding que especifique la codificación de caracteres a usar para la ruta de enlace pasada al callback. Si encoding se establece en 'buffer', la ruta de enlace devuelta se pasará como un objeto <Buffer>.

fs.readv(fd, buffers[, position], callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar una función de devolución de llamada inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v13.13.0, v12.17.0	Añadido en: v13.13.0, v12.17.0

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer> | <null> Predeterminado: null
• callback <Function>
  • err <Error>
  • bytesRead <integer>
  • buffers <ArrayBufferView[]>

Lee desde un archivo especificado por fd y escribe en un array de ArrayBufferView usando readv().

position es el desplazamiento desde el comienzo del archivo desde donde se deben leer los datos. Si typeof position !== 'number', los datos se leerán desde la posición actual.

La función de devolución de llamada recibirá tres argumentos: err, bytesRead y buffers. bytesRead es la cantidad de bytes leídos del archivo.

Si este método se invoca como su versión util.promisify(), devuelve una promesa para un objeto con las propiedades bytesRead y buffers.

fs.realpath(path[, options], callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar una devolución de llamada inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v8.0.0	Se agregó soporte para la resolución de tuberías/sockets.
v7.6.0	El parámetro path puede ser un objeto URL WHATWG usando el protocolo file:.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de deprecación con el ID DEP0013.
v6.4.0	Llamar a realpath ahora funciona de nuevo para varios casos límite en Windows.
v6.0.0	Se eliminó el parámetro cache.
v0.1.31	Añadido en: v0.1.31

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Predeterminado: 'utf8'

• callback <Function>

  • err <Error>
  • resolvedPath <string> | <Buffer>

Calcula asincrónicamente el nombre de ruta canónico resolviendo ., .., y enlaces simbólicos.

Un nombre de ruta canónico no es necesariamente único. Los enlaces duros y los montajes de enlace pueden exponer una entidad del sistema de archivos a través de muchos nombres de ruta.

Esta función se comporta como realpath(3), con algunas excepciones:

La devolución de llamada obtiene dos argumentos (err, resolvedPath). Puede usar process.cwd para resolver rutas relativas.

Solo se admiten rutas que se pueden convertir a cadenas UTF8.

El argumento options opcional puede ser una cadena que especifique una codificación, o un objeto con una propiedad encoding que especifique la codificación de caracteres que se usará para la ruta pasada a la devolución de llamada. Si encoding se establece en 'buffer', la ruta devuelta se pasará como un objeto <Buffer>.

Si path se resuelve a un socket o una tubería, la función devolverá un nombre dependiente del sistema para ese objeto.

Una ruta que no existe resulta en un error ENOENT. error.path es la ruta de archivo absoluta.

fs.realpath.native(path[, options], callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar un callback inválido al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v9.2.0	Añadido en: v9.2.0

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Predeterminado: 'utf8'

• callback <Function>

  • err <Error>
  • resolvedPath <string> | <Buffer>

realpath(3) Asíncrono.

El callback recibe dos argumentos (err, resolvedPath).

Solo se admiten rutas que se pueden convertir a cadenas UTF8.

El argumento options opcional puede ser una cadena que especifique una codificación, o un objeto con una propiedad encoding que especifique la codificación de caracteres que se utilizará para la ruta pasada al callback. Si encoding se establece en 'buffer', la ruta devuelta se pasará como un objeto <Buffer>.

En Linux, cuando Node.js está enlazado con musl libc, el sistema de archivos procfs debe estar montado en /proc para que esta función funcione. Glibc no tiene esta restricción.

fs.rename(oldPath, newPath, callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar un callback inválido al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.6.0	Los parámetros oldPath y newPath pueden ser objetos URL WHATWG usando el protocolo file:. El soporte actualmente es aún experimental.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de deprecación con el id DEP0013.
v0.0.2	Añadido en: v0.0.2

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• callback <Function>
  • err <Error>

Renombra asíncronamente el archivo en oldPath al nombre de archivo proporcionado como newPath. En el caso de que newPath ya exista, será sobrescrito. Si hay un directorio en newPath, se lanzará un error. No se dan otros argumentos que una posible excepción al callback de finalización.

Véase también: rename(2).

import { rename } from 'node:fs'

rename('oldFile.txt', 'newFile.txt', err => {
  if (err) throw err
  console.log('¡Renombrado completo!')
})

fs.rmdir(path[, options], callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar una devolución de llamada inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v16.0.0	Usar fs.rmdir(path, { recursive: true }) en una path que es un archivo ya no está permitido y resulta en un error ENOENT en Windows y un error ENOTDIR en POSIX.
v16.0.0	Usar fs.rmdir(path, { recursive: true }) en una path que no existe ya no está permitido y resulta en un error ENOENT.
v16.0.0	La opción recursive está en desuso, usarla activa una advertencia de desuso.
v14.14.0	La opción recursive está en desuso, use fs.rm en su lugar.
v13.3.0, v12.16.0	La opción maxBusyTries se renombra a maxRetries, y su valor predeterminado es 0. La opción emfileWait se ha eliminado, y los errores EMFILE usan la misma lógica de reintento que otros errores. Ahora se admite la opción retryDelay. Ahora se reintentan los errores ENFILE.
v12.10.0	Ahora se admiten las opciones recursive, maxBusyTries y emfileWait.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.6.0	Los parámetros path pueden ser un objeto URL WHATWG usando el protocolo file:.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de desuso con el id DEP0013.
v0.0.2	Añadido en: v0.0.2

• path <string> | <Buffer> | <URL>

• options <Object>

  • maxRetries <integer> Si se encuentra un error EBUSY, EMFILE, ENFILE, ENOTEMPTY o EPERM, Node.js reintenta la operación con una espera de retroceso lineal de retryDelay milisegundos más en cada intento. Esta opción representa el número de reintentos. Esta opción se ignora si la opción recursive no es true. Predeterminado: 0.
  • recursive <boolean> Si es true, realiza una eliminación de directorio recursiva. En modo recursivo, las operaciones se reintentan en caso de fallo. Predeterminado: false. En desuso.
  • retryDelay <integer> La cantidad de tiempo en milisegundos que se debe esperar entre reintentos. Esta opción se ignora si la opción recursive no es true. Predeterminado: 100.

• callback <Function>

  • err <Error>

rmdir(2) asincrónica. No se dan otros argumentos además de una posible excepción a la devolución de llamada de finalización.

Usar fs.rmdir() en un archivo (no un directorio) resulta en un error ENOENT en Windows y un error ENOTDIR en POSIX.

Para obtener un comportamiento similar al comando Unix rm -rf, use fs.rm() con las opciones { recursive: true, force: true }.

fs.rm(path[, options], callback)

[Historial]

Versión	Cambios
v17.3.0, v16.14.0	El parámetro path puede ser un objeto URL WHATWG usando el protocolo file:
v14.14.0	Añadido en: v14.14.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • force <boolean> Cuando es true, se ignorarán las excepciones si path no existe. Predeterminado: false.
  • maxRetries <integer> Si se encuentra un error EBUSY, EMFILE, ENFILE, ENOTEMPTY, o EPERM, Node.js volverá a intentar la operación con una espera de retroceso lineal de retryDelay milisegundos más en cada intento. Esta opción representa el número de reintentos. Esta opción se ignora si la opción recursive no es true. Predeterminado: 0.
  • recursive <boolean> Si es true, realiza una eliminación recursiva. En modo recursivo, las operaciones se reintentan en caso de fallo. Predeterminado: false.
  • retryDelay <integer> La cantidad de tiempo en milisegundos que se debe esperar entre reintentos. Esta opción se ignora si la opción recursive no es true. Predeterminado: 100.

• callback <Function>

  • err <Error>

Elimina asincrónicamente archivos y directorios (modelado en la utilidad POSIX rm estándar). No se proporcionan otros argumentos que una posible excepción a la devolución de llamada de finalización.

fs.stat(path[, options], callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar un callback inválido al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v10.5.0	Acepta un objeto options adicional para especificar si los valores numéricos devueltos deben ser bigint.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.6.0	El parámetro path puede ser un objeto URL WHATWG usando el protocolo file:.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de obsolescencia con el id DEP0013.
v0.0.2	Agregado en: v0.0.2

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Indica si los valores numéricos en el objeto <fs.Stats> devuelto deberían ser bigint. Predeterminado: false.

• callback <Function>

  • err <Error>
  • stats <fs.Stats>

stat(2) asíncrono. La callback recibe dos argumentos (err, stats) donde stats es un objeto <fs.Stats>.

En caso de error, el err.code será uno de los Errores comunes del sistema.

fs.stat() sigue enlaces simbólicos. Usa fs.lstat() para observar los enlaces en sí.

No se recomienda usar fs.stat() para comprobar la existencia de un archivo antes de llamar a fs.open(), fs.readFile() o fs.writeFile(). En cambio, el código de usuario debería abrir/leer/escribir el archivo directamente y manejar el error generado si el archivo no está disponible.

Para verificar si un archivo existe sin manipularlo posteriormente, se recomienda fs.access().

Por ejemplo, dada la siguiente estructura de directorios:

- txtDir
-- file.txt
- app.js

El siguiente programa verificará las estadísticas de las rutas dadas:

import { stat } from 'node:fs'

const pathsToCheck = ['./txtDir', './txtDir/file.txt']

for (let i = 0; i < pathsToCheck.length; i++) {
  stat(pathsToCheck[i], (err, stats) => {
    console.log(stats.isDirectory())
    console.log(stats)
  })
}

El resultado resultante se asemejará a:

true
Stats {
  dev: 16777220,
  mode: 16877,
  nlink: 3,
  uid: 501,
  gid: 20,
  rdev: 0,
  blksize: 4096,
  ino: 14214262,
  size: 96,
  blocks: 0,
  atimeMs: 1561174653071.963,
  mtimeMs: 1561174614583.3518,
  ctimeMs: 1561174626623.5366,
  birthtimeMs: 1561174126937.2893,
  atime: 2019-06-22T03:37:33.072Z,
  mtime: 2019-06-22T03:36:54.583Z,
  ctime: 2019-06-22T03:37:06.624Z,
  birthtime: 2019-06-22T03:28:46.937Z
}
false
Stats {
  dev: 16777220,
  mode: 33188,
  nlink: 1,
  uid: 501,
  gid: 20,
  rdev: 0,
  blksize: 4096,
  ino: 14214074,
  size: 8,
  blocks: 8,
  atimeMs: 1561174616618.8555,
  mtimeMs: 1561174614584,
  ctimeMs: 1561174614583.8145,
  birthtimeMs: 1561174007710.7478,
  atime: 2019-06-22T03:36:56.619Z,
  mtime: 2019-06-22T03:36:54.584Z,
  ctime: 2019-06-22T03:36:54.584Z,
  birthtime: 2019-06-22T03:26:47.711Z
}

fs.statfs(path[, options], callback)

Añadido en: v19.6.0, v18.15.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Indica si los valores numéricos en el objeto <fs.StatFs> devuelto deben ser bigint. Predeterminado: false.

• callback <Function>

  • err <Error>
  • stats <fs.StatFs>

statfs(2) asíncrono. Devuelve información sobre el sistema de archivos montado que contiene path. La función de retrollamada recibe dos argumentos (err, stats) donde stats es un objeto <fs.StatFs>.

En caso de error, el err.code será uno de los Errores Comunes del Sistema.

fs.symlink(target, path[, type], callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar una devolución de llamada no válida al argumento callback ahora arroja ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v12.0.0	Si el argumento type se deja sin definir, Node autodetectará el tipo de target y seleccionará automáticamente dir o file.
v7.6.0	Los parámetros target y path pueden ser objetos URL WHATWG utilizando el protocolo file:. El soporte actualmente sigue siendo experimental.
v0.1.31	Agregado en: v0.1.31

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> | <null> Predeterminado: null
• callback <Function>
  • err <Error>

Crea el enlace llamado path apuntando a target. No se dan más argumentos que una posible excepción a la devolución de llamada de finalización.

Consulte la documentación POSIX symlink(2) para obtener más detalles.

El argumento type solo está disponible en Windows y se ignora en otras plataformas. Se puede establecer en 'dir', 'file' o 'junction'. Si el argumento type es null, Node.js autodetectará el tipo de target y utilizará 'file' o 'dir'. Si el target no existe, se usará 'file'. Los puntos de unión de Windows requieren que la ruta de destino sea absoluta. Cuando se utiliza 'junction', el argumento target se normalizará automáticamente a la ruta absoluta. Los puntos de unión en los volúmenes NTFS solo pueden apuntar a directorios.

Los destinos relativos son relativos al directorio principal del enlace.

import { symlink } from 'node:fs'

symlink('./mew', './mewtwo', callback)

El ejemplo anterior crea un enlace simbólico mewtwo que apunta a mew en el mismo directorio:

$ tree .
.
├── mew
└── mewtwo -> ./mew

fs.truncate(path[, len], callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar un callback inválido al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v16.0.0	El error devuelto puede ser un AggregateError si se devuelve más de un error.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de obsolescencia con el id DEP0013.
v0.8.6	Añadido en: v0.8.6

• path <string> | <Buffer> | <URL>
• len <integer> Predeterminado: 0
• callback <Function>
  • err <Error> | <AggregateError>

Trunca el archivo. No se dan más argumentos que una posible excepción al callback de finalización. También se puede pasar un descriptor de archivo como primer argumento. En este caso, se llama a fs.ftruncate().

ESM

import { truncate } from 'node:fs'
// Asumiendo que 'path/file.txt' es un archivo regular.
truncate('path/file.txt', err => {
  if (err) throw err
  console.log('path/file.txt fue truncado')
})

CJS

const { truncate } = require('node:fs')
// Asumiendo que 'path/file.txt' es un archivo regular.
truncate('path/file.txt', err => {
  if (err) throw err
  console.log('path/file.txt fue truncado')
})

Pasar un descriptor de archivo está obsoleto y puede resultar en que se lance un error en el futuro.

Consulta la documentación POSIX truncate(2) para obtener más detalles.

fs.unlink(path, callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar una función callback inválida al argumento callback ahora arroja ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo arrojará un TypeError en tiempo de ejecución.
v7.6.0	El parámetro path puede ser un objeto URL WHATWG usando el protocolo file:.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de obsolescencia con el ID DEP0013.
v0.0.2	Añadido en: v0.0.2

• path <string> | <Buffer> | <URL>
• callback <Function>
  • err <Error>

Elimina de forma asíncrona un archivo o enlace simbólico. No se proporcionan argumentos a la función callback de finalización, aparte de una posible excepción.

import { unlink } from 'node:fs'
// Asumiendo que 'path/file.txt' es un archivo regular.
unlink('path/file.txt', err => {
  if (err) throw err
  console.log('path/file.txt fue eliminado')
})

fs.unlink() no funcionará en un directorio, esté vacío o no. Para eliminar un directorio, use fs.rmdir().

Consulte la documentación POSIX unlink(2) para obtener más detalles.

fs.unwatchFile(filename[, listener])

Agregado en: v0.1.31

• filename <string> | <Buffer> | <URL>
• listener <Function> Opcional, un listener previamente adjuntado usando fs.watchFile()

Deja de observar los cambios en filename. Si se especifica listener, solo se elimina ese listener en particular. De lo contrario, se eliminan todos los listeners, deteniendo efectivamente la observación de filename.

Llamar a fs.unwatchFile() con un nombre de archivo que no se está observando es una operación sin efecto, no un error.

Usar fs.watch() es más eficiente que fs.watchFile() y fs.unwatchFile(). fs.watch() debe usarse en lugar de fs.watchFile() y fs.unwatchFile() cuando sea posible.

fs.utimes(path, atime, mtime, callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar una callback inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v8.0.0	NaN, Infinity y -Infinity ya no son especificadores de tiempo válidos.
v7.6.0	El parámetro path puede ser un objeto URL WHATWG usando el protocolo file:.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de obsolescencia con el id DEP0013.
v4.1.0	Las cadenas numéricas, NaN e Infinity ahora son especificadores de tiempo permitidos.
v0.4.2	Agregado en: v0.4.2

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• callback <Function>
  • err <Error>

Cambia las marcas de tiempo del sistema de archivos del objeto referenciado por path.

Los argumentos atime y mtime siguen estas reglas:

• Los valores pueden ser números que representan el tiempo de época de Unix en segundos, objetos Date o una cadena numérica como '123456789.0'.
• Si el valor no se puede convertir en un número, o es NaN, Infinity o -Infinity, se lanzará un Error.

fs.watch(filename[, options][, listener])

[Historial]

Versión	Cambios
v19.1.0	Se agregó soporte recursivo para Linux, AIX e IBMi.
v15.9.0, v14.17.0	Se agregó soporte para cerrar el observador con un AbortSignal.
v7.6.0	El parámetro filename puede ser un objeto URL WHATWG usando el protocolo file:.
v7.0.0	El objeto options pasado nunca se modificará.
v0.5.10	Agregado en: v0.5.10

• filename <string> | <Buffer> | <URL>

• options <string> | <Object>

  • persistent <boolean> Indica si el proceso debe continuar ejecutándose mientras se están observando archivos. Predeterminado: true.
  • recursive <boolean> Indica si se deben observar todos los subdirectorios o solo el directorio actual. Esto se aplica cuando se especifica un directorio y solo en plataformas compatibles (consulte advertencias). Predeterminado: false.
  • encoding <string> Especifica la codificación de caracteres que se utilizará para el nombre de archivo pasado al oyente. Predeterminado: 'utf8'.
  • signal <AbortSignal> permite cerrar el observador con un AbortSignal.

• listener <Function> | <undefined> Predeterminado: undefined

  • eventType <string>
  • filename <string> | <Buffer> | <null>

• Devuelve: <fs.FSWatcher>

Observa los cambios en filename, donde filename es un archivo o un directorio.

El segundo argumento es opcional. Si se proporciona options como una cadena, especifica la encoding. De lo contrario, options debe pasarse como un objeto.

La función de devolución de llamada del oyente obtiene dos argumentos (eventType, filename). eventType es 'rename' o 'change', y filename es el nombre del archivo que activó el evento.

En la mayoría de las plataformas, se emite 'rename' cada vez que un nombre de archivo aparece o desaparece en el directorio.

La función de devolución de llamada del oyente está adjunta al evento 'change' activado por <fs.FSWatcher>, pero no es lo mismo que el valor 'change' de eventType.

Si se pasa una signal, la cancelación del AbortController correspondiente cerrará el <fs.FSWatcher> devuelto.

Advertencias

La API fs.watch no es 100% consistente en todas las plataformas y no está disponible en algunas situaciones.

En Windows, no se emitirán eventos si el directorio observado se mueve o se cambia de nombre. Se informa de un error EPERM cuando se elimina el directorio observado.

Disponibilidad

Esta característica depende de que el sistema operativo subyacente proporcione una forma de ser notificado de los cambios en el sistema de archivos.

• En sistemas Linux, esto utiliza inotify(7).
• En sistemas BSD, esto utiliza kqueue(2).
• En macOS, esto utiliza kqueue(2) para archivos y FSEvents para directorios.
• En sistemas SunOS (incluidos Solaris y SmartOS), esto utiliza event ports.
• En sistemas Windows, esta función depende de ReadDirectoryChangesW.
• En sistemas AIX, esta función depende de AHAFS, que debe estar habilitado.
• En sistemas IBM i, esta función no es compatible.

Si la funcionalidad subyacente no está disponible por alguna razón, entonces fs.watch() no podrá funcionar y puede generar una excepción. Por ejemplo, la observación de archivos o directorios puede no ser confiable y, en algunos casos, imposible, en sistemas de archivos de red (NFS, SMB, etc.) o sistemas de archivos de host cuando se utiliza software de virtualización como Vagrant o Docker.

Aún es posible usar fs.watchFile(), que utiliza el sondeo de estadísticas, pero este método es más lento y menos confiable.

Inodos

En los sistemas Linux y macOS, fs.watch() resuelve la ruta a un inodo y observa el inodo. Si la ruta observada se elimina y se vuelve a crear, se le asigna un nuevo inodo. El observador emitirá un evento para la eliminación, pero continuará observando el inodo original. Los eventos para el nuevo inodo no se emitirán. Este es el comportamiento esperado.

Los archivos AIX conservan el mismo inodo durante la vida útil de un archivo. Guardar y cerrar un archivo observado en AIX resultará en dos notificaciones (una por agregar contenido nuevo y otra por truncamiento).

Argumento filename

Proporcionar el argumento filename en la devolución de llamada solo es compatible con Linux, macOS, Windows y AIX. Incluso en las plataformas compatibles, no siempre se garantiza que se proporcione filename. Por lo tanto, no asuma que el argumento filename siempre se proporciona en la devolución de llamada, y tenga alguna lógica de reserva si es null.

import { watch } from 'node:fs'
watch('somedir', (eventType, filename) => {
  console.log(`el tipo de evento es: ${eventType}`)
  if (filename) {
    console.log(`filename proporcionado: ${filename}`)
  } else {
    console.log('filename no proporcionado')
  }
})

fs.watchFile(filename[, options], listener)

[Historial]

Versión	Cambios
v10.5.0	Ahora se admite la opción bigint.
v7.6.0	El parámetro filename puede ser un objeto WHATWG URL usando el protocolo file:.
v0.1.31	Añadido en: v0.1.31

• filename <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Predeterminado: false
  • persistent <boolean> Predeterminado: true
  • interval <integer> Predeterminado: 5007

• listener <Function>

  • current <fs.Stats>
  • previous <fs.Stats>

• Devuelve: <fs.StatWatcher>

Vigila los cambios en filename. La función de devolución de llamada listener se llamará cada vez que se acceda al archivo.

El argumento options puede omitirse. Si se proporciona, debe ser un objeto. El objeto options puede contener un booleano llamado persistent que indica si el proceso debe continuar ejecutándose mientras se vigilan los archivos. El objeto options puede especificar una propiedad interval que indica con qué frecuencia se debe sondear el objetivo en milisegundos.

El listener recibe dos argumentos, el objeto stat actual y el objeto stat anterior:

import { watchFile } from 'node:fs'

watchFile('message.text', (curr, prev) => {
  console.log(`el mtime actual es: ${curr.mtime}`)
  console.log(`el mtime anterior era: ${prev.mtime}`)
})

Estos objetos stat son instancias de fs.Stat. Si la opción bigint es true, los valores numéricos en estos objetos se especifican como BigInts.

Para que se le notifique cuando el archivo fue modificado, no solo accedido, es necesario comparar curr.mtimeMs y prev.mtimeMs.

Cuando una operación fs.watchFile da como resultado un error ENOENT, invocará al listener una vez, con todos los campos a cero (o, para las fechas, la época de Unix). Si el archivo se crea más adelante, se volverá a llamar al listener, con los últimos objetos stat. Este es un cambio en la funcionalidad desde v0.10.

Usar fs.watch() es más eficiente que fs.watchFile y fs.unwatchFile. Se debe usar fs.watch en lugar de fs.watchFile y fs.unwatchFile cuando sea posible.

Cuando un archivo que está siendo vigilado por fs.watchFile() desaparece y reaparece, entonces el contenido de previous en el segundo evento de devolución de llamada (la reaparición del archivo) será el mismo que el contenido de previous en el primer evento de devolución de llamada (su desaparición).

Esto sucede cuando:

• el archivo se elimina, seguido de una restauración
• el archivo se cambia de nombre y luego se vuelve a cambiar de nombre a su nombre original

fs.write(fd, buffer, offset[, length[, position]], callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar un callback inválido al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v14.0.0	El parámetro buffer ya no coercionará entradas no admitidas a cadenas.
v10.10.0	El parámetro buffer ahora puede ser cualquier TypedArray o un DataView.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.4.0	El parámetro buffer ahora puede ser un Uint8Array.
v7.2.0	Los parámetros offset y length ahora son opcionales.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de obsolescencia con el id DEP0013.
v0.0.2	Añadido en: v0.0.2

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer> Predeterminado: 0
• length <integer> Predeterminado: buffer.byteLength - offset
• position <integer> | <null> Predeterminado: null
• callback <Function>
  • err <Error>
  • bytesWritten <integer>
  • buffer <Buffer> | <TypedArray> | <DataView>

Escribe buffer en el archivo especificado por fd.

offset determina la parte del buffer que se va a escribir, y length es un entero que especifica el número de bytes a escribir.

position se refiere al desplazamiento desde el comienzo del archivo donde se deben escribir estos datos. Si typeof position !== 'number', los datos se escribirán en la posición actual. Ver pwrite(2).

El callback recibirá tres argumentos (err, bytesWritten, buffer) donde bytesWritten especifica cuántos bytes se escribieron desde buffer.

Si este método se invoca como su versión util.promisify()ed, devuelve una promesa para un Object con propiedades bytesWritten y buffer.

No es seguro usar fs.write() varias veces en el mismo archivo sin esperar el callback. Para este escenario, se recomienda fs.createWriteStream().

En Linux, las escrituras posicionales no funcionan cuando el archivo se abre en modo de anexar. El kernel ignora el argumento de posición y siempre agrega los datos al final del archivo.

fs.write(fd, buffer[, options], callback)

Agregado en: v18.3.0, v16.17.0

• fd <integer>

• buffer <Buffer> | <TypedArray> | <DataView>

• options <Object>

  • offset <integer> Predeterminado: 0
  • length <integer> Predeterminado: buffer.byteLength - offset
  • position <integer> Predeterminado: null

• callback <Function>

  • err <Error>
  • bytesWritten <integer>
  • buffer <Buffer> | <TypedArray> | <DataView>

Escribe buffer en el archivo especificado por fd.

Similar a la función fs.write anterior, esta versión toma un objeto options opcional. Si no se especifica un objeto options, se usará de forma predeterminada los valores anteriores.

fs.write(fd, string[, position[, encoding]], callback)

[Historial]

Versión	Cambios
v19.0.0	Ya no se admite pasar al parámetro string un objeto con una función toString propia.
v17.8.0	Se ha dejado de utilizar pasar al parámetro string un objeto con una función toString propia.
v14.12.0	El parámetro string convertirá en cadena un objeto con una función toString explícita.
v14.0.0	El parámetro string ya no forzará la conversión de entradas no admitidas a cadenas.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo generará un TypeError en tiempo de ejecución.
v7.2.0	El parámetro position ahora es opcional.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de obsolescencia con id DEP0013.
v0.11.5	Añadido en: v0.11.5

• fd <integer>
• string <string>
• position <integer> | <null> Predeterminado: null
• encoding <string> Predeterminado: 'utf8'
• callback <Function>
  • err <Error>
  • written <integer>
  • string <string>

Escribe string en el archivo especificado por fd. Si string no es una cadena, se produce una excepción.

position se refiere al desplazamiento desde el principio del archivo donde se deben escribir estos datos. Si typeof position !== 'number', los datos se escribirán en la posición actual. Consulta pwrite(2).

encoding es la codificación de cadena esperada.

El callback recibirá los argumentos (err, written, string), donde written especifica cuántos bytes requirió la cadena pasada para ser escrita. Los bytes escritos no son necesariamente los mismos que los caracteres de cadena escritos. Consulta Buffer.byteLength.

No es seguro usar fs.write() varias veces en el mismo archivo sin esperar el callback. Para este escenario, se recomienda fs.createWriteStream().

En Linux, las escrituras posicionales no funcionan cuando el archivo se abre en modo de anexión. El kernel ignora el argumento de posición y siempre anexa los datos al final del archivo.

En Windows, si el descriptor de archivo está conectado a la consola (p. ej., fd == 1 o stdout), una cadena que contenga caracteres no ASCII no se representará correctamente de forma predeterminada, independientemente de la codificación utilizada. Es posible configurar la consola para que represente UTF-8 correctamente cambiando la página de códigos activa con el comando chcp 65001. Consulta los documentos de chcp para obtener más detalles.

fs.writeFile(archivo, datos[, opciones], callback)

[Historial]

Versión	Cambios
v21.0.0, v20.10.0	Ahora se admite la opción flush.
v19.0.0	Ya no se admite pasar al parámetro string un objeto con una función propia toString.
v18.0.0	Pasar una callback inválida al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v17.8.0	Pasar al parámetro string un objeto con una función propia toString está obsoleto.
v16.0.0	El error devuelto puede ser un AggregateError si se devuelve más de un error.
v15.2.0, v14.17.0	El argumento de opciones puede incluir un AbortSignal para abortar una solicitud writeFile en curso.
v14.12.0	El parámetro data convertirá en string un objeto con una función explícita toString.
v14.0.0	El parámetro data ya no coaccionará las entradas no admitidas a strings.
v10.10.0	El parámetro data ahora puede ser cualquier TypedArray o un DataView.
v10.0.0	El parámetro callback ya no es opcional. No pasarlo lanzará un TypeError en tiempo de ejecución.
v7.4.0	El parámetro data ahora puede ser un Uint8Array.
v7.0.0	El parámetro callback ya no es opcional. No pasarlo emitirá una advertencia de obsolescencia con el ID DEP0013.
v5.0.0	El parámetro archivo ahora puede ser un descriptor de archivo.
v0.1.29	Añadido en: v0.1.29

• archivo <string> | <Buffer> | <URL> | <integer> nombre de archivo o descriptor de archivo

• datos <string> | <Buffer> | <TypedArray> | <DataView>

• opciones <Object> | <string>

  • encoding <string> | <null> Predeterminado: 'utf8'
  • mode <integer> Predeterminado: 0o666
  • flag <string> Consulte soporte de flags del sistema de archivos. Predeterminado: 'w'.
  • flush <boolean> Si todos los datos se escriben correctamente en el archivo y flush es true, se usa fs.fsync() para vaciar los datos. Predeterminado: false.
  • signal <AbortSignal> permite abortar una writeFile en progreso

• callback <Function>

  • err <Error> | <AggregateError>

Cuando archivo es un nombre de archivo, escribe datos de forma asíncrona en el archivo, reemplazando el archivo si ya existe. datos puede ser un string o un buffer.

Cuando archivo es un descriptor de archivo, el comportamiento es similar a llamar a fs.write() directamente (lo cual es recomendado). Consulte las notas a continuación sobre el uso de un descriptor de archivo.

La opción encoding se ignora si datos es un buffer.

La opción mode solo afecta al archivo recién creado. Consulte fs.open() para obtener más detalles.

import { writeFile } from 'node:fs'
import { Buffer } from 'node:buffer'

const datos = new Uint8Array(Buffer.from('Hola Node.js'))
writeFile('mensaje.txt', datos, err => {
  if (err) throw err
  console.log('¡El archivo ha sido guardado!')
})

Si opciones es un string, entonces especifica la codificación:

import { writeFile } from 'node:fs'

writeFile('mensaje.txt', 'Hola Node.js', 'utf8', callback)

No es seguro usar fs.writeFile() varias veces en el mismo archivo sin esperar la callback. Para este escenario, se recomienda fs.createWriteStream().

De manera similar a fs.readFile, fs.writeFile es un método de conveniencia que realiza varias llamadas a write internamente para escribir el buffer que se le pasa. Para código sensible al rendimiento, considere usar fs.createWriteStream().

Es posible usar un <AbortSignal> para cancelar un fs.writeFile(). La cancelación es "el mejor esfuerzo", y es probable que todavía se escriba una cierta cantidad de datos.

import { writeFile } from 'node:fs'
import { Buffer } from 'node:buffer'

const controlador = new AbortController()
const { signal } = controlador
const datos = new Uint8Array(Buffer.from('Hola Node.js'))
writeFile('mensaje.txt', datos, { signal }, err => {
  // Cuando se aborta una solicitud, se llama a la callback con un AbortError
})
// Cuando se debe abortar la solicitud
controlador.abort()

Abortar una solicitud en curso no aborta las solicitudes individuales del sistema operativo, sino el almacenamiento en búfer interno que realiza fs.writeFile.

Usando fs.writeFile() con descriptores de archivo

Cuando file es un descriptor de archivo, el comportamiento es casi idéntico a llamar directamente a fs.write() como:

import { write } from 'node:fs'
import { Buffer } from 'node:buffer'

write(fd, Buffer.from(data, options.encoding), callback)

La diferencia de llamar directamente a fs.write() es que bajo algunas condiciones inusuales, fs.write() podría escribir solo parte del búfer y necesitaría reintentarse para escribir los datos restantes, mientras que fs.writeFile() reintenta hasta que los datos se escriben completamente (o se produce un error).

Las implicaciones de esto son una fuente común de confusión. En el caso del descriptor de archivo, ¡el archivo no se reemplaza! Los datos no se escriben necesariamente al principio del archivo, y los datos originales del archivo pueden permanecer antes y/o después de los datos recién escritos.

Por ejemplo, si fs.writeFile() se llama dos veces seguidas, primero para escribir la cadena 'Hola', luego para escribir la cadena ', Mundo', el archivo contendría 'Hola, Mundo', y podría contener algunos de los datos originales del archivo (dependiendo del tamaño del archivo original y la posición del descriptor de archivo). Si se hubiera usado un nombre de archivo en lugar de un descriptor, se garantizaría que el archivo solo contendría ', Mundo'.

fs.writev(fd, buffers[, position], callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar una devolución de llamada no válida al argumento callback ahora arroja ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v12.9.0	Añadido en: v12.9.0

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer> | <null> Predeterminado: null
• callback <Function>
  • err <Error>
  • bytesWritten <integer>
  • buffers <ArrayBufferView[]>

Escribe un array de ArrayBufferViews al archivo especificado por fd usando writev().

position es el desplazamiento desde el principio del archivo donde se deben escribir estos datos. Si typeof position !== 'number', los datos se escribirán en la posición actual.

La devolución de llamada recibirá tres argumentos: err, bytesWritten y buffers. bytesWritten es la cantidad de bytes que se escribieron desde buffers.

Si este método es util.promisify()ed, devuelve una promesa para un Objeto con propiedades bytesWritten y buffers.

No es seguro usar fs.writev() varias veces en el mismo archivo sin esperar la devolución de llamada. Para este escenario, use fs.createWriteStream().

En Linux, las escrituras posicionales no funcionan cuando el archivo se abre en modo de anexión. El kernel ignora el argumento de posición y siempre agrega los datos al final del archivo.

API Síncrona

Las API síncronas realizan todas las operaciones de forma síncrona, bloqueando el bucle de eventos hasta que la operación se completa o falla.

fs.accessSync(path[, mode])

[Historial]

Versión	Cambios
v7.6.0	El parámetro path puede ser un objeto WHATWG URL usando el protocolo file:.
v0.11.15	Añadido en: v0.11.15

• path <string> | <Buffer> | <URL>
• mode <integer> Predeterminado: fs.constants.F_OK

Prueba sincrónicamente los permisos de un usuario para el archivo o directorio especificado por path. El argumento mode es un entero opcional que especifica las comprobaciones de accesibilidad que se realizarán. mode debe ser el valor fs.constants.F_OK o una máscara que consista en el OR bit a bit de cualquiera de fs.constants.R_OK, fs.constants.W_OK y fs.constants.X_OK (p. ej., fs.constants.W_OK | fs.constants.R_OK). Consulte Constantes de acceso a archivos para conocer los valores posibles de mode.

Si alguna de las comprobaciones de accesibilidad falla, se lanzará un Error. De lo contrario, el método devolverá undefined.

import { accessSync, constants } from 'node:fs'

try {
  accessSync('etc/passwd', constants.R_OK | constants.W_OK)
  console.log('can read/write')
} catch (err) {
  console.error('no access!')
}

fs.appendFileSync(path, data[, options])

[Historial]

Versión	Cambios
v21.1.0, v20.10.0	Ahora se soporta la opción flush.
v7.0.0	El objeto options pasado nunca será modificado.
v5.0.0	El parámetro file ahora puede ser un descriptor de archivo.
v0.6.7	Añadido en: v0.6.7

• path <string> | <Buffer> | <URL> | <number> nombre de archivo o descriptor de archivo
• data <string> | <Buffer>
• options <Object> | <string>
  • encoding <string> | <null> Predeterminado: 'utf8'
  • mode <integer> Predeterminado: 0o666
  • flag <string> Consulte el soporte de flags del sistema de archivos. Predeterminado: 'a'.
  • flush <boolean> Si es true, el descriptor de archivo subyacente se vacía antes de cerrarlo. Predeterminado: false.

Agrega datos de forma síncrona a un archivo, creando el archivo si aún no existe. data puede ser una cadena o un <Buffer>.

La opción mode solo afecta al archivo recién creado. Consulte fs.open() para obtener más detalles.

import { appendFileSync } from 'node:fs'

try {
  appendFileSync('message.txt', 'datos para agregar')
  console.log('¡Los "datos para agregar" fueron agregados al archivo!')
} catch (err) {
  /* Manejar el error */
}

Si options es una cadena, entonces especifica la codificación:

import { appendFileSync } from 'node:fs'

appendFileSync('message.txt', 'datos para agregar', 'utf8')

El path puede especificarse como un descriptor de archivo numérico que se ha abierto para agregar (usando fs.open() o fs.openSync()). El descriptor de archivo no se cerrará automáticamente.

import { openSync, closeSync, appendFileSync } from 'node:fs'

let fd

try {
  fd = openSync('message.txt', 'a')
  appendFileSync(fd, 'datos para agregar', 'utf8')
} catch (err) {
  /* Manejar el error */
} finally {
  if (fd !== undefined) closeSync(fd)
}

fs.chmodSync(path, mode)

[Historial]

Versión	Cambios
v7.6.0	El parámetro path puede ser un objeto WHATWG URL usando el protocolo file:.
v0.6.7	Añadido en: v0.6.7

• path <string> | <Buffer> | <URL>
• mode <string> | <integer>

Para obtener información detallada, consulta la documentación de la versión asíncrona de esta API: fs.chmod().

Consulta la documentación POSIX chmod(2) para obtener más detalles.

fs.chownSync(path, uid, gid)

[Historial]

Versión	Cambios
v7.6.0	El parámetro path puede ser un objeto WHATWG URL usando el protocolo file:.
v0.1.97	Añadido en: v0.1.97

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>

Cambia sincrónicamente el propietario y el grupo de un archivo. Devuelve undefined. Esta es la versión síncrona de fs.chown().

Consulta la documentación POSIX chown(2) para obtener más detalles.

fs.closeSync(fd)

Añadido en: v0.1.21

• fd <integer>

Cierra el descriptor de archivo. Devuelve undefined.

Llamar a fs.closeSync() en cualquier descriptor de archivo (fd) que esté actualmente en uso a través de cualquier otra operación fs puede llevar a un comportamiento indefinido.

Consulte la documentación POSIX close(2) para obtener más detalles.

fs.copyFileSync(src, dest[, mode])

[Historial]

Versión	Cambios
v14.0.0	Se cambió el argumento flags a mode y se impuso una validación de tipo más estricta.
v8.5.0	Añadido en: v8.5.0

• src <string> | <Buffer> | <URL> nombre de archivo de origen que se copiará
• dest <string> | <Buffer> | <URL> nombre de archivo de destino de la operación de copia
• mode <integer> modificadores para la operación de copia. Predeterminado: 0.

Copia sincrónicamente src a dest. De forma predeterminada, dest se sobrescribe si ya existe. Devuelve undefined. Node.js no ofrece garantías sobre la atomicidad de la operación de copia. Si se produce un error después de que el archivo de destino se haya abierto para escritura, Node.js intentará eliminar el destino.

mode es un entero opcional que especifica el comportamiento de la operación de copia. Es posible crear una máscara que consiste en la operación OR bit a bit de dos o más valores (por ejemplo, fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE).

• fs.constants.COPYFILE_EXCL: La operación de copia fallará si dest ya existe.
• fs.constants.COPYFILE_FICLONE: La operación de copia intentará crear un reflink de copia sobre escritura. Si la plataforma no admite la copia sobre escritura, se utiliza un mecanismo de copia de reserva.
• fs.constants.COPYFILE_FICLONE_FORCE: La operación de copia intentará crear un reflink de copia sobre escritura. Si la plataforma no admite la copia sobre escritura, la operación fallará.

import { copyFileSync, constants } from 'node:fs'

// destination.txt se creará o sobrescribirá de forma predeterminada.
copyFileSync('source.txt', 'destination.txt')
console.log('source.txt se copió a destination.txt')

// Al usar COPYFILE_EXCL, la operación fallará si destination.txt existe.
copyFileSync('source.txt', 'destination.txt', constants.COPYFILE_EXCL)

fs.cpSync(src, dest[, options])

[Historial]

Versión	Cambios
v22.3.0	Esta API ya no es experimental.
v20.1.0, v18.17.0	Acepta una opción mode adicional para especificar el comportamiento de copia como el argumento mode de fs.copyFile().
v17.6.0, v16.15.0	Acepta una opción verbatimSymlinks adicional para especificar si se debe realizar la resolución de rutas para los enlaces simbólicos.
v16.7.0	Añadido en: v16.7.0

• src <string> | <URL> ruta de origen para copiar.

• dest <string> | <URL> ruta de destino para copiar.

• options <Object>

  • dereference <boolean> desreferenciar enlaces simbólicos. Predeterminado: false.

  • errorOnExist <boolean> cuando force es false, y el destino existe, lanza un error. Predeterminado: false.

  • filter <Function> Función para filtrar archivos/directorios copiados. Devuelve true para copiar el elemento, false para ignorarlo. Al ignorar un directorio, todo su contenido también se omitirá. Predeterminado: undefined

  • src <string> ruta de origen para copiar.

  • dest <string> ruta de destino para copiar.

  • Devuelve: <boolean> Cualquier valor que no sea Promise que se pueda forzar a boolean.

  • force <boolean> sobreescribir archivo o directorio existente. La operación de copia ignorará los errores si establece esto en falso y el destino existe. Utilice la opción errorOnExist para cambiar este comportamiento. Predeterminado: true.

  • mode <integer> modificadores para la operación de copia. Predeterminado: 0. Ver indicador mode de fs.copyFileSync().

  • preserveTimestamps <boolean> Cuando es true, se conservarán las marcas de tiempo de src. Predeterminado: false.

  • recursive <boolean> copiar directorios recursivamente. Predeterminado: false

  • verbatimSymlinks <boolean> Cuando es true, se omitirá la resolución de rutas para los enlaces simbólicos. Predeterminado: false

Copia sincrónicamente toda la estructura de directorios de src a dest, incluidos subdirectorios y archivos.

Al copiar un directorio a otro directorio, los globs no son compatibles y el comportamiento es similar a cp dir1/ dir2/.

fs.existsSync(path)

[Historial]

Versión	Cambios
v7.6.0	El parámetro path puede ser un objeto URL WHATWG usando el protocolo file:
v0.1.21	Añadido en: v0.1.21

• path <string> | <Buffer> | <URL>
• Devuelve: <boolean>

Devuelve true si la ruta existe, false en caso contrario.

Para información detallada, consulte la documentación de la versión asíncrona de esta API: fs.exists().

fs.exists() está en desuso, pero fs.existsSync() no lo está. El parámetro callback de fs.exists() acepta parámetros que son inconsistentes con otros callbacks de Node.js. fs.existsSync() no usa un callback.

import { existsSync } from 'node:fs'

if (existsSync('/etc/passwd')) console.log('La ruta existe.')

fs.fchmodSync(fd, mode)

Añadido en: v0.4.7

• fd <integer>
• mode <string> | <integer>

Establece los permisos del archivo. Devuelve undefined.

Consulte la documentación POSIX fchmod(2) para obtener más detalles.

fs.fchownSync(fd, uid, gid)

Añadido en: v0.4.7

• fd <integer>
• uid <integer> El nuevo ID de usuario del propietario del archivo.
• gid <integer> El nuevo ID de grupo del grupo del archivo.

Establece el propietario del archivo. Devuelve undefined.

Consulte la documentación POSIX fchown(2) para obtener más detalles.

fs.fdatasyncSync(fd)

Añadido en: v0.1.96

• fd <integer>

Fuerza todas las operaciones de E/S actualmente en cola asociadas con el archivo al estado de finalización de E/S sincronizada del sistema operativo. Consulte la documentación de POSIX fdatasync(2) para obtener más detalles. Devuelve undefined.

fs.fstatSync(fd[, options])

[Historial]

Versión	Cambios
v10.5.0	Acepta un objeto options adicional para especificar si los valores numéricos devueltos deben ser bigint.
v0.1.95	Añadido en: v0.1.95

• fd <integer>

• options <Object>

  • bigint <boolean> Si los valores numéricos en el objeto <fs.Stats> devuelto deben ser bigint. Predeterminado: false.

• Devuelve: <fs.Stats>

Recupera el <fs.Stats> para el descriptor de archivo.

Consulte la documentación de POSIX fstat(2) para obtener más detalles.

fs.fsyncSync(fd)

Añadido en: v0.1.96

• fd <integer>

Solicita que todos los datos del descriptor de archivo abierto se vacíen en el dispositivo de almacenamiento. La implementación específica depende del sistema operativo y del dispositivo. Consulte la documentación POSIX fsync(2) para obtener más detalles. Devuelve undefined.

fs.ftruncateSync(fd[, len])

Añadido en: v0.8.6

• fd <integer>
• len <integer> Predeterminado: 0

Trunca el descriptor de archivo. Devuelve undefined.

Para obtener información detallada, consulte la documentación de la versión asíncrona de esta API: fs.ftruncate().

fs.futimesSync(fd, atime, mtime)

[Historial]

Versión	Cambios
v4.1.0	Las cadenas numéricas, NaN e Infinity ahora son especificadores de tiempo permitidos.
v0.4.2	Añadido en: v0.4.2

• fd <integer>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>

Versión síncrona de fs.futimes(). Devuelve undefined.

fs.globSync(pattern[, options])

[Historial]

Versión	Cambios
v22.2.0	Se agregó soporte para withFileTypes como opción.
v22.0.0	Añadido en: v22.0.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

• pattern <string> | <string[]>

• options <Object>

  • cwd <string> directorio de trabajo actual. Predeterminado: process.cwd()
  • exclude <Function> Función para filtrar archivos/directorios. Devuelve true para excluir el elemento, false para incluirlo. Predeterminado: undefined.
  • withFileTypes <boolean> true si el glob debe devolver rutas como Dirents, false de lo contrario. Predeterminado: false.

• Devuelve: <string[]> rutas de los archivos que coinciden con el patrón.

ESM

import { globSync } from 'node:fs'

console.log(globSync('**/*.js'))

CJS

const { globSync } = require('node:fs')

console.log(globSync('**/*.js'))

fs.lchmodSync(path, mode)

En desuso desde: v0.4.7

• path <string> | <Buffer> | <URL>
• mode <integer>

Cambia los permisos de un enlace simbólico. Devuelve undefined.

Este método solo está implementado en macOS.

Consulte la documentación POSIX lchmod(2) para más detalles.

fs.lchownSync(path, uid, gid)

[Historial]

Versión	Cambios
v10.6.0	Esta API ya no está en desuso.
v0.4.7	Deprecación solo en la documentación.

• path <string> | <Buffer> | <URL>
• uid <integer> El nuevo ID de usuario del propietario del archivo.
• gid <integer> El nuevo ID de grupo del grupo del archivo.

Establece el propietario de la ruta. Devuelve undefined.

Consulte la documentación POSIX lchown(2) para más detalles.

fs.lutimesSync(path, atime, mtime)

Añadido en: v14.5.0, v12.19.0

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>

Cambia las marcas de tiempo del sistema de archivos del enlace simbólico referenciado por path. Devuelve undefined, o lanza una excepción cuando los parámetros son incorrectos o la operación falla. Esta es la versión síncrona de fs.lutimes().

fs.linkSync(existingPath, newPath)

[Historial]

Versión	Cambios
v7.6.0	Los parámetros existingPath y newPath pueden ser objetos URL WHATWG usando el protocolo file:. El soporte actualmente es todavía experimental.
v0.1.31	Añadido en: v0.1.31

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>

Crea un nuevo enlace desde existingPath a newPath. Ver la documentación POSIX link(2) para más detalles. Devuelve undefined.

fs.lstatSync(path[, options])

[Historial]

Versión	Cambios
v15.3.0, v14.17.0	Acepta una opción throwIfNoEntry para especificar si se debe lanzar una excepción si la entrada no existe.
v10.5.0	Acepta un objeto options adicional para especificar si los valores numéricos devueltos deben ser bigint.
v7.6.0	El parámetro path puede ser un objeto URL WHATWG usando el protocolo file:.
v0.1.30	Añadido en: v0.1.30

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Si los valores numéricos en el objeto <fs.Stats> devuelto deben ser bigint. Predeterminado: false.
  • throwIfNoEntry <boolean> Si se lanzará una excepción si no existe ninguna entrada en el sistema de archivos, en lugar de devolver undefined. Predeterminado: true.

• Devuelve: <fs.Stats>

Recupera el <fs.Stats> para el enlace simbólico al que se refiere path.

Ver la documentación POSIX lstat(2) para más detalles.

fs.mkdirSync(path[, options])

[Historial]

Versión	Cambios
v13.11.0, v12.17.0	En modo recursive, ahora se devuelve la primera ruta creada.
v10.12.0	El segundo argumento ahora puede ser un objeto options con las propiedades recursive y mode.
v7.6.0	El parámetro path puede ser un objeto URL WHATWG usando el protocolo file:.
v0.1.21	Añadido en: v0.1.21

• path <string> | <Buffer> | <URL>

• options <Object> | <integer>

  • recursive <boolean> Predeterminado: false
  • mode <string> | <integer> No soportado en Windows. Predeterminado: 0o777.

• Devuelve: <string> | <undefined>

Crea un directorio de forma síncrona. Devuelve undefined, o si recursive es true, la primera ruta de directorio creada. Esta es la versión síncrona de fs.mkdir().

Consulte la documentación POSIX mkdir(2) para obtener más detalles.

fs.mkdtempSync(prefix[, options])

[Historial]

Versión	Cambios
v20.6.0, v18.19.0	El parámetro prefix ahora acepta buffers y URL.
v16.5.0, v14.18.0	El parámetro prefix ahora acepta una cadena vacía.
v5.10.0	Añadido en: v5.10.0

• prefix <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Predeterminado: 'utf8'

• Devuelve: <string>

Devuelve la ruta del directorio creado.

Para información detallada, consulte la documentación de la versión asíncrona de esta API: fs.mkdtemp().

El argumento opcional options puede ser una cadena que especifique una codificación, o un objeto con una propiedad encoding que especifique la codificación de caracteres a utilizar.

fs.opendirSync(path[, options])

[Historial]

Versión	Cambios
v20.1.0, v18.17.0	Se agregó la opción recursive.
v13.1.0, v12.16.0	Se introdujo la opción bufferSize.
v12.12.0	Añadido en: v12.12.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • encoding <string> | <null> Predeterminado: 'utf8'
  • bufferSize <number> Número de entradas de directorio que se almacenan en búfer internamente al leer desde el directorio. Valores más altos conducen a un mejor rendimiento pero a un mayor consumo de memoria. Predeterminado: 32
  • recursive <boolean> Predeterminado: false

• Devuelve: <fs.Dir>

Abre un directorio de forma síncrona. Ver opendir(3).

Crea un <fs.Dir>, que contiene todas las funciones adicionales para leer y limpiar el directorio.

La opción encoding establece la codificación para la ruta (path) al abrir el directorio y las operaciones de lectura posteriores.

fs.openSync(path[, flags[, mode]])

[Historial]

Versión	Cambios
v11.1.0	El argumento flags ahora es opcional y su valor predeterminado es 'r'.
v9.9.0	Ahora se admiten las marcas as y as+.
v7.6.0	El parámetro path puede ser un objeto URL WHATWG usando el protocolo file:.
v0.1.21	Añadido en: v0.1.21

• path <string> | <Buffer> | <URL>
• flags <string> | <number> Predeterminado: 'r'. Ver compatibilidad de marcas del sistema de archivos.
• mode <string> | <integer> Predeterminado: 0o666
• Devuelve: <number>

Devuelve un entero que representa el descriptor de archivo.

Para información detallada, consulte la documentación de la versión asíncrona de esta API: fs.open().

fs.readdirSync(path[, options])

[Historial]

Versión	Cambios
v20.1.0, v18.17.0	Se agregó la opción recursive.
v10.10.0	Se agregó la nueva opción withFileTypes.
v7.6.0	El parámetro path puede ser un objeto URL de WHATWG usando el protocolo file:.
v0.1.21	Añadido en: v0.1.21

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Predeterminado: 'utf8'
  • withFileTypes <boolean> Predeterminado: false
  • recursive <boolean> Si es true, lee el contenido de un directorio de forma recursiva. En modo recursivo, listará todos los archivos, subarchivos y directorios. Predeterminado: false.

• Devuelve: <string[]> | <Buffer[]> | <fs.Dirent[]>

Lee el contenido del directorio.

Consulte la documentación POSIX readdir(3) para obtener más detalles.

El argumento options opcional puede ser una cadena que especifica una codificación, o un objeto con una propiedad encoding que especifica la codificación de caracteres que se utilizará para los nombres de archivo devueltos. Si encoding se establece en 'buffer', los nombres de archivo devueltos se pasarán como objetos <Buffer>.

Si options.withFileTypes se establece en true, el resultado contendrá objetos <fs.Dirent>.

fs.readFileSync(path[, options])

[Historial]

Versión	Cambios
v7.6.0	El parámetro path puede ser un objeto URL de WHATWG usando el protocolo file:
v5.0.0	El parámetro path puede ser ahora un descriptor de archivo.
v0.1.8	Añadido en: v0.1.8

• path <string> | <Buffer> | <URL> | <integer> nombre de archivo o descriptor de archivo

• options <Object> | <string>

  • encoding <string> | <null> Predeterminado: null
  • flag <string> Ver compatibilidad de flags del sistema de archivos. Predeterminado: 'r'.

• Devuelve: <string> | <Buffer>

Devuelve el contenido de path.

Para información detallada, consulte la documentación de la versión asíncrona de esta API: fs.readFile().

Si se especifica la opción encoding, esta función devuelve una cadena. De lo contrario, devuelve un buffer.

Similar a fs.readFile(), cuando la ruta es un directorio, el comportamiento de fs.readFileSync() es específico de la plataforma.

import { readFileSync } from 'node:fs'

// macOS, Linux y Windows
readFileSync('<directory>')
// => [Error: EISDIR: operación ilegal en un directorio, lectura <directory>]

// FreeBSD
readFileSync('<directory>') // => <data>

fs.readlinkSync(path[, options])

[Historial]

Versión	Cambios
v7.6.0	El parámetro path puede ser un objeto URL de WHATWG usando el protocolo file:
v0.1.31	Añadido en: v0.1.31

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Predeterminado: 'utf8'

• Devuelve: <string> | <Buffer>

Devuelve el valor de cadena del enlace simbólico.

Consulte la documentación POSIX readlink(2) para obtener más detalles.

El argumento options opcional puede ser una cadena que especifica una codificación, o un objeto con una propiedad encoding que especifica la codificación de caracteres que se utilizará para la ruta de enlace devuelta. Si encoding se establece en 'buffer', la ruta de enlace devuelta se pasará como un objeto <Buffer>.

fs.readSync(fd, buffer, offset, length[, position])

[Historial]

Versión	Cambios
v10.10.0	El parámetro buffer ahora puede ser cualquier TypedArray o un DataView.
v6.0.0	El parámetro length ahora puede ser 0.
v0.1.21	Añadido en: v0.1.21

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer>
• length <integer>
• position <integer> | <bigint> | <null> Predeterminado: null
• Devuelve: <number>

Devuelve el número de bytesRead.

Para información detallada, consulte la documentación de la versión asíncrona de esta API: fs.read().

fs.readSync(fd, buffer[, options])

[Historial]

Versión	Cambios
v13.13.0, v12.17.0	Se puede pasar un objeto de opciones para que el desplazamiento, la longitud y la posición sean opcionales.
v13.13.0, v12.17.0	Añadido en: v13.13.0, v12.17.0

• fd <integer>

• buffer <Buffer> | <TypedArray> | <DataView>

• options <Object>

  • offset <integer> Predeterminado: 0
  • length <integer> Predeterminado: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> Predeterminado: null

• Devuelve: <number>

Devuelve el número de bytesRead.

Similar a la función fs.readSync anterior, esta versión toma un objeto options opcional. Si no se especifica ningún objeto options, se utilizará el valor predeterminado anterior.

Para obtener información detallada, consulte la documentación de la versión asíncrona de esta API: fs.read().

fs.readvSync(fd, buffers[, position])

Añadido en: v13.13.0, v12.17.0

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer> | <null> Predeterminado: null
• Devuelve: <number> El número de bytes leídos.

Para información detallada, consulte la documentación de la versión asíncrona de esta API: fs.readv().

fs.realpathSync(path[, options])

[Historial]

Versión	Cambios
v8.0.0	Se añadió la compatibilidad con la resolución de canalizaciones/sockets.
v7.6.0	El parámetro path puede ser un objeto URL WHATWG usando el protocolo file:.
v6.4.0	Llamar a realpathSync ahora funciona de nuevo para varios casos límite en Windows.
v6.0.0	Se eliminó el parámetro cache.
v0.1.31	Añadido en: v0.1.31

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Predeterminado: 'utf8'

• Devuelve: <string> | <Buffer>

Devuelve el nombre de ruta resuelto.

Para información detallada, consulte la documentación de la versión asíncrona de esta API: fs.realpath().

fs.realpathSync.native(path[, options])

Añadido en: v9.2.0

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Predeterminado: 'utf8'

• Devuelve: <string> | <Buffer>

realpath(3) sincrónica.

Solo se admiten rutas que se pueden convertir a cadenas UTF8.

El argumento options opcional puede ser una cadena que especifique una codificación, o un objeto con una propiedad encoding que especifique la codificación de caracteres que se utilizará para la ruta devuelta. Si encoding se establece en 'buffer', la ruta devuelta se pasará como un objeto <Buffer>.

En Linux, cuando Node.js está enlazado con musl libc, el sistema de archivos procfs debe estar montado en /proc para que esta función funcione. Glibc no tiene esta restricción.

fs.renameSync(oldPath, newPath)

[Historial]

Versión	Cambios
v7.6.0	Los parámetros oldPath y newPath pueden ser objetos URL de WHATWG usando el protocolo file:. El soporte aún es experimental.
v0.1.21	Añadido en: v0.1.21

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>

Renombra el archivo de oldPath a newPath. Devuelve undefined.

Vea la documentación POSIX rename(2) para más detalles.

fs.rmdirSync(path[, options])

[Historial]

Versión	Cambios
v16.0.0	Usar fs.rmdirSync(path, { recursive: true }) en una path que es un archivo ya no está permitido y resulta en un error ENOENT en Windows y un error ENOTDIR en POSIX.
v16.0.0	Usar fs.rmdirSync(path, { recursive: true }) en una path que no existe ya no está permitido y resulta en un error ENOENT.
v16.0.0	La opción recursive está en desuso, usarla activa una advertencia de desuso.
v14.14.0	La opción recursive está en desuso, use fs.rmSync en su lugar.
v13.3.0, v12.16.0	La opción maxBusyTries se renombra a maxRetries, y su valor predeterminado es 0. La opción emfileWait se ha eliminado, y los errores EMFILE usan la misma lógica de reintento que otros errores. La opción retryDelay ahora es compatible. Los errores ENFILE ahora se reintentan.
v12.10.0	Las opciones recursive, maxBusyTries y emfileWait ahora son compatibles.
v7.6.0	El parámetro path puede ser un objeto URL de WHATWG usando el protocolo file:.
v0.1.21	Añadido en: v0.1.21

• path <string> | <Buffer> | <URL>
• options <Object>
  • maxRetries <integer> Si se encuentra un error EBUSY, EMFILE, ENFILE, ENOTEMPTY o EPERM, Node.js reintenta la operación con una espera de retroceso lineal de retryDelay milisegundos más en cada intento. Esta opción representa el número de reintentos. Esta opción se ignora si la opción recursive no es true. Predeterminado: 0.
  • recursive <boolean> Si es true, realiza una eliminación de directorio recursiva. En modo recursivo, las operaciones se reintentan en caso de fallo. Predeterminado: false. En desuso.
  • retryDelay <integer> La cantidad de tiempo en milisegundos que se debe esperar entre reintentos. Esta opción se ignora si la opción recursive no es true. Predeterminado: 100.

rmdir(2) sincrónico. Devuelve undefined.

Usar fs.rmdirSync() en un archivo (no un directorio) resulta en un error ENOENT en Windows y un error ENOTDIR en POSIX.

Para obtener un comportamiento similar al comando Unix rm -rf, use fs.rmSync() con las opciones { recursive: true, force: true }.

fs.rmSync(path[, options])

[Historial]

Versión	Cambios
v17.3.0, v16.14.0	El parámetro path puede ser un objeto URL de WHATWG usando el protocolo file:
v14.14.0	Añadido en: v14.14.0

• path <string> | <Buffer> | <URL>
• options <Object>
  • force <boolean> Cuando es true, se ignorarán las excepciones si path no existe. Predeterminado: false.
  • maxRetries <integer> Si se encuentra un error EBUSY, EMFILE, ENFILE, ENOTEMPTY o EPERM, Node.js volverá a intentar la operación con una espera de retroceso lineal de retryDelay milisegundos más en cada intento. Esta opción representa el número de reintentos. Esta opción se ignora si la opción recursive no es true. Predeterminado: 0.
  • recursive <boolean> Si es true, realiza una eliminación de directorio recursiva. En modo recursivo, las operaciones se reintentan en caso de fallo. Predeterminado: false.
  • retryDelay <integer> La cantidad de tiempo en milisegundos que se debe esperar entre reintentos. Esta opción se ignora si la opción recursive no es true. Predeterminado: 100.

Elimina de forma síncrona archivos y directorios (modelado en la utilidad POSIX estándar rm). Devuelve undefined.

fs.statSync(path[, options])

[Historial]

Versión	Cambios
v15.3.0, v14.17.0	Acepta una opción throwIfNoEntry para especificar si se debe lanzar una excepción si la entrada no existe.
v10.5.0	Acepta un objeto options adicional para especificar si los valores numéricos devueltos deben ser bigint.
v7.6.0	El parámetro path puede ser un objeto URL WHATWG usando el protocolo file:.
v0.1.21	Añadido en: v0.1.21

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Si los valores numéricos en el objeto <fs.Stats> devuelto deben ser bigint. Predeterminado: false.
  • throwIfNoEntry <boolean> Si se lanzará una excepción si no existe ninguna entrada en el sistema de archivos, en lugar de devolver undefined. Predeterminado: true.

• Devuelve: <fs.Stats>

Recupera las <fs.Stats> para la ruta.

fs.statfsSync(path[, options])

Añadido en: v19.6.0, v18.15.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Si los valores numéricos en el objeto <fs.StatFs> devuelto deben ser bigint. Predeterminado: false.

• Devuelve: <fs.StatFs>

statfs(2) sincrónico. Devuelve información sobre el sistema de archivos montado que contiene path.

En caso de error, err.code será uno de los Errores comunes del sistema.

fs.symlinkSync(target, path[, type])

[Historial]

Versión	Cambios
v12.0.0	Si el argumento type se deja sin definir, Node detectará automáticamente el tipo de target y seleccionará automáticamente dir o file.
v7.6.0	Los parámetros target y path pueden ser objetos URL WHATWG usando el protocolo file:. El soporte es actualmente aún experimental.
v0.1.31	Añadido en: v0.1.31

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> | <null> Predeterminado: null

Devuelve undefined.

Para información detallada, consulte la documentación de la versión asíncrona de esta API: fs.symlink().

fs.truncateSync(path[, len])

Añadido en: v0.8.6

• path <string> | <Buffer> | <URL>
• len <integer> Predeterminado: 0

Trunca el archivo. Devuelve undefined. También se puede pasar un descriptor de archivo como primer argumento. En este caso, se llama a fs.ftruncateSync().

Pasar un descriptor de archivo está en desuso y puede provocar que se lance un error en el futuro.

fs.unlinkSync(path)

[Historial]

Versión	Cambios
v7.6.0	El parámetro path puede ser un objeto URL WHATWG usando el protocolo file:
v0.1.21	Añadido en: v0.1.21

• path <string> | <Buffer> | <URL>

unlink(2) sincrónico. Devuelve undefined.

fs.utimesSync(path, atime, mtime)

[Historial]

Versión	Cambios
v8.0.0	NaN, Infinity y -Infinity ya no son especificadores de tiempo válidos.
v7.6.0	El parámetro path puede ser un objeto URL WHATWG usando el protocolo file:.
v4.1.0	Las cadenas numéricas, NaN e Infinity ahora son especificadores de tiempo permitidos.
v0.4.2	Añadido en: v0.4.2

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>

Devuelve undefined.

Para información detallada, consulte la documentación de la versión asíncrona de esta API: fs.utimes().

fs.writeFileSync(file, data[, options])

[Historial]

Versión	Cambios
v21.0.0, v20.10.0	Ahora se admite la opción flush.
v19.0.0	Ya no se admite pasar al parámetro data un objeto con una función toString propia.
v17.8.0	Se ha declarado en desuso pasar al parámetro data un objeto con una función toString propia.
v14.12.0	El parámetro data convertirá en cadena un objeto con una función toString explícita.
v14.0.0	El parámetro data ya no forzará la conversión de entradas no compatibles a cadenas.
v10.10.0	El parámetro data ahora puede ser cualquier TypedArray o un DataView.
v7.4.0	El parámetro data ahora puede ser un Uint8Array.
v5.0.0	El parámetro file ahora puede ser un descriptor de archivo.
v0.1.29	Añadido en: v0.1.29

• file <string> | <Buffer> | <URL> | <integer> nombre de archivo o descriptor de archivo
• data <string> | <Buffer> | <TypedArray> | <DataView>
• options <Object> | <string>
  • encoding <string> | <null> Predeterminado: 'utf8'
  • mode <integer> Predeterminado: 0o666
  • flag <string> Ver compatibilidad de indicadores del sistema de archivos. Predeterminado: 'w'.
  • flush <boolean> Si todos los datos se escriben correctamente en el archivo y flush es true, se utiliza fs.fsyncSync() para vaciar los datos.

Devuelve undefined.

La opción mode solo afecta al archivo recién creado. Consulte fs.open() para obtener más detalles.

Para obtener información detallada, consulte la documentación de la versión asincrónica de esta API: fs.writeFile().

fs.writeSync(fd, buffer, offset[, length[, position]])

[Historial]

Versión	Cambios
v14.0.0	El parámetro buffer ya no forzará la conversión de entradas no compatibles a cadenas.
v10.10.0	El parámetro buffer ahora puede ser cualquier TypedArray o un DataView.
v7.4.0	El parámetro buffer ahora puede ser un Uint8Array.
v7.2.0	Los parámetros offset y length ahora son opcionales.
v0.1.21	Añadido en: v0.1.21

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer> Predeterminado: 0
• length <integer> Predeterminado: buffer.byteLength - offset
• position <integer> | <null> Predeterminado: null
• Devuelve: <number> El número de bytes escritos.

Para información detallada, consulte la documentación de la versión asíncrona de esta API: fs.write(fd, buffer...).

fs.writeSync(fd, buffer[, options])

Añadido en: v18.3.0, v16.17.0

• fd <integer>

• buffer <Buffer> | <TypedArray> | <DataView>

• options <Object>

  • offset <integer> Predeterminado: 0
  • length <integer> Predeterminado: buffer.byteLength - offset
  • position <integer> Predeterminado: null

• Devuelve: <number> El número de bytes escritos.

Para información detallada, consulte la documentación de la versión asíncrona de esta API: fs.write(fd, buffer...).

fs.writeSync(fd, string[, position[, encoding]])

[Historial]

Versión	Cambios
v14.0.0	El parámetro string ya no forzará la conversión de entradas no compatibles a cadenas.
v7.2.0	El parámetro position ahora es opcional.
v0.11.5	Añadido en: v0.11.5

• fd <integer>
• string <string>
• position <integer> | <null> Predeterminado: null
• encoding <string> Predeterminado: 'utf8'
• Devuelve: <number> El número de bytes escritos.

Para información detallada, consulte la documentación de la versión asíncrona de esta API: fs.write(fd, string...).

fs.writevSync(fd, buffers[, position])

Añadido en: v12.9.0

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer> | <null> Predeterminado: null
• Devuelve: <number> El número de bytes escritos.

Para información detallada, consulte la documentación de la versión asíncrona de esta API: fs.writev().

Objetos Comunes

Los objetos comunes son compartidos por todas las variantes de la API del sistema de archivos (promesa, devolución de llamada y sincrónica).

Clase: fs.Dir

Añadido en: v12.12.0

Una clase que representa una secuencia de directorios.

Creada por fs.opendir(), fs.opendirSync(), o fsPromises.opendir().

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

try {
  const dir = await opendir('./')
  for await (const dirent of dir) console.log(dirent.name)
} catch (err) {
  console.error(err)
}

Cuando se utiliza el iterador asíncrono, el objeto <fs.Dir> se cerrará automáticamente después de que el iterador salga.

dir.close()

Añadido en: v12.12.0

• Devuelve: <Promise>

Cierra de forma asíncrona el manejador de recursos subyacente del directorio. Las lecturas posteriores producirán errores.

Se devuelve una promesa que se cumplirá después de que el recurso haya sido cerrado.

dir.close(callback)

[Historial]

Versión	Cambios
v18.0.0	Pasar un callback inválido al argumento callback ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
v12.12.0	Añadido en: v12.12.0

• callback <Function>
  • err <Error>

Cierra de forma asíncrona el manejador de recursos subyacente del directorio. Las lecturas posteriores producirán errores.

El callback se llamará después de que el manejador de recursos haya sido cerrado.

dir.closeSync()

Añadido en: v12.12.0

Cierra sincrónicamente el manejador de recursos subyacente del directorio. Las lecturas posteriores resultarán en errores.

dir.path

Añadido en: v12.12.0

• <string>

La ruta de solo lectura de este directorio, tal como se proporcionó a fs.opendir(), fs.opendirSync(), o fsPromises.opendir().

dir.read()

Añadido en: v12.12.0

• Devuelve: <Promise> Se cumple con un <fs.Dirent> | <null>

Lee asíncronamente la siguiente entrada del directorio a través de readdir(3) como un <fs.Dirent>.

Se devuelve una promesa que se cumplirá con un <fs.Dirent>, o null si no hay más entradas de directorio que leer.

Las entradas de directorio devueltas por esta función no tienen un orden en particular, según lo proporciona los mecanismos de directorio subyacentes del sistema operativo. Las entradas agregadas o eliminadas mientras se itera sobre el directorio podrían no incluirse en los resultados de la iteración.

dir.read(callback)

Añadido en: v12.12.0

• callback <Function>
  • err <Error>
  • dirent <fs.Dirent> | <null>

Lee asincrónicamente la siguiente entrada de directorio a través de readdir(3) como un <fs.Dirent>.

Una vez completada la lectura, se llamará a la función callback con un <fs.Dirent>, o null si no hay más entradas de directorio que leer.

Las entradas de directorio devueltas por esta función no están en ningún orden en particular, según lo proporcionado por los mecanismos de directorio subyacentes del sistema operativo. Las entradas añadidas o eliminadas mientras se itera sobre el directorio podrían no incluirse en los resultados de la iteración.

dir.readSync()

Añadido en: v12.12.0

• Devuelve: <fs.Dirent> | <null>

Lee sincrónicamente la siguiente entrada de directorio como un <fs.Dirent>. Consulta la documentación POSIX readdir(3) para más detalles.

Si no hay más entradas de directorio que leer, se devolverá null.

Las entradas de directorio devueltas por esta función no tienen un orden en particular, según los mecanismos subyacentes de directorio del sistema operativo. Las entradas agregadas o eliminadas mientras se itera sobre el directorio podrían no incluirse en los resultados de la iteración.

dir[Symbol.asyncIterator]()

Añadido en: v12.12.0

• Devuelve: <AsyncIterator> Un AsyncIterator de <fs.Dirent>

Itera asincrónicamente sobre el directorio hasta que se hayan leído todas las entradas. Consulta la documentación POSIX readdir(3) para más detalles.

Las entradas devueltas por el iterador asíncrono son siempre un <fs.Dirent>. El caso null de dir.read() se maneja internamente.

Ver <fs.Dir> para un ejemplo.

Las entradas de directorio devueltas por este iterador no tienen un orden en particular, según los mecanismos subyacentes de directorio del sistema operativo. Las entradas agregadas o eliminadas mientras se itera sobre el directorio podrían no incluirse en los resultados de la iteración.

Clase: fs.Dirent

Añadido en: v10.10.0

Una representación de una entrada de directorio, que puede ser un archivo o un subdirectorio dentro del directorio, como se devuelve al leer desde un <fs.Dir>. La entrada del directorio es una combinación de pares de nombre de archivo y tipo de archivo.

Además, cuando se llama a fs.readdir() o fs.readdirSync() con la opción withFileTypes establecida en true, la matriz resultante se llena con objetos <fs.Dirent>, en lugar de cadenas o <Buffer>.

dirent.isBlockDevice()

Añadido en: v10.10.0

• Devuelve: <boolean>

Devuelve true si el objeto <fs.Dirent> describe un dispositivo de bloque.

dirent.isCharacterDevice()

Añadido en: v10.10.0

• Devuelve: <boolean>

Devuelve true si el objeto <fs.Dirent> describe un dispositivo de carácter.

dirent.isDirectory()

Añadido en: v10.10.0

• Devuelve: <boolean>

Devuelve true si el objeto <fs.Dirent> describe un directorio del sistema de archivos.

dirent.isFIFO()

Añadido en: v10.10.0

• Devuelve: <boolean>

Devuelve true si el objeto <fs.Dirent> describe una tubería FIFO (first-in-first-out).

dirent.isFile()

Añadido en: v10.10.0

• Devuelve: <boolean>

Devuelve true si el objeto <fs.Dirent> describe un archivo regular.

dirent.isSocket()

Añadido en: v10.10.0

• Devuelve: <boolean>

Devuelve true si el objeto <fs.Dirent> describe un socket.

dirent.isSymbolicLink()

Añadido en: v10.10.0

• Devuelve: <boolean>

Devuelve true si el objeto <fs.Dirent> describe un enlace simbólico.

dirent.name

Añadido en: v10.10.0

• <string> | <Buffer>

El nombre del archivo al que se refiere este objeto <fs.Dirent>. El tipo de este valor está determinado por options.encoding pasado a fs.readdir() o fs.readdirSync().

dirent.parentPath

Añadido en: v21.4.0, v20.12.0, v18.20.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

• <string>

La ruta al directorio padre del archivo al que se refiere este objeto <fs.Dirent>.

dirent.path

[Historial]

Versión	Cambios
v23.2.0	La propiedad ya no es de solo lectura.
v23.0.0	Acceder a esta propiedad emite una advertencia. Ahora es de solo lectura.
v21.5.0, v20.12.0, v18.20.0	Obsoleto desde: v21.5.0, v20.12.0, v18.20.0
v20.1.0, v18.17.0	Añadido en: v20.1.0, v18.17.0

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto: Use dirent.parentPath en su lugar.

• <string>

Alias de dirent.parentPath.

Clase: fs.FSWatcher

Añadido en: v0.5.8

• Extiende <EventEmitter>

Una llamada exitosa al método fs.watch() devolverá un nuevo objeto <fs.FSWatcher>.

Todos los objetos <fs.FSWatcher> emiten un evento 'change' cada vez que se modifica un archivo específico observado.

Evento: 'change'

Añadido en: v0.5.8

• eventType <string> El tipo de evento de cambio que ha ocurrido
• filename <string> | <Buffer> El nombre del archivo que cambió (si es relevante/está disponible)

Emitido cuando algo cambia en un directorio o archivo observado. Ver más detalles en fs.watch().

El argumento filename puede no proporcionarse dependiendo del soporte del sistema operativo. Si se proporciona filename, se proporcionará como un <Buffer> si fs.watch() se llama con su opción encoding establecida en 'buffer', de lo contrario filename será una cadena UTF-8.

import { watch } from 'node:fs'
// Ejemplo cuando se maneja a través del escuchador fs.watch()
watch('./tmp', { encoding: 'buffer' }, (eventType, filename) => {
  if (filename) {
    console.log(filename)
    // Imprime: <Buffer ...>
  }
})

Evento: 'close'

Agregado en: v10.0.0

Se emite cuando el observador deja de buscar cambios. El objeto <fs.FSWatcher> cerrado ya no se puede usar en el controlador de eventos.

Evento: 'error'

Agregado en: v0.5.8

• error <Error>

Se emite cuando ocurre un error al observar el archivo. El objeto <fs.FSWatcher> con error ya no se puede usar en el controlador de eventos.

watcher.close()

Agregado en: v0.5.8

Deja de observar los cambios en el <fs.FSWatcher> dado. Una vez detenido, el objeto <fs.FSWatcher> ya no se puede usar.

watcher.ref()

Agregado en: v14.3.0, v12.20.0

• Devuelve: <fs.FSWatcher>

Cuando se llama, solicita que el bucle de eventos de Node.js no se cierre mientras el <fs.FSWatcher> esté activo. Llamar a watcher.ref() varias veces no tendrá ningún efecto.

De forma predeterminada, todos los objetos <fs.FSWatcher> están "referenciados", por lo que normalmente no es necesario llamar a watcher.ref() a menos que se haya llamado previamente a watcher.unref().

watcher.unref()

Agregado en: v14.3.0, v12.20.0

• Devuelve: <fs.FSWatcher>

Cuando se llama, el objeto <fs.FSWatcher> activo no requerirá que el bucle de eventos de Node.js permanezca activo. Si no hay otra actividad que mantenga el bucle de eventos en ejecución, el proceso puede finalizar antes de que se invoque la devolución de llamada del objeto <fs.FSWatcher>. Llamar a watcher.unref() varias veces no tendrá ningún efecto.

Clase: fs.StatWatcher

Agregado en: v14.3.0, v12.20.0

• Se extiende de <EventEmitter>

Una llamada exitosa al método fs.watchFile() devolverá un nuevo objeto <fs.StatWatcher>.

watcher.ref()

Agregado en: v14.3.0, v12.20.0

• Devuelve: <fs.StatWatcher>

Cuando se llama, solicita que el bucle de eventos de Node.js no finalice mientras el <fs.StatWatcher> esté activo. Llamar a watcher.ref() varias veces no tendrá ningún efecto.

De forma predeterminada, todos los objetos <fs.StatWatcher> están "referenciados", por lo que normalmente no es necesario llamar a watcher.ref() a menos que se haya llamado a watcher.unref() previamente.

watcher.unref()

Agregado en: v14.3.0, v12.20.0

• Devuelve: <fs.StatWatcher>

Cuando se llama, el objeto <fs.StatWatcher> activo no requerirá que el bucle de eventos de Node.js permanezca activo. Si no hay otra actividad que mantenga el bucle de eventos en funcionamiento, el proceso puede salir antes de que se invoque la función de callback del objeto <fs.StatWatcher>. Llamar a watcher.unref() varias veces no tendrá ningún efecto.

Clase: fs.ReadStream

Agregado en: v0.1.93

• Extiende: <stream.Readable>

Las instancias de <fs.ReadStream> se crean y se devuelven utilizando la función fs.createReadStream().

Evento: 'close'

Agregado en: v0.1.93

Emitido cuando se ha cerrado el descriptor de archivo subyacente de <fs.ReadStream>.

Evento: 'open'

Agregado en: v0.1.93

• fd <integer> Descriptor de archivo entero utilizado por <fs.ReadStream>.

Emitido cuando se ha abierto el descriptor de archivo de <fs.ReadStream>.

Evento: 'ready'

Agregado en: v9.11.0

Se emite cuando el <fs.ReadStream> está listo para ser usado.

Se activa inmediatamente después de 'open'.

readStream.bytesRead

Agregado en: v6.4.0

• <number>

El número de bytes que se han leído hasta el momento.

readStream.path

Agregado en: v0.1.93

• <string> | <Buffer>

La ruta al archivo desde el que el flujo está leyendo, como se especifica en el primer argumento de fs.createReadStream(). Si path se pasa como una cadena, entonces readStream.path será una cadena. Si path se pasa como un <Buffer>, entonces readStream.path será un <Buffer>. Si se especifica fd, entonces readStream.path será undefined.

readStream.pending

Agregado en: v11.2.0, v10.16.0

• <boolean>

Esta propiedad es true si el archivo subyacente aún no se ha abierto, es decir, antes de que se emita el evento 'ready'.

Clase: fs.Stats

[Historial]

Versión	Cambios
v22.0.0, v20.13.0	El constructor público está obsoleto.
v8.1.0	Se añadieron los tiempos como números.
v0.1.21	Añadido en: v0.1.21

Un objeto <fs.Stats> proporciona información sobre un archivo.

Los objetos devueltos por fs.stat(), fs.lstat(), fs.fstat() y sus contrapartes síncronas son de este tipo. Si bigint en las options pasadas a esos métodos es verdadero, los valores numéricos serán bigint en lugar de number, y el objeto contendrá propiedades adicionales con precisión en nanosegundos con el sufijo Ns. Los objetos Stat no se deben crear directamente usando la palabra clave new.

Stats {
  dev: 2114,
  ino: 48064969,
  mode: 33188,
  nlink: 1,
  uid: 85,
  gid: 100,
  rdev: 0,
  size: 527,
  blksize: 4096,
  blocks: 8,
  atimeMs: 1318289051000.1,
  mtimeMs: 1318289051000.1,
  ctimeMs: 1318289051000.1,
  birthtimeMs: 1318289051000.1,
  atime: Lun, 10 Oct 2011 23:24:11 GMT,
  mtime: Lun, 10 Oct 2011 23:24:11 GMT,
  ctime: Lun, 10 Oct 2011 23:24:11 GMT,
  birthtime: Lun, 10 Oct 2011 23:24:11 GMT }

Versión bigint:

BigIntStats {
  dev: 2114n,
  ino: 48064969n,
  mode: 33188n,
  nlink: 1n,
  uid: 85n,
  gid: 100n,
  rdev: 0n,
  size: 527n,
  blksize: 4096n,
  blocks: 8n,
  atimeMs: 1318289051000n,
  mtimeMs: 1318289051000n,
  ctimeMs: 1318289051000n,
  birthtimeMs: 1318289051000n,
  atimeNs: 1318289051000000000n,
  mtimeNs: 1318289051000000000n,
  ctimeNs: 1318289051000000000n,
  birthtimeNs: 1318289051000000000n,
  atime: Lun, 10 Oct 2011 23:24:11 GMT,
  mtime: Lun, 10 Oct 2011 23:24:11 GMT,
  ctime: Lun, 10 Oct 2011 23:24:11 GMT,
  birthtime: Lun, 10 Oct 2011 23:24:11 GMT }

stats.isBlockDevice()

Agregado en: v0.1.10

• Devuelve: <boolean>

Devuelve true si el objeto <fs.Stats> describe un dispositivo de bloque.

stats.isCharacterDevice()

Agregado en: v0.1.10

• Devuelve: <boolean>

Devuelve true si el objeto <fs.Stats> describe un dispositivo de carácter.

stats.isDirectory()

Agregado en: v0.1.10

• Devuelve: <boolean>

Devuelve true si el objeto <fs.Stats> describe un directorio del sistema de archivos.

Si el objeto <fs.Stats> se obtuvo al llamar a fs.lstat() en un enlace simbólico que se resuelve en un directorio, este método devolverá false. Esto se debe a que fs.lstat() devuelve información sobre un enlace simbólico en sí mismo y no sobre la ruta a la que se resuelve.

stats.isFIFO()

Agregado en: v0.1.10

• Devuelve: <boolean>

Devuelve true si el objeto <fs.Stats> describe una tubería primero en entrar, primero en salir (FIFO).

stats.isFile()

Agregado en: v0.1.10

• Devuelve: <boolean>

Devuelve true si el objeto <fs.Stats> describe un archivo regular.

stats.isSocket()

Agregado en: v0.1.10

• Devuelve: <boolean>

Devuelve true si el objeto <fs.Stats> describe un socket.

stats.isSymbolicLink()

Agregado en: v0.1.10

• Devuelve: <boolean>

Devuelve true si el objeto <fs.Stats> describe un enlace simbólico.

Este método solo es válido cuando se usa fs.lstat().

stats.dev

• <number> | <bigint>

El identificador numérico del dispositivo que contiene el archivo.

stats.ino

• <number> | <bigint>

El número "Inode" específico del sistema de archivos para el archivo.

stats.mode

• <number> | <bigint>

Un campo de bits que describe el tipo y modo de archivo.

stats.nlink

• <number> | <bigint>

El número de enlaces físicos que existen para el archivo.

stats.uid

• <number> | <bigint>

El identificador numérico del usuario propietario del archivo (POSIX).

stats.gid

• <number> | <bigint>

El identificador numérico del grupo propietario del archivo (POSIX).

stats.rdev

• <number> | <bigint>

Un identificador numérico de dispositivo si el archivo representa un dispositivo.

stats.size

• <number> | <bigint>

El tamaño del archivo en bytes.

Si el sistema de archivos subyacente no admite la obtención del tamaño del archivo, este será 0.

stats.blksize

• <number> | <bigint>

El tamaño del bloque del sistema de archivos para las operaciones de i/o.

stats.blocks

• <number> | <bigint>

El número de bloques asignados para este archivo.

stats.atimeMs

Agregado en: v8.1.0

• <number> | <bigint>

La marca de tiempo que indica la última vez que se accedió a este archivo, expresada en milisegundos desde la época POSIX.

stats.mtimeMs

Agregado en: v8.1.0

• <number> | <bigint>

La marca de tiempo que indica la última vez que se modificó este archivo, expresada en milisegundos desde la época POSIX.

stats.ctimeMs

Añadido en: v8.1.0

• <number> | <bigint>

La marca de tiempo que indica la última vez que se cambió el estado del archivo expresada en milisegundos desde la época POSIX.

stats.birthtimeMs

Añadido en: v8.1.0

• <number> | <bigint>

La marca de tiempo que indica la hora de creación de este archivo expresada en milisegundos desde la época POSIX.

stats.atimeNs

Añadido en: v12.10.0

• <bigint>

Solo presente cuando se pasa bigint: true al método que genera el objeto. La marca de tiempo que indica la última vez que se accedió a este archivo expresada en nanosegundos desde la época POSIX.

stats.mtimeNs

Agregado en: v12.10.0

• <bigint>

Solo presente cuando se pasa bigint: true al método que genera el objeto. La marca de tiempo que indica la última vez que se modificó este archivo, expresada en nanosegundos desde la Época POSIX.

stats.ctimeNs

Agregado en: v12.10.0

• <bigint>

Solo presente cuando se pasa bigint: true al método que genera el objeto. La marca de tiempo que indica la última vez que se cambió el estado del archivo, expresada en nanosegundos desde la Época POSIX.

stats.birthtimeNs

Agregado en: v12.10.0

• <bigint>

Solo presente cuando se pasa bigint: true al método que genera el objeto. La marca de tiempo que indica la hora de creación de este archivo, expresada en nanosegundos desde la Época POSIX.

stats.atime

Agregado en: v0.11.13

• <Fecha>

La marca de tiempo que indica la última vez que se accedió a este archivo.

stats.mtime

Agregado en: v0.11.13

• <Fecha>

La marca de tiempo que indica la última vez que se modificó este archivo.

stats.ctime

Agregado en: v0.11.13

• <Fecha>

La marca de tiempo que indica la última vez que se cambió el estado del archivo.

stats.birthtime

Agregado en: v0.11.13

• <Fecha>

La marca de tiempo que indica la hora de creación de este archivo.

Valores de tiempo Stat

Las propiedades atimeMs, mtimeMs, ctimeMs, birthtimeMs son valores numéricos que contienen los tiempos correspondientes en milisegundos. Su precisión es específica de la plataforma. Cuando se pasa bigint: true al método que genera el objeto, las propiedades serán bigints, de lo contrario serán números.

Las propiedades atimeNs, mtimeNs, ctimeNs, birthtimeNs son bigints que contienen los tiempos correspondientes en nanosegundos. Solo están presentes cuando se pasa bigint: true al método que genera el objeto. Su precisión es específica de la plataforma.

atime, mtime, ctime y birthtime son representaciones alternativas de objetos Date de los diferentes tiempos. Los valores de Date y número no están conectados. La asignación de un nuevo valor numérico o la modificación del valor Date no se reflejarán en la representación alternativa correspondiente.

Los tiempos en el objeto stat tienen la siguiente semántica:

• atime "Tiempo de acceso": Tiempo en que se accedió por última vez a los datos del archivo. Cambiado por las llamadas al sistema mknod(2), utimes(2) y read(2).
• mtime "Tiempo de modificación": Tiempo en que se modificaron por última vez los datos del archivo. Cambiado por las llamadas al sistema mknod(2), utimes(2) y write(2).
• ctime "Tiempo de cambio": Tiempo en que se cambió por última vez el estado del archivo (modificación de datos del inodo). Cambiado por las llamadas al sistema chmod(2), chown(2), link(2), mknod(2), rename(2), unlink(2), utimes(2), read(2) y write(2).
• birthtime "Tiempo de creación": Tiempo de creación del archivo. Se establece una vez cuando se crea el archivo. En los sistemas de archivos donde no está disponible el tiempo de creación, este campo puede contener el ctime o 1970-01-01T00:00Z (es decir, la marca de tiempo de la época Unix 0). En este caso, este valor puede ser mayor que atime o mtime. En Darwin y otras variantes de FreeBSD, también se establece si el atime se establece explícitamente en un valor anterior al birthtime actual utilizando la llamada al sistema utimes(2).

Antes de Node.js 0.12, el ctime contenía el birthtime en los sistemas Windows. A partir de 0.12, ctime no es el "tiempo de creación", y en los sistemas Unix, nunca lo fue.

Clase: fs.StatFs

Añadido en: v19.6.0, v18.15.0

Proporciona información sobre un sistema de archivos montado.

Los objetos devueltos por fs.statfs() y su contraparte síncrona son de este tipo. Si bigint en las options pasadas a esos métodos es true, los valores numéricos serán bigint en lugar de number.

StatFs {
  type: 1397114950,
  bsize: 4096,
  blocks: 121938943,
  bfree: 61058895,
  bavail: 61058895,
  files: 999,
  ffree: 1000000
}

Versión bigint:

StatFs {
  type: 1397114950n,
  bsize: 4096n,
  blocks: 121938943n,
  bfree: 61058895n,
  bavail: 61058895n,
  files: 999n,
  ffree: 1000000n
}

statfs.bavail

Añadido en: v19.6.0, v18.15.0

• <number> | <bigint>

Bloques libres disponibles para usuarios no privilegiados.

statfs.bfree

Agregado en: v19.6.0, v18.15.0

• <number> | <bigint>

Bloques libres en el sistema de archivos.

statfs.blocks

Agregado en: v19.6.0, v18.15.0

• <number> | <bigint>

Total de bloques de datos en el sistema de archivos.

statfs.bsize

Agregado en: v19.6.0, v18.15.0

• <number> | <bigint>

Tamaño óptimo de bloque de transferencia.

statfs.ffree

Agregado en: v19.6.0, v18.15.0

• <number> | <bigint>

Nodos de archivo libres en el sistema de archivos.

statfs.files

Añadido en: v19.6.0, v18.15.0

• <number> | <bigint>

Nodos de archivo totales en el sistema de archivos.

statfs.type

Añadido en: v19.6.0, v18.15.0

• <number> | <bigint>

Tipo de sistema de archivos.

Clase: fs.WriteStream

Añadido en: v0.1.93

• Extiende <stream.Writable>

Las instancias de <fs.WriteStream> se crean y se devuelven utilizando la función fs.createWriteStream().

Evento: 'close'

Añadido en: v0.1.93

Emitido cuando se ha cerrado el descriptor de archivo subyacente de <fs.WriteStream>.

Evento: 'open'

Agregado en: v0.1.93

• fd <integer> Descriptor de archivo entero utilizado por <fs.WriteStream>.

Se emite cuando se abre el archivo de <fs.WriteStream>.

Evento: 'ready'

Agregado en: v9.11.0

Se emite cuando <fs.WriteStream> está listo para usarse.

Se activa inmediatamente después de 'open'.

writeStream.bytesWritten

Agregado en: v0.4.7

El número de bytes escritos hasta ahora. No incluye los datos que todavía están en cola para ser escritos.

writeStream.close([callback])

Agregado en: v0.9.4

• callback <Function>
  • err <Error>

Cierra writeStream. Opcionalmente acepta una devolución de llamada que se ejecutará una vez que se cierre writeStream.

writeStream.path

Agregado en: v0.1.93

La ruta al archivo en el que el flujo está escribiendo, tal como se especifica en el primer argumento de fs.createWriteStream(). Si path se pasa como una cadena, entonces writeStream.path será una cadena. Si path se pasa como un <Buffer>, entonces writeStream.path será un <Buffer>.

writeStream.pending

Agregado en: v11.2.0

• <boolean>

Esta propiedad es true si el archivo subyacente aún no se ha abierto, es decir, antes de que se emita el evento 'ready'.

fs.constants

• <Objeto>

Devuelve un objeto que contiene constantes de uso común para las operaciones del sistema de archivos.

Constantes de FS

Las siguientes constantes se exportan mediante fs.constants y fsPromises.constants.

No todas las constantes estarán disponibles en todos los sistemas operativos; esto es especialmente importante para Windows, donde muchas de las definiciones específicas de POSIX no están disponibles. Para aplicaciones portátiles, se recomienda verificar su presencia antes de usarlas.

Para utilizar más de una constante, use el operador OR bit a bit |.

Ejemplo:

import { open, constants } from 'node:fs'

const { O_RDWR, O_CREAT, O_EXCL } = constants

open('/path/to/my/file', O_RDWR | O_CREAT | O_EXCL, (err, fd) => {
  // ...
})

Constantes de acceso a archivos

Las siguientes constantes están destinadas a usarse como parámetro mode pasado a fsPromises.access(), fs.access() y fs.accessSync().

Constante	Descripción
F_OK	Marca que indica que el archivo es visible para el proceso que llama. Esto es útil para determinar si existe un archivo, pero no dice nada sobre los permisos rwx. Valor predeterminado si no se especifica ningún modo.
R_OK	Marca que indica que el proceso que llama puede leer el archivo.
W_OK	Marca que indica que el proceso que llama puede escribir en el archivo.
X_OK	Marca que indica que el proceso que llama puede ejecutar el archivo. Esto no tiene efecto en Windows (se comportará como fs.constants.F_OK).

Las definiciones también están disponibles en Windows.

Constantes de copia de archivos

Las siguientes constantes están destinadas a usarse con fs.copyFile().

Constante	Descripción
COPYFILE_EXCL	Si está presente, la operación de copia fallará con un error si la ruta de destino ya existe.
COPYFILE_FICLONE	Si está presente, la operación de copia intentará crear un reflink de copia en escritura. Si la plataforma subyacente no admite la copia en escritura, se utiliza un mecanismo de copia de respaldo.
COPYFILE_FICLONE_FORCE	Si está presente, la operación de copia intentará crear un reflink de copia en escritura. Si la plataforma subyacente no admite la copia en escritura, la operación fallará con un error.

Las definiciones también están disponibles en Windows.

Constantes de apertura de archivos

Las siguientes constantes están destinadas a usarse con fs.open().

Constante	Descripción
O_RDONLY	Marca que indica que se abrirá un archivo para acceso de solo lectura.
O_WRONLY	Marca que indica que se abrirá un archivo para acceso de solo escritura.
O_RDWR	Marca que indica que se abrirá un archivo para acceso de lectura y escritura.
O_CREAT	Marca que indica que se creará el archivo si aún no existe.
O_EXCL	Marca que indica que la apertura de un archivo debería fallar si la marca O_CREAT está establecida y el archivo ya existe.
O_NOCTTY	Marca que indica que si la ruta identifica un dispositivo terminal, la apertura de la ruta no hará que ese terminal se convierta en el terminal de control para el proceso (si el proceso aún no tiene uno).
O_TRUNC	Marca que indica que si el archivo existe y es un archivo regular, y el archivo se abre correctamente para acceso de escritura, su longitud se truncará a cero.
O_APPEND	Marca que indica que los datos se agregarán al final del archivo.
O_DIRECTORY	Marca que indica que la apertura debería fallar si la ruta no es un directorio.
O_NOATIME	Marca que indica que los accesos de lectura al sistema de archivos ya no darán como resultado una actualización de la información atime asociada con el archivo. Esta marca solo está disponible en sistemas operativos Linux.
O_NOFOLLOW	Marca que indica que la apertura debería fallar si la ruta es un enlace simbólico.
O_SYNC	Marca que indica que el archivo se abre para E/S sincronizada con operaciones de escritura que esperan la integridad del archivo.
O_DSYNC	Marca que indica que el archivo se abre para E/S sincronizada con operaciones de escritura que esperan la integridad de los datos.
O_SYMLINK	Marca que indica que se abra el propio enlace simbólico en lugar del recurso al que apunta.
O_DIRECT	Cuando se establece, se intentará minimizar los efectos de almacenamiento en caché de la E/S de archivos.
O_NONBLOCK	Marca que indica que se abrirá el archivo en modo sin bloqueo cuando sea posible.
UV_FS_O_FILEMAP	Cuando se establece, se utiliza una asignación de archivos en memoria para acceder al archivo. Esta marca solo está disponible en sistemas operativos Windows. En otros sistemas operativos, esta marca se ignora.

En Windows, solo están disponibles O_APPEND, O_CREAT, O_EXCL, O_RDONLY, O_RDWR, O_TRUNC, O_WRONLY y UV_FS_O_FILEMAP.

Constantes de tipo de archivo

Las siguientes constantes están destinadas a usarse con la propiedad mode del objeto <fs.Stats> para determinar el tipo de un archivo.

Constante	Descripción
S_IFMT	Máscara de bits utilizada para extraer el código de tipo de archivo.
S_IFREG	Constante de tipo de archivo para un archivo regular.
S_IFDIR	Constante de tipo de archivo para un directorio.
S_IFCHR	Constante de tipo de archivo para un archivo de dispositivo orientado a caracteres.
S_IFBLK	Constante de tipo de archivo para un archivo de dispositivo orientado a bloques.
S_IFIFO	Constante de tipo de archivo para una FIFO/tubería.
S_IFLNK	Constante de tipo de archivo para un enlace simbólico.
S_IFSOCK	Constante de tipo de archivo para un socket.

En Windows, solo están disponibles S_IFCHR, S_IFDIR, S_IFLNK, S_IFMT y S_IFREG.

Constantes de modo de archivo

Las siguientes constantes están destinadas a usarse con la propiedad mode del objeto <fs.Stats> para determinar los permisos de acceso para un archivo.

Constante	Descripción
S_IRWXU	Modo de archivo que indica que el propietario puede leer, escribir y ejecutar.
S_IRUSR	Modo de archivo que indica que el propietario puede leer.
S_IWUSR	Modo de archivo que indica que el propietario puede escribir.
S_IXUSR	Modo de archivo que indica que el propietario puede ejecutar.
S_IRWXG	Modo de archivo que indica que el grupo puede leer, escribir y ejecutar.
S_IRGRP	Modo de archivo que indica que el grupo puede leer.
S_IWGRP	Modo de archivo que indica que el grupo puede escribir.
S_IXGRP	Modo de archivo que indica que el grupo puede ejecutar.
S_IRWXO	Modo de archivo que indica que otros pueden leer, escribir y ejecutar.
S_IROTH	Modo de archivo que indica que otros pueden leer.
S_IWOTH	Modo de archivo que indica que otros pueden escribir.
S_IXOTH	Modo de archivo que indica que otros pueden ejecutar.

En Windows, solo están disponibles S_IRUSR y S_IWUSR.

Notas

Orden de las operaciones basadas en callback y promesas

Debido a que se ejecutan de forma asíncrona mediante el grupo de subprocesos subyacente, no se garantiza ningún orden al usar los métodos basados en callback o en promesas.

Por ejemplo, lo siguiente es propenso a errores porque la operación fs.stat() podría completarse antes que la operación fs.rename():

const fs = require('node:fs')

fs.rename('/tmp/hello', '/tmp/world', err => {
  if (err) throw err
  console.log('renamed complete')
})
fs.stat('/tmp/world', (err, stats) => {
  if (err) throw err
  console.log(`stats: ${JSON.stringify(stats)}`)
})

Es importante ordenar correctamente las operaciones esperando los resultados de una antes de invocar la otra:

ESM

import { rename, stat } from 'node:fs/promises'

const oldPath = '/tmp/hello'
const newPath = '/tmp/world'

try {
  await rename(oldPath, newPath)
  const stats = await stat(newPath)
  console.log(`stats: ${JSON.stringify(stats)}`)
} catch (error) {
  console.error('there was an error:', error.message)
}

CJS

const { rename, stat } = require('node:fs/promises')

;(async function (oldPath, newPath) {
  try {
    await rename(oldPath, newPath)
    const stats = await stat(newPath)
    console.log(`stats: ${JSON.stringify(stats)}`)
  } catch (error) {
    console.error('there was an error:', error.message)
  }
})('/tmp/hello', '/tmp/world')

O, cuando use las API de callback, mueva la llamada fs.stat() al callback de la operación fs.rename():

ESM

import { rename, stat } from 'node:fs'

rename('/tmp/hello', '/tmp/world', err => {
  if (err) throw err
  stat('/tmp/world', (err, stats) => {
    if (err) throw err
    console.log(`stats: ${JSON.stringify(stats)}`)
  })
})

CJS

const { rename, stat } = require('node:fs/promises')

rename('/tmp/hello', '/tmp/world', err => {
  if (err) throw err
  stat('/tmp/world', (err, stats) => {
    if (err) throw err
    console.log(`stats: ${JSON.stringify(stats)}`)
  })
})

Rutas de archivos

La mayoría de las operaciones fs aceptan rutas de archivo que pueden especificarse en forma de una cadena, un objeto <Buffer> o un objeto <URL> utilizando el protocolo file:.

Rutas de cadena

Las rutas de cadena se interpretan como secuencias de caracteres UTF-8 que identifican el nombre de archivo absoluto o relativo. Las rutas relativas se resolverán con respecto al directorio de trabajo actual según lo determinado llamando a process.cwd().

Ejemplo utilizando una ruta absoluta en POSIX:

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

let fd
try {
  fd = await open('/open/some/file.txt', 'r')
  // Hacer algo con el archivo
} finally {
  await fd?.close()
}

Ejemplo utilizando una ruta relativa en POSIX (relativa a process.cwd()):

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

let fd
try {
  fd = await open('file.txt', 'r')
  // Hacer algo con el archivo
} finally {
  await fd?.close()
}

Rutas de URL de archivo

Agregado en: v7.6.0

Para la mayoría de las funciones del módulo node:fs, el argumento path o filename se puede pasar como un objeto <URL> utilizando el protocolo file:.

import { readFileSync } from 'node:fs'

readFileSync(new URL('file:///tmp/hello'))

Las URL file: son siempre rutas absolutas.

Consideraciones específicas de la plataforma

En Windows, las <URL> file: con un nombre de host se convierten a rutas UNC, mientras que las <URL> file: con letras de unidad se convierten a rutas absolutas locales. Las <URL> file: sin nombre de host y sin letra de unidad darán como resultado un error:

import { readFileSync } from 'node:fs'
// En Windows:

// - Las URL de archivo WHATWG con nombre de host se convierten a ruta UNC
// file://hostname/p/a/t/h/file => \\hostname\p\a\t\h\file
readFileSync(new URL('file://hostname/p/a/t/h/file'))

// - Las URL de archivo WHATWG con letras de unidad se convierten a ruta absoluta
// file:///C:/tmp/hello => C:\tmp\hello
readFileSync(new URL('file:///C:/tmp/hello'))

// - Las URL de archivo WHATWG sin nombre de host deben tener una letra de unidad
readFileSync(new URL('file:///notdriveletter/p/a/t/h/file'))
readFileSync(new URL('file:///c/p/a/t/h/file'))
// TypeError [ERR_INVALID_FILE_URL_PATH]: La ruta de URL de archivo debe ser absoluta

Las <URL> file: con letras de unidad deben usar : como separador justo después de la letra de unidad. El uso de otro separador dará como resultado un error.

En todas las demás plataformas, las <URL> file: con un nombre de host no son compatibles y darán como resultado un error:

import { readFileSync } from 'node:fs'
// En otras plataformas:

// - Las URL de archivo WHATWG con nombre de host no son compatibles
// file://hostname/p/a/t/h/file => ¡arroja error!
readFileSync(new URL('file://hostname/p/a/t/h/file'))
// TypeError [ERR_INVALID_FILE_URL_PATH]: debe ser absoluta

// - Las URL de archivo WHATWG se convierten a ruta absoluta
// file:///tmp/hello => /tmp/hello
readFileSync(new URL('file:///tmp/hello'))

Una <URL> file: que tenga caracteres de barra codificados dará como resultado un error en todas las plataformas:

import { readFileSync } from 'node:fs'

// En Windows
readFileSync(new URL('file:///C:/p/a/t/h/%2F'))
readFileSync(new URL('file:///C:/p/a/t/h/%2f'))
/* TypeError [ERR_INVALID_FILE_URL_PATH]: La ruta de URL de archivo no debe incluir caracteres
\ o / codificados */

// En POSIX
readFileSync(new URL('file:///p/a/t/h/%2F'))
readFileSync(new URL('file:///p/a/t/h/%2f'))
/* TypeError [ERR_INVALID_FILE_URL_PATH]: La ruta de URL de archivo no debe incluir caracteres
/ codificados */

En Windows, las <URL> file: que tengan una barra invertida codificada darán como resultado un error:

import { readFileSync } from 'node:fs'

// En Windows
readFileSync(new URL('file:///C:/path/%5C'))
readFileSync(new URL('file:///C:/path/%5c'))
/* TypeError [ERR_INVALID_FILE_URL_PATH]: La ruta de URL de archivo no debe incluir caracteres
\ o / codificados */

Rutas de búfer

Las rutas especificadas utilizando un <Buffer> son útiles principalmente en ciertos sistemas operativos POSIX que tratan las rutas de archivos como secuencias de bytes opacas. En tales sistemas, es posible que una única ruta de archivo contenga sub-secuencias que utilicen múltiples codificaciones de caracteres. Al igual que con las rutas de cadenas, las rutas <Buffer> pueden ser relativas o absolutas:

Ejemplo utilizando una ruta absoluta en POSIX:

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

let fd
try {
  fd = await open(Buffer.from('/open/some/file.txt'), 'r')
  // Hacer algo con el archivo
} finally {
  await fd?.close()
}

Directorios de trabajo por unidad en Windows

En Windows, Node.js sigue el concepto de directorio de trabajo por unidad. Este comportamiento se puede observar cuando se utiliza una ruta de unidad sin una barra invertida. Por ejemplo, fs.readdirSync('C:\\') podría potencialmente devolver un resultado diferente que fs.readdirSync('C:'). Para obtener más información, consulta esta página de MSDN.

Descriptores de archivo

En los sistemas POSIX, para cada proceso, el kernel mantiene una tabla de archivos y recursos actualmente abiertos. A cada archivo abierto se le asigna un identificador numérico simple llamado descriptor de archivo. A nivel de sistema, todas las operaciones del sistema de archivos utilizan estos descriptores de archivo para identificar y rastrear cada archivo específico. Los sistemas Windows utilizan un mecanismo diferente, pero conceptualmente similar, para el seguimiento de los recursos. Para simplificar las cosas a los usuarios, Node.js abstrae las diferencias entre los sistemas operativos y asigna a todos los archivos abiertos un descriptor de archivo numérico.

Los métodos basados en devoluciones de llamada fs.open() y sincrónicos fs.openSync() abren un archivo y asignan un nuevo descriptor de archivo. Una vez asignado, el descriptor de archivo puede utilizarse para leer datos, escribir datos o solicitar información sobre el archivo.

Los sistemas operativos limitan el número de descriptores de archivo que pueden estar abiertos en un momento dado, por lo que es fundamental cerrar el descriptor cuando se completan las operaciones. Si no se hace así, se producirá una fuga de memoria que acabará provocando un fallo en la aplicación.

import { open, close, fstat } from 'node:fs'

function closeFd(fd) {
  close(fd, err => {
    if (err) throw err
  })
}

open('/open/some/file.txt', 'r', (err, fd) => {
  if (err) throw err
  try {
    fstat(fd, (err, stat) => {
      if (err) {
        closeFd(fd)
        throw err
      }

      // use stat

      closeFd(fd)
    })
  } catch (err) {
    closeFd(fd)
    throw err
  }
})

Las API basadas en promesas utilizan un objeto <FileHandle> en lugar del descriptor de archivo numérico. Estos objetos están mejor gestionados por el sistema para garantizar que no se produzcan fugas de recursos. Sin embargo, sigue siendo necesario cerrarlos cuando se completan las operaciones:

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

let file
try {
  file = await open('/open/some/file.txt', 'r')
  const stat = await file.stat()
  // use stat
} finally {
  await file.close()
}

Uso del pool de hilos

Todas las APIs del sistema de archivos basadas en callbacks y promesas (con la excepción de fs.FSWatcher()) utilizan el pool de hilos de libuv. Esto puede tener implicaciones de rendimiento sorprendentes y negativas para algunas aplicaciones. Consulta la documentación de UV_THREADPOOL_SIZE para obtener más información.

Banderas del sistema de archivos

Las siguientes banderas están disponibles donde la opción flag toma una cadena.

• 'a': Abre el archivo para agregar. El archivo se crea si no existe.
• 'ax': Similar a 'a', pero falla si la ruta existe.
• 'a+': Abre el archivo para lectura y escritura, agregando al final. El archivo se crea si no existe.
• 'ax+': Similar a 'a+', pero falla si la ruta existe.
• 'as': Abre el archivo para agregar en modo síncrono. El archivo se crea si no existe.
• 'as+': Abre el archivo para lectura y escritura, agregando al final en modo síncrono. El archivo se crea si no existe.
• 'r': Abre el archivo para lectura. Ocurre una excepción si el archivo no existe.
• 'rs': Abre el archivo para lectura en modo síncrono. Ocurre una excepción si el archivo no existe.
• 'r+': Abre el archivo para lectura y escritura. Ocurre una excepción si el archivo no existe.
• 'rs+': Abre el archivo para lectura y escritura en modo síncrono. Indica al sistema operativo que omita la caché local del sistema de archivos. Esto es principalmente útil para abrir archivos en montajes NFS, ya que permite omitir la caché local potencialmente obsoleta. Tiene un impacto real en el rendimiento de E/S, por lo que no se recomienda usar esta bandera a menos que sea necesario. Esto no convierte fs.open() o fsPromises.open() en una llamada de bloqueo síncrona. Si se desea una operación síncrona, se debe usar algo como fs.openSync().
• 'w': Abre el archivo para escritura. El archivo se crea (si no existe) o se trunca (si existe).
• 'wx': Similar a 'w', pero falla si la ruta existe.
• 'w+': Abre el archivo para lectura y escritura. El archivo se crea (si no existe) o se trunca (si existe).
• 'wx+': Similar a 'w+', pero falla si la ruta existe.

flag también puede ser un número como se documenta en open(2); las constantes de uso común están disponibles en fs.constants. En Windows, las banderas se traducen a sus equivalentes donde sea aplicable, por ejemplo, O_WRONLY a FILE_GENERIC_WRITE, u O_EXCL|O_CREAT a CREATE_NEW, como es aceptado por CreateFileW.

La bandera exclusiva 'x' (bandera O_EXCL en open(2)) hace que la operación devuelva un error si la ruta ya existe. En POSIX, si la ruta es un enlace simbólico, usar O_EXCL devuelve un error incluso si el enlace es a una ruta que no existe. Es posible que la bandera exclusiva no funcione con sistemas de archivos de red.

En Linux, las escrituras posicionales no funcionan cuando el archivo se abre en modo de anexión. El kernel ignora el argumento de posición y siempre agrega los datos al final del archivo.

Modificar un archivo en lugar de reemplazarlo puede requerir que la opción flag se establezca en 'r+' en lugar del valor predeterminado 'w'.

El comportamiento de algunas banderas es específico de la plataforma. Como tal, abrir un directorio en macOS y Linux con la bandera 'a+', como en el ejemplo a continuación, devolverá un error. En contraste, en Windows y FreeBSD, se devolverá un descriptor de archivo o un FileHandle.

// macOS y Linux
fs.open('<directorio>', 'a+', (err, fd) => {
  // => [Error: EISDIR: operación ilegal en un directorio, open <directorio>]
})

// Windows y FreeBSD
fs.open('<directorio>', 'a+', (err, fd) => {
  // => null, <fd>
})

En Windows, abrir un archivo oculto existente usando la bandera 'w' (ya sea a través de fs.open(), fs.writeFile() o fsPromises.open()) fallará con EPERM. Los archivos ocultos existentes se pueden abrir para escritura con la bandera 'r+'.

Se puede utilizar una llamada a fs.ftruncate() o filehandle.truncate() para restablecer el contenido del archivo.