fs e fs/promises

node:fs e node:fs/promises leem, escrevem e transmitem arquivos em disco - APIs de promessa para trabalho assíncrono, streams para escala e flags explícitas para leituras e escritas sensíveis à segurança.

Receita

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

Quando usar:

• Carregar configuração na inicialização (JSON pequeno)
• Transmitir exportação CSV para resposta HTTP
• Escrever arquivos temporários enviados antes da verificação de vírus
• Rotacionar arquivos de log para o disco em workers

Exemplo de Trabalho

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

O que isso demonstra:

• Escrita atômica via arquivo temporário + rename reduz corrupção de escrita parcial
• filehandle.read lê o segmento final sem carregar o arquivo inteiro
• pipeline + createReadStream comprime logs grandes com memória limitada
• Modo de arquivo 0o600 para configuração sensível no Unix

Mergulho Profundo

Como Funciona

• Thread pool do libuv executa algumas operações de fs - fs síncrono pesado ainda bloqueia o loop se a API síncrona for usada.
• Descritores de arquivo - padrão open/filehandle para leituras/escritas posicionadas.
• Flags - 'r', 'w', 'a', 'wx' (criação exclusiva) - previne sobrescrita acidental.
• watch - fs.watch / fs.promises.watch - use debounce em ferramentas de desenvolvimento; prefira sinais explícitos de recarregamento em produção.

Escolha da API

Notas de TypeScript

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

Armadilhas

• readFileSync em manipulador HTTP - bloqueia o event loop. Correção: fs/promises ou streams.
• Travessia de caminho - o usuário fornece ../../etc/passwd. Correção: resolva sob um diretório base.
• Observando milhares de arquivos - EMFILE e CPU. Correção: restrinja o escopo do watch ou use uma ferramenta de build.
• UTF-8 padrão em arquivos binários - corrupção. Correção: omita a codificação para Buffer.
• Não fechar descritores de arquivo - vazamentos de EMFILE. Correção: try/finally com close().

Alternativas

FAQs

Relacionados

• path e url - junção segura de caminhos
• Fundamentos de Streams - createReadStream
• Segurança de Buffer e Codificação - permissões de arquivo
• Fundamentos de APIs Integradas - visão geral

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.