CEP Search BR

Uma biblioteca Node.js para consulta de CEPs brasileiros utilizando a API ViaCEP.

📦 Instalação

Instale via npm:

npm install cep-search-br

Ou via yarn:

yarn add cep-search-br

🚀 Como usar

Importação

// CommonJS
const { getAddressByCep } = require('cep-search-br');

// ES Modules
import { getAddressByCep } from 'cep-search-br';

Exemplo básico

getAddressByCep('01001000')
  .then(console.log)
  .catch(console.error);

Exemplo com async/await

async function getCEPInfo() {
  try {
    const cepInfo = await getAddressByCep('01001000');
    console.log(cepInfo);
  } catch (error) {
    console.error('Erro ao buscar CEP:', error.message);
  }
}

📋 Retorno da API

A função retorna um objeto com a seguinte estrutura:

{
  "cep": "01001-000",
  "logradouro": "Praça da Sé",
  "complemento": "lado ímpar",
  "bairro": "Sé",
  "localidade": "São Paulo",
  "uf": "SP",
  "ibge": "3550308",
  "gia": "1004",
  "ddd": "11",
  "siafi": "7107"
}

⚙️ Parâmetros

| Parâmetro | Tipo | Obrigatório | Formato | Exemplo | |-----------|--------|-------------|-------------|------------| | cep | string | sim | 8 dígitos | "01001000" |

❌ Tratamento de erros

A função pode lançar os seguintes erros:

• TypeError('CEP deve ser uma string')
• Error('CEP inválido') - Quando não tem 8 dígitos
• Error('CEP não encontrado') - Quando o CEP não existe
• Error('Erro na requisição') - Erros de conexão

🧪 Testes

Cobertura de testes de 100% com Jest:

npm test

🤝 Quer contribuir para o projeto?

1. Faça um fork do projeto
2. Crie uma branch (git checkout -b feature/fooBar)
3. Commit suas mudanças (git commit -am 'Add some fooBar')
4. Push para a branch (git push origin feature/fooBar)
5. Abra um Pull Request

📄 Licença

MIT © G.C. Rodrigues

Feito com ❤️ por G.C. Rodrigues - ✉️ [[email protected]]