Core (@unicep/core)
@unicep/core is plain TypeScript with no framework dependency. It runs in the browser and on
Node.js 20 or newer, with the native fetch.
Creating an instance
Section titled “Creating an instance”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 },});Create the instance once and reuse it. Circuit breaker state and the cache live in it.
| Option | Default | What it does |
|---|---|---|
providers |
required | The providers, in priority order. Names must not repeat. |
timeoutMs |
5000 |
How long to wait for each provider, on every attempt. |
circuitBreaker.failureThreshold |
3 |
How many failures in a row before the circuit opens. |
circuitBreaker.resetTimeoutMs |
30000 |
How long to wait before trying a test request. |
retry |
disabled | See Retry. |
cache |
disabled | See Cache. |
Looking things up
Section titled “Looking things up”const address = await unicep.lookup('01310-100');lookup(cep, options?) accepts the CEP with or without the hyphen and returns a
Promise<Address>.
interface Address { cep: string; // 8 digits, no mask street: string; // empty for city-level CEPs complement?: string; neighborhood: string; // empty for city-level CEPs city: string; state: string; // the UF, for example "SP" ibgeCode?: string; provider: string; // who answered}By default a failing provider is skipped right away. To retry the same provider before moving on
to the next one, turn on retry:
const unicep = new Unicep({ providers: defaultProviders(), retry: { attempts: 2, // extra attempts per provider, default 0 delayMs: 200, // wait before the first retry; doubles on each further one, default 200 },});Only provider failures are retried. “CEP not found” and cancellations are final. A provider that fails every attempt counts as one failure for its circuit breaker.
Turn on the in-memory cache to avoid repeated requests for the same CEP:
const unicep = new Unicep({ providers: defaultProviders(), cache: { ttlMs: 5 * 60_000, // how long an address is reused, default 5 minutes maxEntries: 500, // when it fills up, the least used ones go first, default 500 },});
unicep.clearCache();Only successful lookups are cached (not “not found” or failures). CEPs with and without the hyphen share an entry, and each call gets its own copy of the address.
Cancellation
Section titled “Cancellation”const controller = new AbortController();const promise = unicep.lookup('01310100', { signal: controller.signal });
controller.abort(); // the promise rejects with the abort reasonCancelling never counts as a failure for the circuit breaker.
Shared instance
Section titled “Shared instance”import { getDefaultUnicep } from '@unicep/core';
const unicep = getDefaultUnicep(); // all built-in providers, created on the first callThis is the instance the React, Vue and Angular bindings use when you do not pass your own.
Helpers
Section titled “Helpers”import { formatCep, isValidCep, normalizeCep } from '@unicep/core';
isValidCep('01310-100'); // truenormalizeCep('01310-100'); // '01310100'formatCep('01310100'); // '01310-100'Circuit state
Section titled “Circuit state”unicep.status();// [{ name: 'viacep', circuit: 'closed' }, { name: 'brasilapi', circuit: 'open' }, ...]