Este pacote utiliza GitHub Actions para rodar testes automáticos a cada push ou pull request na branch master.
O workflow executa:
- Instalação de dependências com pnpm
- Build do projeto
- Execução dos testes
O arquivo de configuração está em .github/workflows/ci.yml.
Importante: O workflow não faz deploy nem publica o pacote automaticamente, apenas executa testes e build.
Utilitários gerais para desenvolvimento no Brasil.
ou ou
npm install @phdiniiz/brasil-utilsO pacote inclui funções de validação para documentos e telefones brasileiros, sem dependências externas.
Valida um CPF (Cadastro de Pessoa Física) brasileiro.
import { validarCPF } from "@phdiniiz/brasil-utils";
// Aceita CPF formatado ou apenas números
validarCPF("123.456.789-09"); // true
validarCPF("12345678909"); // true
validarCPF("111.111.111-11"); // false (sequência repetida)
validarCPF("123.456.789-00"); // false (dígitos verificadores inválidos)Valida um CNPJ (Cadastro Nacional de Pessoa Jurídica) brasileiro.
import { validarCNPJ } from "@phdiniiz/brasil-utils";
// Aceita CNPJ formatado ou apenas números
validarCNPJ("11.222.333/0001-81"); // true
validarCNPJ("11222333000181"); // true
validarCNPJ("11.111.111/1111-11"); // false (sequência repetida)
validarCNPJ("11.222.333/0001-00"); // false (dígitos verificadores inválidos)Valida um telefone fixo brasileiro (10 dígitos: DDD + 8 dígitos).
import { validarTelefone } from "@phdiniiz/brasil-utils";
// Aceita telefone formatado ou apenas números
validarTelefone("(11) 3456-7890"); // true
validarTelefone("1134567890"); // true
validarTelefone("(11) 91234-5678"); // false (celular, não telefone fixo)
validarTelefone("(10) 3456-7890"); // false (DDD inválido)Valida um celular brasileiro (11 dígitos: DDD + 9 dígitos começando com 9).
import { validarCelular } from "@phdiniiz/brasil-utils";
// Aceita celular formatado ou apenas números
validarCelular("(11) 91234-5678"); // true
validarCelular("11912345678"); // true
validarCelular("(11) 3456-7890"); // false (telefone fixo, não celular)
validarCelular("(11) 81234-5678"); // false (não começa com 9)
validarCelular("(10) 91234-5678"); // false (DDD inválido)Você pode importar todas as funções de uma vez:
import {
validarCPF,
validarCNPJ,
validarTelefone,
validarCelular,
} from "@phdiniiz/brasil-utils";
// Exemplo de uso em formulário
const cpf = "123.456.789-09";
const cnpj = "11.222.333/0001-81";
const telefone = "(11) 3456-7890";
const celular = "(11) 91234-5678";
if (validarCPF(cpf)) {
console.log("CPF válido");
}
if (validarCNPJ(cnpj)) {
console.log("CNPJ válido");
}
if (validarTelefone(telefone)) {
console.log("Telefone válido");
}
if (validarCelular(celular)) {
console.log("Celular válido");
}O pacote inclui funções para busca de informações de empresas a partir do CNPJ utilizando a API gratuita do ReceitaWS, sem dependências externas (usa apenas fetch nativo do Node.js 24+).
Busca informações de empresa a partir de um CNPJ.
import { buscarCNPJ } from "@phdiniiz/brasil-utils";
// Busca por CNPJ
const empresa = await buscarCNPJ("27865757000102");
if (empresa) {
console.log(empresa.nome); // "CAIXA ECONOMICA FEDERAL"
console.log(empresa.fantasia); // "CAIXA ECONOMICA FEDERAL"
// ... outros campos
} else {
console.log("CNPJ não encontrado ou inválido");
}
// Retorna null se o CNPJ não for encontrado ou tiver formato inválido
const empresa2 = await buscarCNPJ("00000000000000"); // nullO pacote também exporta utilitários para consulta de status da API ReceitaWS e busca alternativa via proxy:
import {
consultarStatusReceitaWS,
buscarCNPJProxy,
} from "@phdiniiz/brasil-utils";
const status = await consultarStatusReceitaWS();
console.log(status?.status); // "UP", "DOWN" ou "DEGRADED"
const empresaProxy = await buscarCNPJProxy("27865757000102");O pacote exporta tipos para facilitar o uso com TypeScript:
import type {
ReceitaWSResponse,
ReceitaWSStatusResponse,
} from "@phdiniiz/brasil-utils";
const empresa: ReceitaWSResponse | null = await buscarCNPJ("27865757000102");
const status: ReceitaWSStatusResponse | null = await consultarStatusReceitaWS();O pacote inclui funções para busca de CEP utilizando a API gratuita do ViaCEP, sem dependências externas (usa apenas fetch nativo do Node.js 18+).
Valida o formato de um CEP brasileiro (8 dígitos).
import { validarCEP } from "@phdiniiz/brasil-utils";
// Aceita CEP formatado ou apenas números
validarCEP("01001000"); // true
validarCEP("01001-000"); // true
validarCEP("12345"); // false (menos de 8 dígitos)
validarCEP("123456789"); // false (mais de 8 dígitos)Busca informações de endereço a partir de um CEP.
import { buscarCEP } from "@phdiniiz/brasil-utils";
// Busca por CEP
const endereco = await buscarCEP("01001000");
if (endereco) {
console.log(endereco.logradouro); // "Praça da Sé"
console.log(endereco.bairro); // "Sé"
console.log(endereco.localidade); // "São Paulo"
console.log(endereco.uf); // "SP"
} else {
console.log("CEP não encontrado");
}
// Retorna null se o CEP não for encontrado ou tiver formato inválido
const endereco2 = await buscarCEP("99999999"); // nullBusca CEPs a partir de UF, cidade e logradouro.
import { buscarCEPPorEndereco } from "@phdiniiz/brasil-utils";
// Busca por endereço (retorna até 50 resultados)
const ceps = await buscarCEPPorEndereco("SP", "São Paulo", "Praça da Sé");
if (ceps.length > 0) {
ceps.forEach((cep) => {
console.log(`${cep.cep} - ${cep.logradouro}`);
});
} else {
console.log("Nenhum CEP encontrado");
}
// Retorna array vazio se não encontrar resultados ou parâmetros inválidos
const ceps2 = await buscarCEPPorEndereco("RS", "Porto Alegre", "Domingos");O pacote exporta tipos TypeScript para facilitar o desenvolvimento:
import type {
ViaCEPResponse,
ViaCEPSearchResponse,
} from "@phdiniiz/brasil-utils";
const endereco: ViaCEPResponse | null = await buscarCEP("01001000");
const resultados: ViaCEPSearchResponse = await buscarCEPPorEndereco(
"SP",
"São Paulo",
"Rua"
);Você pode importar todas as funções de CEP de uma vez:
import {
validarCEP,
buscarCEP,
buscarCEPPorEndereco,
} from "@phdiniiz/brasil-utils";
// Exemplo de uso em formulário
const cep = "01001-000";
if (validarCEP(cep)) {
const endereco = await buscarCEP(cep);
if (endereco) {
console.log(`Endereço: ${endereco.logradouro}, ${endereco.bairro}`);
}
}Todas as funções de busca tratam erros automaticamente:
import { buscarCEP } from "@phdiniiz/brasil-utils";
try {
const endereco = await buscarCEP("01001000");
if (endereco) {
// CEP encontrado
console.log(endereco);
} else {
// CEP não encontrado ou formato inválido
console.log("CEP inválido ou não encontrado");
}
} catch (error) {
// Erro de rede (já tratado internamente, retorna null)
console.error("Erro ao buscar CEP");
}Nota: A API ViaCEP possui rate limiting. Uso massivo para validação de bases de dados pode resultar em bloqueio temporário. Para mais informações, consulte a documentação oficial do ViaCEP.
- Node.js >= 24.12.0
- npm (recomendado)
npm installnpm run buildnpm run prepublishOnly
npm publish --access publicbrasil-utils/
├── src/
│ ├── index.ts # Ponto de entrada principal
│ ├── validators/ # Funções de validação
│ │ ├── cpf.ts # Validação de CPF
│ │ ├── cnpj.ts # Validação de CNPJ
│ │ ├── phone.ts # Validação de Telefone e Celular
│ │ ├── index.ts # Exportações centralizadas
│ │ └── __tests__/ # Testes unitários
│ │ ├── cpf.test.ts
│ │ ├── cnpj.test.ts
│ │ └── phone.test.ts
│ ├── cep/ # Funções de CEP
│ │ ├── validator.ts # Validação de formato de CEP
│ │ ├── types.ts # Tipos TypeScript
│ │ ├── index.ts # Exportações centralizadas
│ │ └── __tests__/ # Testes unitários
│ │ ├── validator.test.ts
│ │ └── viacep.test.ts
│ └── libs/ # Funções de integração com APIs externas
│ ├── viacep.ts # Busca na API ViaCEP
│ └── receitaws.ts # Busca na API ReceitaWS
├── dist/ # Build output (gerado)
├── package.json
├── tsconfig.json
└── README.md
- Formato aceito: Com ou sem formatação (pontos e traços)
- Exemplo formatado:
123.456.789-09 - Exemplo sem formatação:
12345678909 - Total de dígitos: 11 (9 dígitos + 2 verificadores)
- Formato aceito: Com ou sem formatação (pontos, barra e traço)
- Exemplo formatado:
11.222.333/0001-81 - Exemplo sem formatação:
11222333000181 - Total de dígitos: 14 (12 dígitos + 2 verificadores)
- Formato aceito: Com ou sem formatação (parênteses, espaços, traços)
- Exemplo formatado:
(11) 3456-7890 - Exemplo sem formatação:
1134567890 - Total de dígitos: 10 (2 DDD + 8 número)
- DDD válido: 11 a 99
- Primeiro dígito do número: Não pode ser 0 ou 1
- Formato aceito: Com ou sem formatação (parênteses, espaços, traços)
- Exemplo formatado:
(11) 91234-5678 - Exemplo sem formatação:
11912345678 - Total de dígitos: 11 (2 DDD + 9 número)
- DDD válido: 11 a 99
- Primeiro dígito do número: Deve ser 9
- Formato aceito: Com ou sem formatação (traços)
- Exemplo formatado:
01001-000 - Exemplo sem formatação:
01001000 - Total de dígitos: 8
- API utilizada: ViaCEP (gratuita, sem autenticação)
- Requisitos: Node.js 18+ (para suporte nativo ao
fetch)
MIT