Como você trabalha com o sistema de arquivos em Node?

Question

Accepted Answer

O módulo integrado **`fs`** lê e escreve arquivos e diretórios. Oferece três estilos de API — **promises** (moderno, preferido), **callbacks** (async original) e **sync** (bloqueante) — para que você possa escolher o certo para a situação.

## Por que isso importa

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

async function work() {
  const data = await readFile("input.txt", "utf8");     // read (utf8 → string)
  await writeFile("output.txt", "Hello");                // write (overwrites)
  await mkdir("new-dir", { recursive: true });           // create dirs (recursive = mkdir -p)
  const files = await readdir("./");                      // list directory contents
}
```

A API `fs/promises` funciona de forma limpa com async/await — o padrão moderno para I/O de arquivos.

## Variantes de callback e sync

```js
import fs from "fs";

fs.readFile("file.txt", "utf8", (err, data) => { ... }); // async callback
const data = fs.readFileSync("file.txt", "utf8");         // SYNC — blocks the event loop!
```

**Cuidado:** Métodos `*Sync` **bloqueiam todo o event loop** até que a operação seja concluída. Eles são adequados na inicialização (carregando config uma vez), mas devem ser evitados em manipuladores de requisição — uma leitura bloqueante congela todas as requisições concorrentes.

## Operações comuns

```js
await fs.promises.appendFile("log.txt", "new line
"); // append
await fs.promises.unlink("old.txt");                    // delete a file
await fs.promises.rename("a.txt", "b.txt");             // rename/move
const stats = await fs.promises.stat("file.txt");       // metadata (size, mtime)
const exists = fs.existsSync("file.txt");               // check existence
```

## Para arquivos grandes: use streams

```js
// ❌ readFile loads the WHOLE file into memory — bad for huge files
const huge = await readFile("10gb.txt"); // could exhaust memory

// ✅ stream it in chunks (constant memory)
fs.createReadStream("10gb.txt").pipe(fs.createWriteStream("copy.txt"));
```

Para arquivos grandes, `readFile` carrega tudo na memória de uma vez; **streams** processam dados em chunks com memória constante.

## Por que isso importa

I/O de arquivo é uma capacidade central do Node para carregamento de configuração, logging, upload/download de arquivos e ferramentas.

Conhecer os três estilos de API — e crucialmente, que **métodos sync bloqueiam o event loop** (evite-os em servidores) e que **arquivos grandes precisam de streams** (não `readFile`) — é essencial para escrever código de manipulação de arquivos que seja correto e com bom desempenho sob concorrência.

A API promise com async/await é o padrão limpo para uso cotidiano.