📧 valid-email.ts

Uma biblioteca TypeScript-first para validação de emails, incluindo:

• Validação de formato (RFC)
• Normalização automática (trim + lowercase)
• Regras de tamanho (RFC: 64/255/254)
• Verificação de TLDs (lista oficial IANA, com cache em memória)
• Bloqueio de domínios descartáveis
• Checagem de DNS (MX records)
• Deep Check SMTP (opcional, best effort)
• Suporte a múltiplos idiomas (inglês e português)

🚀 Instalação

npm  install  valid-email.ts

ou com yarn:

yarn  add  valid-email.ts

🛠️ Uso básico

import { validate } from "valid-email.ts";

const email = "[email protected]";
const result = await validate(email);

console.log(result);

Saída:

{
  "email": "[email protected]",
  "user": "test",
  "domain": "gmail.com",
  "status": "valid",
  "reasonCode": "VALID",
  "reason": "Email is valid",
  "disposable": false
}

⚙️ Opções de validação

export interface ValidationOptions {
  checkDNS?: boolean; // padrão: true - valida MX records
  deepCheckSMTP?: boolean; // padrão: false - conecta via SMTP (lento e opcional)
  allowDisposable?: boolean; // padrão: false - bloqueia descartáveis
  checkTLD?: boolean; // padrão: true - valida TLDs oficiais IANA
  lang?: "en" | "pt"; // padrão: "en" - seleciona idioma
  customMessages?: ValidationMessages; // sobrescreve mensagens padrão
}

Exemplo:

await validate("[email protected]", { allowDisposable: true });
// retorna como válido, mesmo sendo descartável

📦 Validação em lote

import { validateMany } from "valid-email.ts";

const emails = ["[email protected]", "[email protected]", "c@invalid"];
const results = await validateMany(emails);

console.log(results);

📑 Códigos de retorno (reasonCode)

| Code | Descrição |

|-----------------|----------------------------------------|

| MISSING_AT | Email não contém @ ou contém mais de um |

| MISSING_USER | Não há usuário antes do @ |

| MISSING_DOMAIN| Domínio inválido ou sem . |

| TOO_LONG | Ultrapassa limite de tamanho RFC |

| INVALID_FORMAT| Regex básica falhou |

| INVALID_TLD | TLD não está na lista oficial da IANA |

| DISPOSABLE | Domínio descartável detectado |

| NO_MX | Domínio sem MX records válidos |

| SMTP_FAIL | SMTP check falhou (best effort) |

| VALID | Email válido |

🌍 Configurações globais

Você pode definir defaults para todas as chamadas:

import { setDefaultOptions } from "valid-email.ts";

setDefaultOptions({
  allowDisposable: true,
  checkDNS: false,
});

🧪 Testes

Rodar com Vitest:

npm  run  test
npm  run  test:coverage

📄 Licença

MIT © 2025 Tiago Dias Laureano

🤝 Contribuindo

Pull Requests são bem-vindos!

• Fork o repositório

• Crie uma branch: git checkout -b feature/nova-feature

• Faça commit: git commit -m 'feat: nova feature'

• Envie PR 🚀