Utilitários de validação e formatação para o Brasil — CPF, CNPJ, CEP, telefone, moeda, PIS e cartão.
Zero dependências · Tipado em TypeScript · Tree-shakeable · ESM + CJS.
- ✅ Validação real — algoritmos oficiais de dígitos verificadores de CPF e CNPJ
- 🎭 Formatação e máscaras — saída pronta para exibir ao usuário
- 🧪 Testado — 34 testes com Vitest e CI no GitHub Actions
- 📦 Leve — zero dependências, ESM + CJS, com tree-shaking
- 🦺 Tipado — definições
.d.tsincluídas
Ainda não publicado no npm. Por enquanto, use clonando o repositório:
git clone https://github.com/Samuelf27/br-utils.git
cd br-utils && npm install && npm run buildOu instale direto do GitHub:
npm install github:Samuelf27/br-utilsimport { isValidCPF, formatCPF, formatBRL, isValidPhone } from '@eusamuelf/br-utils';
isValidCPF('529.982.247-25'); // true
formatCPF('52998224725'); // '529.982.247-25'
isValidPhone('(11) 98888-7777'); // true
formatBRL(1234.5); // 'R$ 1.234,50'| Função | Descrição |
|---|---|
isValidCPF(cpf) |
Valida um CPF (dígitos verificadores) |
formatCPF(cpf) |
Formata como 000.000.000-00 |
generateCPF(formatted?) |
Gera um CPF válido aleatório (para testes) |
isValidCNPJ(cnpj) |
Valida um CNPJ |
formatCNPJ(cnpj) |
Formata como 00.000.000/0000-00 |
generateCNPJ(formatted?) |
Gera um CNPJ válido aleatório |
isValidCEP(cep) |
Valida o formato (8 dígitos) |
formatCEP(cep) |
Formata como 00000-000 |
isValidPhone(phone) |
Valida telefone fixo/celular com DDD |
formatPhone(phone) |
Formata (00) 00000-0000 ou (00) 0000-0000 |
formatBRL(value) |
Formata número como R$ 1.234,56 |
parseBRL(value) |
Converte 'R$ 1.234,56' → 1234.56 |
isValidPIS(pis) |
Valida um PIS/PASEP (dígito verificador) |
formatPIS(pis) |
Formata como 000.00000.00-0 |
generatePIS(formatted?) |
Gera um PIS válido aleatório |
isValidCreditCard(card) |
Valida cartão pelo algoritmo de Luhn |
getCardBrand(card) |
Detecta a bandeira (Visa, Mastercard, Amex...) |
formatCreditCard(card) |
Formata em grupos (4111 1111 1111 1111) |
onlyDigits(str) |
Remove tudo que não for dígito |
allSameDigits(str) |
Indica se todos os dígitos são iguais (ex.: 111.111.111-11) |
Todas as funções aceitam entradas com ou sem máscara.
npm install
npm test # roda os testes (Vitest)
npm run typecheck # checagem de tipos
npm run build # gera dist/ (ESM + CJS + .d.ts)O workflow publish.yml publica no npm automaticamente ao criar uma tag v* (basta configurar o secret NPM_TOKEN):
npm version patch # cria a tag
git push --follow-tags34 testes em 5 arquivos (Vitest), rodando no CI a cada push e pull request.
| Arquivo | Cobre |
|---|---|
test/cpf.test.ts |
Dígitos verificadores, sequências repetidas, máscara e formatação — inclusive entrada não-string, coagida com segurança |
test/cnpj.test.ts |
Validação com e sem máscara, DV incorreto, tamanhos inválidos |
test/pis.test.ts |
PIS/PASEP: DV, sequências repetidas e formatação |
test/card.test.ts |
Algoritmo de Luhn, detecção de bandeira e prioridade de Elo sobre Visa/Discover em BINs compartilhados |
test/others.test.ts |
CEP, telefone (DDD, celular com 9, fixo) e moeda — tolerante ao tipo de espaço do Intl |
npm test # roda a suíte
npm run test:watch # modo watchMIT © Samuel Ferreira