BUSCA CEP

Uma ferramenta leve em Node.js para buscar informações de CEPs em arquivos JSON grandes usando streaming, evitando o carregamento completo na memória e garantindo alta performance.

Instalação

npm install @devmaggioni/busca-cep

ou com Yarn:

yarn add @devmaggioni/busca-cep

Uso

Importe e utilize a função buscarCep com async/await:

import { buscarCep } from "@devmaggioni/busca-cep";

(async () => {
  const cep = await buscarCep("89600000");

  console.log(cep);
})();

Exemplo de retorno

{
  "ID": 5064,
  "UF": "SC",
  "REGIAO": "Sul",
  "LOCALIDADE": "Joaçaba",
  "LOCALIDADE_SEM_ACENTOS": "Joacaba",
  "FAIXA_DE_CEP": "89600-000 a 89608-999",
  "CEP_INICIAL": "89600000 ",
  "CEP_FINAL": " 89608999",
  "SITUACAO": "Não codificada por logradouros",
  "TIPO_DE_FAIXA": "Total do município",
  "LATITUDE": "-27,17394453",
  "LONGITUDE": "-51,50668973",
  "COD_GEOGRAFICO_SUBDIVISAO": "42090030500",
  "COD_GEOGRAFICO_DISTRITO": "420900305",
  "COD_IBGE": "4209003",
  "MICRORREGIAO": "JOAÇABA",
  "MESORREGIAO": "OESTE CATARINENSE",
  "CATEGORIA": "CIDADE",
  "ALTITUDE": "525,25",
  "LOCALIZACAO": "BRA, SANTA CATARINA, JOAÇABA",
  "LOCALIZACAO_SEM_ACENTOS": "BR, SANTA CATARINA, JOACABA"
}

API

buscarCep(cepBuscado: string): Promise<Cep | null>

• Parâmetro:

  • cepBuscado — O CEP que deseja buscar, como string. Pode conter hífens ou espaços.

• Retorno:

  • Promise<Cep | null> — Retorna o objeto Cep correspondente ou null se o CEP não for encontrado.

Tipos

export interface Cep {
  ID: number;
  UF: string;
  REGIAO: string;
  LOCALIDADE: string;
  LOCALIDADE_SEM_ACENTOS: string;
  FAIXA_DE_CEP: string;
  CEP_INICIAL: string;
  CEP_FINAL: string;
  SITUACAO: string;
  TIPO_DE_FAIXA: string;
  LATITUDE: string;
  LONGITUDE: string;
  COD_GEOGRAFICO_SUBDIVISAO: string;
  COD_GEOGRAFICO_DISTRITO: string;
  COD_IBGE: string;
  MICRORREGIAO: string;
  MESORREGIAO: string;
  CATEGORIA: string;
  ALTITUDE: string;
  LOCALIZACAO: string;
  LOCALIZACAO_SEM_ACENTOS: string;
}

Recursos

• Busca eficiente em arquivos JSON grandes sem carregar tudo na memória.
• Suporte para CEPs em diferentes formatos.
• Retorna informações detalhadas sobre localidades e faixas de CEP.

Contribuição

Contribuições são bem-vindas!

1. Fork o projeto
2. Crie uma branch (git checkout -b feature/nova-funcionalidade)
3. Commit suas mudanças (git commit -m "Descrição da mudança")
4. Push para a branch (git push origin feature/nova-funcionalidade)
5. Abra um Pull Request

Licença

MIT © Gabriel Maggioni