Um script que usa readFile para copiar um arquivo de 2 GB precisa lidar com o conteúdo inteiro em memória. Ao copiar com streams, a leitura avança em pedaços e acompanha a capacidade de escrita do destino.
import { createReadStream, createWriteStream } from "node:fs"
import { pipeline } from "node:stream/promises"
await pipeline(
createReadStream("entrada.bin"),
createWriteStream("saida.bin"),
)
pipeline coordena a transferência e propaga falhas dos streams. Você também pode adicionar uma etapa de transformação, como compressão, entre leitura e escrita. O uso de memória depende dos buffers envolvidos e do comportamento da transformação.
Se o destino for consumido por outro processo, escreva primeiro em um arquivo temporário no mesmo diretório e só renomeie após pipeline concluir. Uma falha durante a escrita pode deixar um arquivo parcial. Teste a cópia com um destino sem permissão e com um arquivo grande para verificar que o script retorna o erro e trata o temporário conforme a política do programa.
Documentação de referência · npm ci ou npm install? Como usar o lockfile no projeto
Respeite backpressure e erros
Streams transferem dados em blocos e aplicam backpressure para que a origem não produza indefinidamente mais rápido do que o destino consome. Isso reduz a necessidade de guardar o arquivo inteiro em memória, mas não torna o uso de memória zero. Uma transformação pode manter buffers e um consumidor lento pode prolongar a operação. Prefira pipeline, que conecta os streams e encaminha erros e cancelamentos entre eles.
Use sinais de abortamento quando uma solicitação externa puder cancelar a cópia. Feche descritores nos caminhos de falha e confirme o comportamento quando a origem desaparece ou o destino fica sem espaço. Um pipeline com transformação precisa propagar erros de cada etapa. Não transforme qualquer erro em sucesso só para encerrar o processo silenciosamente.
Publique arquivos completos
Se o arquivo final precisa aparecer completo ou não aparecer, escreva em um temporário e renomeie depois que pipeline conclui. Crie o temporário no mesmo sistema de arquivos do destino para que a renomeação tenha as propriedades esperadas pelo sistema operacional. Defina como remover arquivos parciais após interrupção e como tratar uma cópia anterior com o mesmo nome.
O streaming não substitui validação de caminho, limite de tamanho ou autorização. Se o nome vem do usuário, resolva-o dentro de um diretório permitido e rejeite caminhos que escapem desse escopo. Em downloads, confira status e headers antes de iniciar a gravação para não salvar HTML de erro com extensão .bin.
O tamanho de bloco e a estratégia de leitura dependem dos tipos de stream envolvidos. Uma transformação que comprime ou criptografa também mantém estado interno e pode falhar antes de escrever a saída final. Encapsule a sequência completa em pipeline para que o erro de uma etapa seja propagado e os streams sejam destruídos corretamente. O teste deve cobrir um erro na origem e outro na transformação, não apenas uma cópia bem-sucedida.