@felipe7/valida-form 🛡️

Biblioteca modular, leve e extensível para validação de dados de formulários em JavaScript e TypeScript. Desenvolvida especialmente para atender aos padrões e regras de negócio do Brasil (CPF, CNPJ, CEP com busca via ViaCEP, telefones nacionais com DDD) e regras universais de segurança (e-mail RFC e senha forte), com mensagens de erro em português totalmente configuráveis.

📦 Instalação

# Usando NPM
npm install @felipe7/valida-form

# Usando Yarn
yarn add @felipe7/valida-form

# Usando PNPM
pnpm add @felipe7/valida-form

✨ Funcionalidades Principais

• 🧩 Estrutura Modular: Importe apenas os módulos necessários ou utilize a biblioteca completa.
• 🇧🇷 Foco em regras brasileiras: Algoritmos oficiais da Receita Federal para CPF e CNPJ, suporte a DDDs válidos em telefones e integração assíncrona com a API ViaCEP.
• 💬 Mensagens Customizáveis: Defina mensagens de erro sob medida para cada campo ou utilize o padrão claro em pt-BR.
• 📋 Validador Estruturado de Formulários: Função validateForm que processa formulários completos a partir de schemas declarativos.
• 🔒 Tipagem Estrita com TypeScript: Suporte nativo a autocompletion e checagem de tipos estáticos (.d.ts).
• 🧪 100% Testado: Suíte de testes automatizados abrangente com Jest cobrindo casos de borda e sucesso.

🚀 Como Usar

1. Validação de CPF

Verifica o cálculo oficial de dígitos verificadores e rejeita sequências repetidas (111.111.111-11, etc.).

import { validateCPF, isValidCPF, formatCPF, cleanCPF } from '@felipe7/valida-form';

// Validação simples (booleano)
isValidCPF('529.982.247-25'); // true
isValidCPF('111.111.111-11'); // false

// Validação com objeto de resultado
const result = validateCPF('123.456.789-00', {
  message: 'Por favor, informe um CPF válido para emissão do contrato.'
});

if (!result.isValid) {
  console.log(result.error); // Mensagem personalizada ou padrão
}

// Utilitários de formatação e limpeza
cleanCPF('529.982.247-25'); // '52998224725'
formatCPF('52998224725');    // '529.982.247-25'

2. Validação de CNPJ

Valida os dois dígitos verificadores segundo a regra da Receita Federal para empresas.

import { validateCNPJ, isValidCNPJ, formatCNPJ } from '@felipe7/valida-form';

isValidCNPJ('11.222.333/0001-81'); // true
isValidCNPJ('00.000.000/0000-00'); // false

const result = validateCNPJ('11222333000100');
console.log(result.isValid); // false
console.log(result.error);   // 'CNPJ inválido.'

formatCNPJ('11222333000181'); // '11.222.333/0001-81'

3. Validação de E-mail

Valida a sintaxe e estrutura do endereço de e-mail segundo especificações RFC / W3C.

import { validateEmail, isValidEmail } from '@felipe7/valida-form';

isValidEmail('[email protected]'); // true
isValidEmail('usuario@');               // false

const res = validateEmail('email_invalido', {
  message: 'Endereço corporativo inválido.'
});

4. Validação de Telefone Brasileiro

Suporta telefones celulares (11 dígitos, com nono dígito 9) e telefones fixos (10 dígitos), validando os códigos de DDD oficiais do Brasil.

import { validatePhone, isValidPhone, formatPhone } from '@felipe7/valida-form';

isValidPhone('(11) 98765-4321'); // true (celular SP)
isValidPhone('(21) 2233-4455');  // true (fixo RJ)
isValidPhone('00987654321');     // false (DDD 00 não existe)

formatPhone('11987654321'); // '(11) 98765-4321'
formatPhone('2122334455');  // '(21) 2233-4455'

5. Validação de Senha Forte

Permite checar múltiplos critérios de segurança com retorno detalhado de quais regras foram atendidas ou violadas.

import { validatePassword, isStrongPassword } from '@felipe7/valida-form';

// Verificação booleana
isStrongPassword('SenhaForte#2026'); // true
isStrongPassword('12345');           // false

// Validação com detalhes e regras personalizadas
const check = validatePassword('minhasenha123', {
  minLength: 8,
  requireUppercase: true,
  requireNumber: true,
  requireSpecial: true
});

console.log(check.isValid); // false
console.log(check.error);   // 'A senha deve conter pelo menos uma letra maiúscula. A senha deve conter pelo menos um caractere especial (!@#$%^&* etc.).'
console.log(check.details);
// {
//   hasMinLength: true,
//   hasUppercase: false,
//   hasLowercase: true,
//   hasNumber: true,
//   hasSpecial: false
// }

6. Validação e Consulta de CEP (com ViaCEP)

Valida o formato e permite buscar dados reais de endereço via API pública do ViaCEP.

import { validateCEP, formatCEP, fetchAddressByCEP } from '@felipe7/valida-form';

// 1. Validação síncrona de formato
validateCEP('01001-000').isValid; // true

// 2. Consulta assíncrona na API pública ViaCEP
async function carregarEndereco() {
  const result = await fetchAddressByCEP('01001-000');

  if (result.isValid && result.data) {
    console.log(result.data.logradouro); // 'Praça da Sé'
    console.log(result.data.bairro);     // 'Sé'
    console.log(result.data.localidade); // 'São Paulo'
    console.log(result.data.uf);         // 'SP'
  } else {
    console.error(result.error);
  }
}

7. Validação de Formulário Completo (validateForm)

Valide objetos inteiros de formulários usando um schema simples e intuitivo:

import { validateForm } from '@felipe7/valida-form';

const dadosDoFormulario = {
  nome: 'Felipe Silva',
  email: 'felipe@email',
  cpf: '11111111111',
  telefone: '(11) 98765-4321',
  senha: '123'
};

const schema = {
  nome: { type: 'required', message: 'O nome completo é obrigatório.' },
  email: { type: 'email' },
  cpf: { type: 'cpf' },
  telefone: { type: 'phone', required: false },
  senha: { type: 'password' }
};

const { isValid, errors } = validateForm(dadosDoFormulario, schema);

if (!isValid) {
  console.log(errors);
  /*
  {
    email: 'E-mail em formato inválido.',
    cpf: 'CPF inválido.',
    senha: 'A senha deve conter no mínimo 8 caracteres. ...'
  }
  */
}

🧪 Testes Automatizados

O projeto conta com mais de 55 testes unitários desenvolvidos com Jest:

# Executar todos os testes
npm test

# Executar com relatório de cobertura de código
npm run test:coverage

📄 Licença

Distribuído sob a licença MIT.