Sistema de arquivos

[Estável: 2 - Estável]

Estável: 2 Estabilidade: 2 - Estável

Código-fonte: lib/fs.js

O módulo node:fs permite interagir com o sistema de arquivos de uma maneira modelada nas funções POSIX padrão.

Para usar as APIs baseadas em promessas:

ESM

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

CJS

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

Para usar as APIs de callback e síncronas:

ESM

import * as fs from 'node:fs'

CJS

const fs = require('node:fs')

Todas as operações do sistema de arquivos têm formas síncronas, de callback e baseadas em promessas, e são acessíveis usando tanto a sintaxe CommonJS quanto os Módulos ES6 (ESM).

Exemplo de Promessa

As operações baseadas em promessas retornam uma promessa que é cumprida quando a operação assíncrona é concluída.

ESM

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

try {
  await unlink('/tmp/hello')
  console.log('excluído com sucesso /tmp/hello')
} catch (error) {
  console.error('ocorreu um erro:', error.message)
}

CJS

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

;(async function (path) {
  try {
    await unlink(path)
    console.log(`excluído com sucesso ${path}`)
  } catch (error) {
    console.error('ocorreu um erro:', error.message)
  }
})('/tmp/hello')

Exemplo de Callback

A forma de callback recebe uma função de callback de conclusão como seu último argumento e invoca a operação de forma assíncrona. Os argumentos passados para o callback de conclusão dependem do método, mas o primeiro argumento é sempre reservado para uma exceção. Se a operação for concluída com sucesso, o primeiro argumento é null ou undefined.

ESM

import { unlink } from 'node:fs'

unlink('/tmp/hello', err => {
  if (err) throw err
  console.log('excluído com sucesso /tmp/hello')
})

CJS

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

unlink('/tmp/hello', err => {
  if (err) throw err
  console.log('excluído com sucesso /tmp/hello')
})

As versões baseadas em callback das APIs do módulo node:fs são preferíveis ao uso das APIs de promessa quando o desempenho máximo (tanto em termos de tempo de execução quanto de alocação de memória) é necessário.

Exemplo Síncrono

As APIs síncronas bloqueiam o loop de eventos do Node.js e a execução adicional de JavaScript até que a operação seja concluída. Exceções são lançadas imediatamente e podem ser tratadas usando try…catch, ou podem ser permitidas a propagar.

ESM

import { unlinkSync } from 'node:fs'

try {
  unlinkSync('/tmp/hello')
  console.log('apagado com sucesso /tmp/hello')
} catch (err) {
  // tratar o erro
}

CJS

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

try {
  unlinkSync('/tmp/hello')
  console.log('apagado com sucesso /tmp/hello')
} catch (err) {
  // tratar o erro
}

API de Promises

[Histórico]

Versão	Mudanças
v14.0.0	Exposto como require('fs/promises').
v11.14.0, v10.17.0	Esta API não é mais experimental.
v10.1.0	A API está acessível via require('fs').promises apenas.
v10.0.0	Adicionado em: v10.0.0

A API fs/promises fornece métodos assíncronos de sistema de arquivos que retornam promises.

As APIs de promise usam o threadpool subjacente do Node.js para executar operações de sistema de arquivos fora da thread do loop de eventos. Essas operações não são sincronizadas ou thread-safe. É preciso ter cuidado ao realizar várias modificações simultâneas no mesmo arquivo, pois pode ocorrer corrupção de dados.

Classe: FileHandle

Adicionado em: v10.0.0

Um objeto <FileHandle> é um wrapper de objeto para um descritor de arquivo numérico.

Instâncias do objeto <FileHandle> são criadas pelo método fsPromises.open().

Todos os objetos <FileHandle> são <EventEmitter>s.

Se um <FileHandle> não for fechado usando o método filehandle.close(), ele tentará fechar automaticamente o descritor de arquivo e emitir um aviso de processo, ajudando a prevenir vazamentos de memória. Por favor, não confie neste comportamento, pois pode ser não confiável e o arquivo pode não ser fechado. Em vez disso, sempre feche explicitamente os <FileHandle>s. O Node.js pode alterar este comportamento no futuro.

Evento: 'close'

Adicionado em: v15.4.0

O evento 'close' é emitido quando o <FileHandle> foi fechado e não pode mais ser usado.

filehandle.appendFile(data[, options])

[Histórico]

Versão	Mudanças
v21.1.0, v20.10.0	A opção flush agora é suportada.
v15.14.0, v14.18.0	O argumento data suporta AsyncIterable, Iterable e Stream.
v14.0.0	O parâmetro data não forçará mais a conversão de entradas não suportadas em strings.
v10.0.0	Adicionado em: v10.0.0

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

• options <Object> | <string>

  • encoding <string> | <null> Padrão: 'utf8'
  • flush <boolean> Se true, o descritor de arquivo subjacente é liberado antes de ser fechado. Padrão: false.

• Retorna: <Promise> Cumpre com undefined após o sucesso.

Alias de filehandle.writeFile().

Ao operar em manipuladores de arquivos, o modo não pode ser alterado em relação ao que foi definido com fsPromises.open(). Portanto, isso é equivalente a filehandle.writeFile().

filehandle.chmod(mode)

Adicionado em: v10.0.0

• mode <integer> a máscara de bits do modo de arquivo.
• Retorna: <Promise> Cumpre com undefined em caso de sucesso.

Modifica as permissões no arquivo. Consulte chmod(2).

filehandle.chown(uid, gid)

Adicionado em: v10.0.0

• uid <integer> O novo ID de usuário do proprietário do arquivo.
• gid <integer> O novo ID de grupo do grupo do arquivo.
• Retorna: <Promise> Cumpre com undefined em caso de sucesso.

Altera a propriedade do arquivo. Um invólucro para chown(2).

filehandle.close()

Adicionado em: v10.0.0

• Retorna: <Promise> Cumpre com undefined em caso de sucesso.

Fecha o manipulador de arquivo após aguardar a conclusão de qualquer operação pendente no manipulador.

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

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

filehandle.createReadStream([options])

Adicionado em: v16.11.0

• options <Object>

  • encoding <string> Padrão: null
  • autoClose <boolean> Padrão: true
  • emitClose <boolean> Padrão: true
  • start <integer>
  • end <integer> Padrão: Infinity
  • highWaterMark <integer> Padrão: 64 * 1024
  • signal <AbortSignal> | <undefined> Padrão: undefined

• Retorna: <fs.ReadStream>

options pode incluir valores start e end para ler um intervalo de bytes do arquivo em vez do arquivo inteiro. Tanto start quanto end são inclusivos e começam a contar a partir de 0, os valores permitidos estão no intervalo [0, Number.MAX_SAFE_INTEGER]. Se start for omitido ou undefined, filehandle.createReadStream() lê sequencialmente a partir da posição atual do arquivo. O encoding pode ser qualquer um dos aceitos por <Buffer>.

Se o FileHandle apontar para um dispositivo de caractere que suporte apenas leituras de bloqueio (como teclado ou placa de som), as operações de leitura não terminarão até que os dados estejam disponíveis. Isso pode impedir que o processo saia e que o fluxo feche naturalmente.

Por padrão, o fluxo emitirá um evento 'close' após ser destruído. Defina a opção emitClose como false para alterar esse comportamento.

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

const fd = await open('/dev/input/event0')
// Crie um fluxo a partir de algum dispositivo de caractere.
const stream = fd.createReadStream()
setTimeout(() => {
  stream.close() // Isso pode não fechar o fluxo.
  // Marcar artificialmente o final do fluxo, como se o recurso subjacente tivesse
  // indicado o final do arquivo por si só, permite que o fluxo feche.
  // Isso não cancela as operações de leitura pendentes e, se houver tal
  // operação, o processo ainda pode não conseguir sair com sucesso
  // até que termine.
  stream.push(null)
  stream.read(0)
}, 100)

Se autoClose for false, o descritor de arquivo não será fechado, mesmo se houver um erro. É responsabilidade do aplicativo fechá-lo e garantir que não haja vazamento de descritor de arquivo. Se autoClose estiver definido como true (comportamento padrão), em 'error' ou 'end', o descritor de arquivo será fechado automaticamente.

Um exemplo para ler os últimos 10 bytes de um arquivo com 100 bytes de comprimento:

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

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

filehandle.createWriteStream([options])

[Histórico]

Versão	Mudanças
v21.0.0, v20.10.0	A opção flush agora é suportada.
v16.11.0	Adicionado em: v16.11.0

• options <Objeto>

  • encoding <string> Padrão: 'utf8'
  • autoClose <boolean> Padrão: true
  • emitClose <boolean> Padrão: true
  • start <integer>
  • highWaterMark <number> Padrão: 16384
  • flush <boolean> Se true, o descritor de arquivo subjacente é liberado antes de ser fechado. Padrão: false.

• Retorna: <fs.WriteStream>

options também pode incluir uma opção start para permitir a gravação de dados em alguma posição após o início do arquivo, os valores permitidos estão no intervalo [0, Number.MAX_SAFE_INTEGER]. Modificar um arquivo em vez de substituí-lo pode exigir que a opção flags open seja definida como r+ em vez do padrão r. O encoding pode ser qualquer um daqueles aceitos por <Buffer>.

Se autoClose estiver definido como true (comportamento padrão) em 'error' ou 'finish', o descritor de arquivo será fechado automaticamente. Se autoClose for false, o descritor de arquivo não será fechado, mesmo que haja um erro. É responsabilidade do aplicativo fechá-lo e garantir que não haja vazamento do descritor de arquivo.

Por padrão, o fluxo emitirá um evento 'close' após ter sido destruído. Defina a opção emitClose como false para alterar esse comportamento.

filehandle.datasync()

Adicionado em: v10.0.0

• Retorna: <Promise> Cumpre com undefined em caso de sucesso.

Força todas as operações de E/S atualmente enfileiradas associadas ao arquivo para o estado de conclusão de E/S sincronizado do sistema operacional. Consulte a documentação POSIX fdatasync(2) para obter detalhes.

Ao contrário de filehandle.sync, este método não limpa metadados modificados.

filehandle.fd

Adicionado em: v10.0.0

• <number> O descritor de arquivo numérico gerenciado pelo objeto <FileHandle>.

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

[Histórico]

Versão	Mudanças
v21.0.0	Aceita valores bigint como position.
v10.0.0	Adicionado em: v10.0.0

• buffer <Buffer> | <TypedArray> | <DataView> Um buffer que será preenchido com os dados do arquivo lidos.
• offset <integer> A localização no buffer em que começar a preencher. Padrão: 0
• length <integer> O número de bytes a serem lidos. Padrão: buffer.byteLength - offset
• position <integer> | <bigint> | <null> A localização onde começar a ler dados do arquivo. Se null ou -1, os dados serão lidos da posição atual do arquivo e a posição será atualizada. Se position for um inteiro não negativo, a posição atual do arquivo permanecerá inalterada. Padrão: null
• Retorna: <Promise> Cumpre com sucesso um objeto com duas propriedades:
  • bytesRead <integer> O número de bytes lidos
  • buffer <Buffer> | <TypedArray> | <DataView> Uma referência ao argumento buffer passado.

Lê dados do arquivo e os armazena no buffer fornecido.

Se o arquivo não for modificado simultaneamente, o fim do arquivo é alcançado quando o número de bytes lidos é zero.

filehandle.read([options])

[Histórico]

Versão	Mudanças
v21.0.0	Aceita valores bigint como position.
v13.11.0, v12.17.0	Adicionado em: v13.11.0, v12.17.0

• options <Objeto>

  • buffer <Buffer> | <TypedArray> | <DataView> Um buffer que será preenchido com os dados do arquivo lido. Padrão: Buffer.alloc(16384)
  • offset <inteiro> A localização no buffer em que se deve começar a preencher. Padrão: 0
  • length <inteiro> O número de bytes a serem lidos. Padrão: buffer.byteLength - offset
  • position <inteiro> | <bigint> | <null> A localização de onde começar a ler os dados do arquivo. Se null ou -1, os dados serão lidos da posição atual do arquivo e a posição será atualizada. Se position for um inteiro não negativo, a posição atual do arquivo permanecerá inalterada. Padrão:: null

• Retorna: <Promise> Cumpre após o sucesso com um objeto com duas propriedades:

  • bytesRead <inteiro> O número de bytes lidos
  • buffer <Buffer> | <TypedArray> | <DataView> Uma referência ao argumento buffer passado.

Lê os dados do arquivo e os armazena no buffer fornecido.

Se o arquivo não for modificado concorrentemente, o fim do arquivo será alcançado quando o número de bytes lidos for zero.

filehandle.read(buffer[, options])

[Histórico]

Versão	Mudanças
v21.0.0	Aceita valores bigint como position.
v18.2.0, v16.17.0	Adicionado em: v18.2.0, v16.17.0

• buffer <Buffer> | <TypedArray> | <DataView> Um buffer que será preenchido com os dados do arquivo lidos.

• options <Object>

  • offset <integer> A localização no buffer onde começar a preencher. Padrão: 0
  • length <integer> O número de bytes a serem lidos. Padrão: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> A localização onde começar a ler os dados do arquivo. Se null ou -1, os dados serão lidos da posição atual do arquivo e a posição será atualizada. Se position for um número inteiro não negativo, a posição atual do arquivo permanecerá inalterada. Padrão:: null

• Retorna: <Promise> É cumprida com sucesso com um objeto com duas propriedades:

  • bytesRead <integer> O número de bytes lidos
  • buffer <Buffer> | <TypedArray> | <DataView> Uma referência ao argumento buffer passado.

Lê os dados do arquivo e os armazena no buffer fornecido.

Se o arquivo não for modificado simultaneamente, o fim-do-arquivo é atingido quando o número de bytes lidos for zero.

filehandle.readableWebStream([options])

[Histórico]

Versão	Mudanças
v20.0.0, v18.17.0	Adicionada opção para criar um fluxo 'bytes'.
v17.0.0	Adicionado em: v17.0.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• options <Objeto>

  • type <string> | <undefined> Se deve abrir um fluxo normal ou um fluxo 'bytes'. Padrão: undefined

• Retorna: <ReadableStream>

Retorna um ReadableStream que pode ser usado para ler os dados dos arquivos.

Um erro será lançado se este método for chamado mais de uma vez ou se for chamado após o FileHandle ser fechado ou estar fechando.

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()
})()

Enquanto o ReadableStream lê o arquivo até a conclusão, ele não fechará o FileHandle automaticamente. O código do usuário ainda deve chamar o método fileHandle.close().

filehandle.readFile(options)

Adicionado em: v10.0.0

• options <Objeto> | <string>

  • encoding <string> | <null> Padrão: null
  • signal <AbortSignal> permite abortar um readFile em andamento

• Retorna: <Promise> Cumpre com sucesso uma leitura com o conteúdo do arquivo. Se nenhuma codificação for especificada (usando options.encoding), os dados são retornados como um objeto <Buffer>. Caso contrário, os dados serão uma string.

Lê assincronamente todo o conteúdo de um arquivo.

Se options for uma string, ele especificará a encoding.

O <FileHandle> deve suportar a leitura.

Se uma ou mais chamadas filehandle.read() forem feitas em um manipulador de arquivo e, em seguida, uma chamada filehandle.readFile() for feita, os dados serão lidos da posição atual até o final do arquivo. Nem sempre ele lê desde o início do arquivo.

filehandle.readLines([options])

Adicionado em: v18.11.0

• options <Object>

  • encoding <string> Padrão: null
  • autoClose <boolean> Padrão: true
  • emitClose <boolean> Padrão: true
  • start <integer>
  • end <integer> Padrão: Infinity
  • highWaterMark <integer> Padrão: 64 * 1024

• Retorna: <readline.InterfaceConstructor>

Método de conveniência para criar uma interface readline e transmitir o arquivo. Veja filehandle.createReadStream() para as opções.

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])

Adicionado em: v13.13.0, v12.17.0

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <integer> | <null> O deslocamento a partir do início do arquivo de onde os dados devem ser lidos. Se position não for um number, os dados serão lidos a partir da posição atual. Padrão: null
• Retorna: <Promise> Cumpre com sucesso um objeto contendo duas propriedades:
  • bytesRead <integer> o número de bytes lidos
  • buffers <Buffer[]> | <TypedArray[]> | <DataView[]> propriedade contendo uma referência à entrada buffers.

Leia de um arquivo e escreva em um array de <ArrayBufferView>s

filehandle.stat([options])

[Histórico]

Versão	Mudanças
v10.5.0	Aceita um objeto options adicional para especificar se os valores numéricos retornados devem ser bigint.
v10.0.0	Adicionado em: v10.0.0

• options <Objeto>

  • bigint <boolean> Se os valores numéricos no objeto <fs.Stats> retornado devem ser bigint. Padrão: false.

• Retorna: <Promise> Cumpre com um <fs.Stats> para o arquivo.

filehandle.sync()

Adicionado em: v10.0.0

• Retorna: <Promise> Cumpre com undefined após o sucesso.

Solicita que todos os dados para o descritor de arquivo aberto sejam descarregados para o dispositivo de armazenamento. A implementação específica é específica do sistema operacional e do dispositivo. Consulte a documentação POSIX fsync(2) para obter mais detalhes.

filehandle.truncate(len)

Adicionado em: v10.0.0

• len <integer> Padrão: 0
• Retorna: <Promise> Cumpre com undefined após o sucesso.

Trunca o arquivo.

Se o arquivo for maior que len bytes, apenas os primeiros len bytes serão retidos no arquivo.

O exemplo a seguir retém apenas os primeiros quatro bytes do arquivo:

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

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

Se o arquivo anteriormente era menor que len bytes, ele é estendido e a parte estendida é preenchida com bytes nulos ('\0'):

Se len for negativo, então 0 será usado.

filehandle.utimes(atime, mtime)

Adicionado em: v10.0.0

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

Altera os timestamps do sistema de arquivos do objeto referenciado por <FileHandle> e, em seguida, cumpre a promessa sem argumentos em caso de sucesso.

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

[Histórico]

Versão	Mudanças
v14.0.0	O parâmetro buffer não forçará mais entradas não suportadas em buffers.
v10.0.0	Adicionado em: v10.0.0

• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer> A posição inicial dentro do buffer onde os dados a serem gravados começam.
• length <integer> O número de bytes de buffer a serem gravados. Padrão: buffer.byteLength - offset
• position <integer> | <null> O deslocamento do início do arquivo onde os dados de buffer devem ser gravados. Se position não for um number, os dados serão gravados na posição atual. Consulte a documentação POSIX pwrite(2) para obter mais detalhes. Padrão: null
• Retorna: <Promise>

Grava buffer no arquivo.

A promessa é cumprida com um objeto contendo duas propriedades:

• bytesWritten <integer> o número de bytes gravados
• buffer <Buffer> | <TypedArray> | <DataView> uma referência ao buffer gravado.

Não é seguro usar filehandle.write() várias vezes no mesmo arquivo sem esperar que a promessa seja cumprida (ou rejeitada). Para este cenário, use filehandle.createWriteStream().

No Linux, gravações posicionais não funcionam quando o arquivo é aberto em modo de anexação. O kernel ignora o argumento de posição e sempre anexa os dados ao final do arquivo.

filehandle.write(buffer[, options])

Adicionado em: v18.3.0, v16.17.0

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

• options <Object>

  • offset <integer> Padrão: 0
  • length <integer> Padrão: buffer.byteLength - offset
  • position <integer> Padrão: null

• Retorna: <Promise>

Escreve buffer no arquivo.

Semelhante à função filehandle.write acima, esta versão aceita um objeto options opcional. Se nenhum objeto options for especificado, ele usará os valores padrão acima.

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

[Histórico]

Versão	Mudanças
v14.0.0	O parâmetro string não forçará mais entradas não suportadas para strings.
v10.0.0	Adicionado em: v10.0.0

• string <string>
• position <integer> | <null> O deslocamento a partir do início do arquivo onde os dados de string devem ser escritos. Se position não for um number, os dados serão gravados na posição atual. Consulte a documentação POSIX pwrite(2) para obter mais detalhes. Padrão: null
• encoding <string> A codificação de string esperada. Padrão: 'utf8'
• Retorna: <Promise>

Escreve string no arquivo. Se string não for uma string, a promessa é rejeitada com um erro.

A promessa é cumprida com um objeto contendo duas propriedades:

• bytesWritten <integer> o número de bytes gravados
• buffer <string> uma referência à string escrita.

Não é seguro usar filehandle.write() várias vezes no mesmo arquivo sem esperar que a promessa seja cumprida (ou rejeitada). Para este cenário, use filehandle.createWriteStream().

No Linux, gravações posicionais não funcionam quando o arquivo é aberto no modo de anexação. O kernel ignora o argumento de posição e sempre anexa os dados ao final do arquivo.

filehandle.writeFile(data, options)

[Histórico]

Versão	Mudanças
v15.14.0, v14.18.0	O argumento data suporta AsyncIterable, Iterable e Stream.
v14.0.0	O parâmetro data não forçará mais a entrada não suportada para strings.
v10.0.0	Adicionado em: v10.0.0

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

• options <Object> | <string>

  • encoding <string> | <null> A codificação de caracteres esperada quando data é uma string. Padrão: 'utf8'

• Retorna: <Promise>

Escreve dados de forma assíncrona em um arquivo, substituindo o arquivo se ele já existir. data pode ser uma string, um buffer, um objeto <AsyncIterable> ou um objeto <Iterable>. A promessa é cumprida sem argumentos após o sucesso.

Se options for uma string, ela especifica a encoding.

O <FileHandle> deve suportar a escrita.

Não é seguro usar filehandle.writeFile() várias vezes no mesmo arquivo sem esperar que a promessa seja cumprida (ou rejeitada).

Se uma ou mais chamadas filehandle.write() forem feitas em um manipulador de arquivo e, em seguida, uma chamada filehandle.writeFile() for feita, os dados serão gravados da posição atual até o final do arquivo. Nem sempre ele escreve a partir do início do arquivo.

filehandle.writev(buffers[, position])

Adicionado em: v12.9.0

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <integer> | <null> O deslocamento a partir do início do arquivo onde os dados de buffers devem ser escritos. Se position não for um number, os dados serão escritos na posição atual. Padrão: null
• Retorna: <Promise>

Escreve um array de <ArrayBufferView>s no arquivo.

A promise é cumprida com um objeto contendo duas propriedades:

• bytesWritten <integer> o número de bytes escritos
• buffers <Buffer[]> | <TypedArray[]> | <DataView[]> uma referência à entrada buffers.

É inseguro chamar writev() várias vezes no mesmo arquivo sem esperar que a promise seja cumprida (ou rejeitada).

No Linux, as escritas posicionais não funcionam quando o arquivo é aberto no modo de anexação. O kernel ignora o argumento de posição e sempre anexa os dados ao final do arquivo.

filehandle[Symbol.asyncDispose]()

Adicionado em: v20.4.0, v18.18.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

Um alias para filehandle.close().

fsPromises.access(path[, mode])

Adicionado em: v10.0.0

• path <string> | <Buffer> | <URL>
• mode <integer> Padrão: fs.constants.F_OK
• Retorna: <Promise> Cumpre com undefined em caso de sucesso.

Testa as permissões de um usuário para o arquivo ou diretório especificado por path. O argumento mode é um inteiro opcional que especifica as verificações de acessibilidade a serem realizadas. mode deve ser o valor fs.constants.F_OK ou uma máscara que consiste no OR bit a bit de qualquer um de fs.constants.R_OK, fs.constants.W_OK e fs.constants.X_OK (por exemplo, fs.constants.W_OK | fs.constants.R_OK). Verifique Constantes de acesso a arquivos para os valores possíveis de mode.

Se a verificação de acessibilidade for bem-sucedida, a promessa é cumprida sem valor. Se alguma das verificações de acessibilidade falhar, a promessa é rejeitada com um objeto <Error>. O exemplo a seguir verifica se o arquivo /etc/passwd pode ser lido e gravado pelo processo atual.

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

try {
  await access('/etc/passwd', constants.R_OK | constants.W_OK)
  console.log('pode acessar')
} catch {
  console.error('não pode acessar')
}

Não é recomendado usar fsPromises.access() para verificar a acessibilidade de um arquivo antes de chamar fsPromises.open(). Isso introduz uma condição de corrida, já que outros processos podem alterar o estado do arquivo entre as duas chamadas. Em vez disso, o código do usuário deve abrir/ler/gravar o arquivo diretamente e tratar o erro gerado se o arquivo não for acessível.

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

[Histórico]

Versão	Alterações
v21.1.0, v20.10.0	A opção flush agora é suportada.
v10.0.0	Adicionado em: v10.0.0

• path <string> | <Buffer> | <URL> | <FileHandle> nome do arquivo ou <FileHandle>

• data <string> | <Buffer>

• options <Object> | <string>

  • encoding <string> | <null> Padrão: 'utf8'
  • mode <integer> Padrão: 0o666
  • flag <string> Consulte suporte de flags do sistema de arquivos. Padrão: 'a'.
  • flush <boolean> Se true, o descritor de arquivo subjacente é esvaziado antes de ser fechado. Padrão: false.

• Retorna: <Promise> Cumpre com undefined em caso de sucesso.

Acrescenta dados de forma assíncrona a um arquivo, criando o arquivo se ele ainda não existir. data pode ser uma string ou um <Buffer>.

Se options for uma string, ela especifica a encoding.

A opção mode afeta apenas o arquivo recém-criado. Consulte fs.open() para obter mais detalhes.

O path pode ser especificado como um <FileHandle> que foi aberto para anexar (usando fsPromises.open()).

fsPromises.chmod(path, mode)

Adicionado em: v10.0.0

• path <string> | <Buffer> | <URL>
• mode <string> | <integer>
• Retorna: <Promise> Cumpre com undefined após o sucesso.

Altera as permissões de um arquivo.

fsPromises.chown(path, uid, gid)

Adicionado em: v10.0.0

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• Retorna: <Promise> Cumpre com undefined após o sucesso.

Altera a propriedade de um arquivo.

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

[Histórico]

Versão	Alterações
v14.0.0	Alterado o argumento flags para mode e imposta validação de tipo mais estrita.
v10.0.0	Adicionado em: v10.0.0

• src <string> | <Buffer> | <URL> nome do arquivo de origem para copiar

• dest <string> | <Buffer> | <URL> nome do arquivo de destino da operação de cópia

• mode <integer> Modificadores opcionais que especificam o comportamento da operação de cópia. É possível criar uma máscara consistindo no OR bit a bit de dois ou mais valores (por exemplo, fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE) Padrão: 0.

  • fs.constants.COPYFILE_EXCL: A operação de cópia falhará se dest já existir.
  • fs.constants.COPYFILE_FICLONE: A operação de cópia tentará criar um reflink de cópia sob demanda. Se a plataforma não oferecer suporte à cópia sob demanda, um mecanismo de cópia de fallback será usado.
  • fs.constants.COPYFILE_FICLONE_FORCE: A operação de cópia tentará criar um reflink de cópia sob demanda. Se a plataforma não oferecer suporte à cópia sob demanda, a operação falhará.

• Retorna: <Promise> Cumpre com undefined após o sucesso.

Copia assincronamente src para dest. Por padrão, dest é sobrescrito se já existir.

Não há garantias sobre a atomicidade da operação de cópia. Se ocorrer um erro após o arquivo de destino ter sido aberto para gravação, uma tentativa será feita para remover o destino.

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

try {
  await copyFile('source.txt', 'destination.txt')
  console.log('source.txt foi copiado para destination.txt')
} catch {
  console.error('O arquivo não pôde ser copiado')
}

// Ao usar COPYFILE_EXCL, a operação falhará se destination.txt existir.
try {
  await copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL)
  console.log('source.txt foi copiado para destination.txt')
} catch {
  console.error('O arquivo não pôde ser copiado')
}

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

[Histórico]

Versão	Mudanças
v22.3.0	Esta API não é mais experimental.
v20.1.0, v18.17.0	Aceita uma opção adicional mode para especificar o comportamento da cópia como o argumento mode de fs.copyFile().
v17.6.0, v16.15.0	Aceita uma opção adicional verbatimSymlinks para especificar se deve executar a resolução de caminho para symlinks.
v16.7.0	Adicionado em: v16.7.0

• src <string> | <URL> caminho de origem a ser copiado.

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

• options <Object>

  • dereference <boolean> desreferenciar symlinks. Padrão: false.

  • errorOnExist <boolean> quando force é false e o destino existe, lança um erro. Padrão: false.

  • filter <Function> Função para filtrar arquivos/diretórios copiados. Retorne true para copiar o item, false para ignorá-lo. Ao ignorar um diretório, todo o seu conteúdo também será ignorado. Também pode retornar uma Promise que resolve para true ou false Padrão: undefined.

  • src <string> caminho de origem a ser copiado.

  • dest <string> caminho de destino para onde copiar.

  • Retorna: <boolean> | <Promise> Um valor que pode ser coagido a boolean ou uma Promise que é cumprida com tal valor.

  • force <boolean> sobrescrever arquivo ou diretório existente. A operação de cópia ignorará erros se você definir isso como false e o destino existir. Use a opção errorOnExist para alterar este comportamento. Padrão: true.

  • mode <integer> modificadores para a operação de cópia. Padrão: 0. Veja o sinalizador mode de fsPromises.copyFile().

  • preserveTimestamps <boolean> Quando true, os carimbos de data/hora de src serão preservados. Padrão: false.

  • recursive <boolean> copiar diretórios recursivamente Padrão: false

  • verbatimSymlinks <boolean> Quando true, a resolução de caminho para symlinks será ignorada. Padrão: false

• Retorna: <Promise> Cumprida com undefined após o sucesso.

Copia de forma assíncrona toda a estrutura de diretório de src para dest, incluindo subdiretórios e arquivos.

Ao copiar um diretório para outro diretório, globos não são suportados e o comportamento é semelhante a cp dir1/ dir2/.

fsPromises.glob(pattern[, options])

[Histórico]

Versão	Mudanças
v22.2.0	Adicionado suporte para withFileTypes como uma opção.
v22.0.0	Adicionado em: v22.0.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• pattern <string> | <string[]>

• options <Object>

  • cwd <string> diretório de trabalho atual. Padrão: process.cwd()
  • exclude <Function> Função para filtrar arquivos/diretórios. Retorne true para excluir o item, false para incluí-lo. Padrão: undefined.
  • withFileTypes <boolean> true se o glob deve retornar caminhos como Dirents, false caso contrário. Padrão: false.

• Retorna: <AsyncIterator> Um AsyncIterator que produz os caminhos dos arquivos que correspondem ao padrão.

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>
• Retorna: <Promise> Cumpre com undefined após o sucesso.

Altera as permissões em um link simbólico.

Este método é implementado apenas no macOS.

fsPromises.lchown(path, uid, gid)

[Histórico]

Versão	Mudanças
v10.6.0	Esta API não está mais obsoleta.
v10.0.0	Adicionado em: v10.0.0

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• Retorna: <Promise> Cumpre com undefined em caso de sucesso.

Altera a propriedade em um link simbólico.

fsPromises.lutimes(path, atime, mtime)

Adicionado em: v14.5.0, v12.19.0

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• Retorna: <Promise> Cumpre com undefined em caso de sucesso.

Altera os tempos de acesso e modificação de um arquivo da mesma forma que fsPromises.utimes(), com a diferença de que, se o caminho se referir a um link simbólico, o link não é desreferenciado: em vez disso, os carimbos de data/hora do próprio link simbólico são alterados.

fsPromises.link(existingPath, newPath)

Adicionado em: v10.0.0

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• Retorna: <Promise> Cumpre com undefined após o sucesso.

Cria um novo link de existingPath para newPath. Consulte a documentação POSIX link(2) para mais detalhes.

fsPromises.lstat(path[, options])

[Histórico]

Versão	Mudanças
v10.5.0	Aceita um objeto options adicional para especificar se os valores numéricos retornados devem ser bigint.
v10.0.0	Adicionado em: v10.0.0

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

• options <Object>

  • bigint <boolean> Se os valores numéricos no objeto <fs.Stats> retornado devem ser bigint. Padrão: false.

• Retorna: <Promise> Cumpre com o objeto <fs.Stats> para o link simbólico path fornecido.

Equivalente a fsPromises.stat(), a menos que path se refira a um link simbólico, caso em que o próprio link é stat-ed, e não o arquivo ao qual ele se refere. Consulte o documento POSIX lstat(2) para mais detalhes.

fsPromises.mkdir(path[, options])

Adicionado em: v10.0.0

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

• options <Object> | <integer>

  • recursive <boolean> Padrão: false
  • mode <string> | <integer> Não suportado no Windows. Padrão: 0o777.

• Retorna: <Promise> Em caso de sucesso, é cumprida com undefined se recursive for false, ou o primeiro caminho de diretório criado se recursive for true.

Cria um diretório de forma assíncrona.

O argumento opcional options pode ser um número inteiro especificando mode (permissão e bits sticky), ou um objeto com uma propriedade mode e uma propriedade recursive indicando se os diretórios pai devem ser criados. Chamar fsPromises.mkdir() quando path é um diretório que já existe resulta em uma rejeição apenas quando recursive é false.

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(`criado ${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])

[Histórico]

Versão	Mudanças
v20.6.0, v18.19.0	O parâmetro prefix agora aceita buffers e URL.
v16.5.0, v14.18.0	O parâmetro prefix agora aceita uma string vazia.
v10.0.0	Adicionado em: v10.0.0

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

• options <string> | <Object>

  • encoding <string> Padrão: 'utf8'

• Retorna: <Promise> Cumpre com uma string contendo o caminho do sistema de arquivos do diretório temporário recém-criado.

Cria um diretório temporário único. Um nome de diretório único é gerado anexando seis caracteres aleatórios ao final do prefix fornecido. Devido a inconsistências de plataforma, evite caracteres X finais em prefix. Algumas plataformas, notavelmente as BSDs, podem retornar mais de seis caracteres aleatórios e substituir os caracteres X finais em prefix por caracteres aleatórios.

O argumento options opcional pode ser uma string especificando uma codificação, ou um objeto com uma propriedade encoding especificando a codificação de caracteres a ser usada.

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)
}

O método fsPromises.mkdtemp() anexará os seis caracteres selecionados aleatoriamente diretamente à string prefix. Por exemplo, dado um diretório /tmp, se a intenção é criar um diretório temporário dentro de /tmp, o prefix deve terminar com um separador de caminho específico da plataforma (require('node:path').sep).

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

[Histórico]

Versão	Mudanças
v11.1.0	O argumento flags agora é opcional e o padrão é 'r'.
v10.0.0	Adicionado em: v10.0.0

• path <string> | <Buffer> | <URL>
• flags <string> | <number> Veja suporte de flags do sistema de arquivos. Padrão: 'r'.
• mode <string> | <integer> Define o modo de arquivo (permissão e bits sticky) se o arquivo for criado. Padrão: 0o666 (legível e gravável)
• Retorna: <Promise> Cumpre com um objeto <FileHandle>.

Abre um <FileHandle>.

Consulte a documentação POSIX open(2) para mais detalhes.

Alguns caracteres (\< \> : " / \ | ? *) são reservados no Windows, conforme documentado em Nomeando Arquivos, Caminhos e Namespaces. No NTFS, se o nome do arquivo contiver dois pontos, o Node.js abrirá um fluxo do sistema de arquivos, conforme descrito por esta página da MSDN.

fsPromises.opendir(path[, options])

[Histórico]

Versão	Mudanças
v20.1.0, v18.17.0	Adicionada a opção recursive.
v13.1.0, v12.16.0	A opção bufferSize foi introduzida.
v12.12.0	Adicionado em: v12.12.0

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

• options <Object>

  • encoding <string> | <null> Padrão: 'utf8'
  • bufferSize <number> Número de entradas de diretório que são armazenadas em buffer internamente ao ler do diretório. Valores mais altos levam a um melhor desempenho, mas maior uso de memória. Padrão: 32
  • recursive <boolean> Dir resolvido será um <AsyncIterable> contendo todos os subarquivos e diretórios. Padrão: false

• Retorna: <Promise> Cumpre com um <fs.Dir>.

Abre um diretório de forma assíncrona para varredura iterativa. Consulte a documentação POSIX opendir(3) para mais detalhes.

Cria um <fs.Dir>, que contém todas as funções adicionais para ler e limpar o diretório.

A opção encoding define a codificação para o path ao abrir o diretório e operações de leitura subsequentes.

Exemplo usando iteração assí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)
}

Ao usar o iterador assíncrono, o objeto <fs.Dir> será fechado automaticamente após a saída do iterador.

fsPromises.readdir(path[, options])

[Histórico]

Versão	Mudanças
v20.1.0, v18.17.0	Adicionada opção recursive.
v10.11.0	Nova opção withFileTypes foi adicionada.
v10.0.0	Adicionado em: v10.0.0

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

• options <string> | <Object>

  • encoding <string> Padrão: 'utf8'
  • withFileTypes <boolean> Padrão: false
  • recursive <boolean> Se true, lê o conteúdo de um diretório recursivamente. No modo recursivo, ele listará todos os arquivos, subarquivos e diretórios. Padrão: false.

• Retorna: <Promise> Cumpre com um array dos nomes dos arquivos no diretório, excluindo '.' e '..'.

Lê o conteúdo de um diretório.

O argumento opcional options pode ser uma string especificando uma codificação, ou um objeto com uma propriedade encoding especificando a codificação de caracteres a ser usada para os nomes dos arquivos. Se a encoding estiver definida como 'buffer', os nomes de arquivos retornados serão passados como objetos <Buffer>.

Se options.withFileTypes estiver definido como true, o array retornado conterá 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])

[Histórico]

Versão	Mudanças
v15.2.0, v14.17.0	O argumento options pode incluir um AbortSignal para abortar uma solicitação readFile em andamento.
v10.0.0	Adicionado em: v10.0.0

• path <string> | <Buffer> | <URL> | <FileHandle> nome do arquivo ou FileHandle

• options <Object> | <string>

  • encoding <string> | <null> Padrão: null
  • flag <string> Consulte suporte para flags do sistema de arquivos. Padrão: 'r'.
  • signal <AbortSignal> permite abortar um readFile em andamento

• Retorna: <Promise> É resolvida com o conteúdo do arquivo.

Lê de forma assíncrona todo o conteúdo de um arquivo.

Se nenhuma codificação for especificada (usando options.encoding), os dados serão retornados como um objeto <Buffer>. Caso contrário, os dados serão uma string.

Se options for uma string, ela especificará a codificação.

Quando o path é um diretório, o comportamento de fsPromises.readFile() é específico da plataforma. No macOS, Linux e Windows, a promise será rejeitada com um erro. No FreeBSD, uma representação do conteúdo do diretório será retornada.

Um exemplo de leitura de um arquivo package.json localizado no mesmo diretório do código em execução:

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()

É possível abortar um readFile em andamento usando um <AbortSignal>. Se uma solicitação for abortada, a promise retornada será rejeitada com um AbortError:

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

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

  // Aborta a solicitação antes que a promise seja resolvida.
  controller.abort()

  await promise
} catch (err) {
  // Quando uma solicitação é abortada - err é um AbortError
  console.error(err)
}

Abortar uma solicitação em andamento não aborta solicitações individuais do sistema operacional, mas sim o buffer interno que fs.readFile realiza.

Qualquer <FileHandle> especificado deve suportar a leitura.

fsPromises.readlink(path[, options])

Adicionado em: v10.0.0

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

• options <string> | <Object>

  • encoding <string> Padrão: 'utf8'

• Retorna: <Promise> Cumpre com o linkString após o sucesso.

Lê o conteúdo do link simbólico referenciado por path. Veja a documentação POSIX readlink(2) para mais detalhes. A promessa é cumprida com o linkString após o sucesso.

O argumento opcional options pode ser uma string especificando uma codificação, ou um objeto com uma propriedade encoding especificando a codificação de caracteres a ser usada para o caminho do link retornado. Se o encoding estiver definido como 'buffer', o caminho do link retornado será passado como um objeto <Buffer>.

fsPromises.realpath(path[, options])

Adicionado em: v10.0.0

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

• options <string> | <Object>

  • encoding <string> Padrão: 'utf8'

• Retorna: <Promise> Cumpre com o caminho resolvido após o sucesso.

Determina a localização real de path usando a mesma semântica da função fs.realpath.native().

Apenas caminhos que podem ser convertidos em strings UTF8 são suportados.

O argumento opcional options pode ser uma string especificando uma codificação, ou um objeto com uma propriedade encoding especificando a codificação de caracteres a ser usada para o caminho. Se o encoding estiver definido como 'buffer', o caminho retornado será passado como um objeto <Buffer>.

No Linux, quando o Node.js está vinculado ao musl libc, o sistema de arquivos procfs deve ser montado em /proc para que esta função funcione. Glibc não tem essa restrição.

fsPromises.rename(oldPath, newPath)

Adicionado em: v10.0.0

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• Retorna: <Promise> Cumpre com undefined em caso de sucesso.

Renomeia oldPath para newPath.

fsPromises.rmdir(path[, options])

[Histórico]

Versão	Mudanças
v16.0.0	Usar fsPromises.rmdir(path, { recursive: true }) em um path que é um arquivo não é mais permitido e resulta em um erro ENOENT no Windows e um erro ENOTDIR no POSIX.
v16.0.0	Usar fsPromises.rmdir(path, { recursive: true }) em um path que não existe não é mais permitido e resulta em um erro ENOENT.
v16.0.0	A opção recursive está obsoleta, usá-la aciona um aviso de obsolescência.
v14.14.0	A opção recursive está obsoleta, use fsPromises.rm em vez disso.
v13.3.0, v12.16.0	A opção maxBusyTries foi renomeada para maxRetries, e seu padrão é 0. A opção emfileWait foi removida, e os erros EMFILE usam a mesma lógica de repetição que outros erros. A opção retryDelay agora é suportada. Erros ENFILE agora são repetidos.
v12.10.0	As opções recursive, maxBusyTries e emfileWait agora são suportadas.
v10.0.0	Adicionado em: v10.0.0

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

• options <Object>

  • maxRetries <integer> Se um erro EBUSY, EMFILE, ENFILE, ENOTEMPTY ou EPERM for encontrado, o Node.js repete a operação com uma espera de backoff linear de retryDelay milissegundos a mais em cada tentativa. Esta opção representa o número de tentativas. Esta opção é ignorada se a opção recursive não for true. Padrão: 0.
  • recursive <boolean> Se true, execute uma remoção de diretório recursiva. No modo recursivo, as operações são repetidas em caso de falha. Padrão: false. Obsoleto.
  • retryDelay <integer> A quantidade de tempo em milissegundos para esperar entre as repetições. Esta opção é ignorada se a opção recursive não for true. Padrão: 100.

• Retorna: <Promise> Cumpre com undefined em caso de sucesso.

Remove o diretório identificado por path.

Usar fsPromises.rmdir() em um arquivo (não um diretório) resulta na rejeição da promise com um erro ENOENT no Windows e um erro ENOTDIR no POSIX.

Para obter um comportamento semelhante ao comando Unix rm -rf, use fsPromises.rm() com as opções { recursive: true, force: true }.

fsPromises.rm(path[, options])

Adicionado em: v14.14.0

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

• options <Object>

  • force <boolean> Quando true, as exceções serão ignoradas se path não existir. Padrão: false.
  • maxRetries <integer> Se um erro EBUSY, EMFILE, ENFILE, ENOTEMPTY ou EPERM for encontrado, o Node.js irá tentar novamente a operação com uma espera de backoff linear de retryDelay milissegundos mais longa em cada tentativa. Essa opção representa o número de tentativas. Essa opção é ignorada se a opção recursive não for true. Padrão: 0.
  • recursive <boolean> Se true, realiza uma remoção de diretório recursiva. No modo recursivo, as operações são repetidas em caso de falha. Padrão: false.
  • retryDelay <integer> A quantidade de tempo em milissegundos para esperar entre as tentativas. Essa opção é ignorada se a opção recursive não for true. Padrão: 100.

• Retorna: <Promise> É resolvida com undefined em caso de sucesso.

Remove arquivos e diretórios (modelado no utilitário POSIX padrão rm).

fsPromises.stat(path[, options])

[Histórico]

Versão	Mudanças
v10.5.0	Aceita um objeto options adicional para especificar se os valores numéricos retornados devem ser bigint.
v10.0.0	Adicionado em: v10.0.0

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

• options <Object>

  • bigint <boolean> Se os valores numéricos no objeto <fs.Stats> retornado devem ser bigint. Padrão: false.

• Retorna: <Promise> É resolvida com o objeto <fs.Stats> para o path fornecido.

fsPromises.statfs(path[, options])

Adicionado em: v19.6.0, v18.15.0

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

• options <Object>

  • bigint <boolean> Indica se os valores numéricos no objeto <fs.StatFs> retornado devem ser bigint. Padrão: false.

• Retorna: <Promise> Cumpre com o objeto <fs.StatFs> para o path fornecido.

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

[Histórico]

Versão	Mudanças
v19.0.0	Se o argumento type for null ou omitido, o Node.js irá detetar automaticamente o tipo do target e selecionar automaticamente dir ou file.
v10.0.0	Adicionado em: v10.0.0

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> | <null> Padrão: null
• Retorna: <Promise> Cumpre com undefined após o sucesso.

Cria um link simbólico.

O argumento type é usado apenas em plataformas Windows e pode ser um de 'dir', 'file' ou 'junction'. Se o argumento type for null, o Node.js irá detetar automaticamente o tipo do target e usar 'file' ou 'dir'. Se o target não existir, 'file' será usado. Pontos de junção do Windows exigem que o caminho de destino seja absoluto. Ao usar 'junction', o argumento target será automaticamente normalizado para um caminho absoluto. Pontos de junção em volumes NTFS só podem apontar para diretórios.

fsPromises.truncate(path[, len])

Adicionado em: v10.0.0

• path <string> | <Buffer> | <URL>
• len <integer> Padrão: 0
• Retorna: <Promise> Cumpre com undefined após o sucesso.

Trunca (encurta ou estende o comprimento) do conteúdo em path para len bytes.

fsPromises.unlink(path)

Adicionado em: v10.0.0

• path <string> | <Buffer> | <URL>
• Retorna: <Promise> Cumpre com undefined após o sucesso.

Se path se referir a um link simbólico, o link é removido sem afetar o arquivo ou diretório para o qual esse link se refere. Se o path se referir a um caminho de arquivo que não é um link simbólico, o arquivo é excluído. Consulte a documentação POSIX unlink(2) para obter mais detalhes.

fsPromises.utimes(path, atime, mtime)

Adicionado em: v10.0.0

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• Retorna: <Promise> Cumpre com undefined após o sucesso.

Altera os carimbos de data/hora do sistema de arquivos do objeto referenciado por path.

Os argumentos atime e mtime seguem estas regras:

• Os valores podem ser números representando o tempo Unix epoch, Dates ou uma string numérica como '123456789.0'.
• Se o valor não puder ser convertido em um número, ou for NaN, Infinity ou -Infinity, um Error será lançado.

fsPromises.watch(filename[, options])

Adicionado em: v15.9.0, v14.18.0

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

• options <string> | <Object>

  • persistent <boolean> Indica se o processo deve continuar a ser executado enquanto os arquivos estiverem sendo observados. Padrão: true.
  • recursive <boolean> Indica se todos os subdiretórios devem ser observados ou apenas o diretório atual. Isso se aplica quando um diretório é especificado e apenas em plataformas suportadas (Consulte resalvas). Padrão: false.
  • encoding <string> Especifica a codificação de caracteres a ser usada para o nome do arquivo passado para o listener. Padrão: 'utf8'.
  • signal <AbortSignal> Um <AbortSignal> usado para sinalizar quando o observador deve parar.

• Retorna: <AsyncIterator> de objetos com as propriedades:

  • eventType <string> O tipo de alteração
  • filename <string> | <Buffer> | <null> O nome do arquivo alterado.

Retorna um iterador assíncrono que observa as alterações em filename, onde filename é um arquivo ou um diretório.

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
  }
})()

Na maioria das plataformas, 'rename' é emitido sempre que um nome de arquivo aparece ou desaparece no diretório.

Todas as resalvas para fs.watch() também se aplicam a fsPromises.watch().

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

[Histórico]

Versão	Mudanças
v21.0.0, v20.10.0	A opção flush agora é suportada.
v15.14.0, v14.18.0	O argumento data suporta AsyncIterable, Iterable e Stream.
v15.2.0, v14.17.0	O argumento de opções pode incluir um AbortSignal para abortar uma solicitação writeFile em andamento.
v14.0.0	O parâmetro data não irá mais forçar entradas não suportadas para strings.
v10.0.0	Adicionado em: v10.0.0

• file <string> | <Buffer> | <URL> | <FileHandle> nome do arquivo ou FileHandle
• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>
• options <Object> | <string>
  • encoding <string> | <null> Padrão: 'utf8'
  • mode <integer> Padrão: 0o666
  • flag <string> Consulte suporte de flags do sistema de arquivos. Padrão: 'w'.
  • flush <boolean> Se todos os dados forem gravados com sucesso no arquivo e flush for true, filehandle.sync() é usado para liberar os dados. Padrão: false.
  • signal <AbortSignal> permite abortar um writeFile em andamento
• Retorna: <Promise> Cumpre com undefined após o sucesso.

Grava dados assincronamente em um arquivo, substituindo o arquivo se ele já existir. data pode ser uma string, um buffer, um objeto <AsyncIterable> ou um objeto <Iterable>.

A opção encoding é ignorada se data for um buffer.

Se options for uma string, ela especifica a codificação.

A opção mode afeta apenas o arquivo recém-criado. Consulte fs.open() para mais detalhes.

Qualquer <FileHandle> especificado deve suportar gravação.

Não é seguro usar fsPromises.writeFile() várias vezes no mesmo arquivo sem esperar que a promessa seja resolvida.

Semelhante a fsPromises.readFile - fsPromises.writeFile é um método de conveniência que executa várias chamadas write internamente para gravar o buffer passado para ele. Para código sensível ao desempenho, considere usar fs.createWriteStream() ou filehandle.createWriteStream().

É possível usar um <AbortSignal> para cancelar um fsPromises.writeFile(). O cancelamento é "o melhor possível" e é provável que alguma quantidade de dados ainda seja gravada.

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 })

  // Aborta a solicitação antes que a promessa seja resolvida.
  controller.abort()

  await promise
} catch (err) {
  // Quando uma solicitação é abortada - err é um AbortError
  console.error(err)
}

Abortar uma solicitação em andamento não aborta solicitações individuais do sistema operacional, mas sim o armazenamento em buffer interno que fs.writeFile executa.

fsPromises.constants

Adicionado em: v18.4.0, v16.17.0

• <Object>

Retorna um objeto contendo constantes comumente usadas para operações do sistema de arquivos. O objeto é o mesmo que fs.constants. Consulte constantes FS para mais detalhes.

API de Callback

As APIs de callback executam todas as operações de forma assíncrona, sem bloquear o loop de eventos, e então invocam uma função de callback após a conclusão ou erro.

As APIs de callback usam o threadpool Node.js subjacente para realizar operações do sistema de arquivos fora da thread do loop de eventos. Essas operações não são sincronizadas nem threadsafe. Deve-se ter cuidado ao realizar várias modificações simultâneas no mesmo arquivo, ou pode ocorrer corrupção de dados.

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

[Histórico]

Versão	Alterações
v20.8.0	As constantes fs.F_OK, fs.R_OK, fs.W_OK e fs.X_OK que estavam presentes diretamente em fs estão depreciadas.
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v7.6.0	O parâmetro path pode ser um objeto URL WHATWG usando o protocolo file:.
v6.3.0	As constantes como fs.R_OK, etc., que estavam presentes diretamente em fs, foram movidas para fs.constants como uma depreciação suave. Assim, para Node.js \< v6.3.0, use fs para acessar essas constantes ou faça algo como `(fs.constants
v0.11.15	Adicionado em: v0.11.15

• path <string> | <Buffer> | <URL>
• mode <integer> Padrão: fs.constants.F_OK
• callback <Function>
  • err <Error>

Testa as permissões de um usuário para o arquivo ou diretório especificado por path. O argumento mode é um inteiro opcional que especifica as verificações de acessibilidade a serem realizadas. mode deve ser o valor fs.constants.F_OK ou uma máscara consistindo no OR bit a bit de qualquer um de fs.constants.R_OK, fs.constants.W_OK e fs.constants.X_OK (por exemplo, fs.constants.W_OK | fs.constants.R_OK). Verifique Constantes de acesso a arquivos para possíveis valores de mode.

O argumento final, callback, é uma função de callback que é invocada com um possível argumento de erro. Se alguma das verificações de acessibilidade falhar, o argumento de erro será um objeto Error. Os exemplos a seguir verificam se package.json existe e se ele é legível ou gravável.

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

const file = 'package.json'

// Verifica se o arquivo existe no diretório atual.
access(file, constants.F_OK, err => {
  console.log(`${file} ${err ? 'não existe' : 'existe'}`)
})

// Verifica se o arquivo é legível.
access(file, constants.R_OK, err => {
  console.log(`${file} ${err ? 'não é legível' : 'é legível'}`)
})

// Verifica se o arquivo é gravável.
access(file, constants.W_OK, err => {
  console.log(`${file} ${err ? 'não é gravável' : 'é gravável'}`)
})

// Verifica se o arquivo é legível e gravável.
access(file, constants.R_OK | constants.W_OK, err => {
  console.log(`${file} ${err ? 'não é' : 'é'} legível e gravável`)
})

Não use fs.access() para verificar a acessibilidade de um arquivo antes de chamar fs.open(), fs.readFile() ou fs.writeFile(). Fazer isso introduz uma condição de corrida, já que outros processos podem alterar o estado do arquivo entre as duas chamadas. Em vez disso, o código do usuário deve abrir/ler/escrever o arquivo diretamente e lidar com o erro gerado se o arquivo não estiver acessível.

gravar (NÃO RECOMENDADO)

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

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

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

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

gravar (RECOMENDADO)

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

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

    throw err
  }

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

ler (NÃO RECOMENDADO)

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

    throw err
  }

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

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

ler (RECOMENDADO)

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

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

    throw err
  }

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

Os exemplos "não recomendados" acima verificam a acessibilidade e, em seguida, usam o arquivo; os exemplos "recomendados" são melhores porque usam o arquivo diretamente e lidam com o erro, se houver.

Em geral, verifique a acessibilidade de um arquivo apenas se o arquivo não for usado diretamente, por exemplo, quando sua acessibilidade for um sinal de outro processo.

No Windows, as políticas de controle de acesso (ACLs) em um diretório podem limitar o acesso a um arquivo ou diretório. A função fs.access(), no entanto, não verifica a ACL e, portanto, pode relatar que um caminho está acessível, mesmo que a ACL restrinja o usuário de ler ou gravar nele.

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

[Histórico]

Versão	Mudanças
v21.1.0, v20.10.0	A opção flush agora é suportada.
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com o id DEP0013.
v7.0.0	O objeto options passado nunca será modificado.
v5.0.0	O parâmetro file agora pode ser um descritor de arquivo.
v0.6.7	Adicionado em: v0.6.7

• path <string> | <Buffer> | <URL> | <number> nome do arquivo ou descritor de arquivo

• data <string> | <Buffer>

• options <Object> | <string>

  • encoding <string> | <null> Padrão: 'utf8'
  • mode <integer> Padrão: 0o666
  • flag <string> Veja suporte de flags do sistema de arquivos. Padrão: 'a'.
  • flush <boolean> Se true, o descritor de arquivo subjacente é esvaziado antes de ser fechado. Padrão: false.

• callback <Function>

  • err <Error>

Anexa dados de forma assíncrona a um arquivo, criando o arquivo se ele ainda não existir. data pode ser uma string ou um <Buffer>.

A opção mode afeta apenas o arquivo recém-criado. Veja fs.open() para mais detalhes.

import { appendFile } from 'node:fs'

appendFile('message.txt', 'dados para anexar', err => {
  if (err) throw err
  console.log('Os "dados para anexar" foram anexados ao arquivo!')
})

Se options for uma string, ela especifica a codificação:

import { appendFile } from 'node:fs'

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

O path pode ser especificado como um descritor de arquivo numérico que foi aberto para anexação (usando fs.open() ou fs.openSync()). O descritor de arquivo não será fechado automaticamente.

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, 'dados para anexar', 'utf8', err => {
      closeFd(fd)
      if (err) throw err
    })
  } catch (err) {
    closeFd(fd)
    throw err
  }
})

fs.chmod(path, mode, callback)

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.6.0	O parâmetro path pode ser um objeto WHATWG URL usando o protocolo file:.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com o id DEP0013.
v0.1.30	Adicionado em: v0.1.30

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

Altera as permissões de um arquivo de forma assíncrona. Nenhum argumento além de uma possível exceção é fornecido ao callback de conclusão.

Consulte a documentação POSIX chmod(2) para obter mais detalhes.

import { chmod } from 'node:fs'

chmod('meu_arquivo.txt', 0o775, err => {
  if (err) throw err
  console.log('As permissões do arquivo "meu_arquivo.txt" foram alteradas!')
})

Modos de arquivo

O argumento mode usado nos métodos fs.chmod() e fs.chmodSync() é uma máscara de bits numérica criada usando um OR lógico das seguintes constantes:

Constante	Octal	Descrição
fs.constants.S_IRUSR	0o400	leitura pelo proprietário
fs.constants.S_IWUSR	0o200	escrita pelo proprietário
fs.constants.S_IXUSR	0o100	execução/pesquisa pelo proprietário
fs.constants.S_IRGRP	0o40	leitura pelo grupo
fs.constants.S_IWGRP	0o20	escrita pelo grupo
fs.constants.S_IXGRP	0o10	execução/pesquisa pelo grupo
fs.constants.S_IROTH	0o4	leitura por outros
fs.constants.S_IWOTH	0o2	escrita por outros
fs.constants.S_IXOTH	0o1	execução/pesquisa por outros

Um método mais fácil de construir o mode é usar uma sequência de três dígitos octais (por exemplo, 765). O dígito mais à esquerda (7 no exemplo) especifica as permissões para o proprietário do arquivo. O dígito do meio (6 no exemplo) especifica as permissões para o grupo. O dígito mais à direita (5 no exemplo) especifica as permissões para outros.

Número	Descrição
7	leitura, escrita e execução
6	leitura e escrita
5	leitura e execução
4	somente leitura
3	escrita e execução
2	somente escrita
1	somente execução
0	sem permissão

Por exemplo, o valor octal 0o765 significa:

• O proprietário pode ler, escrever e executar o arquivo.
• O grupo pode ler e escrever o arquivo.
• Outros podem ler e executar o arquivo.

Ao usar números brutos onde os modos de arquivo são esperados, qualquer valor maior que 0o777 pode resultar em comportamentos específicos da plataforma que não têm suporte para funcionar de forma consistente. Portanto, constantes como S_ISVTX, S_ISGID ou S_ISUID não são expostas em fs.constants.

Ressalvas: no Windows, apenas a permissão de escrita pode ser alterada, e a distinção entre as permissões de grupo, proprietário ou outros não é implementada.

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.6.0	O parâmetro path pode ser um objeto WHATWG URL usando o protocolo file:.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com o id DEP0013.
v0.1.97	Adicionado em: v0.1.97

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

Altera de forma assíncrona o proprietário e o grupo de um arquivo. Nenhum argumento além de uma possível exceção é dado ao callback de conclusão.

Consulte a documentação POSIX chown(2) para mais detalhes.

fs.close(fd[, callback])

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v15.9.0, v14.17.0	Um callback padrão agora é usado se nenhum for fornecido.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com o id DEP0013.
v0.0.2	Adicionado em: v0.0.2

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

Fecha o descritor de arquivo. Nenhum argumento além de uma possível exceção é dado ao callback de conclusão.

Chamar fs.close() em qualquer descritor de arquivo (fd) que esteja atualmente em uso por meio de qualquer outra operação fs pode levar a um comportamento indefinido.

Consulte a documentação POSIX close(2) para mais detalhes.

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v14.0.0	Alterou o argumento flags para mode e impôs uma validação de tipo mais rigorosa.
v8.5.0	Adicionado em: v8.5.0

• src <string> | <Buffer> | <URL> nome do arquivo de origem a ser copiado
• dest <string> | <Buffer> | <URL> nome do arquivo de destino da operação de cópia
• mode <integer> modificadores para a operação de cópia. Padrão: 0.
• callback <Function>
  • err <Error>

Copia assincronamente src para dest. Por padrão, dest é sobrescrito se já existir. Nenhum argumento além de uma possível exceção é fornecido para a função de callback. O Node.js não oferece garantias sobre a atomicidade da operação de cópia. Se ocorrer um erro após o arquivo de destino ter sido aberto para escrita, o Node.js tentará remover o destino.

mode é um número inteiro opcional que especifica o comportamento da operação de cópia. É possível criar uma máscara que consiste na OR bit a bit de dois ou mais valores (por exemplo, fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE).

• fs.constants.COPYFILE_EXCL: A operação de cópia falhará se dest já existir.
• fs.constants.COPYFILE_FICLONE: A operação de cópia tentará criar uma reflink de cópia na escrita. Se a plataforma não suportar cópia na escrita, um mecanismo de cópia de fallback será usado.
• fs.constants.COPYFILE_FICLONE_FORCE: A operação de cópia tentará criar uma reflink de cópia na escrita. Se a plataforma não suportar cópia na escrita, a operação falhará.

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

function callback(err) {
  if (err) throw err
  console.log('source.txt foi copiado para destination.txt')
}

// destination.txt será criado ou sobrescrito por padrão.
copyFile('source.txt', 'destination.txt', callback)

// Ao usar COPYFILE_EXCL, a operação falhará se destination.txt existir.
copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL, callback)

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

[Histórico]

Versão	Mudanças
v22.3.0	Esta API não é mais experimental.
v20.1.0, v18.17.0	Aceita uma opção mode adicional para especificar o comportamento de cópia como o argumento mode de fs.copyFile().
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v17.6.0, v16.15.0	Aceita uma opção verbatimSymlinks adicional para especificar se deve realizar a resolução de caminho para symlinks.
v16.7.0	Adicionado em: v16.7.0

• src <string> | <URL> caminho de origem para copiar.

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

• options <Object>

  • dereference <boolean> desreferenciar symlinks. Padrão: false.

  • errorOnExist <boolean> quando force é false e o destino existe, lança um erro. Padrão: false.

  • filter <Function> Função para filtrar arquivos/diretórios copiados. Retorna true para copiar o item, false para ignorá-lo. Ao ignorar um diretório, todo o seu conteúdo também será ignorado. Também pode retornar uma Promise que se resolve para true ou false. Padrão: undefined.

  • src <string> caminho de origem para copiar.

  • dest <string> caminho de destino para copiar.

  • Retorna: <boolean> | <Promise> Um valor que pode ser coagido para boolean ou uma Promise que se cumpre com tal valor.

  • force <boolean> sobrescrever arquivo ou diretório existente. A operação de cópia irá ignorar erros se você definir isso como falso e o destino existir. Use a opção errorOnExist para alterar este comportamento. Padrão: true.

  • mode <integer> modificadores para operação de cópia. Padrão: 0. Consulte a flag mode de fs.copyFile().

  • preserveTimestamps <boolean> Quando true os timestamps de src serão preservados. Padrão: false.

  • recursive <boolean> copiar diretórios recursivamente. Padrão: false

  • verbatimSymlinks <boolean> Quando true, a resolução de caminho para symlinks será ignorada. Padrão: false.

• callback <Function>

  • err <Error>

Copia assíncronamente toda a estrutura de diretório de src para dest, incluindo subdiretórios e arquivos.

Ao copiar um diretório para outro diretório, globs não são suportados e o comportamento é semelhante a cp dir1/ dir2/.

fs.createReadStream(path[, options])

[Histórico]

Versão	Mudanças
v16.10.0	A opção fs não precisa do método open se um fd foi fornecido.
v16.10.0	A opção fs não precisa do método close se autoClose for false.
v15.5.0	Adicionado suporte para AbortSignal.
v15.4.0	A opção fd aceita argumentos FileHandle.
v14.0.0	Alterado o padrão de emitClose para true.
v13.6.0, v12.17.0	As opções fs permitem substituir a implementação fs usada.
v12.10.0	Habilitada a opção emitClose.
v11.0.0	Impostas novas restrições em start e end, lançando erros mais apropriados nos casos em que não podemos lidar razoavelmente com os valores de entrada.
v7.6.0	O parâmetro path pode ser um objeto WHATWG URL usando o protocolo file:.
v7.0.0	O objeto options passado nunca será modificado.
v2.3.0	O objeto options passado agora pode ser uma string.
v0.1.31	Adicionado em: v0.1.31

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

• options <string> | <Object>

  • flags <string> Veja suporte de flags do sistema de arquivos. Padrão: 'r'.
  • encoding <string> Padrão: null
  • fd <integer> | <FileHandle> Padrão: null
  • mode <integer> Padrão: 0o666
  • autoClose <boolean> Padrão: true
  • emitClose <boolean> Padrão: true
  • start <integer>
  • end <integer> Padrão: Infinity
  • highWaterMark <integer> Padrão: 64 * 1024
  • fs <Object> | <null> Padrão: null
  • signal <AbortSignal> | <null> Padrão: null

• Retorna: <fs.ReadStream>

options pode incluir valores start e end para ler um intervalo de bytes do arquivo em vez do arquivo inteiro. Tanto start quanto end são inclusivos e começam a contar a partir de 0, os valores permitidos estão no intervalo [0, Number.MAX_SAFE_INTEGER]. Se fd for especificado e start for omitido ou undefined, fs.createReadStream() lê sequencialmente a partir da posição atual do arquivo. O encoding pode ser qualquer um dos aceitos por <Buffer>.

Se fd for especificado, ReadStream irá ignorar o argumento path e usará o descritor de arquivo especificado. Isso significa que nenhum evento 'open' será emitido. fd deve ser bloqueador; fds não bloqueadores devem ser passados para <net.Socket>.

Se fd apontar para um dispositivo de caractere que suporta apenas leituras bloqueadoras (como teclado ou placa de som), as operações de leitura não terminarão até que os dados estejam disponíveis. Isso pode impedir que o processo seja encerrado e o stream seja fechado naturalmente.

Por padrão, o stream emitirá um evento 'close' depois de ser destruído. Defina a opção emitClose como false para alterar esse comportamento.

Ao fornecer a opção fs, é possível substituir as implementações fs correspondentes para open, read e close. Ao fornecer a opção fs, é necessário uma substituição para read. Se nenhum fd for fornecido, também será necessário uma substituição para open. Se autoClose for true, também será necessário uma substituição para close.

import { createReadStream } from 'node:fs'

// Cria um stream a partir de algum dispositivo de caractere.
const stream = createReadStream('/dev/input/event0')
setTimeout(() => {
  stream.close() // Isso pode não fechar o stream.
  // Marca artificialmente o fim do stream, como se o recurso subjacente
  // tivesse indicado o fim do arquivo por si só, permitindo que o stream seja fechado.
  // Isso não cancela operações de leitura pendentes e, se houver tal
  // operação, o processo ainda pode não conseguir sair com sucesso
  // até que termine.
  stream.push(null)
  stream.read(0)
}, 100)

Se autoClose for false, o descritor de arquivo não será fechado, mesmo que haja um erro. É responsabilidade do aplicativo fechá-lo e garantir que não haja vazamento do descritor de arquivo. Se autoClose for definido como true (comportamento padrão), em 'error' ou 'end' o descritor de arquivo será fechado automaticamente.

mode define o modo de arquivo (permissão e bits de sticky), mas apenas se o arquivo foi criado.

Um exemplo para ler os últimos 10 bytes de um arquivo que tem 100 bytes de comprimento:

import { createReadStream } from 'node:fs'

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

Se options for uma string, ele especificará a codificação.

fs.createWriteStream(path[, options])

[Histórico]

Versão	Mudanças
v21.0.0, v20.10.0	A opção flush agora é suportada.
v16.10.0	A opção fs não precisa do método open se um fd foi fornecido.
v16.10.0	A opção fs não precisa do método close se autoClose for false.
v15.5.0	Adicionado suporte para AbortSignal.
v15.4.0	A opção fd aceita argumentos FileHandle.
v14.0.0	Alterado o padrão de emitClose para true.
v13.6.0, v12.17.0	As opções fs permitem substituir a implementação fs utilizada.
v12.10.0	Habilitada a opção emitClose.
v7.6.0	O parâmetro path pode ser um objeto WHATWG URL usando o protocolo file:.
v7.0.0	O objeto options passado nunca será modificado.
v5.5.0	A opção autoClose agora é suportada.
v2.3.0	O objeto options passado pode ser uma string agora.
v0.1.31	Adicionado em: v0.1.31

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

• options <string> | <Object>

  • flags <string> Veja suporte das flags do sistema de arquivos. Padrão: 'w'.
  • encoding <string> Padrão: 'utf8'
  • fd <integer> | <FileHandle> Padrão: null
  • mode <integer> Padrão: 0o666
  • autoClose <boolean> Padrão: true
  • emitClose <boolean> Padrão: true
  • start <integer>
  • fs <Object> | <null> Padrão: null
  • signal <AbortSignal> | <null> Padrão: null
  • highWaterMark <number> Padrão: 16384
  • flush <boolean> Se true, o descritor de arquivo subjacente é descarregado antes de ser fechado. Padrão: false.

• Retorna: <fs.WriteStream>

options também pode incluir uma opção start para permitir a escrita de dados em alguma posição após o início do arquivo, os valores permitidos estão no intervalo [0, Number.MAX_SAFE_INTEGER]. Modificar um arquivo em vez de substituí-lo pode exigir que a opção flags seja definida como r+ em vez do padrão w. O encoding pode ser qualquer um dos aceitos por <Buffer>.

Se autoClose estiver definido como true (comportamento padrão) em 'error' ou 'finish', o descritor de arquivo será fechado automaticamente. Se autoClose for false, o descritor de arquivo não será fechado, mesmo que haja um erro. É responsabilidade do aplicativo fechá-lo e garantir que não haja vazamento do descritor de arquivo.

Por padrão, o fluxo emitirá um evento 'close' depois de ser destruído. Defina a opção emitClose como false para alterar este comportamento.

Ao fornecer a opção fs, é possível substituir as implementações fs correspondentes para open, write, writev e close. Substituir write() sem writev() pode reduzir o desempenho, pois algumas otimizações (_writev()) serão desabilitadas. Ao fornecer a opção fs, são necessárias substituições para pelo menos um de write e writev. Se nenhuma opção fd for fornecida, uma substituição para open também é necessária. Se autoClose for true, uma substituição para close também é necessária.

Como <fs.ReadStream>, se fd for especificado, <fs.WriteStream> ignorará o argumento path e usará o descritor de arquivo especificado. Isso significa que nenhum evento 'open' será emitido. fd deve ser bloqueador; fds não bloqueadores devem ser passados para <net.Socket>.

Se options for uma string, então especifica a codificação.

fs.exists(path, callback)

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v7.6.0	O parâmetro path pode ser um objeto WHATWG URL usando o protocolo file:.
v1.0.0	Descontinuado desde: v1.0.0
v0.0.2	Adicionado em: v0.0.2

[Estável: 0 - Descontinuado]

Estável: 0 Estabilidade: 0 - Descontinuado: Use fs.stat() ou fs.access() em vez disso.

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

Teste se o elemento no path fornecido existe verificando com o sistema de arquivos. Em seguida, chame o argumento callback com verdadeiro ou falso:

import { exists } from 'node:fs'

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

Os parâmetros para este callback não são consistentes com outros callbacks do Node.js. Normalmente, o primeiro parâmetro para um callback do Node.js é um parâmetro err, opcionalmente seguido por outros parâmetros. O callback fs.exists() tem apenas um parâmetro booleano. Esta é uma razão pela qual fs.access() é recomendado em vez de fs.exists().

Se path for um link simbólico, ele será seguido. Assim, se path existir, mas apontar para um elemento inexistente, o callback receberá o valor false.

Não é recomendado usar fs.exists() para verificar a existência de um arquivo antes de chamar fs.open(), fs.readFile() ou fs.writeFile(). Isso introduz uma condição de corrida, pois outros processos podem alterar o estado do arquivo entre as duas chamadas. Em vez disso, o código do usuário deve abrir/ler/escrever o arquivo diretamente e lidar com o erro gerado se o arquivo não existir.

escrever (NÃO RECOMENDADO)

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

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

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

escrever (RECOMENDADO)

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

    throw err
  }

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

ler (NÃO 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 não existe')
  }
})

ler (RECOMENDADO)

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

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

    throw err
  }

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

Os exemplos "não recomendados" acima verificam a existência e depois usam o arquivo; os exemplos "recomendados" são melhores porque usam o arquivo diretamente e lidam com o erro, se houver.

Em geral, verifique a existência de um arquivo apenas se o arquivo não for usado diretamente, por exemplo, quando sua existência for um sinal de outro processo.

fs.fchmod(fd, mode, callback)

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com o ID DEP0013.
v0.4.7	Adicionado em: v0.4.7

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

Define as permissões no arquivo. Nenhum argumento além de uma possível exceção é dado ao callback de conclusão.

Veja a documentação POSIX fchmod(2) para mais detalhes.

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com o ID DEP0013.
v0.4.7	Adicionado em: v0.4.7

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

Define o proprietário do arquivo. Nenhum argumento além de uma possível exceção é dado ao callback de conclusão.

Veja a documentação POSIX fchown(2) para mais detalhes.

fs.fdatasync(fd, callback)

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com o id DEP0013.
v0.1.96	Adicionado em: v0.1.96

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

Força todas as operações de I/O atualmente enfileiradas associadas ao arquivo para o estado de conclusão de I/O sincronizado do sistema operacional. Consulte a documentação POSIX fdatasync(2) para obter detalhes. Nenhum argumento além de uma possível exceção é dado ao callback de conclusão.

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v10.5.0	Aceita um objeto options adicional para especificar se os valores numéricos retornados devem ser bigint.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com o id DEP0013.
v0.1.95	Adicionado em: v0.1.95

• fd <integer>
• options <Object>
  • bigint <boolean> Se os valores numéricos no objeto <fs.Stats> retornado devem ser bigint. Padrão: false.
• callback <Function>
  • err <Error>
  • stats <fs.Stats>

Invoca o callback com o <fs.Stats> para o descritor de arquivo.

Consulte a documentação POSIX fstat(2) para obter mais detalhes.

fs.fsync(fd, callback)

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com o id DEP0013.
v0.1.96	Adicionado em: v0.1.96

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

Solicita que todos os dados do descritor de arquivo aberto sejam descarregados para o dispositivo de armazenamento. A implementação específica é específica do sistema operacional e do dispositivo. Consulte a documentação POSIX fsync(2) para mais detalhes. Nenhum argumento além de uma possível exceção é dado ao callback de conclusão.

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com o id DEP0013.
v0.8.6	Adicionado em: v0.8.6

• fd <integer>
• len <integer> Padrão: 0
• callback <Function>
  • err <Error>

Trunca o descritor de arquivo. Nenhum argumento além de uma possível exceção é dado ao callback de conclusão.

Consulte a documentação POSIX ftruncate(2) para mais detalhes.

Se o arquivo referenciado pelo descritor de arquivo for maior que len bytes, apenas os primeiros len bytes serão retidos no arquivo.

Por exemplo, o seguinte programa retém apenas os primeiros quatro bytes do arquivo:

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
  }
})

Se o arquivo era anteriormente menor que len bytes, ele é estendido, e a parte estendida é preenchida com bytes nulos ('\0'):

Se len for negativo, então 0 será usado.

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com id DEP0013.
v4.1.0	Strings numéricas, NaN e Infinity agora são permitidos como especificadores de tempo.
v0.4.2	Adicionado em: v0.4.2

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

Altera os carimbos de data/hora do sistema de arquivos do objeto referenciado pelo descritor de arquivo fornecido. Consulte fs.utimes().

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

[Histórico]

Versão	Mudanças
v22.2.0	Adiciona suporte para withFileTypes como uma opção.
v22.0.0	Adicionado em: v22.0.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• pattern <string> | <string[]>

• options <Object>

  • cwd <string> diretório de trabalho atual. Padrão: process.cwd()
  • exclude <Function> Função para filtrar arquivos/diretórios. Retorna true para excluir o item, false para incluí-lo. Padrão: undefined.
  • withFileTypes <boolean> true se o glob deve retornar caminhos como Dirents, false caso contrário. Padrão: false.

• callback <Function>

  • err <Error>

• Recupera os arquivos que correspondem ao padrão 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)

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v16.0.0	O erro retornado pode ser um AggregateError se mais de um erro for retornado.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com o id DEP0013.
v0.4.7	Obsoleto desde: v0.4.7

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

Altera as permissões em um link simbólico. Nenhum argumento além de uma possível exceção é dado ao callback de conclusão.

Este método é implementado apenas no macOS.

Consulte a documentação POSIX lchmod(2) para obter mais detalhes.

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v10.6.0	Esta API não está mais obsoleta.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com o id DEP0013.
v0.4.7	Depreciação apenas na documentação.

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

Define o proprietário do link simbólico. Nenhum argumento além de uma possível exceção é dado ao callback de conclusão.

Consulte a documentação POSIX lchown(2) para obter mais detalhes.

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v14.5.0, v12.19.0	Adicionado em: v14.5.0, v12.19.0

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

Altera os tempos de acesso e modificação de um arquivo da mesma forma que fs.utimes(), com a diferença de que se o caminho se referir a um link simbólico, então o link não é desreferenciado: em vez disso, os timestamps do próprio link simbólico são alterados.

Nenhum argumento além de uma possível exceção é dado ao callback de conclusão.

fs.link(existingPath, newPath, callback)

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.6.0	Os parâmetros existingPath e newPath podem ser objetos WHATWG URL usando o protocolo file:. O suporte ainda é experimental atualmente.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com o id DEP0013.
v0.1.31	Adicionado em: v0.1.31

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

Cria um novo link de existingPath para newPath. Veja a documentação POSIX link(2) para mais detalhes. Nenhum argumento além de uma possível exceção é dado ao callback de conclusão.

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v10.5.0	Aceita um objeto options adicional para especificar se os valores numéricos retornados devem ser bigint.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.6.0	O parâmetro path pode ser um objeto WHATWG URL usando o protocolo file:.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com id DEP0013.
v0.1.30	Adicionado em: v0.1.30

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

• options <Object>

  • bigint <boolean> Indica se os valores numéricos no objeto <fs.Stats> retornado devem ser bigint. Padrão: false.

• callback <Function>

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

Recupera o <fs.Stats> para o link simbólico referido pelo caminho. O callback recebe dois argumentos (err, stats) onde stats é um objeto <fs.Stats>. lstat() é idêntico a stat(), exceto que, se path for um link simbólico, então o próprio link é stat-ed, não o arquivo ao qual ele se refere.

Consulte a documentação POSIX lstat(2) para obter mais detalhes.

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v13.11.0, v12.17.0	No modo recursive, o callback agora recebe o primeiro caminho criado como um argumento.
v10.12.0	O segundo argumento agora pode ser um objeto options com propriedades recursive e mode.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.6.0	O parâmetro path pode ser um objeto URL WHATWG usando o protocolo file:.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com id DEP0013.
v0.1.8	Adicionado em: v0.1.8

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

• options <Object> | <integer>

  • recursive <boolean> Padrão: false
  • mode <string> | <integer> Não suportado no Windows. Padrão: 0o777.

• callback <Function>

  • err <Error>
  • path <string> | <undefined> Presente apenas se um diretório for criado com recursive definido como true.

Cria um diretório de forma assíncrona.

O callback recebe uma possível exceção e, se recursive for true, o primeiro caminho de diretório criado, (err[, path]). path ainda pode ser undefined quando recursive é true, se nenhum diretório foi criado (por exemplo, se ele foi criado anteriormente).

O argumento opcional options pode ser um inteiro especificando mode (permissão e bits sticky), ou um objeto com uma propriedade mode e uma propriedade recursive indicando se os diretórios pai devem ser criados. Chamar fs.mkdir() quando path é um diretório que existe resulta em um erro apenas quando recursive é falso. Se recursive é falso e o diretório existe, ocorre um erro EEXIST.

import { mkdir } from 'node:fs'

// Cria ./tmp/a/apple, independentemente se ./tmp e ./tmp/a existem.
mkdir('./tmp/a/apple', { recursive: true }, err => {
  if (err) throw err
})

No Windows, usar fs.mkdir() no diretório raiz, mesmo com recursão, resultará em um erro:

import { mkdir } from 'node:fs'

mkdir('/', { recursive: true }, err => {
  // => [Error: EPERM: operação não permitida, mkdir 'C:\']
})

Consulte a documentação POSIX mkdir(2) para obter mais detalhes.

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

[Histórico]

Versão	Mudanças
v20.6.0, v18.19.0	O parâmetro prefix agora aceita buffers e URL.
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v16.5.0, v14.18.0	O parâmetro prefix agora aceita uma string vazia.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com o id DEP0013.
v6.2.1	O parâmetro callback agora é opcional.
v5.10.0	Adicionado em: v5.10.0

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

• options <string> | <Object>

  • encoding <string> Padrão: 'utf8'

• callback <Function>

  • err <Error>
  • directory <string>

Cria um diretório temporário único.

Gera seis caracteres aleatórios para serem anexados atrás de um prefix obrigatório para criar um diretório temporário único. Devido a inconsistências da plataforma, evite caracteres X finais em prefix. Algumas plataformas, notavelmente os BSDs, podem retornar mais de seis caracteres aleatórios e substituir os caracteres X finais em prefix por caracteres aleatórios.

O caminho do diretório criado é passado como uma string para o segundo parâmetro do callback.

O argumento opcional options pode ser uma string especificando uma codificação ou um objeto com uma propriedade encoding especificando a codificação de caracteres a ser usada.

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 ou C:\Users\...\AppData\Local\Temp\foo-itXde2
})

O método fs.mkdtemp() anexará os seis caracteres selecionados aleatoriamente diretamente à string prefix. Por exemplo, dado um diretório /tmp, se a intenção é criar um diretório temporário dentro de /tmp, o prefix deve terminar com um separador de caminho específico da plataforma (require('node:path').sep).

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

// O diretório pai para o novo diretório temporário
const tmpDir = tmpdir()

// Este método está *INCORRETO*:
mkdtemp(tmpDir, (err, directory) => {
  if (err) throw err
  console.log(directory)
  // Imprimirá algo semelhante a `/tmpabc123`.
  // Um novo diretório temporário é criado na raiz do sistema de arquivos
  // em vez de *dentro* do diretório /tmp.
})

// Este método está *CORRETO*:
import { sep } from 'node:path'
mkdtemp(`${tmpDir}${sep}`, (err, directory) => {
  if (err) throw err
  console.log(directory)
  // Imprimirá algo semelhante a `/tmp/abc123`.
  // Um novo diretório temporário é criado dentro
  // do diretório /tmp.
})

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v11.1.0	O argumento flags agora é opcional e o padrão é 'r'.
v9.9.0	Os flags as e as+ agora são suportados.
v7.6.0	O parâmetro path pode ser um objeto URL WHATWG usando o protocolo file:.
v0.0.2	Adicionado em: v0.0.2

• path <string> | <Buffer> | <URL>
• flags <string> | <number> Consulte suporte de flags do sistema de arquivos. Padrão: 'r'.
• mode <string> | <integer> Padrão: 0o666 (legível e gravável)
• callback <Function>
  • err <Error>
  • fd <integer>

Abertura de arquivo assíncrona. Consulte a documentação POSIX open(2) para obter mais detalhes.

mode define o modo do arquivo (permissão e bits sticky), mas apenas se o arquivo foi criado. No Windows, apenas a permissão de gravação pode ser manipulada; consulte fs.chmod().

O callback recebe dois argumentos (err, fd).

Alguns caracteres (\< \> : " / \ | ? *) são reservados no Windows, conforme documentado em Nomenclatura de Arquivos, Caminhos e Namespaces. No NTFS, se o nome do arquivo contiver dois pontos, o Node.js abrirá um fluxo do sistema de arquivos, conforme descrito por esta página da MSDN.

As funções baseadas em fs.open() também exibem esse comportamento: fs.writeFile(), fs.readFile(), etc.

fs.openAsBlob(path[, options])

Adicionado em: v19.8.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

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

• options <Object>

  • type <string> Um tipo mime opcional para o blob.

• Retorna: <Promise> Cumpre com um <Blob> em caso de sucesso.

Retorna um <Blob> cujos dados são suportados pelo arquivo fornecido.

O arquivo não deve ser modificado após a criação do <Blob>. Quaisquer modificações farão com que a leitura dos dados do <Blob> falhe com um erro DOMException. Operações síncronas de stat no arquivo quando o Blob é criado e antes de cada leitura para detectar se os dados do arquivo foram modificados no disco.

ESM

import { openAsBlob } from 'node:fs'

const blob = await openAsBlob('o.arquivo.txt')
const ab = await blob.arrayBuffer()
blob.stream()

CJS

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

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

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

[Histórico]

Versão	Mudanças
v20.1.0, v18.17.0	Adicionada a opção recursive.
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v13.1.0, v12.16.0	A opção bufferSize foi introduzida.
v12.12.0	Adicionado em: v12.12.0

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

• options <Object>

  • encoding <string> | <null> Padrão: 'utf8'
  • bufferSize <number> Número de entradas de diretório que são armazenadas em buffer internamente ao ler do diretório. Valores mais altos levam a um melhor desempenho, mas maior uso de memória. Padrão: 32
  • recursive <boolean> Padrão: false

• callback <Function>

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

Abre um diretório de forma assíncrona. Consulte a documentação POSIX opendir(3) para mais detalhes.

Cria um <fs.Dir>, que contém todas as outras funções para ler e limpar o diretório.

A opção encoding define a codificação para o path ao abrir o diretório e operações de leitura subsequentes.

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v10.10.0	O parâmetro buffer agora pode ser qualquer TypedArray ou um DataView.
v7.4.0	O parâmetro buffer agora pode ser um Uint8Array.
v6.0.0	O parâmetro length agora pode ser 0.
v0.0.2	Adicionado em: v0.0.2

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView> O buffer no qual os dados serão gravados.
• offset <integer> A posição em buffer para escrever os dados.
• length <integer> O número de bytes a serem lidos.
• position <integer> | <bigint> | <null> Especifica onde começar a leitura no arquivo. Se position for null ou -1, os dados serão lidos a partir da posição atual do arquivo e a posição do arquivo será atualizada. Se position for um inteiro não negativo, a posição do arquivo permanecerá inalterada.
• callback <Function>
  • err <Error>
  • bytesRead <integer>
  • buffer <Buffer>

Lê dados do arquivo especificado por fd.

O callback recebe três argumentos, (err, bytesRead, buffer).

Se o arquivo não for modificado simultaneamente, o final do arquivo será atingido quando o número de bytes lidos for zero.

Se este método for invocado como sua versão util.promisify()ed, ele retornará uma promise para um Object com as propriedades bytesRead e buffer.

O método fs.read() lê dados do arquivo especificado pelo descritor de arquivo (fd). O argumento length indica o número máximo de bytes que o Node.js tentará ler do kernel. No entanto, o número real de bytes lidos (bytesRead) pode ser menor do que o length especificado por vários motivos.

Por exemplo:

• Se o arquivo for menor que o length especificado, bytesRead será definido como o número real de bytes lidos.
• Se o arquivo encontrar EOF (Fim do Arquivo) antes que o buffer possa ser preenchido, o Node.js lerá todos os bytes disponíveis até que EOF seja encontrado, e o parâmetro bytesRead no callback indicará o número real de bytes lidos, que pode ser menor que o length especificado.
• Se o arquivo estiver em um sistema de arquivos de rede lenta ou encontrar qualquer outro problema durante a leitura, bytesRead poderá ser menor que o length especificado.

Portanto, ao usar fs.read(), é importante verificar o valor de bytesRead para determinar quantos bytes foram realmente lidos do arquivo. Dependendo da lógica da sua aplicação, você pode precisar lidar com casos em que bytesRead é menor que o length especificado, como encapsulando a chamada de leitura em um loop se você exigir uma quantidade mínima de bytes.

Este comportamento é semelhante à função POSIX preadv2.

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

[Histórico]

Versão	Mudanças
v13.11.0, v12.17.0	O objeto de opções pode ser passado para tornar buffer, offset, length e position opcionais.
v13.11.0, v12.17.0	Adicionado em: v13.11.0, v12.17.0

• fd <integer>

• options <Object>

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

• callback <Function>

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

Semelhante à função fs.read(), esta versão recebe um objeto options opcional. Se nenhum objeto options for especificado, ele usará os valores acima como padrão.

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

Adicionado em: v18.2.0, v16.17.0

• fd <integer>

• buffer <Buffer> | <TypedArray> | <DataView> O buffer no qual os dados serão escritos.

• options <Object>

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

• callback <Function>

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

Semelhante à função fs.read(), esta versão aceita um objeto options opcional. Se nenhum objeto options for especificado, ele usará os valores acima por padrão.

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

[Histórico]

Versão	Mudanças
v20.1.0, v18.17.0	Adicionada a opção recursive.
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v10.10.0	Nova opção withFileTypes foi adicionada.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.6.0	O parâmetro path pode ser um objeto WHATWG URL usando o protocolo file:.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com id DEP0013.
v6.0.0	O parâmetro options foi adicionado.
v0.1.8	Adicionado em: v0.1.8

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

• options <string> | <Object>

  • encoding <string> Padrão: 'utf8'
  • withFileTypes <boolean> Padrão: false
  • recursive <boolean> Se true, lê o conteúdo de um diretório recursivamente. No modo recursivo, ele listará todos os arquivos, subarquivos e diretórios. Padrão: false.

• callback <Function>

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

Lê o conteúdo de um diretório. O callback recebe dois argumentos (err, files) onde files é um array com os nomes dos arquivos no diretório, excluindo '.' e '..'.

Veja a documentação POSIX readdir(3) para mais detalhes.

O argumento opcional options pode ser uma string especificando uma codificação, ou um objeto com uma propriedade encoding especificando a codificação de caractere a ser usada para os nomes de arquivo passados para o callback. Se encoding estiver definido como 'buffer', os nomes de arquivo retornados serão passados como objetos <Buffer>.

Se options.withFileTypes estiver definido como true, o array files conterá objetos <fs.Dirent>.

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v16.0.0	O erro retornado pode ser um AggregateError se mais de um erro for retornado.
v15.2.0, v14.17.0	O argumento options pode incluir um AbortSignal para abortar uma solicitação readFile em andamento.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.6.0	O parâmetro path pode ser um objeto URL WHATWG usando o protocolo file:.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com o id DEP0013.
v5.1.0	O callback sempre será chamado com null como o parâmetro error em caso de sucesso.
v5.0.0	O parâmetro path agora pode ser um descritor de arquivo.
v0.1.29	Adicionado em: v0.1.29

• path <string> | <Buffer> | <URL> | <integer> nome do arquivo ou descritor de arquivo

• options <Object> | <string>

  • encoding <string> | <null> Padrão: null
  • flag <string> Veja o suporte de flags do sistema de arquivos. Padrão: 'r'.
  • signal <AbortSignal> permite abortar um readFile em andamento

• callback <Function>

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

Lê de forma assíncrona todo o conteúdo de um arquivo.

import { readFile } from 'node:fs'

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

O callback recebe dois argumentos (err, data), onde data é o conteúdo do arquivo.

Se nenhuma codificação for especificada, o buffer bruto será retornado.

Se options for uma string, ela especifica a codificação:

import { readFile } from 'node:fs'

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

Quando o caminho é um diretório, o comportamento de fs.readFile() e fs.readFileSync() é específico da plataforma. No macOS, Linux e Windows, um erro será retornado. No FreeBSD, uma representação do conteúdo do diretório será retornada.

import { readFile } from 'node:fs'

// macOS, Linux e Windows
readFile('<diretório>', (err, data) => {
  // => [Error: EISDIR: operação ilegal em um diretório, read <diretório>]
})

// FreeBSD
readFile('<diretório>', (err, data) => {
  // => null, <data>
})

É possível abortar uma solicitação em andamento usando um AbortSignal. Se uma solicitação for abortada, o callback será chamado com um AbortError:

import { readFile } from 'node:fs'

const controller = new AbortController()
const signal = controller.signal
readFile(fileInfo[0].name, { signal }, (err, buf) => {
  // ...
})
// Quando você quiser abortar a solicitação
controller.abort()

A função fs.readFile() armazena em buffer o arquivo inteiro. Para minimizar os custos de memória, quando possível, prefira o streaming via fs.createReadStream().

Abortar uma solicitação em andamento não aborta solicitações individuais do sistema operacional, mas sim o buffering interno que fs.readFile realiza.

Descritores de Arquivos

Considerações sobre Desempenho

O método fs.readFile() lê de forma assíncrona o conteúdo de um arquivo para a memória um bloco de cada vez, permitindo que o loop de eventos gire entre cada bloco. Isso permite que a operação de leitura tenha menos impacto em outras atividades que possam estar usando o pool de threads libuv subjacente, mas significa que levará mais tempo para ler um arquivo completo para a memória.

A sobrecarga de leitura adicional pode variar amplamente em diferentes sistemas e depende do tipo de arquivo que está sendo lido. Se o tipo de arquivo não for um arquivo regular (um pipe, por exemplo) e o Node.js não conseguir determinar um tamanho de arquivo real, cada operação de leitura carregará 64 KiB de dados. Para arquivos regulares, cada leitura processará 512 KiB de dados.

Para aplicações que exigem a leitura mais rápida possível do conteúdo do arquivo, é melhor usar fs.read() diretamente e para o código da aplicação gerenciar a leitura do conteúdo completo do arquivo.

A issue do Node.js no GitHub #25741 fornece mais informações e uma análise detalhada sobre o desempenho de fs.readFile() para vários tamanhos de arquivo em diferentes versões do Node.js.

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.6.0	O parâmetro path pode ser um objeto WHATWG URL usando o protocolo file:.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com o id DEP0013.
v0.1.31	Adicionado em: v0.1.31

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> Padrão: 'utf8'
• callback <Function>
  • err <Error>
  • linkString <string> | <Buffer>

Lê o conteúdo do link simbólico referido por path. O callback recebe dois argumentos (err, linkString).

Consulte a documentação POSIX readlink(2) para mais detalhes.

O argumento opcional options pode ser uma string especificando uma codificação, ou um objeto com uma propriedade encoding especificando a codificação de caracteres a ser usada para o caminho do link passado para o callback. Se encoding for definido como 'buffer', o caminho do link retornado será passado como um objeto <Buffer>.

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v13.13.0, v12.17.0	Adicionado em: v13.13.0, v12.17.0

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

Leia de um arquivo especificado por fd e escreva em um array de ArrayBufferViews usando readv().

position é o deslocamento do início do arquivo de onde os dados devem ser lidos. Se typeof position !== 'number', os dados serão lidos da posição atual.

O callback receberá três argumentos: err, bytesRead e buffers. bytesRead é quantos bytes foram lidos do arquivo.

Se este método for invocado como sua versão util.promisify()ed, ele retorna uma promessa para um Object com as propriedades bytesRead e buffers.

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v8.0.0	O suporte para resolução de Pipe/Socket foi adicionado.
v7.6.0	O parâmetro path pode ser um objeto WHATWG URL usando o protocolo file:.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com id DEP0013.
v6.4.0	Chamar realpath agora funciona novamente para vários casos extremos no Windows.
v6.0.0	O parâmetro cache foi removido.
v0.1.31	Adicionado em: v0.1.31

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> Padrão: 'utf8'
• callback <Function>
  • err <Error>
  • resolvedPath <string> | <Buffer>

Calcula assincronamente o nome do caminho canônico resolvendo ., .. e links simbólicos.

Um nome de caminho canônico não é necessariamente único. Links rígidos e montagens de ligação podem expor uma entidade do sistema de arquivos por meio de muitos nomes de caminho.

Esta função se comporta como realpath(3), com algumas exceções:

O callback recebe dois argumentos (err, resolvedPath). Pode usar process.cwd para resolver caminhos relativos.

Apenas caminhos que podem ser convertidos em strings UTF8 são suportados.

O argumento opcional options pode ser uma string especificando uma codificação ou um objeto com uma propriedade encoding especificando a codificação de caracteres a ser usada para o caminho passado para o callback. Se o encoding estiver definido como 'buffer', o caminho retornado será passado como um objeto <Buffer>.

Se path resolver para um socket ou um pipe, a função retornará um nome dependente do sistema para esse objeto.

Um caminho que não existe resulta em um erro ENOENT. error.path é o caminho absoluto do arquivo.

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v9.2.0	Adicionado em: v9.2.0

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

• options <string> | <Object>

  • encoding <string> Padrão: 'utf8'

• callback <Function>

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

realpath(3) assíncrono.

O callback recebe dois argumentos (err, resolvedPath).

Apenas caminhos que podem ser convertidos em strings UTF8 são suportados.

O argumento options opcional pode ser uma string especificando uma codificação ou um objeto com uma propriedade encoding especificando a codificação de caracteres a ser usada para o caminho passado para o callback. Se o encoding estiver definido como 'buffer', o caminho retornado será passado como um objeto <Buffer>.

No Linux, quando o Node.js está vinculado ao musl libc, o sistema de arquivos procfs deve ser montado em /proc para que esta função funcione. O Glibc não tem essa restrição.

fs.rename(oldPath, newPath, callback)

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.6.0	Os parâmetros oldPath e newPath podem ser objetos WHATWG URL usando o protocolo file:. O suporte ainda é experimental.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com o id DEP0013.
v0.0.2	Adicionado em: v0.0.2

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

Renomeia de forma assíncrona o arquivo em oldPath para o nome de caminho fornecido como newPath. Caso newPath já exista, ele será sobrescrito. Se houver um diretório em newPath, um erro será gerado. Nenhum argumento além de uma possível exceção é fornecido ao callback de conclusão.

Veja também: rename(2).

import { rename } from 'node:fs'

rename('oldFile.txt', 'newFile.txt', err => {
  if (err) throw err
  console.log('Rename complete!')
})

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v16.0.0	Usar fs.rmdir(path, { recursive: true }) em um path que é um arquivo não é mais permitido e resulta em um erro ENOENT no Windows e um erro ENOTDIR no POSIX.
v16.0.0	Usar fs.rmdir(path, { recursive: true }) em um path que não existe não é mais permitido e resulta em um erro ENOENT.
v16.0.0	A opção recursive está obsoleta, usá-la aciona um aviso de obsolescência.
v14.14.0	A opção recursive está obsoleta, use fs.rm em vez disso.
v13.3.0, v12.16.0	A opção maxBusyTries foi renomeada para maxRetries, e seu padrão é 0. A opção emfileWait foi removida e os erros EMFILE usam a mesma lógica de repetição que outros erros. A opção retryDelay agora é suportada. Erros ENFILE agora são repetidos.
v12.10.0	As opções recursive, maxBusyTries e emfileWait agora são suportadas.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.6.0	Os parâmetros path podem ser um objeto URL WHATWG usando o protocolo file:.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de obsolescência com o id DEP0013.
v0.0.2	Adicionado em: v0.0.2

• path <string> | <Buffer> | <URL>
• options <Object>
  • maxRetries <integer> Se um erro EBUSY, EMFILE, ENFILE, ENOTEMPTY ou EPERM for encontrado, o Node.js repete a operação com uma espera de backoff linear de retryDelay milissegundos a mais em cada tentativa. Esta opção representa o número de tentativas. Esta opção é ignorada se a opção recursive não for true. Padrão: 0.
  • recursive <boolean> Se true, execute uma remoção de diretório recursiva. No modo recursivo, as operações são repetidas em caso de falha. Padrão: false. Obsoleto.
  • retryDelay <integer> A quantidade de tempo em milissegundos para esperar entre as tentativas. Esta opção é ignorada se a opção recursive não for true. Padrão: 100.
• callback <Function>
  • err <Error>

rmdir(2) assíncrono. Nenhum argumento além de uma possível exceção é fornecido ao callback de conclusão.

Usar fs.rmdir() em um arquivo (não em um diretório) resulta em um erro ENOENT no Windows e um erro ENOTDIR no POSIX.

Para obter um comportamento semelhante ao comando Unix rm -rf, use fs.rm() com as opções { recursive: true, force: true }.

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

[Histórico]

Versão	Mudanças
v17.3.0, v16.14.0	O parâmetro path pode ser um objeto WHATWG URL usando o protocolo file:.
v14.14.0	Adicionado em: v14.14.0

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

• options <Object>

  • force <boolean> Quando true, as exceções serão ignoradas se path não existir. Padrão: false.
  • maxRetries <integer> Se um erro EBUSY, EMFILE, ENFILE, ENOTEMPTY ou EPERM for encontrado, o Node.js tentará novamente a operação com uma espera de recuo linear de retryDelay milissegundos mais longa em cada tentativa. Esta opção representa o número de novas tentativas. Esta opção é ignorada se a opção recursive não for true. Padrão: 0.
  • recursive <boolean> Se true, realiza uma remoção recursiva. No modo recursivo, as operações são repetidas em caso de falha. Padrão: false.
  • retryDelay <integer> A quantidade de tempo em milissegundos para esperar entre as tentativas. Esta opção é ignorada se a opção recursive não for true. Padrão: 100.

• callback <Function>

  • err <Error>

Remove de forma assíncrona arquivos e diretórios (modelado no utilitário POSIX rm padrão). Nenhum argumento além de uma possível exceção é dado ao callback de conclusão.

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v10.5.0	Aceita um objeto options adicional para especificar se os valores numéricos retornados devem ser bigint.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.6.0	O parâmetro path pode ser um objeto WHATWG URL usando o protocolo file:.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com o id DEP0013.
v0.0.2	Adicionado em: v0.0.2

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

• options <Object>

  • bigint <boolean> Indica se os valores numéricos no objeto <fs.Stats> retornado devem ser bigint. Padrão: false.

• callback <Function>

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

stat(2) assíncrono. O callback recebe dois argumentos (err, stats) onde stats é um objeto <fs.Stats>.

Em caso de erro, o err.code será um dos Erros Comuns do Sistema.

fs.stat() segue links simbólicos. Use fs.lstat() para olhar para os próprios links.

Não é recomendado usar fs.stat() para verificar a existência de um arquivo antes de chamar fs.open(), fs.readFile() ou fs.writeFile(). Em vez disso, o código do usuário deve abrir/ler/escrever o arquivo diretamente e tratar o erro levantado se o arquivo não estiver disponível.

Para verificar se um arquivo existe sem manipulá-lo posteriormente, recomenda-se fs.access().

Por exemplo, dada a seguinte estrutura de diretório:

- txtDir
-- file.txt
- app.js

O próximo programa irá verificar as estatísticas dos caminhos fornecidos:

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)
  })
}

A saída resultante será semelhante 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)

Adicionado em: v19.6.0, v18.15.0

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

• options <Object>

  • bigint <boolean> Se os valores numéricos no objeto <fs.StatFs> retornado devem ser bigint. Padrão: false.

• callback <Function>

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

Assíncrono statfs(2). Retorna informações sobre o sistema de arquivos montado que contém path. O callback recebe dois argumentos (err, stats) onde stats é um objeto <fs.StatFs>.

Em caso de erro, o err.code será um dos Erros Comuns do Sistema.

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v12.0.0	Se o argumento type for deixado indefinido, o Node irá autodectar o tipo de target e selecionar automaticamente dir ou file.
v7.6.0	Os parâmetros target e path podem ser objetos WHATWG URL usando o protocolo file:. O suporte ainda é experimental.
v0.1.31	Adicionado em: v0.1.31

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

Cria o link chamado path apontando para target. Nenhum argumento além de uma possível exceção é dado ao callback de conclusão.

Consulte a documentação POSIX symlink(2) para mais detalhes.

O argumento type está disponível apenas no Windows e é ignorado em outras plataformas. Ele pode ser definido como 'dir', 'file' ou 'junction'. Se o argumento type for null, o Node.js irá autodectar o tipo de target e usar 'file' ou 'dir'. Se o target não existir, 'file' será usado. Os pontos de junção do Windows exigem que o caminho de destino seja absoluto. Ao usar 'junction', o argumento target será normalizado automaticamente para o caminho absoluto. Os pontos de junção em volumes NTFS só podem apontar para diretórios.

Os alvos relativos são relativos ao diretório pai do link.

import { symlink } from 'node:fs'

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

O exemplo acima cria um link simbólico mewtwo que aponta para mew no mesmo diretório:

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

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v16.0.0	O erro retornado pode ser um AggregateError se mais de um erro for retornado.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com o ID DEP0013.
v0.8.6	Adicionado em: v0.8.6

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

Trunca o arquivo. Nenhum argumento além de uma possível exceção é fornecido ao callback de conclusão. Um descritor de arquivo também pode ser passado como o primeiro argumento. Nesse caso, fs.ftruncate() é chamado.

ESM

import { truncate } from 'node:fs'
// Assumindo que 'path/file.txt' é um arquivo regular.
truncate('path/file.txt', err => {
  if (err) throw err
  console.log('path/file.txt foi truncado')
})

CJS

const { truncate } = require('node:fs')
// Assumindo que 'path/file.txt' é um arquivo regular.
truncate('path/file.txt', err => {
  if (err) throw err
  console.log('path/file.txt foi truncado')
})

Passar um descritor de arquivo é descontinuado e pode resultar em um erro sendo lançado no futuro.

Veja a documentação POSIX truncate(2) para mais detalhes.

fs.unlink(path, callback)

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.6.0	O parâmetro path pode ser um objeto WHATWG URL usando o protocolo file:.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com o ID DEP0013.
v0.0.2	Adicionado em: v0.0.2

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

Remove assincronamente um arquivo ou link simbólico. Nenhum argumento além de uma possível exceção é dado ao callback de conclusão.

import { unlink } from 'node:fs'
// Supondo que 'path/file.txt' seja um arquivo regular.
unlink('path/file.txt', err => {
  if (err) throw err
  console.log('path/file.txt foi deletado')
})

fs.unlink() não funcionará em um diretório, vazio ou não. Para remover um diretório, use fs.rmdir().

Consulte a documentação POSIX unlink(2) para obter mais detalhes.

fs.unwatchFile(filename[, listener])

Adicionado em: v0.1.31

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

Para de observar por mudanças em filename. Se listener for especificado, apenas aquele listener em particular é removido. Caso contrário, todos os listeners são removidos, efetivamente parando a observação de filename.

Chamar fs.unwatchFile() com um nome de arquivo que não está sendo observado é uma operação nula, não um erro.

Usar fs.watch() é mais eficiente do que fs.watchFile() e fs.unwatchFile(). fs.watch() deve ser usado em vez de fs.watchFile() e fs.unwatchFile() quando possível.

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v8.0.0	NaN, Infinity e -Infinity não são mais especificadores de tempo válidos.
v7.6.0	O parâmetro path pode ser um objeto URL WHATWG usando o protocolo file:.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com o id DEP0013.
v4.1.0	Strings numéricas, NaN e Infinity agora são especificadores de tempo permitidos.
v0.4.2	Adicionado em: v0.4.2

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

Altera os timestamps do sistema de arquivos do objeto referenciado por path.

Os argumentos atime e mtime seguem estas regras:

• Os valores podem ser números que representam o tempo Unix epoch em segundos, Dates, ou uma string numérica como '123456789.0'.
• Se o valor não puder ser convertido em um número, ou for NaN, Infinity ou -Infinity, um Error será lançado.

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

[Histórico]

Versão	Mudanças
v19.1.0	Adicionado suporte recursivo para Linux, AIX e IBMi.
v15.9.0, v14.17.0	Adicionado suporte para fechar o observador com um AbortSignal.
v7.6.0	O parâmetro filename pode ser um objeto URL WHATWG usando o protocolo file:.
v7.0.0	O objeto options passado nunca será modificado.
v0.5.10	Adicionado em: v0.5.10

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

• options <string> | <Object>

  • persistent <boolean> Indica se o processo deve continuar em execução enquanto os arquivos estiverem sendo observados. Padrão: true.
  • recursive <boolean> Indica se todos os subdiretórios devem ser observados ou apenas o diretório atual. Isso se aplica quando um diretório é especificado e apenas em plataformas suportadas (consulte ressalvas). Padrão: false.
  • encoding <string> Especifica a codificação de caracteres a ser usada para o nome do arquivo passado para o listener. Padrão: 'utf8'.
  • signal <AbortSignal> permite fechar o observador com um AbortSignal.

• listener <Function> | <undefined> Padrão: undefined

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

• Retorna: <fs.FSWatcher>

Observa alterações em filename, onde filename é um arquivo ou um diretório.

O segundo argumento é opcional. Se options for fornecido como uma string, ele especificará o encoding. Caso contrário, options deve ser passado como um objeto.

O retorno de chamada do listener recebe dois argumentos (eventType, filename). eventType é 'rename' ou 'change', e filename é o nome do arquivo que acionou o evento.

Na maioria das plataformas, 'rename' é emitido sempre que um nome de arquivo aparece ou desaparece no diretório.

O retorno de chamada do listener é anexado ao evento 'change' acionado por <fs.FSWatcher>, mas não é a mesma coisa que o valor 'change' de eventType.

Se um signal for passado, abortar o AbortController correspondente fechará o <fs.FSWatcher> retornado.

Advertências

A API fs.watch não é 100% consistente entre plataformas e não está disponível em algumas situações.

No Windows, nenhum evento será emitido se o diretório observado for movido ou renomeado. Um erro EPERM é relatado quando o diretório observado é excluído.

Disponibilidade

Este recurso depende do sistema operacional subjacente fornecer uma maneira de ser notificado sobre as alterações do sistema de arquivos.

• Em sistemas Linux, isso usa inotify(7).
• Em sistemas BSD, isso usa kqueue(2).
• No macOS, isso usa kqueue(2) para arquivos e FSEvents para diretórios.
• Em sistemas SunOS (incluindo Solaris e SmartOS), isso usa event ports.
• Em sistemas Windows, este recurso depende de ReadDirectoryChangesW.
• Em sistemas AIX, este recurso depende de AHAFS, que deve ser habilitado.
• Em sistemas IBM i, este recurso não é suportado.

Se a funcionalidade subjacente não estiver disponível por algum motivo, então fs.watch() não poderá funcionar e poderá lançar uma exceção. Por exemplo, observar arquivos ou diretórios pode não ser confiável e, em alguns casos, impossível, em sistemas de arquivos de rede (NFS, SMB, etc) ou sistemas de arquivos de host ao usar softwares de virtualização como Vagrant ou Docker.

Ainda é possível usar fs.watchFile(), que usa polling stat, mas este método é mais lento e menos confiável.

Inodes

Em sistemas Linux e macOS, fs.watch() resolve o caminho para um inode e observa o inode. Se o caminho observado for excluído e recriado, ele será atribuído a um novo inode. O observador emitirá um evento para a exclusão, mas continuará observando o inode original. Os eventos para o novo inode não serão emitidos. Este é o comportamento esperado.

Arquivos AIX retêm o mesmo inode durante toda a vida útil de um arquivo. Salvar e fechar um arquivo observado no AIX resultará em duas notificações (uma para adicionar novo conteúdo e outra para truncamento).

Argumento filename

Fornecer o argumento filename no callback só é suportado em Linux, macOS, Windows e AIX. Mesmo em plataformas suportadas, não há garantia de que filename seja sempre fornecido. Portanto, não assuma que o argumento filename é sempre fornecido no callback e tenha alguma lógica de fallback caso seja null.

import { watch } from 'node:fs'
watch('somedir', (eventType, filename) => {
  console.log(`o tipo de evento é: ${eventType}`)
  if (filename) {
    console.log(`filename fornecido: ${filename}`)
  } else {
    console.log('filename não fornecido')
  }
})

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

[Histórico]

Versão	Mudanças
v10.5.0	A opção bigint agora é suportada.
v7.6.0	O parâmetro filename pode ser um objeto WHATWG URL usando o protocolo file:.
v0.1.31	Adicionado em: v0.1.31

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

• options <Object>

  • bigint <boolean> Padrão: false
  • persistent <boolean> Padrão: true
  • interval <integer> Padrão: 5007

• listener <Function>

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

• Retorna: <fs.StatWatcher>

Monitora as mudanças em filename. O callback listener será chamado cada vez que o arquivo for acessado.

O argumento options pode ser omitido. Se fornecido, deve ser um objeto. O objeto options pode conter um booleano chamado persistent que indica se o processo deve continuar em execução enquanto os arquivos estão sendo monitorados. O objeto options pode especificar uma propriedade interval indicando com que frequência o alvo deve ser sondado em milissegundos.

O listener recebe dois argumentos: o objeto de estatísticas atual e o objeto de estatísticas anterior:

import { watchFile } from 'node:fs'

watchFile('message.text', (curr, prev) => {
  console.log(`o mtime atual é: ${curr.mtime}`)
  console.log(`o mtime anterior era: ${prev.mtime}`)
})

Esses objetos de estatísticas são instâncias de fs.Stat. Se a opção bigint for true, os valores numéricos nesses objetos são especificados como BigInts.

Para ser notificado quando o arquivo foi modificado, e não apenas acessado, é necessário comparar curr.mtimeMs e prev.mtimeMs.

Quando uma operação fs.watchFile resulta em um erro ENOENT, ele invocará o listener uma vez, com todos os campos zerados (ou, para datas, a Época Unix). Se o arquivo for criado posteriormente, o listener será chamado novamente, com os objetos de estatísticas mais recentes. Esta é uma mudança na funcionalidade desde a v0.10.

Usar fs.watch() é mais eficiente do que fs.watchFile e fs.unwatchFile. fs.watch deve ser usado em vez de fs.watchFile e fs.unwatchFile quando possível.

Quando um arquivo sendo monitorado por fs.watchFile() desaparece e reaparece, então o conteúdo de previous no segundo evento de callback (o reaparecimento do arquivo) será o mesmo que o conteúdo de previous no primeiro evento de callback (seu desaparecimento).

Isso acontece quando:

• o arquivo é excluído, seguido por uma restauração
• o arquivo é renomeado e depois renomeado uma segunda vez de volta para seu nome original

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v14.0.0	O parâmetro buffer não forçará mais entradas não suportadas para strings.
v10.10.0	O parâmetro buffer agora pode ser qualquer TypedArray ou um DataView.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.4.0	O parâmetro buffer agora pode ser um Uint8Array.
v7.2.0	Os parâmetros offset e length agora são opcionais.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com o ID DEP0013.
v0.0.2	Adicionado em: v0.0.2

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

Escreve o buffer no arquivo especificado por fd.

offset determina a parte do buffer a ser escrita e length é um número inteiro que especifica o número de bytes a serem escritos.

position refere-se ao deslocamento desde o início do arquivo onde esses dados devem ser escritos. Se typeof position !== 'number', os dados serão escritos na posição atual. Veja pwrite(2).

O callback receberá três argumentos (err, bytesWritten, buffer) onde bytesWritten especifica quantos bytes foram escritos do buffer.

Se este método for invocado como sua versão util.promisify()ed, ele retornará uma promessa para um Object com propriedades bytesWritten e buffer.

Não é seguro usar fs.write() várias vezes no mesmo arquivo sem esperar pelo callback. Para este cenário, o fs.createWriteStream() é recomendado.

No Linux, as escritas posicionais não funcionam quando o arquivo é aberto no modo de acréscimo. O kernel ignora o argumento de posição e sempre adiciona os dados ao final do arquivo.

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

Adicionado em: v18.3.0, v16.17.0

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

Escreve o buffer no arquivo especificado por fd.

Semelhante à função fs.write acima, esta versão aceita um objeto options opcional. Se nenhum objeto options for especificado, ele usará os valores acima por padrão.

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

[Histórico]

Versão	Mudanças
v19.0.0	Passar um objeto com sua própria função toString para o parâmetro string não é mais suportado.
v17.8.0	Passar um objeto com sua própria função toString para o parâmetro string está obsoleto.
v14.12.0	O parâmetro string converterá um objeto com uma função toString explícita.
v14.0.0	O parâmetro string não irá mais forçar a entrada não suportada para strings.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.2.0	O parâmetro position agora é opcional.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com o id DEP0013.
v0.11.5	Adicionado em: v0.11.5

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

Escreve string no arquivo especificado por fd. Se string não for uma string, uma exceção será lançada.

position refere-se ao deslocamento desde o início do arquivo onde esses dados devem ser escritos. Se typeof position !== 'number', os dados serão gravados na posição atual. Veja pwrite(2).

encoding é a codificação de string esperada.

O callback receberá os argumentos (err, written, string), onde written especifica quantos bytes a string passada precisou para ser escrita. Os bytes escritos não são necessariamente os mesmos que os caracteres de string escritos. Veja Buffer.byteLength.

Não é seguro usar fs.write() várias vezes no mesmo arquivo sem esperar pelo callback. Para este cenário, fs.createWriteStream() é recomendado.

No Linux, as gravações posicionais não funcionam quando o arquivo é aberto no modo de anexação. O kernel ignora o argumento da posição e sempre anexa os dados ao final do arquivo.

No Windows, se o descritor de arquivo estiver conectado ao console (por exemplo, fd == 1 ou stdout), uma string contendo caracteres não ASCII não será renderizada corretamente por padrão, independentemente da codificação usada. É possível configurar o console para renderizar UTF-8 corretamente alterando a página de código ativa com o comando chcp 65001. Consulte a documentação chcp para obter mais detalhes.

fs.writeFile(file, data[, options], callback)

[Histórico]

Versão	Mudanças
v21.0.0, v20.10.0	A opção flush agora é suportada.
v19.0.0	Passar para o parâmetro string um objeto com sua própria função toString não é mais suportado.
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v17.8.0	Passar para o parâmetro string um objeto com sua própria função toString está obsoleto.
v16.0.0	O erro retornado pode ser um AggregateError se mais de um erro for retornado.
v15.2.0, v14.17.0	O argumento options pode incluir um AbortSignal para abortar uma solicitação writeFile em andamento.
v14.12.0	O parâmetro data irá stringificar um objeto com uma função toString explícita.
v14.0.0	O parâmetro data não forçará mais a entrada não suportada para strings.
v10.10.0	O parâmetro data agora pode ser qualquer TypedArray ou DataView.
v10.0.0	O parâmetro callback não é mais opcional. Não passá-lo lançará um TypeError em tempo de execução.
v7.4.0	O parâmetro data agora pode ser um Uint8Array.
v7.0.0	O parâmetro callback não é mais opcional. Não passá-lo emitirá um aviso de depreciação com id DEP0013.
v5.0.0	O parâmetro file agora pode ser um descritor de arquivo.
v0.1.29	Adicionado em: v0.1.29

• file <string> | <Buffer> | <URL> | <integer> nome do arquivo ou descritor de arquivo

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

• options <Object> | <string>

  • encoding <string> | <null> Padrão: 'utf8'
  • mode <integer> Padrão: 0o666
  • flag <string> Veja suporte a flags do sistema de arquivos. Padrão: 'w'.
  • flush <boolean> Se todos os dados forem gravados com sucesso no arquivo e flush for true, fs.fsync() é usado para liberar os dados. Padrão: false.
  • signal <AbortSignal> permite abortar um writeFile em andamento

• callback <Function>

  • err <Error> | <AggregateError>

Quando file é um nome de arquivo, grava dados de forma assíncrona no arquivo, substituindo o arquivo se ele já existir. data pode ser uma string ou um buffer.

Quando file é um descritor de arquivo, o comportamento é semelhante a chamar fs.write() diretamente (o que é recomendado). Veja as notas abaixo sobre como usar um descritor de arquivo.

A opção encoding é ignorada se data for um buffer.

A opção mode afeta apenas o arquivo recém-criado. Veja fs.open() para mais detalhes.

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

const data = new Uint8Array(Buffer.from('Olá Node.js'))
writeFile('message.txt', data, err => {
  if (err) throw err
  console.log('O arquivo foi salvo!')
})

Se options for uma string, especifica a codificação:

import { writeFile } from 'node:fs'

writeFile('message.txt', 'Olá Node.js', 'utf8', callback)

Não é seguro usar fs.writeFile() várias vezes no mesmo arquivo sem esperar pelo callback. Para esse cenário, fs.createWriteStream() é recomendado.

Semelhante a fs.readFile - fs.writeFile é um método de conveniência que executa várias chamadas write internamente para gravar o buffer passado para ele. Para códigos sensíveis ao desempenho, considere usar fs.createWriteStream().

É possível usar um <AbortSignal> para cancelar um fs.writeFile(). O cancelamento é "o melhor possível" e é provável que alguma quantidade de dados ainda seja gravada.

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

const controller = new AbortController()
const { signal } = controller
const data = new Uint8Array(Buffer.from('Olá Node.js'))
writeFile('message.txt', data, { signal }, err => {
  // Quando uma solicitação é abortada - o callback é chamado com um AbortError
})
// Quando a solicitação deve ser abortada
controller.abort()

Abortar uma solicitação em andamento não aborta as solicitações individuais do sistema operacional, mas sim o buffer interno que o fs.writeFile realiza.

Usando fs.writeFile() com descritores de arquivo

Quando file é um descritor de arquivo, o comportamento é quase idêntico a chamar diretamente fs.write() como:

import { write } from 'node:fs'
import { Buffer } from 'node:buffer'

write(fd, Buffer.from(data, options.encoding), callback)

A diferença de chamar diretamente fs.write() é que, sob algumas condições incomuns, fs.write() pode escrever apenas parte do buffer e precisar ser repetido para escrever os dados restantes, enquanto fs.writeFile() repete até que os dados sejam totalmente escritos (ou ocorra um erro).

As implicações disso são uma fonte comum de confusão. No caso do descritor de arquivo, o arquivo não é substituído! Os dados não são necessariamente escritos no início do arquivo, e os dados originais do arquivo podem permanecer antes e/ou depois dos dados recém-escritos.

Por exemplo, se fs.writeFile() for chamado duas vezes seguidas, primeiro para escrever a string 'Olá', depois para escrever a string ', Mundo', o arquivo conteria 'Olá, Mundo', e pode conter alguns dos dados originais do arquivo (dependendo do tamanho do arquivo original e da posição do descritor de arquivo). Se um nome de arquivo fosse usado em vez de um descritor, seria garantido que o arquivo conteria apenas ', Mundo'.

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

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v12.9.0	Adicionado em: v12.9.0

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer> | <null> Padrão: null
• callback <Function>
  • err <Error>
  • bytesWritten <integer>
  • buffers <ArrayBufferView[]>

Escreva um array de ArrayBufferViews no arquivo especificado por fd usando writev().

position é o deslocamento do início do arquivo onde esses dados devem ser escritos. Se typeof position !== 'number', os dados serão escritos na posição atual.

O callback receberá três argumentos: err, bytesWritten e buffers. bytesWritten é quantos bytes foram escritos de buffers.

Se este método for util.promisify()ed, ele retornará uma promessa para um Object com propriedades bytesWritten e buffers.

É inseguro usar fs.writev() várias vezes no mesmo arquivo sem esperar pelo callback. Para este cenário, use fs.createWriteStream().

No Linux, as escritas posicionais não funcionam quando o arquivo é aberto no modo de anexação. O kernel ignora o argumento de posição e sempre anexa os dados ao final do arquivo.

API Síncrona

As APIs síncronas executam todas as operações de forma síncrona, bloqueando o loop de eventos até que a operação seja concluída ou falhe.

fs.accessSync(path[, mode])

[Histórico]

Versão	Alterações
v7.6.0	O parâmetro path pode ser um objeto URL WHATWG usando o protocolo file:.
v0.11.15	Adicionado em: v0.11.15

• path <string> | <Buffer> | <URL>
• mode <integer> Padrão: fs.constants.F_OK

Testa de forma síncrona as permissões de um usuário para o arquivo ou diretório especificado por path. O argumento mode é um inteiro opcional que especifica as verificações de acessibilidade a serem executadas. mode deve ser o valor fs.constants.F_OK ou uma máscara consistindo no OR bit a bit de qualquer um de fs.constants.R_OK, fs.constants.W_OK e fs.constants.X_OK (por exemplo, fs.constants.W_OK | fs.constants.R_OK). Verifique Constantes de acesso a arquivos para obter os valores possíveis de mode.

Se alguma das verificações de acessibilidade falhar, um Error será lançado. Caso contrário, o método retornará undefined.

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

try {
  accessSync('etc/passwd', constants.R_OK | constants.W_OK)
  console.log('pode ler/escrever')
} catch (err) {
  console.error('sem acesso!')
}

fs.appendFileSync(path, data[, options])

[Histórico]

Versão	Alterações
v21.1.0, v20.10.0	A opção flush agora é suportada.
v7.0.0	O objeto options passado nunca será modificado.
v5.0.0	O parâmetro file pode ser um descritor de arquivo agora.
v0.6.7	Adicionado em: v0.6.7

• path <string> | <Buffer> | <URL> | <number> nome do arquivo ou descritor de arquivo
• data <string> | <Buffer>
• options <Object> | <string>
  • encoding <string> | <null> Padrão: 'utf8'
  • mode <integer> Padrão: 0o666
  • flag <string> Veja suporte para flags do sistema de arquivos. Padrão: 'a'.
  • flush <boolean> Se true, o descritor de arquivo subjacente é liberado antes de ser fechado. Padrão: false.

Adiciona dados de forma síncrona a um arquivo, criando o arquivo se ele ainda não existir. data pode ser uma string ou um <Buffer>.

A opção mode afeta apenas o arquivo recém-criado. Consulte fs.open() para obter mais detalhes.

import { appendFileSync } from 'node:fs'

try {
  appendFileSync('message.txt', 'dados para adicionar')
  console.log('Os "dados para adicionar" foram adicionados ao arquivo!')
} catch (err) {
  /* Manipule o erro */
}

Se options for uma string, então ela especifica a codificação:

import { appendFileSync } from 'node:fs'

appendFileSync('message.txt', 'dados para adicionar', 'utf8')

O path pode ser especificado como um descritor de arquivo numérico que foi aberto para adição (usando fs.open() ou fs.openSync()). O descritor de arquivo não será fechado automaticamente.

import { openSync, closeSync, appendFileSync } from 'node:fs'

let fd

try {
  fd = openSync('message.txt', 'a')
  appendFileSync(fd, 'dados para adicionar', 'utf8')
} catch (err) {
  /* Manipule o erro */
} finally {
  if (fd !== undefined) closeSync(fd)
}

fs.chmodSync(path, mode)

[Histórico]

Versão	Mudanças
v7.6.0	O parâmetro path pode ser um objeto URL WHATWG usando o protocolo file:.
v0.6.7	Adicionado em: v0.6.7

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

Para obter informações detalhadas, consulte a documentação da versão assíncrona desta API: fs.chmod().

Consulte a documentação POSIX chmod(2) para obter mais detalhes.

fs.chownSync(path, uid, gid)

[Histórico]

Versão	Mudanças
v7.6.0	O parâmetro path pode ser um objeto URL WHATWG usando o protocolo file:.
v0.1.97	Adicionado em: v0.1.97

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>

Altera de forma síncrona o proprietário e o grupo de um arquivo. Retorna undefined. Esta é a versão síncrona de fs.chown().

Consulte a documentação POSIX chown(2) para obter mais detalhes.

fs.closeSync(fd)

Adicionado em: v0.1.21

• fd <integer>

Fecha o descritor de arquivo. Retorna undefined.

Chamar fs.closeSync() em qualquer descritor de arquivo (fd) que esteja atualmente em uso por meio de qualquer outra operação fs pode levar a um comportamento indefinido.

Consulte a documentação POSIX close(2) para obter mais detalhes.

fs.copyFileSync(src, dest[, mode])

[Histórico]

Versão	Mudanças
v14.0.0	Alterado o argumento flags para mode e imposta validação de tipo mais restrita.
v8.5.0	Adicionado em: v8.5.0

• src <string> | <Buffer> | <URL> nome do arquivo de origem a ser copiado
• dest <string> | <Buffer> | <URL> nome do arquivo de destino da operação de cópia
• mode <integer> modificadores para operação de cópia. Padrão: 0.

Copia de forma síncrona src para dest. Por padrão, dest é sobrescrito se já existir. Retorna undefined. O Node.js não garante a atomicidade da operação de cópia. Se ocorrer um erro depois que o arquivo de destino for aberto para gravação, o Node.js tentará remover o destino.

mode é um inteiro opcional que especifica o comportamento da operação de cópia. É possível criar uma máscara composta pelo OR bit a bit de dois ou mais valores (por exemplo, fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE).

• fs.constants.COPYFILE_EXCL: A operação de cópia falhará se dest já existir.
• fs.constants.COPYFILE_FICLONE: A operação de cópia tentará criar um reflink copy-on-write. Se a plataforma não suportar copy-on-write, um mecanismo de cópia de fallback é usado.
• fs.constants.COPYFILE_FICLONE_FORCE: A operação de cópia tentará criar um reflink copy-on-write. Se a plataforma não suportar copy-on-write, a operação falhará.

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

// destination.txt será criado ou sobrescrito por padrão.
copyFileSync('source.txt', 'destination.txt')
console.log('source.txt foi copiado para destination.txt')

// Ao usar COPYFILE_EXCL, a operação falhará se destination.txt existir.
copyFileSync('source.txt', 'destination.txt', constants.COPYFILE_EXCL)

fs.cpSync(src, dest[, options])

[Histórico]

Versão	Mudanças
v22.3.0	Esta API não é mais experimental.
v20.1.0, v18.17.0	Aceita uma opção adicional mode para especificar o comportamento de cópia como o argumento mode de fs.copyFile().
v17.6.0, v16.15.0	Aceita uma opção adicional verbatimSymlinks para especificar se deve realizar a resolução de caminho para links simbólicos.
v16.7.0	Adicionado em: v16.7.0

• src <string> | <URL> caminho de origem a ser copiado.

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

• options <Object>

  • dereference <boolean> desreferenciar links simbólicos. Padrão: false.

  • errorOnExist <boolean> quando force é false e o destino existe, lança um erro. Padrão: false.

  • filter <Function> Função para filtrar arquivos/diretórios copiados. Retorna true para copiar o item, false para ignorá-lo. Ao ignorar um diretório, todo o seu conteúdo também será ignorado. Padrão: undefined

  • src <string> caminho de origem a ser copiado.

  • dest <string> caminho de destino para onde copiar.

  • Retorna: <boolean> Qualquer valor não Promise que seja coercível para boolean.

  • force <boolean> sobrescrever arquivo ou diretório existente. A operação de cópia ignorará erros se você definir isso como falso e o destino existir. Use a opção errorOnExist para alterar esse comportamento. Padrão: true.

  • mode <integer> modificadores para operação de cópia. Padrão: 0. Consulte a flag mode de fs.copyFileSync().

  • preserveTimestamps <boolean> Quando true, os carimbos de data/hora de src serão preservados. Padrão: false.

  • recursive <boolean> copiar diretórios recursivamente Padrão: false

  • verbatimSymlinks <boolean> Quando true, a resolução de caminho para links simbólicos será ignorada. Padrão: false

Copia de forma síncrona toda a estrutura de diretórios de src para dest, incluindo subdiretórios e arquivos.

Ao copiar um diretório para outro diretório, os globs não são suportados e o comportamento é semelhante a cp dir1/ dir2/.

fs.existsSync(path)

[Histórico]

Versão	Mudanças
v7.6.0	O parâmetro path pode ser um objeto URL WHATWG usando o protocolo file:.
v0.1.21	Adicionado em: v0.1.21

• path <string> | <Buffer> | <URL>
• Retorna: <boolean>

Retorna true se o caminho existir, false caso contrário.

Para informações detalhadas, consulte a documentação da versão assíncrona desta API: fs.exists().

fs.exists() está obsoleto, mas fs.existsSync() não está. O parâmetro callback para fs.exists() aceita parâmetros que são inconsistentes com outros callbacks do Node.js. fs.existsSync() não usa um callback.

import { existsSync } from 'node:fs'

if (existsSync('/etc/passwd')) console.log('O caminho existe.')

fs.fchmodSync(fd, mode)

Adicionado em: v0.4.7

• fd <integer>
• mode <string> | <integer>

Define as permissões do arquivo. Retorna undefined.

Consulte a documentação POSIX fchmod(2) para mais detalhes.

fs.fchownSync(fd, uid, gid)

Adicionado em: v0.4.7

• fd <integer>
• uid <integer> O ID do novo proprietário do arquivo.
• gid <integer> O ID do novo grupo do arquivo.

Define o proprietário do arquivo. Retorna undefined.

Consulte a documentação POSIX fchown(2) para mais detalhes.

fs.fdatasyncSync(fd)

Adicionado em: v0.1.96

• fd <integer>

Força todas as operações de E/S atualmente enfileiradas associadas ao arquivo para o estado de conclusão de E/S sincronizada do sistema operacional. Consulte a documentação POSIX fdatasync(2) para obter detalhes. Retorna undefined.

fs.fstatSync(fd[, options])

[Histórico]

Versão	Alterações
v10.5.0	Aceita um objeto options adicional para especificar se os valores numéricos retornados devem ser bigint.
v0.1.95	Adicionado em: v0.1.95

• fd <integer>

• options <Object>

  • bigint <boolean> Se os valores numéricos no objeto <fs.Stats> retornado devem ser bigint. Padrão: false.

• Retorna: <fs.Stats>

Recupera o <fs.Stats> para o descritor de arquivo.

Consulte a documentação POSIX fstat(2) para mais detalhes.

fs.fsyncSync(fd)

Adicionado em: v0.1.96

• fd <integer>

Solicita que todos os dados para o descritor de arquivo aberto sejam descarregados para o dispositivo de armazenamento. A implementação específica é específica do sistema operacional e do dispositivo. Consulte a documentação POSIX fsync(2) para mais detalhes. Retorna undefined.

fs.ftruncateSync(fd[, len])

Adicionado em: v0.8.6

• fd <integer>
• len <integer> Padrão: 0

Trunca o descritor de arquivo. Retorna undefined.

Para obter informações detalhadas, consulte a documentação da versão assíncrona desta API: fs.ftruncate().

fs.futimesSync(fd, atime, mtime)

[Histórico]

Versão	Mudanças
v4.1.0	Strings numéricas, NaN e Infinity agora são permitidos como especificadores de tempo.
v0.4.2	Adicionado em: v0.4.2

• fd <integer>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>

Versão síncrona de fs.futimes(). Retorna undefined.

fs.globSync(pattern[, options])

[Histórico]

Versão	Mudanças
v22.2.0	Adicionado suporte para withFileTypes como uma opção.
v22.0.0	Adicionado em: v22.0.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• pattern <string> | <string[]>

• options <Object>

  • cwd <string> diretório de trabalho atual. Padrão: process.cwd()
  • exclude <Function> Função para filtrar arquivos/diretórios. Retorna true para excluir o item, false para incluir. Padrão: undefined.
  • withFileTypes <boolean> true se o glob deve retornar caminhos como Dirents, false caso contrário. Padrão: false.

• Retorna: <string[]> caminhos dos arquivos que correspondem ao padrão.

ESM

import { globSync } from 'node:fs'

console.log(globSync('**/*.js'))

CJS

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

console.log(globSync('**/*.js'))

fs.lchmodSync(path, mode)

Obsoleto desde: v0.4.7

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

Altera as permissões em um link simbólico. Retorna undefined.

Este método só é implementado no macOS.

Consulte a documentação POSIX lchmod(2) para mais detalhes.

fs.lchownSync(path, uid, gid)

[Histórico]

Versão	Mudanças
v10.6.0	Esta API não está mais obsoleta.
v0.4.7	Obsoleto apenas na documentação.

• path <string> | <Buffer> | <URL>
• uid <integer> O novo ID de usuário do proprietário do arquivo.
• gid <integer> O novo ID de grupo do grupo do arquivo.

Define o proprietário para o caminho. Retorna undefined.

Consulte a documentação POSIX lchown(2) para obter mais detalhes.

fs.lutimesSync(path, atime, mtime)

Adicionado em: v14.5.0, v12.19.0

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>

Altera os carimbos de data/hora do sistema de arquivos do link simbólico referenciado por path. Retorna undefined ou lança uma exceção quando os parâmetros estão incorretos ou a operação falha. Esta é a versão síncrona de fs.lutimes().

fs.linkSync(existingPath, newPath)

[Histórico]

Versão	Mudanças
v7.6.0	Os parâmetros existingPath e newPath podem ser objetos WHATWG URL usando o protocolo file:. O suporte ainda é experimental.
v0.1.31	Adicionado em: v0.1.31

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>

Cria um novo link de existingPath para newPath. Consulte a documentação POSIX link(2) para obter mais detalhes. Retorna undefined.

fs.lstatSync(path[, options])

[Histórico]

Versão	Mudanças
v15.3.0, v14.17.0	Aceita uma opção throwIfNoEntry para especificar se uma exceção deve ser lançada caso a entrada não exista.
v10.5.0	Aceita um objeto options adicional para especificar se os valores numéricos retornados devem ser bigint.
v7.6.0	O parâmetro path pode ser um objeto WHATWG URL usando o protocolo file:.
v0.1.30	Adicionado em: v0.1.30

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

• options <Object>

  • bigint <boolean> Indica se os valores numéricos no objeto <fs.Stats> retornado devem ser bigint. Padrão: false.
  • throwIfNoEntry <boolean> Indica se uma exceção será lançada caso não exista uma entrada no sistema de arquivos, em vez de retornar undefined. Padrão: true.

• Retorna: <fs.Stats>

Recupera o <fs.Stats> para o link simbólico referenciado por path.

Consulte a documentação POSIX lstat(2) para obter mais detalhes.

fs.mkdirSync(path[, options])

[Histórico]

Versão	Mudanças
v13.11.0, v12.17.0	No modo recursive, o primeiro caminho criado agora é retornado.
v10.12.0	O segundo argumento agora pode ser um objeto options com as propriedades recursive e mode.
v7.6.0	O parâmetro path pode ser um objeto WHATWG URL usando o protocolo file:.
v0.1.21	Adicionado em: v0.1.21

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

• options <Object> | <integer>

  • recursive <boolean> Padrão: false
  • mode <string> | <integer> Não suportado no Windows. Padrão: 0o777.

• Retorna: <string> | <undefined>

Cria um diretório de forma síncrona. Retorna undefined ou, se recursive for true, o primeiro caminho de diretório criado. Esta é a versão síncrona de fs.mkdir().

Consulte a documentação POSIX mkdir(2) para mais detalhes.

fs.mkdtempSync(prefix[, options])

[Histórico]

Versão	Mudanças
v20.6.0, v18.19.0	O parâmetro prefix agora aceita buffers e URL.
v16.5.0, v14.18.0	O parâmetro prefix agora aceita uma string vazia.
v5.10.0	Adicionado em: v5.10.0

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

• options <string> | <Object>

  • encoding <string> Padrão: 'utf8'

• Retorna: <string>

Retorna o caminho do diretório criado.

Para obter informações detalhadas, consulte a documentação da versão assíncrona desta API: fs.mkdtemp().

O argumento opcional options pode ser uma string que especifica uma codificação ou um objeto com uma propriedade encoding que especifica a codificação de caracteres a ser usada.

fs.opendirSync(path[, options])

[Histórico]

Versão	Mudanças
v20.1.0, v18.17.0	Adicionada opção recursive.
v13.1.0, v12.16.0	Introduzida a opção bufferSize.
v12.12.0	Adicionado em: v12.12.0

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

• options <Object>

  • encoding <string> | <null> Padrão: 'utf8'
  • bufferSize <number> Número de entradas de diretório que são armazenadas em buffer internamente ao ler do diretório. Valores mais altos levam a um melhor desempenho, mas maior uso de memória. Padrão: 32
  • recursive <boolean> Padrão: false

• Retorna: <fs.Dir>

Abre um diretório de forma síncrona. Veja opendir(3).

Cria um <fs.Dir>, que contém todas as funções adicionais para leitura e limpeza do diretório.

A opção encoding define a codificação para o path ao abrir o diretório e operações de leitura subsequentes.

fs.openSync(path[, flags[, mode]])

[Histórico]

Versão	Mudanças
v11.1.0	O argumento flags agora é opcional e o padrão é 'r'.
v9.9.0	Os flags as e as+ são suportados agora.
v7.6.0	O parâmetro path pode ser um objeto WHATWG URL usando o protocolo file:.
v0.1.21	Adicionado em: v0.1.21

• path <string> | <Buffer> | <URL>
• flags <string> | <number> Padrão: 'r'. Consulte o suporte para flags do sistema de arquivos.
• mode <string> | <integer> Padrão: 0o666
• Retorna: <number>

Retorna um inteiro representando o descritor de arquivo.

Para informações detalhadas, veja a documentação da versão assíncrona desta API: fs.open().

fs.readdirSync(path[, options])

[Histórico]

Versão	Mudanças
v20.1.0, v18.17.0	Adicionada a opção recursive.
v10.10.0	Nova opção withFileTypes foi adicionada.
v7.6.0	O parâmetro path pode ser um objeto WHATWG URL usando o protocolo file:.
v0.1.21	Adicionado em: v0.1.21

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

• options <string> | <Object>

  • encoding <string> Padrão: 'utf8'
  • withFileTypes <boolean> Padrão: false
  • recursive <boolean> Se true, lê o conteúdo de um diretório recursivamente. No modo recursivo, listará todos os arquivos, subarquivos e diretórios. Padrão: false.

• Retorna: <string[]> | <Buffer[]> | <fs.Dirent[]>

Lê o conteúdo do diretório.

Veja a documentação POSIX readdir(3) para mais detalhes.

O argumento opcional options pode ser uma string especificando uma codificação, ou um objeto com uma propriedade encoding especificando a codificação de caracteres a ser usada para os nomes de arquivos retornados. Se encoding for definido como 'buffer', os nomes de arquivos retornados serão passados como objetos <Buffer>.

Se options.withFileTypes for definido como true, o resultado conterá objetos <fs.Dirent>.

fs.readFileSync(path[, options])

[Histórico]

Versão	Mudanças
v7.6.0	O parâmetro path pode ser um objeto URL WHATWG usando o protocolo file:.
v5.0.0	O parâmetro path agora pode ser um descritor de arquivo.
v0.1.8	Adicionado em: v0.1.8

• path <string> | <Buffer> | <URL> | <integer> nome do arquivo ou descritor de arquivo

• options <Object> | <string>

  • encoding <string> | <null> Padrão: null
  • flag <string> Consulte suporte de flags do sistema de arquivos. Padrão: 'r'.

• Retorna: <string> | <Buffer>

Retorna o conteúdo do path.

Para informações detalhadas, consulte a documentação da versão assíncrona desta API: fs.readFile().

Se a opção encoding for especificada, esta função retornará uma string. Caso contrário, ela retornará um buffer.

Semelhante a fs.readFile(), quando o caminho é um diretório, o comportamento de fs.readFileSync() é específico da plataforma.

import { readFileSync } from 'node:fs'

// macOS, Linux e Windows
readFileSync('<diretório>')
// => [Error: EISDIR: operação ilegal em um diretório, read <diretório>]

// FreeBSD
readFileSync('<diretório>') // => <dados>

fs.readlinkSync(path[, options])

[Histórico]

Versão	Mudanças
v7.6.0	O parâmetro path pode ser um objeto URL WHATWG usando o protocolo file:.
v0.1.31	Adicionado em: v0.1.31

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

• options <string> | <Object>

  • encoding <string> Padrão: 'utf8'

• Retorna: <string> | <Buffer>

Retorna o valor de string do link simbólico.

Consulte a documentação POSIX readlink(2) para mais detalhes.

O argumento opcional options pode ser uma string especificando uma codificação, ou um objeto com uma propriedade encoding especificando a codificação de caracteres a ser usada para o caminho do link retornado. Se a encoding estiver definida como 'buffer', o caminho do link retornado será passado como um objeto <Buffer>.

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

[Histórico]

Versão	Mudanças
v10.10.0	O parâmetro buffer agora pode ser qualquer TypedArray ou DataView.
v6.0.0	O parâmetro length agora pode ser 0.
v0.1.21	Adicionado em: v0.1.21

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer>
• length <integer>
• position <integer> | <bigint> | <null> Padrão: null
• Retorna: <number>

Retorna o número de bytesRead.

Para informações detalhadas, consulte a documentação da versão assíncrona desta API: fs.read().

fs.readSync(fd, buffer[, options])

[Histórico]

Versão	Mudanças
v13.13.0, v12.17.0	O objeto de opções pode ser passado para tornar offset, length e position opcionais.
v13.13.0, v12.17.0	Adicionado em: v13.13.0, v12.17.0

• fd <integer>

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

• options <Object>

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

• Retorna: <number>

Retorna o número de bytesRead.

Semelhante à função fs.readSync acima, esta versão usa um objeto options opcional. Se nenhum objeto options for especificado, ele usará os valores acima como padrão.

Para obter informações detalhadas, consulte a documentação da versão assíncrona desta API: fs.read().

fs.readvSync(fd, buffers[, position])

Adicionado em: v13.13.0, v12.17.0

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer> | <null> Padrão: null
• Retorna: <number> O número de bytes lidos.

Para obter informações detalhadas, consulte a documentação da versão assíncrona desta API: fs.readv().

fs.realpathSync(path[, options])

[Histórico]

Versão	Alterações
v8.0.0	Suporte para resolução de Pipe/Socket foi adicionado.
v7.6.0	O parâmetro path pode ser um objeto URL WHATWG usando o protocolo file:.
v6.4.0	Chamar realpathSync agora funciona novamente para vários casos extremos no Windows.
v6.0.0	O parâmetro cache foi removido.
v0.1.31	Adicionado em: v0.1.31

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

• options <string> | <Object>

  • encoding <string> Padrão: 'utf8'

• Retorna: <string> | <Buffer>

Retorna o nome do caminho resolvido.

Para informações detalhadas, consulte a documentação da versão assíncrona desta API: fs.realpath().

fs.realpathSync.native(path[, options])

Adicionado em: v9.2.0

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

• options <string> | <Object>

  • encoding <string> Padrão: 'utf8'

• Retorna: <string> | <Buffer>

realpath(3) síncrono.

Apenas caminhos que podem ser convertidos para strings UTF8 são suportados.

O argumento opcional options pode ser uma string especificando uma codificação, ou um objeto com uma propriedade encoding especificando a codificação de caracteres a ser usada para o caminho retornado. Se o encoding estiver definido como 'buffer', o caminho retornado será passado como um objeto <Buffer>.

No Linux, quando o Node.js é vinculado à musl libc, o sistema de arquivos procfs deve ser montado em /proc para que esta função funcione. O Glibc não tem essa restrição.

fs.renameSync(oldPath, newPath)

[Histórico]

Versão	Mudanças
v7.6.0	Os parâmetros oldPath e newPath podem ser objetos URL do WHATWG usando o protocolo file:. O suporte ainda é experimental.
v0.1.21	Adicionado em: v0.1.21

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>

Renomeia o arquivo de oldPath para newPath. Retorna undefined.

Consulte a documentação POSIX rename(2) para obter mais detalhes.

fs.rmdirSync(path[, options])

[Histórico]

Versão	Mudanças
v16.0.0	Usar fs.rmdirSync(path, { recursive: true }) em um path que é um arquivo não é mais permitido e resulta em um erro ENOENT no Windows e um erro ENOTDIR no POSIX.
v16.0.0	Usar fs.rmdirSync(path, { recursive: true }) em um path que não existe não é mais permitido e resulta em um erro ENOENT.
v16.0.0	A opção recursive está obsoleta, usá-la aciona um aviso de depreciação.
v14.14.0	A opção recursive está obsoleta, use fs.rmSync em vez disso.
v13.3.0, v12.16.0	A opção maxBusyTries foi renomeada para maxRetries, e seu valor padrão é 0. A opção emfileWait foi removida, e os erros EMFILE usam a mesma lógica de repetição que outros erros. A opção retryDelay agora é suportada. Os erros ENFILE agora são repetidos.
v12.10.0	As opções recursive, maxBusyTries e emfileWait agora são suportadas.
v7.6.0	Os parâmetros path podem ser um objeto URL do WHATWG usando o protocolo file:.
v0.1.21	Adicionado em: v0.1.21

• path <string> | <Buffer> | <URL>
• options <Object>
  • maxRetries <integer> Se um erro EBUSY, EMFILE, ENFILE, ENOTEMPTY ou EPERM for encontrado, o Node.js repete a operação com uma espera de recuo linear de retryDelay milissegundos mais longa em cada tentativa. Esta opção representa o número de tentativas. Esta opção é ignorada se a opção recursive não for true. Padrão: 0.
  • recursive <boolean> Se true, executa uma remoção de diretório recursiva. No modo recursivo, as operações são repetidas em caso de falha. Padrão: false. Obsoleto.
  • retryDelay <integer> A quantidade de tempo em milissegundos para esperar entre as tentativas. Esta opção é ignorada se a opção recursive não for true. Padrão: 100.

rmdir(2) síncrono. Retorna undefined.

Usar fs.rmdirSync() em um arquivo (não em um diretório) resulta em um erro ENOENT no Windows e em um erro ENOTDIR no POSIX.

Para obter um comportamento semelhante ao comando Unix rm -rf, use fs.rmSync() com as opções { recursive: true, force: true }.

fs.rmSync(path[, options])

[Histórico]

Versão	Mudanças
v17.3.0, v16.14.0	O parâmetro path pode ser um objeto WHATWG URL usando o protocolo file:.
v14.14.0	Adicionado em: v14.14.0

• path <string> | <Buffer> | <URL>
• options <Object>
  • force <boolean> Quando true, as exceções serão ignoradas se path não existir. Padrão: false.
  • maxRetries <integer> Se um erro EBUSY, EMFILE, ENFILE, ENOTEMPTY ou EPERM for encontrado, o Node.js tentará novamente a operação com uma espera de recuo linear de retryDelay milissegundos mais longa a cada tentativa. Esta opção representa o número de tentativas. Esta opção é ignorada se a opção recursive não for true. Padrão: 0.
  • recursive <boolean> Se true, realiza uma remoção recursiva de diretório. No modo recursivo, as operações são repetidas em caso de falha. Padrão: false.
  • retryDelay <integer> A quantidade de tempo em milissegundos para esperar entre as tentativas. Esta opção é ignorada se a opção recursive não for true. Padrão: 100.

Remove arquivos e diretórios de forma síncrona (modelado no utilitário POSIX rm padrão). Retorna undefined.

fs.statSync(path[, options])

[Histórico]

Versão	Mudanças
v15.3.0, v14.17.0	Aceita uma opção throwIfNoEntry para especificar se uma exceção deve ser lançada se a entrada não existir.
v10.5.0	Aceita um objeto options adicional para especificar se os valores numéricos retornados devem ser bigint.
v7.6.0	O parâmetro path pode ser um objeto WHATWG URL usando o protocolo file:.
v0.1.21	Adicionado em: v0.1.21

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

• options <Object>

  • bigint <boolean> Se os valores numéricos no objeto <fs.Stats> retornado devem ser bigint. Padrão: false.
  • throwIfNoEntry <boolean> Se uma exceção será lançada caso nenhuma entrada do sistema de arquivos exista, ao invés de retornar undefined. Padrão: true.

• Retorna: <fs.Stats>

Recupera o <fs.Stats> para o caminho.

fs.statfsSync(path[, options])

Adicionado em: v19.6.0, v18.15.0

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

• options <Object>

  • bigint <boolean> Se os valores numéricos no objeto <fs.StatFs> retornado devem ser bigint. Padrão: false.

• Retorna: <fs.StatFs>

Síncrono statfs(2). Retorna informações sobre o sistema de arquivos montado que contém path.

Em caso de erro, o err.code será um dos Erros Comuns do Sistema.

fs.symlinkSync(target, path[, type])

[Histórico]

Versão	Mudanças
v12.0.0	Se o argumento type for deixado indefinido, o Node detectará automaticamente o tipo de target e selecionará automaticamente dir ou file.
v7.6.0	Os parâmetros target e path podem ser objetos WHATWG URL usando o protocolo file:. O suporte ainda é experimental.
v0.1.31	Adicionado em: v0.1.31

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> | <null> Padrão: null

Retorna undefined.

Para informações detalhadas, consulte a documentação da versão assíncrona desta API: fs.symlink().

fs.truncateSync(path[, len])

Adicionado em: v0.8.6

• path <string> | <Buffer> | <URL>
• len <integer> Padrão: 0

Trunca o arquivo. Retorna undefined. Um descritor de arquivo também pode ser passado como o primeiro argumento. Neste caso, fs.ftruncateSync() é chamado.

Passar um descritor de arquivo está obsoleto e pode resultar em um erro sendo lançado no futuro.

fs.unlinkSync(path)

[Histórico]

Versão	Mudanças
v7.6.0	O parâmetro path pode ser um objeto URL WHATWG usando o protocolo file:.
v0.1.21	Adicionado em: v0.1.21

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

unlink(2) síncrono. Retorna undefined.

fs.utimesSync(path, atime, mtime)

[Histórico]

Versão	Mudanças
v8.0.0	NaN, Infinity e -Infinity não são mais especificadores de tempo válidos.
v7.6.0	O parâmetro path pode ser um objeto URL WHATWG usando o protocolo file:.
v4.1.0	Strings numéricas, NaN e Infinity agora são permitidos como especificadores de tempo.
v0.4.2	Adicionado em: v0.4.2

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>

Retorna undefined.

Para obter informações detalhadas, consulte a documentação da versão assíncrona desta API: fs.utimes().

fs.writeFileSync(file, data[, options])

[Histórico]

Versão	Mudanças
v21.0.0, v20.10.0	A opção flush agora é suportada.
v19.0.0	Passar para o parâmetro data um objeto com uma função toString própria não é mais suportado.
v17.8.0	Passar para o parâmetro data um objeto com uma função toString própria está obsoleto.
v14.12.0	O parâmetro data irá stringificar um objeto com uma função toString explícita.
v14.0.0	O parâmetro data não irá mais forçar a conversão de entradas não suportadas para strings.
v10.10.0	O parâmetro data agora pode ser qualquer TypedArray ou um DataView.
v7.4.0	O parâmetro data agora pode ser um Uint8Array.
v5.0.0	O parâmetro file agora pode ser um descritor de arquivo.
v0.1.29	Adicionado em: v0.1.29

• file <string> | <Buffer> | <URL> | <integer> nome do arquivo ou descritor de arquivo
• data <string> | <Buffer> | <TypedArray> | <DataView>
• options <Object> | <string>
  • encoding <string> | <null> Padrão: 'utf8'
  • mode <integer> Padrão: 0o666
  • flag <string> Veja suporte a flags do sistema de arquivos. Padrão: 'w'.
  • flush <boolean> Se todos os dados forem gravados com sucesso no arquivo, e flush for true, fs.fsyncSync() é usado para liberar os dados.

Retorna undefined.

A opção mode afeta apenas o arquivo recém-criado. Veja fs.open() para mais detalhes.

Para informações detalhadas, veja a documentação da versão assíncrona desta API: fs.writeFile().

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

[Histórico]

Versão	Mudanças
v14.0.0	O parâmetro buffer não forçará mais a conversão de entradas não suportadas em strings.
v10.10.0	O parâmetro buffer agora pode ser qualquer TypedArray ou DataView.
v7.4.0	O parâmetro buffer agora pode ser um Uint8Array.
v7.2.0	Os parâmetros offset e length agora são opcionais.
v0.1.21	Adicionado em: v0.1.21

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer> Padrão: 0
• length <integer> Padrão: buffer.byteLength - offset
• position <integer> | <null> Padrão: null
• Retorna: <number> O número de bytes gravados.

Para informações detalhadas, consulte a documentação da versão assíncrona desta API: fs.write(fd, buffer...).

fs.writeSync(fd, buffer[, options])

Adicionado em: v18.3.0, v16.17.0

• fd <integer>

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

• options <Object>

  • offset <integer> Padrão: 0
  • length <integer> Padrão: buffer.byteLength - offset
  • position <integer> Padrão: null

• Retorna: <number> O número de bytes gravados.

Para informações detalhadas, consulte a documentação da versão assíncrona desta API: fs.write(fd, buffer...).

fs.writeSync(fd, string[, position[, encoding]])

[Histórico]

Versão	Mudanças
v14.0.0	O parâmetro string não forçará mais entradas não suportadas para strings.
v7.2.0	O parâmetro position agora é opcional.
v0.11.5	Adicionado em: v0.11.5

• fd <integer>
• string <string>
• position <integer> | <null> Padrão: null
• encoding <string> Padrão: 'utf8'
• Retorna: <number> O número de bytes gravados.

Para informações detalhadas, consulte a documentação da versão assíncrona desta API: fs.write(fd, string...).

fs.writevSync(fd, buffers[, position])

Adicionado em: v12.9.0

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer> | <null> Padrão: null
• Retorna: <number> O número de bytes gravados.

Para informações detalhadas, consulte a documentação da versão assíncrona desta API: fs.writev().

Objetos Comuns

Os objetos comuns são compartilhados por todas as variantes da API do sistema de arquivos (promise, callback e síncrona).

Classe: fs.Dir

Adicionado em: v12.12.0

Uma classe representando um fluxo de diretório.

Criado por fs.opendir(), fs.opendirSync() ou 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)
}

Ao usar o iterador assíncrono, o objeto <fs.Dir> será fechado automaticamente após a saída do iterador.

dir.close()

Adicionado em: v12.12.0

• Retorna: <Promise>

Fecha assincronamente o identificador de recurso subjacente do diretório. Leituras subsequentes resultarão em erros.

Uma promessa é retornada que será cumprida depois que o recurso for fechado.

dir.close(callback)

[Histórico]

Versão	Mudanças
v18.0.0	Passar um callback inválido para o argumento callback agora lança ERR_INVALID_ARG_TYPE em vez de ERR_INVALID_CALLBACK.
v12.12.0	Adicionado em: v12.12.0

• callback <Function>
  • err <Error>

Fecha assincronamente o identificador de recurso subjacente do diretório. Leituras subsequentes resultarão em erros.

O callback será chamado depois que o identificador de recurso for fechado.

dir.closeSync()

Adicionado em: v12.12.0

Fecha sincronamente o identificador de recurso subjacente do diretório. Leituras subsequentes resultarão em erros.

dir.path

Adicionado em: v12.12.0

• <string>

O caminho somente leitura deste diretório, conforme foi fornecido para fs.opendir(), fs.opendirSync() ou fsPromises.opendir().

dir.read()

Adicionado em: v12.12.0

• Retorna: <Promise> Cumpre com um <fs.Dirent> | <null>

Lê assincronamente a próxima entrada de diretório via readdir(3) como um <fs.Dirent>.

Uma promise é retornada que será cumprida com um <fs.Dirent>, ou null se não houver mais entradas de diretório para ler.

As entradas de diretório retornadas por esta função não estão em nenhuma ordem particular, conforme fornecido pelos mecanismos de diretório subjacentes do sistema operacional. As entradas adicionadas ou removidas durante a iteração sobre o diretório podem não ser incluídas nos resultados da iteração.

dir.read(callback)

Adicionado em: v12.12.0

• callback <Function>
  • err <Error>
  • dirent <fs.Dirent> | <null>

Lê assincronamente a próxima entrada de diretório via readdir(3) como um <fs.Dirent>.

Após a conclusão da leitura, o callback será chamado com um <fs.Dirent>, ou null se não houver mais entradas de diretório para ler.

As entradas de diretório retornadas por esta função não estão em nenhuma ordem particular, conforme fornecido pelos mecanismos de diretório subjacentes do sistema operacional. As entradas adicionadas ou removidas durante a iteração sobre o diretório podem não ser incluídas nos resultados da iteração.

dir.readSync()

Adicionado em: v12.12.0

• Retorna: <fs.Dirent> | <null>

Lê sincronamente a próxima entrada de diretório como um <fs.Dirent>. Consulte a documentação POSIX readdir(3) para mais detalhes.

Se não houver mais entradas de diretório para ler, null será retornado.

As entradas de diretório retornadas por esta função não estão em nenhuma ordem particular, conforme fornecido pelos mecanismos de diretório subjacentes do sistema operacional. As entradas adicionadas ou removidas durante a iteração sobre o diretório podem não ser incluídas nos resultados da iteração.

dir[Symbol.asyncIterator]()

Adicionado em: v12.12.0

• Retorna: <AsyncIterator> Um AsyncIterator de <fs.Dirent>

Itera assincronamente sobre o diretório até que todas as entradas sejam lidas. Consulte a documentação POSIX readdir(3) para obter mais detalhes.

As entradas retornadas pelo iterador assíncrono são sempre um <fs.Dirent>. O caso null de dir.read() é tratado internamente.

Consulte <fs.Dir> para obter um exemplo.

As entradas de diretório retornadas por este iterador não estão em nenhuma ordem específica, conforme fornecido pelos mecanismos de diretório subjacentes do sistema operacional. Entradas adicionadas ou removidas durante a iteração sobre o diretório podem não ser incluídas nos resultados da iteração.

Classe: fs.Dirent

Adicionado em: v10.10.0

Uma representação de uma entrada de diretório, que pode ser um arquivo ou um subdiretório dentro do diretório, conforme retornado pela leitura de um <fs.Dir>. A entrada do diretório é uma combinação do nome do arquivo e dos pares de tipo de arquivo.

Além disso, quando fs.readdir() ou fs.readdirSync() é chamado com a opção withFileTypes definida como true, o array resultante é preenchido com objetos <fs.Dirent>, em vez de strings ou <Buffer>s.

dirent.isBlockDevice()

Adicionado em: v10.10.0

• Retorna: <boolean>

Retorna true se o objeto <fs.Dirent> descreve um dispositivo de bloco.

dirent.isCharacterDevice()

Adicionado em: v10.10.0

• Retorna: <boolean>

Retorna true se o objeto <fs.Dirent> descreve um dispositivo de caractere.

dirent.isDirectory()

Adicionado em: v10.10.0

• Retorna: <boolean>

Retorna true se o objeto <fs.Dirent> descreve um diretório do sistema de arquivos.

dirent.isFIFO()

Adicionado em: v10.10.0

• Retorna: <boolean>

Retorna true se o objeto <fs.Dirent> descreve um pipe first-in-first-out (FIFO).

dirent.isFile()

Adicionado em: v10.10.0

• Retorna: <boolean>

Retorna true se o objeto <fs.Dirent> descreve um arquivo regular.

dirent.isSocket()

Adicionado em: v10.10.0

• Retorna: <boolean>

Retorna true se o objeto <fs.Dirent> descreve um socket.

dirent.isSymbolicLink()

Adicionado em: v10.10.0

• Retorna: <boolean>

Retorna true se o objeto <fs.Dirent> descreve um link simbólico.

dirent.name

Adicionado em: v10.10.0

• <string> | <Buffer>

O nome do arquivo ao qual este objeto <fs.Dirent> se refere. O tipo deste valor é determinado pelo options.encoding passado para fs.readdir() ou fs.readdirSync().

dirent.parentPath

Adicionado em: v21.4.0, v20.12.0, v18.20.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

• <string>

O caminho para o diretório pai do arquivo ao qual este objeto <fs.Dirent> se refere.

dirent.path

[Histórico]

Versão	Mudanças
v23.2.0	A propriedade não é mais somente leitura.
v23.0.0	Acessar esta propriedade emite um aviso. Agora é somente leitura.
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	Adicionado em: v20.1.0, v18.17.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto: Use dirent.parentPath em vez disso.

• <string>

Alias para dirent.parentPath.

Classe: fs.FSWatcher

Adicionado em: v0.5.8

• Estende <EventEmitter>

Uma chamada bem-sucedida para o método fs.watch() retornará um novo objeto <fs.FSWatcher>.

Todos os objetos <fs.FSWatcher> emitem um evento 'change' sempre que um arquivo específico observado é modificado.

Evento: 'change'

Adicionado em: v0.5.8

• eventType <string> O tipo de evento de mudança que ocorreu
• filename <string> | <Buffer> O nome do arquivo que foi alterado (se relevante/disponível)

Emitido quando algo muda em um diretório ou arquivo observado. Consulte mais detalhes em fs.watch().

O argumento filename pode não ser fornecido dependendo do suporte do sistema operacional. Se filename for fornecido, ele será fornecido como um <Buffer> se fs.watch() for chamado com sua opção encoding definida como 'buffer', caso contrário, filename será uma string UTF-8.

import { watch } from 'node:fs'
// Exemplo quando manipulado através do listener fs.watch()
watch('./tmp', { encoding: 'buffer' }, (eventType, filename) => {
  if (filename) {
    console.log(filename)
    // Imprime: <Buffer ...>
  }
})

Evento: 'close'

Adicionado em: v10.0.0

Emitido quando o observador para de monitorar as alterações. O objeto <fs.FSWatcher> fechado não está mais utilizável no manipulador de eventos.

Evento: 'error'

Adicionado em: v0.5.8

• error <Error>

Emitido quando ocorre um erro ao monitorar o arquivo. O objeto <fs.FSWatcher> com erro não está mais utilizável no manipulador de eventos.

watcher.close()

Adicionado em: v0.5.8

Interrompe o monitoramento de alterações no <fs.FSWatcher> fornecido. Uma vez parado, o objeto <fs.FSWatcher> não está mais utilizável.

watcher.ref()

Adicionado em: v14.3.0, v12.20.0

• Retorna: <fs.FSWatcher>

Quando chamado, solicita que o loop de eventos do Node.js não seja encerrado enquanto o <fs.FSWatcher> estiver ativo. Chamar watcher.ref() várias vezes não terá efeito.

Por padrão, todos os objetos <fs.FSWatcher> são "referenciados", tornando normalmente desnecessário chamar watcher.ref() a menos que watcher.unref() tenha sido chamado anteriormente.

watcher.unref()

Adicionado em: v14.3.0, v12.20.0

• Retorna: <fs.FSWatcher>

Quando chamado, o objeto <fs.FSWatcher> ativo não exigirá que o loop de eventos do Node.js permaneça ativo. Se não houver outra atividade mantendo o loop de eventos em execução, o processo poderá ser encerrado antes que o callback do objeto <fs.FSWatcher> seja invocado. Chamar watcher.unref() várias vezes não terá efeito.

Classe: fs.StatWatcher

Adicionado em: v14.3.0, v12.20.0

• Estende <EventEmitter>

Uma chamada bem-sucedida para o método fs.watchFile() retornará um novo objeto <fs.StatWatcher>.

watcher.ref()

Adicionado em: v14.3.0, v12.20.0

• Retorna: <fs.StatWatcher>

Quando chamado, solicita que o loop de eventos do Node.js não seja encerrado enquanto o <fs.StatWatcher> estiver ativo. Chamar watcher.ref() várias vezes não terá efeito.

Por padrão, todos os objetos <fs.StatWatcher> são "referenciados", tornando normalmente desnecessário chamar watcher.ref() a menos que watcher.unref() tenha sido chamado anteriormente.

watcher.unref()

Adicionado em: v14.3.0, v12.20.0

• Retorna: <fs.StatWatcher>

Quando chamado, o objeto <fs.StatWatcher> ativo não exigirá que o loop de eventos do Node.js permaneça ativo. Se não houver outra atividade mantendo o loop de eventos em execução, o processo poderá ser encerrado antes que o callback do objeto <fs.StatWatcher> seja invocado. Chamar watcher.unref() várias vezes não terá efeito.

Classe: fs.ReadStream

Adicionado em: v0.1.93

• Estende: <stream.Readable>

Instâncias de <fs.ReadStream> são criadas e retornadas usando a função fs.createReadStream().

Evento: 'close'

Adicionado em: v0.1.93

Emitido quando o descritor de arquivo subjacente do <fs.ReadStream> foi fechado.

Evento: 'open'

Adicionado em: v0.1.93

• fd <integer> Descritor de arquivo inteiro usado pelo <fs.ReadStream>.

Emitido quando o descritor de arquivo do <fs.ReadStream> foi aberto.

Evento: 'ready'

Adicionado em: v9.11.0

Emitido quando o <fs.ReadStream> está pronto para ser usado.

Dispara imediatamente após 'open'.

readStream.bytesRead

Adicionado em: v6.4.0

• <number>

O número de bytes que foram lidos até agora.

readStream.path

Adicionado em: v0.1.93

• <string> | <Buffer>

O caminho para o arquivo do qual o stream está lendo, conforme especificado no primeiro argumento para fs.createReadStream(). Se path for passado como uma string, então readStream.path será uma string. Se path for passado como um <Buffer>, então readStream.path será um <Buffer>. Se fd for especificado, então readStream.path será undefined.

readStream.pending

Adicionado em: v11.2.0, v10.16.0

• <boolean>

Esta propriedade é true se o arquivo subjacente ainda não foi aberto, ou seja, antes que o evento 'ready' seja emitido.

Classe: fs.Stats

[Histórico]

Versão	Mudanças
v22.0.0, v20.13.0	O construtor público está obsoleto.
v8.1.0	Adicionado tempos como números.
v0.1.21	Adicionado em: v0.1.21

Um objeto <fs.Stats> fornece informações sobre um arquivo.

Objetos retornados de fs.stat(), fs.lstat(), fs.fstat(), e suas contrapartes síncronas são deste tipo. Se bigint nas options passadas para esses métodos for verdadeiro, os valores numéricos serão bigint em vez de number, e o objeto conterá propriedades adicionais com precisão de nanossegundos sufixadas com Ns. Objetos Stat não devem ser criados diretamente usando a palavra-chave 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: Mon, 10 Oct 2011 23:24:11 GMT,
  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
  ctime: Mon, 10 Oct 2011 23:24:11 GMT,
  birthtime: Mon, 10 Oct 2011 23:24:11 GMT }

Versão 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: Mon, 10 Oct 2011 23:24:11 GMT,
  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
  ctime: Mon, 10 Oct 2011 23:24:11 GMT,
  birthtime: Mon, 10 Oct 2011 23:24:11 GMT }

stats.isBlockDevice()

Adicionado em: v0.1.10

• Retorna: <boolean>

Retorna true se o objeto <fs.Stats> descreve um dispositivo de bloco.

stats.isCharacterDevice()

Adicionado em: v0.1.10

• Retorna: <boolean>

Retorna true se o objeto <fs.Stats> descreve um dispositivo de caractere.

stats.isDirectory()

Adicionado em: v0.1.10

• Retorna: <boolean>

Retorna true se o objeto <fs.Stats> descreve um diretório do sistema de arquivos.

Se o objeto <fs.Stats> foi obtido ao chamar fs.lstat() em um link simbólico que se resolve para um diretório, este método retornará false. Isso ocorre porque fs.lstat() retorna informações sobre um link simbólico em si e não sobre o caminho para o qual ele se resolve.

stats.isFIFO()

Adicionado em: v0.1.10

• Retorna: <boolean>

Retorna true se o objeto <fs.Stats> descreve um pipe first-in-first-out (FIFO).

stats.isFile()

Adicionado em: v0.1.10

• Retorna: <boolean>

Retorna true se o objeto <fs.Stats> descreve um arquivo regular.

stats.isSocket()

Adicionado em: v0.1.10

• Retorna: <boolean>

Retorna true se o objeto <fs.Stats> descreve um socket.

stats.isSymbolicLink()

Adicionado em: v0.1.10

• Retorna: <boolean>

Retorna true se o objeto <fs.Stats> descreve um link simbólico.

Este método é válido apenas ao usar fs.lstat().

stats.dev

• <number> | <bigint>

O identificador numérico do dispositivo que contém o arquivo.

stats.ino

• <number> | <bigint>

O número "Inode" específico do sistema de arquivos para o arquivo.

stats.mode

• <number> | <bigint>

Um campo de bits que descreve o tipo e o modo do arquivo.

stats.nlink

• <number> | <bigint>

O número de links físicos que existem para o arquivo.

stats.uid

• <number> | <bigint>

O identificador numérico do usuário proprietário do arquivo (POSIX).

stats.gid

• <number> | <bigint>

O identificador numérico do grupo proprietário do arquivo (POSIX).

stats.rdev

• <number> | <bigint>

Um identificador de dispositivo numérico se o arquivo representar um dispositivo.

stats.size

• <number> | <bigint>

O tamanho do arquivo em bytes.

Se o sistema de arquivos subjacente não suportar a obtenção do tamanho do arquivo, este será 0.

stats.blksize

• <number> | <bigint>

O tamanho do bloco do sistema de arquivos para operações de i/o.

stats.blocks

• <number> | <bigint>

O número de blocos alocados para este arquivo.

stats.atimeMs

Adicionado em: v8.1.0

• <number> | <bigint>

O timestamp que indica a última vez que este arquivo foi acessado, expresso em milissegundos desde a Época POSIX.

stats.mtimeMs

Adicionado em: v8.1.0

• <number> | <bigint>

O timestamp que indica a última vez que este arquivo foi modificado, expresso em milissegundos desde a Época POSIX.

stats.ctimeMs

Adicionado em: v8.1.0

• <number> | <bigint>

O timestamp que indica a última vez que o status do arquivo foi alterado, expresso em milissegundos desde a Época POSIX.

stats.birthtimeMs

Adicionado em: v8.1.0

• <number> | <bigint>

O timestamp que indica a hora de criação deste arquivo, expresso em milissegundos desde a Época POSIX.

stats.atimeNs

Adicionado em: v12.10.0

• <bigint>

Presente apenas quando bigint: true é passado para o método que gera o objeto. O timestamp que indica a última vez que este arquivo foi acessado, expresso em nanossegundos desde a Época POSIX.

stats.mtimeNs

Adicionado em: v12.10.0

• <bigint>

Presente apenas quando bigint: true é passado para o método que gera o objeto. O timestamp que indica a última vez que este arquivo foi modificado, expresso em nanossegundos desde a Época POSIX.

stats.ctimeNs

Adicionado em: v12.10.0

• <bigint>

Presente apenas quando bigint: true é passado para o método que gera o objeto. O timestamp que indica a última vez que o status do arquivo foi alterado, expresso em nanossegundos desde a Época POSIX.

stats.birthtimeNs

Adicionado em: v12.10.0

• <bigint>

Presente apenas quando bigint: true é passado para o método que gera o objeto. O timestamp que indica a hora de criação deste arquivo, expresso em nanossegundos desde a Época POSIX.

stats.atime

Adicionado em: v0.11.13

• <Date>

O timestamp que indica a última vez que este arquivo foi acessado.

stats.mtime

Adicionado em: v0.11.13

• <Date>

O timestamp que indica a última vez que este arquivo foi modificado.

stats.ctime

Adicionado em: v0.11.13

• <Date>

O timestamp que indica a última vez que o status do arquivo foi alterado.

stats.birthtime

Adicionado em: v0.11.13

• <Date>

O timestamp que indica a hora de criação deste arquivo.

Valores de tempo Stat

As propriedades atimeMs, mtimeMs, ctimeMs, birthtimeMs são valores numéricos que armazenam os horários correspondentes em milissegundos. Sua precisão é específica da plataforma. Quando bigint: true é passado para o método que gera o objeto, as propriedades serão bigints, caso contrário, serão números.

As propriedades atimeNs, mtimeNs, ctimeNs, birthtimeNs são bigints que armazenam os horários correspondentes em nanossegundos. Elas estão presentes apenas quando bigint: true é passado para o método que gera o objeto. Sua precisão é específica da plataforma.

atime, mtime, ctime e birthtime são representações alternativas do objeto Date dos vários horários. Os valores Date e numéricos não estão conectados. Atribuir um novo valor numérico ou alterar o valor Date, não será refletido na representação alternativa correspondente.

Os horários no objeto stat têm a seguinte semântica:

• atime "Tempo de Acesso": Tempo quando os dados do arquivo foram acessados pela última vez. Alterado pelas chamadas de sistema mknod(2), utimes(2) e read(2).
• mtime "Tempo de Modificação": Tempo quando os dados do arquivo foram modificados pela última vez. Alterado pelas chamadas de sistema mknod(2), utimes(2) e write(2).
• ctime "Tempo de Alteração": Tempo quando o status do arquivo foi alterado pela última vez (modificação dos dados do inode). Alterado pelas chamadas de sistema chmod(2), chown(2), link(2), mknod(2), rename(2), unlink(2), utimes(2), read(2) e write(2).
• birthtime "Tempo de Criação": Tempo de criação do arquivo. Definido uma vez quando o arquivo é criado. Em sistemas de arquivos onde o birthtime não está disponível, este campo pode conter o ctime ou 1970-01-01T00:00Z (ou seja, o timestamp da época Unix 0). Este valor pode ser maior que atime ou mtime neste caso. Em Darwin e outras variantes FreeBSD, também definido se o atime é explicitamente definido para um valor anterior ao birthtime atual usando a chamada de sistema utimes(2).

Antes do Node.js 0.12, o ctime armazenava o birthtime em sistemas Windows. A partir do 0.12, ctime não é "tempo de criação" e, em sistemas Unix, nunca foi.

Classe: fs.StatFs

Adicionado em: v19.6.0, v18.15.0

Fornece informações sobre um sistema de arquivos montado.

Objetos retornados de fs.statfs() e sua contraparte síncrona são deste tipo. Se bigint nas options passadas para esses métodos for true, os valores numéricos serão bigint em vez de number.

StatFs {
  type: 1397114950,
  bsize: 4096,
  blocks: 121938943,
  bfree: 61058895,
  bavail: 61058895,
  files: 999,
  ffree: 1000000
}

Versão bigint:

StatFs {
  type: 1397114950n,
  bsize: 4096n,
  blocks: 121938943n,
  bfree: 61058895n,
  bavail: 61058895n,
  files: 999n,
  ffree: 1000000n
}

statfs.bavail

Adicionado em: v19.6.0, v18.15.0

• <number> | <bigint>

Blocos livres disponíveis para usuários não privilegiados.

statfs.bfree

Adicionado em: v19.6.0, v18.15.0

• <number> | <bigint>

Blocos livres no sistema de arquivos.

statfs.blocks

Adicionado em: v19.6.0, v18.15.0

• <number> | <bigint>

Total de blocos de dados no sistema de arquivos.

statfs.bsize

Adicionado em: v19.6.0, v18.15.0

• <number> | <bigint>

Tamanho ideal do bloco de transferência.

statfs.ffree

Adicionado em: v19.6.0, v18.15.0

• <number> | <bigint>

Nós de arquivos livres no sistema de arquivos.

statfs.files

Adicionado em: v19.6.0, v18.15.0

• <number> | <bigint>

Total de nós de arquivo no sistema de arquivos.

statfs.type

Adicionado em: v19.6.0, v18.15.0

• <number> | <bigint>

Tipo de sistema de arquivos.

Classe: fs.WriteStream

Adicionado em: v0.1.93

• Estende <stream.Writable>

Instâncias de <fs.WriteStream> são criadas e retornadas usando a função fs.createWriteStream().

Evento: 'close'

Adicionado em: v0.1.93

Emitido quando o descritor de arquivo subjacente do <fs.WriteStream> foi fechado.

Evento: 'open'

Adicionado em: v0.1.93

• fd <integer> Descritor de arquivo inteiro usado pelo <fs.WriteStream>.

Emitido quando o arquivo do <fs.WriteStream> é aberto.

Evento: 'ready'

Adicionado em: v9.11.0

Emitido quando o <fs.WriteStream> está pronto para ser usado.

Dispara imediatamente após 'open'.

writeStream.bytesWritten

Adicionado em: v0.4.7

O número de bytes gravados até agora. Não inclui dados que ainda estão na fila para escrita.

writeStream.close([callback])

Adicionado em: v0.9.4

• callback <Function>
  • err <Error>

Fecha writeStream. Opcionalmente, aceita um retorno de chamada que será executado quando o writeStream for fechado.

writeStream.path

Adicionado em: v0.1.93

O caminho para o arquivo no qual o fluxo está escrevendo, conforme especificado no primeiro argumento de fs.createWriteStream(). Se path for passado como uma string, então writeStream.path será uma string. Se path for passado como um <Buffer>, então writeStream.path será um <Buffer>.

writeStream.pending

Adicionado em: v11.2.0

• <boolean>

Esta propriedade é true se o arquivo subjacente ainda não foi aberto, ou seja, antes que o evento 'ready' seja emitido.

fs.constants

• <Objeto>

Retorna um objeto contendo constantes comumente usadas para operações do sistema de arquivos.

Constantes FS

As seguintes constantes são exportadas por fs.constants e fsPromises.constants.

Nem todas as constantes estarão disponíveis em todos os sistemas operacionais; isso é especialmente importante para o Windows, onde muitas das definições específicas do POSIX não estão disponíveis. Para aplicativos portáteis, é recomendável verificar sua presença antes de usar.

Para usar mais de uma constante, use o operador OR bit a bit |.

Exemplo:

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 acesso a arquivos

As seguintes constantes são destinadas ao uso como parâmetro mode passado para fsPromises.access(), fs.access() e fs.accessSync().

Constante	Descrição
F_OK	Sinalizador que indica que o arquivo está visível para o processo que está chamando. Isso é útil para determinar se um arquivo existe, mas não diz nada sobre as permissões rwx. Padrão se nenhum modo for especificado.
R_OK	Sinalizador que indica que o arquivo pode ser lido pelo processo que está chamando.
W_OK	Sinalizador que indica que o arquivo pode ser gravado pelo processo que está chamando.
X_OK	Sinalizador que indica que o arquivo pode ser executado pelo processo que está chamando. Isso não tem efeito no Windows (se comportará como fs.constants.F_OK).

As definições também estão disponíveis no Windows.

Constantes de cópia de arquivo

As seguintes constantes são destinadas ao uso com fs.copyFile().

Constante	Descrição
COPYFILE_EXCL	Se presente, a operação de cópia falhará com um erro se o caminho de destino já existir.
COPYFILE_FICLONE	Se presente, a operação de cópia tentará criar um reflink de cópia em gravação. Se a plataforma subjacente não suportar cópia em gravação, um mecanismo de cópia de fallback é usado.
COPYFILE_FICLONE_FORCE	Se presente, a operação de cópia tentará criar um reflink de cópia em gravação. Se a plataforma subjacente não suportar cópia em gravação, a operação falhará com um erro.

As definições também estão disponíveis no Windows.

Constantes de abertura de arquivo

As seguintes constantes são destinadas ao uso com fs.open().

Constante	Descrição
O_RDONLY	Flag indicando para abrir um arquivo para acesso somente leitura.
O_WRONLY	Flag indicando para abrir um arquivo para acesso somente gravação.
O_RDWR	Flag indicando para abrir um arquivo para acesso de leitura-gravação.
O_CREAT	Flag indicando para criar o arquivo se ele ainda não existir.
O_EXCL	Flag indicando que a abertura de um arquivo deve falhar se a flag O_CREAT for definida e o arquivo já existir.
O_NOCTTY	Flag indicando que, se o caminho identificar um dispositivo terminal, abrir o caminho não fará com que esse terminal se torne o terminal de controle para o processo (se o processo ainda não tiver um).
O_TRUNC	Flag indicando que, se o arquivo existir e for um arquivo regular, e o arquivo for aberto com sucesso para acesso de gravação, seu comprimento será truncado para zero.
O_APPEND	Flag indicando que os dados serão anexados ao final do arquivo.
O_DIRECTORY	Flag indicando que a abertura deve falhar se o caminho não for um diretório.
O_NOATIME	Flag indicando que os acessos de leitura ao sistema de arquivos não resultarão mais em uma atualização das informações atime associadas ao arquivo. Esta flag está disponível apenas em sistemas operacionais Linux.
O_NOFOLLOW	Flag indicando que a abertura deve falhar se o caminho for um link simbólico.
O_SYNC	Flag indicando que o arquivo é aberto para E/S sincronizada com operações de gravação aguardando a integridade do arquivo.
O_DSYNC	Flag indicando que o arquivo é aberto para E/S sincronizada com operações de gravação aguardando a integridade dos dados.
O_SYMLINK	Flag indicando para abrir o próprio link simbólico em vez do recurso para o qual ele está apontando.
O_DIRECT	Quando definido, será feita uma tentativa de minimizar os efeitos de cache de E/S de arquivo.
O_NONBLOCK	Flag indicando para abrir o arquivo em modo não bloqueante quando possível.
UV_FS_O_FILEMAP	Quando definido, um mapeamento de arquivo de memória é usado para acessar o arquivo. Esta flag está disponível apenas em sistemas operacionais Windows. Em outros sistemas operacionais, esta flag é ignorada.

No Windows, apenas O_APPEND, O_CREAT, O_EXCL, O_RDONLY, O_RDWR, O_TRUNC, O_WRONLY e UV_FS_O_FILEMAP estão disponíveis.

Constantes de tipo de arquivo

As seguintes constantes destinam-se a serem utilizadas com a propriedade mode do objeto <fs.Stats> para determinar o tipo de um arquivo.

Constante	Descrição
S_IFMT	Máscara de bits usada para extrair o código do tipo de arquivo.
S_IFREG	Constante de tipo de arquivo para um arquivo regular.
S_IFDIR	Constante de tipo de arquivo para um diretório.
S_IFCHR	Constante de tipo de arquivo para um arquivo de dispositivo orientado a caracteres.
S_IFBLK	Constante de tipo de arquivo para um arquivo de dispositivo orientado a blocos.
S_IFIFO	Constante de tipo de arquivo para um FIFO/pipe.
S_IFLNK	Constante de tipo de arquivo para um link simbólico.
S_IFSOCK	Constante de tipo de arquivo para um socket.

No Windows, apenas S_IFCHR, S_IFDIR, S_IFLNK, S_IFMT e S_IFREG estão disponíveis.

Constantes de modo de arquivo

As seguintes constantes destinam-se a serem utilizadas com a propriedade mode do objeto <fs.Stats> para determinar as permissões de acesso de um arquivo.

Constante	Descrição
S_IRWXU	Modo de arquivo que indica leitura, gravação e execução pelo proprietário.
S_IRUSR	Modo de arquivo que indica leitura pelo proprietário.
S_IWUSR	Modo de arquivo que indica gravação pelo proprietário.
S_IXUSR	Modo de arquivo que indica execução pelo proprietário.
S_IRWXG	Modo de arquivo que indica leitura, gravação e execução pelo grupo.
S_IRGRP	Modo de arquivo que indica leitura pelo grupo.
S_IWGRP	Modo de arquivo que indica gravação pelo grupo.
S_IXGRP	Modo de arquivo que indica execução pelo grupo.
S_IRWXO	Modo de arquivo que indica leitura, gravação e execução por outros.
S_IROTH	Modo de arquivo que indica leitura por outros.
S_IWOTH	Modo de arquivo que indica gravação por outros.
S_IXOTH	Modo de arquivo que indica execução por outros.

No Windows, apenas S_IRUSR e S_IWUSR estão disponíveis.

Notas

Ordenação de operações baseadas em callback e promise

Como são executadas de forma assíncrona pelo pool de threads subjacente, não há ordem garantida ao usar os métodos baseados em callback ou promise.

Por exemplo, o seguinte é propenso a erros porque a operação fs.stat() pode ser concluída antes da operação 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)}`)
})

É importante ordenar corretamente as operações aguardando os resultados de uma antes de invocar a outra:

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')

Ou, ao usar as APIs de callback, mova a chamada fs.stat() para o callback da operação 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)}`)
  })
})

Caminhos de arquivo

A maioria das operações fs aceita caminhos de arquivo que podem ser especificados na forma de uma string, um objeto <Buffer> ou um objeto <URL> usando o protocolo file:.

Caminhos de string

Caminhos de string são interpretados como sequências de caracteres UTF-8 que identificam o nome de arquivo absoluto ou relativo. Caminhos relativos serão resolvidos em relação ao diretório de trabalho atual, conforme determinado pela chamada process.cwd().

Exemplo usando um caminho absoluto em POSIX:

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

let fd
try {
  fd = await open('/open/some/file.txt', 'r')
  // Faça algo com o arquivo
} finally {
  await fd?.close()
}

Exemplo usando um caminho relativo em POSIX (relativo a process.cwd()):

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

let fd
try {
  fd = await open('file.txt', 'r')
  // Faça algo com o arquivo
} finally {
  await fd?.close()
}

Caminhos de URL de arquivo

Adicionado em: v7.6.0

Para a maioria das funções do módulo node:fs, o argumento path ou filename pode ser passado como um objeto <URL> usando o protocolo file:.

import { readFileSync } from 'node:fs'

readFileSync(new URL('file:///tmp/hello'))

URLs file: são sempre caminhos absolutos.

Considerações específicas da plataforma

No Windows, URLs file: <URL> com um nome de host são convertidas em caminhos UNC, enquanto URLs file: <URL> com letras de unidade são convertidas em caminhos absolutos locais. URLs file: <URL> sem um nome de host e sem letra de unidade resultarão em um erro:

import { readFileSync } from 'node:fs'
// No Windows :

// - URLs de arquivo WHATWG com nome de host são convertidas em caminho UNC
// file://hostname/p/a/t/h/file => \\hostname\p\a\t\h\file
readFileSync(new URL('file://hostname/p/a/t/h/file'))

// - URLs de arquivo WHATWG com letras de unidade são convertidas em caminho absoluto
// file:///C:/tmp/hello => C:\tmp\hello
readFileSync(new URL('file:///C:/tmp/hello'))

// - URLs de arquivo WHATWG sem nome de host devem ter uma letra de unidade
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]: O caminho da URL do arquivo deve ser absoluto

URLs file: <URL> com letras de unidade devem usar : como separador logo após a letra da unidade. Usar outro separador resultará em um erro.

Em todas as outras plataformas, URLs file: <URL> com um nome de host não são suportadas e resultarão em um erro:

import { readFileSync } from 'node:fs'
// Em outras plataformas:

// - URLs de arquivo WHATWG com nome de host não são suportadas
// file://hostname/p/a/t/h/file => throw!
readFileSync(new URL('file://hostname/p/a/t/h/file'))
// TypeError [ERR_INVALID_FILE_URL_PATH]: deve ser absoluto

// - URLs de arquivo WHATWG são convertidas em caminho absoluto
// file:///tmp/hello => /tmp/hello
readFileSync(new URL('file:///tmp/hello'))

Uma URL file: <URL> com caracteres de barra codificados resultará em um erro em todas as plataformas:

import { readFileSync } from 'node:fs'

// No 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]: O caminho da URL do arquivo não deve incluir caracteres \ ou / codificados */

// No 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]: O caminho da URL do arquivo não deve incluir caracteres / codificados */

No Windows, URLs file: <URL> com barra invertida codificada resultarão em um erro:

import { readFileSync } from 'node:fs'

// No Windows
readFileSync(new URL('file:///C:/path/%5C'))
readFileSync(new URL('file:///C:/path/%5c'))
/* TypeError [ERR_INVALID_FILE_URL_PATH]: O caminho da URL do arquivo não deve incluir caracteres \ ou / codificados */

Caminhos de Buffer

Caminhos especificados usando um <Buffer> são úteis principalmente em certos sistemas operacionais POSIX que tratam caminhos de arquivo como sequências de bytes opacas. Em tais sistemas, é possível que um único caminho de arquivo contenha sub-sequências que usam múltiplas codificações de caracteres. Assim como caminhos de string, caminhos <Buffer> podem ser relativos ou absolutos:

Exemplo usando um caminho absoluto no 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')
  // Faça algo com o arquivo
} finally {
  await fd?.close()
}

Diretórios de trabalho por unidade no Windows

No Windows, o Node.js segue o conceito de diretório de trabalho por unidade. Esse comportamento pode ser observado ao usar um caminho de unidade sem uma barra invertida. Por exemplo, fs.readdirSync('C:\\') pode potencialmente retornar um resultado diferente de fs.readdirSync('C:'). Para mais informações, consulte esta página da MSDN.

Descritores de arquivo

Em sistemas POSIX, para cada processo, o kernel mantém uma tabela de arquivos e recursos atualmente abertos. Cada arquivo aberto recebe um identificador numérico simples chamado descritor de arquivo. No nível do sistema, todas as operações do sistema de arquivos usam esses descritores de arquivo para identificar e rastrear cada arquivo específico. Os sistemas Windows usam um mecanismo diferente, mas conceitualmente semelhante, para rastrear recursos. Para simplificar as coisas para os usuários, o Node.js abstrai as diferenças entre os sistemas operacionais e atribui a todos os arquivos abertos um descritor de arquivo numérico.

Os métodos fs.open() baseado em callback e fs.openSync() síncrono abrem um arquivo e alocam um novo descritor de arquivo. Uma vez alocado, o descritor de arquivo pode ser usado para ler dados, escrever dados ou solicitar informações sobre o arquivo.

Os sistemas operacionais limitam o número de descritores de arquivos que podem ser abertos a qualquer momento, por isso é fundamental fechar o descritor quando as operações forem concluídas. Deixar de fazê-lo resultará em um vazamento de memória que acabará fazendo com que um aplicativo trave.

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
  }
})

As APIs baseadas em promise usam um objeto <FileHandle> em vez do descritor de arquivo numérico. Esses objetos são melhor gerenciados pelo sistema para garantir que os recursos não sejam vazados. No entanto, ainda é necessário que eles sejam fechados quando as operações forem concluídas:

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 de Threadpool

Todas as APIs de sistema de arquivos baseadas em callback e promise (com exceção de fs.FSWatcher()) usam o threadpool do libuv. Isso pode ter implicações de desempenho surpreendentes e negativas para algumas aplicações. Consulte a documentação UV_THREADPOOL_SIZE para obter mais informações.

Flags do sistema de arquivos

As seguintes flags estão disponíveis sempre que a opção flag recebe uma string.

• 'a': Abre o arquivo para anexar. O arquivo é criado se não existir.
• 'ax': Semelhante a 'a', mas falha se o caminho existir.
• 'a+': Abre o arquivo para leitura e anexação. O arquivo é criado se não existir.
• 'ax+': Semelhante a 'a+', mas falha se o caminho existir.
• 'as': Abre o arquivo para anexar no modo síncrono. O arquivo é criado se não existir.
• 'as+': Abre o arquivo para leitura e anexação no modo síncrono. O arquivo é criado se não existir.
• 'r': Abre o arquivo para leitura. Ocorre uma exceção se o arquivo não existir.
• 'rs': Abre o arquivo para leitura no modo síncrono. Ocorre uma exceção se o arquivo não existir.
• 'r+': Abre o arquivo para leitura e gravação. Ocorre uma exceção se o arquivo não existir.
• 'rs+': Abre o arquivo para leitura e gravação no modo síncrono. Instrui o sistema operacional a ignorar o cache local do sistema de arquivos. Isso é principalmente útil para abrir arquivos em montagens NFS, pois permite ignorar o cache local potencialmente desatualizado. Isso tem um impacto muito real no desempenho de E/S, portanto, usar essa flag não é recomendado, a menos que seja necessário. Isso não transforma fs.open() ou fsPromises.open() em uma chamada de bloqueio síncrona. Se a operação síncrona for desejada, algo como fs.openSync() deve ser usado.
• 'w': Abre o arquivo para gravação. O arquivo é criado (se não existir) ou truncado (se existir).
• 'wx': Semelhante a 'w', mas falha se o caminho existir.
• 'w+': Abre o arquivo para leitura e gravação. O arquivo é criado (se não existir) ou truncado (se existir).
• 'wx+': Semelhante a 'w+', mas falha se o caminho existir.

flag também pode ser um número, conforme documentado por open(2); constantes comumente usadas estão disponíveis em fs.constants. No Windows, as flags são traduzidas para suas equivalentes, quando aplicável, por exemplo, O_WRONLY para FILE_GENERIC_WRITE, ou O_EXCL|O_CREAT para CREATE_NEW, conforme aceito por CreateFileW.

A flag exclusiva 'x' (flag O_EXCL em open(2)) faz com que a operação retorne um erro se o caminho já existir. Em POSIX, se o caminho for um link simbólico, usar O_EXCL retorna um erro, mesmo que o link seja para um caminho que não existe. A flag exclusiva pode não funcionar com sistemas de arquivos de rede.

No Linux, as gravações posicionais não funcionam quando o arquivo é aberto no modo de anexação. O kernel ignora o argumento de posição e sempre anexa os dados ao final do arquivo.

Modificar um arquivo em vez de substituí-lo pode exigir que a opção flag seja definida como 'r+' em vez do padrão 'w'.

O comportamento de algumas flags é específico da plataforma. Sendo assim, abrir um diretório no macOS e no Linux com a flag 'a+', como no exemplo abaixo, retornará um erro. Em contraste, no Windows e no FreeBSD, um descritor de arquivo ou um FileHandle será retornado.

// macOS e Linux
fs.open('<diretório>', 'a+', (err, fd) => {
  // => [Error: EISDIR: operação ilegal em um diretório, open <diretório>]
})

// Windows e FreeBSD
fs.open('<diretório>', 'a+', (err, fd) => {
  // => null, <fd>
})

No Windows, abrir um arquivo oculto existente usando a flag 'w' (seja por meio de fs.open(), fs.writeFile() ou fsPromises.open()) falhará com EPERM. Arquivos ocultos existentes podem ser abertos para gravação com a flag 'r+'.

Uma chamada para fs.ftruncate() ou filehandle.truncate() pode ser usada para redefinir o conteúdo do arquivo.