Verificação de arquivo no Node.js

Verifica com Promises se um caminho é um arquivo no Node.js. Retorna false em caso de erro, então também serve para checar existência.

Esse tipo de helper é útil quando eu não quero envolver fs.stat() com try-catch em todo lugar. Ele encaixa bem em arquivos de configuração opcionais, caminhos informados pelo usuário e fluxos de limpeza que só devem rodar quando um arquivo regular realmente existe.

import fs from "node:fs/promises";

function isFile(path: string): Promise<boolean> {
  return fs
    .stat(path)
    .then((stats) => stats.isFile())
    .catch(() => false);
}

Onde isso ajuda

Use quando a condição for apenas “o caminho existe e precisa ser um arquivo regular, não um diretório”. O código chamador fica menor porque não precisa repetir tratamento de exceção em cada ramificação.

Por que esse formato é útil

O helper reduz o resultado de fs.stat() a stats.isFile() e transforma qualquer exceção em false. Se caminhos ausentes e alvos que não são arquivos devem ser tratados do mesmo jeito, essa API pequena costuma bastar.

Observações

Esta versão não expõe qual erro aconteceu. Isso significa que ela não diferencia arquivo ausente de erro de permissão. Se essa diferença importar, vale inspecionar o código do erro dentro de catch. Se eu precisar verificar o link simbólico em si, e não o alvo dele, lstat() é a escolha mais adequada.