Skip to content

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.

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

const controller = new AbortController();
const promise = unicep.lookup('01310100', { signal: controller.signal });
controller.abort(); // the promise rejects with the abort reason

Cancelling never counts as a failure for the circuit breaker.

import { getDefaultUnicep } from '@unicep/core';
const unicep = getDefaultUnicep(); // all built-in providers, created on the first call

This is the instance the React, Vue and Angular bindings use when you do not pass your own.

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' }, ...]