@br-geo-kit/core

The contracts every other package in the kit implements. No data, no network.

pnpm add @br-geo-kit/core

You usually do not install this directly — @br-geo-kit/cep, @br-geo-kit/ibge and the providers depend on it and re-export what you need. Install it when you are writing a provider or a cache.

What is in it

The canonical Address. Every provider is normalized into this one shape. ProviderAddress is the same thing minus source and cached, which are the resolver's to set — a provider that could set source could lie about which provider answered.

CepProvider. Three outcomes, and keeping them apart is the contract: return a ProviderAddress, return null when the service says the CEP does not exist, and throw when it is down, rate-limited, or answered with something unreadable. See adding a provider.

CepCache, plus memoryCache (bounded, TTL'd, LRU, with negative entries) and noopCache.

The error hierarchy, all inheriting from BrGeoKitError so one catch distinguishes kit failures from unrelated ones. Each carries structured fields as well as a message.

CEP helpers.

normalizeCep('01.310-100')   // '01310100'
normalizeCep(1310100)        // '01310100' — the zero a spreadsheet dropped
normalizeCep('01310-100abc') // null — a data error, not a CEP
formatCep('01310100')        // '01310-100'
maskCep('013101')            // '01310-1' — progressive, for an input
assertCep('nope')            // throws InvalidCepError

State helpers.

toUF(' sp ')            // 'SP'
toUF('São Paulo')       // null — that is stateByName's job
stateByName('sao paulo')// 'SP'
stateCode('SP')         // '35'
stateByCode('35')       // 'SP'
stateRegion('SP')       // 'SE'

fetchJson, which does what a provider would otherwise repeat: uses the injected fetch and abort signal, maps the statuses you list to null, throws for everything else, re-throws an abort untouched so the resolver can label it a timeout, and throws rather than parsing an HTML error page served with a 200.

SearchIndex, normalizeText and tokenize — accent-, case- and punctuation-insensitive matching with AND semantics.

distanceBetween, haversine, in metres. Returns null rather than NaN for a missing or out-of-range point, because a NaN propagates through a sort and silently reorders a list of nearby stores.

Two entry points

import { normalizeCep } from '@br-geo-kit/core'        // browser-safe
import { loadFromDisk } from '@br-geo-kit/core/node'   // Node only

node:fs lives behind the /node subpath and nowhere else, so a bundler never has to follow an import it cannot resolve.

Conventions

Lookups answer, builders refuse: normalizeCep returns null, assertCep throws. null means "the source did not say" and is never a guess. Dataset tables are deep-frozen on load.

Full rules in API conventions.

Licence

MIT