Core (@unicep/core)
O @unicep/core é TypeScript puro, sem dependência de framework. Roda no navegador e no Node.js
20 ou mais novo, com o fetch nativo.
Criando uma instância
Seção intitulada “Criando uma instância”import { Unicep, defaultProviders } from '@unicep/core';
const unicep = new Unicep({ providers: defaultProviders(), timeoutMs: 3000, circuitBreaker: { failureThreshold: 3, resetTimeoutMs: 30_000 }, retry: { attempts: 1, delayMs: 200 }, cache: { ttlMs: 5 * 60_000, maxEntries: 500 },});Crie a instância uma vez e reutilize. O estado dos circuit breakers e o cache vivem nela.
| Opção | Padrão | O que faz |
|---|---|---|
providers |
obrigatório | Os providers, em ordem de prioridade. Os nomes não podem se repetir. |
timeoutMs |
5000 |
Quanto esperar cada provider, a cada tentativa. |
circuitBreaker.failureThreshold |
3 |
Quantas falhas seguidas até o circuito abrir. |
circuitBreaker.resetTimeoutMs |
30000 |
Quanto esperar antes de tentar uma requisição de teste. |
retry |
desligado | Veja Retry. |
cache |
desligado | Veja Cache. |
Consultando
Seção intitulada “Consultando”const address = await unicep.lookup('01310-100');O lookup(cep, options?) aceita o CEP com ou sem hífen e devolve uma Promise<Address>.
interface Address { cep: string; // 8 dígitos, sem máscara street: string; // vazio em CEPs de cidades inteiras complement?: string; neighborhood: string; // vazio em CEPs de cidades inteiras city: string; state: string; // a UF, por exemplo "SP" ibgeCode?: string; provider: string; // quem respondeu}Por padrão, um provider que falha é pulado na hora. Para repetir o mesmo provider antes de passar
para o próximo, ligue o retry:
const unicep = new Unicep({ providers: defaultProviders(), retry: { attempts: 2, // tentativas extras por provider, padrão 0 delayMs: 200, // espera antes da primeira repetição; dobra a cada nova, padrão 200 },});Só falhas do provider são repetidas. “CEP não encontrado” e cancelamentos são definitivos. Um provider que falha em todas as tentativas conta como uma falha para o circuit breaker.
Ligue o cache em memória para não repetir requisições do mesmo CEP:
const unicep = new Unicep({ providers: defaultProviders(), cache: { ttlMs: 5 * 60_000, // por quanto tempo um endereço é reaproveitado, padrão 5 minutos maxEntries: 500, // quando enche, saem os menos usados, padrão 500 },});
unicep.clearCache();Só consultas bem-sucedidas entram no cache (não “não encontrado” nem falhas). CEPs com e sem hífen usam a mesma entrada, e cada chamada recebe a sua própria cópia do endereço.
Cancelamento
Seção intitulada “Cancelamento”const controller = new AbortController();const promise = unicep.lookup('01310100', { signal: controller.signal });
controller.abort(); // a promise é rejeitada com o motivo do cancelamentoCancelar nunca conta como falha para o circuit breaker.
Instância compartilhada
Seção intitulada “Instância compartilhada”import { getDefaultUnicep } from '@unicep/core';
const unicep = getDefaultUnicep(); // todos os providers embutidos, criada na primeira chamadaÉ a instância que os bindings de React, Vue e Angular usam quando você não passa a sua.
Helpers
Seção intitulada “Helpers”import { formatCep, isValidCep, normalizeCep } from '@unicep/core';
isValidCep('01310-100'); // truenormalizeCep('01310-100'); // '01310100'formatCep('01310100'); // '01310-100'Estado dos circuitos
Seção intitulada “Estado dos circuitos”unicep.status();// [{ name: 'viacep', circuit: 'closed' }, { name: 'brasilapi', circuit: 'open' }, ...]