Pular para o conteúdo

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.

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.
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.

const controller = new AbortController();
const promise = unicep.lookup('01310100', { signal: controller.signal });
controller.abort(); // a promise é rejeitada com o motivo do cancelamento

Cancelar nunca conta como falha para o circuit breaker.

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.

import { formatCep, isValidCep, normalizeCep } from '@unicep/core';
isValidCep('01310-100'); // true
normalizeCep('01310-100'); // '01310100'
formatCep('01310100'); // '01310-100'
unicep.status();
// [{ name: 'viacep', circuit: 'closed' }, { name: 'brasilapi', circuit: 'open' }, ...]