cep-lookupResolução de CEP tolerante a falhas

Corrida entre provedores, circuit breaker, cache persistente e fallback offline - sem mudar uma linha da sua aplicação.

Corrida entre provedores

ViaCEP, BrasilAPI, APICep e OpenCEP disparam em paralelo com escalonamento. A primeira resposta válida vence; as demais são descartadas.

Ver provedores

Circuit breaker por provedor

Provedor que falha repetidamente é isolado, entra em cooldown e volta com uma sonda half-open. Uma API instável não contamina as outras.

Ver resiliência

Cache que sobrevive ao processo

InMemory, localStorage, IndexedDB, Redis e Cloudflare KV - todos com stale-if-error, cache negativo e coalescência de requisições.

Ver cache

Fallback offline sem rede

Mapa oficial de faixas dos Correios embutido (~2 KB). Mesmo com tudo fora do ar, você ainda responde UF e DDD.

Ver camada offline

Observabilidade nativa

Eventos de sucesso, falha, cache hit e stale, mais health score e métricas p95 por provedor prontas para expor num endpoint interno.

Ver observabilidade

React, Vue e ZIP dos EUA

Hooks oficiais para React e Vue 3, além de @eusilvio/zip-lookup com a mesma arquitetura para códigos postais americanos.

Ver integrações

Instale e resolva em 30 segundos

bash

npm install @eusilvio/cep-lookup

import { CepLookup } from "@eusilvio/cep-lookup";
import { viaCepProvider, brasilApiProvider, apicepProvider } from "@eusilvio/cep-lookup/providers";

const cep = new CepLookup({
  providers: [viaCepProvider, brasilApiProvider, apicepProvider],
  circuitBreaker: { enabled: true, failureThreshold: 3, cooldownMs: 30_000 },
  retries: 1,
});

const address = await cep.lookup("01001-000");
// {
//   cep: '01001000',
//   street: 'Praça da Sé',
//   neighborhood: 'Sé',
//   city: 'São Paulo',
//   state: 'SP',
//   service: 'ViaCEP'
// }

Se o ViaCEP cair, a BrasilAPI assume. Se ela também abrir o circuito, o APICep responde. Sua aplicação continua funcionando.

Comparativo

Recurso	cep-promise	wrappers de ViaCEP	cep-lookup
Múltiplos provedores	✅	❌	✅
Circuit breaker por provedor	❌	❌	✅
Health score do provedor	❌	❌	✅
Métricas em runtime	❌	❌	✅
Observabilidade por eventos	❌	❌	✅
Retry com backoff exponencial	❌	❌	✅
Rate limiting	❌	❌	✅
Fallback offline (zero rede)	❌	❌	✅
Verificação de endereço com correção de CEP	❌	❌	✅
Provedores customizados	❌	❌	✅
Integração React / Vue	❌	❌	✅

Já roda em produção

Produtos que resolvem CEP com a biblioteca todos os dias.

agendfy ↗Agenda e gestão para profissionais autônomos da beleza.

semeia ↗Gestão para igrejas: células, membros e discipulado.