{"_id":"@br-geo-kit/core","name":"@br-geo-kit/core","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@br-geo-kit/core","version":"1.0.0","description":"Shared contracts, types and helpers for br-geo-kit packages","license":"MIT","engines":{"node":">=20"},"type":"module","sideEffects":false,"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./node":{"types":"./dist/node.d.ts","import":"./dist/node.js","require":"./dist/node.cjs"}},"publishConfig":{"access":"public"},"keywords":["cep","endereco","brasil","br-geo-kit"],"repository":{"type":"git","url":"git+https://github.com/arielff3/br-geo-kit.git","directory":"packages/core"},"homepage":"https://github.com/arielff3/br-geo-kit/tree/main/packages/core#readme","bugs":{"url":"https://github.com/arielff3/br-geo-kit/issues"},"scripts":{"build":"tsup","clean":"node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""},"_id":"@br-geo-kit/core@1.0.0","_integrity":"sha512-ZHb9yvyvL5abDhf3ZHPUx4ERUNM65fuAPLsMXfHCRrbwZ2jTy82EwRn86VnCVMskjh9qHIWogEInrgOWNzWHNQ==","_resolved":"C:\\Users\\ariel\\AppData\\Local\\Temp\\af8f7bdc04ad7eb162a0aeec83a375e0\\br-geo-kit-core-1.0.0.tgz","_from":"file:br-geo-kit-core-1.0.0.tgz","_nodeVersion":"22.17.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-ZHb9yvyvL5abDhf3ZHPUx4ERUNM65fuAPLsMXfHCRrbwZ2jTy82EwRn86VnCVMskjh9qHIWogEInrgOWNzWHNQ==","shasum":"bfbbe786bab83a7e108a4a333f2cfc1330191bae","tarball":"https://registry.npmjs.org/@br-geo-kit/core/-/core-1.0.0.tgz","fileCount":20,"unpackedSize":269307,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBhRzY+xM5npK2G8psW4OYYThBOZDfLFHW1arsZEb141AiEAoTKS7V10tf1OBxGecBJZ7BPqeHH8I1yOURCWgZhhMPM="}]},"_npmUser":{"name":"arielff03","email":"arielfrancoferreira5@gmail.com"},"directories":{},"maintainers":[{"name":"arielff03","email":"arielfrancoferreira5@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/core_1.0.0_1789134613343_0.05676737903956797"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-11T13:50:13.192Z","1.0.0":"2026-09-11T13:50:13.482Z","modified":"2026-09-11T13:50:13.728Z"},"maintainers":[{"name":"arielff03","email":"arielfrancoferreira5@gmail.com"}],"description":"Shared contracts, types and helpers for br-geo-kit packages","homepage":"https://github.com/arielff3/br-geo-kit/tree/main/packages/core#readme","keywords":["cep","endereco","brasil","br-geo-kit"],"repository":{"type":"git","url":"git+https://github.com/arielff3/br-geo-kit.git","directory":"packages/core"},"bugs":{"url":"https://github.com/arielff3/br-geo-kit/issues"},"license":"MIT","readme":"# @br-geo-kit/core\n\n> The contracts every other package in the kit implements. No data, no\n> network.\n\n```bash\npnpm add @br-geo-kit/core\n```\n\nYou usually do not install this directly — `@br-geo-kit/cep`,\n`@br-geo-kit/ibge` and the providers depend on it and re-export what you\nneed. Install it when you are **writing a provider** or a cache.\n\n---\n\n## What is in it\n\n**The canonical `Address`.** Every provider is normalized into this one\nshape. `ProviderAddress` is the same thing minus `source` and `cached`,\nwhich are the resolver's to set — a provider that could set `source`\ncould lie about which provider answered.\n\n**`CepProvider`.** Three outcomes, and keeping them apart is the\ncontract: return a `ProviderAddress`, return `null` when the service\nsays the CEP does not exist, and **throw** when it is down,\nrate-limited, or answered with something unreadable. See\n[adding a provider](https://github.com/arielff3/br-geo-kit/blob/main/docs/adding-a-provider.md).\n\n**`CepCache`**, plus `memoryCache` (bounded, TTL'd, LRU, with negative\nentries) and `noopCache`.\n\n**The error hierarchy**, all inheriting from `BrGeoKitError` so one\n`catch` distinguishes kit failures from unrelated ones. Each carries\nstructured fields as well as a message.\n\n**CEP helpers.**\n\n```ts\nnormalizeCep('01.310-100')   // '01310100'\nnormalizeCep(1310100)        // '01310100' — the zero a spreadsheet dropped\nnormalizeCep('01310-100abc') // null — a data error, not a CEP\nformatCep('01310100')        // '01310-100'\nmaskCep('013101')            // '01310-1' — progressive, for an input\nassertCep('nope')            // throws InvalidCepError\n```\n\n**State helpers.**\n\n```ts\ntoUF(' sp ')            // 'SP'\ntoUF('São Paulo')       // null — that is stateByName's job\nstateByName('sao paulo')// 'SP'\nstateCode('SP')         // '35'\nstateByCode('35')       // 'SP'\nstateRegion('SP')       // 'SE'\n```\n\n**`fetchJson`**, which does what a provider would otherwise repeat: uses\nthe injected `fetch` and abort signal, maps the statuses you list to\n`null`, throws for everything else, re-throws an abort untouched so the\nresolver can label it a timeout, and throws rather than parsing an HTML\nerror page served with a 200.\n\n**`SearchIndex`**, `normalizeText` and `tokenize` — accent-, case- and\npunctuation-insensitive matching with AND semantics.\n\n**`distanceBetween`**, haversine, in metres. Returns `null` rather than\n`NaN` for a missing or out-of-range point, because a `NaN` propagates\nthrough a sort and silently reorders a list of nearby stores.\n\n---\n\n## Two entry points\n\n```ts\nimport { normalizeCep } from '@br-geo-kit/core'        // browser-safe\nimport { loadFromDisk } from '@br-geo-kit/core/node'   // Node only\n```\n\n`node:fs` lives behind the `/node` subpath and nowhere else, so a\nbundler never has to follow an import it cannot resolve.\n\n---\n\n## Conventions\n\nLookups answer, builders refuse: `normalizeCep` returns `null`,\n`assertCep` throws. `null` means \"the source did not say\" and is never a\nguess. Dataset tables are deep-frozen on load.\n\nFull rules in\n[API conventions](https://github.com/arielff3/br-geo-kit/blob/main/docs/api-conventions.md).\n\n## Licence\n\nMIT\n","readmeFilename":"README.md","_rev":"1-c09a28126a3d57c2aa5e3d15ad703528"}