{"_id":"@br-geo-kit/address","name":"@br-geo-kit/address","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@br-geo-kit/address","version":"1.0.0","description":"Parse, format and validate Brazilian postal addresses","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"}},"dependencies":{"@br-geo-kit/core":"1.0.0"},"publishConfig":{"access":"public"},"keywords":["endereco","address","logradouro","cep","brasil","br-geo-kit"],"repository":{"type":"git","url":"git+https://github.com/arielff3/br-geo-kit.git","directory":"packages/address"},"homepage":"https://github.com/arielff3/br-geo-kit/tree/main/packages/address#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/address@1.0.0","_integrity":"sha512-2NJ0+ceWcahzJEktI/XjEtZExKKXItxqwvbhwnLoeKAC6zY2GZnN679xOUA/IQazgZYroa6rWPncSFE5LeQn4Q==","_resolved":"C:\\Users\\ariel\\AppData\\Local\\Temp\\0e667e9f33ce3282f5bfc19ccb9c7d2a\\br-geo-kit-address-1.0.0.tgz","_from":"file:br-geo-kit-address-1.0.0.tgz","_nodeVersion":"22.17.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-2NJ0+ceWcahzJEktI/XjEtZExKKXItxqwvbhwnLoeKAC6zY2GZnN679xOUA/IQazgZYroa6rWPncSFE5LeQn4Q==","shasum":"96272b173e8809857e1637ef19b5c5905b6d9a29","tarball":"https://registry.npmjs.org/@br-geo-kit/address/-/address-1.0.0.tgz","fileCount":10,"unpackedSize":87880,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD+j6/1iSOleM8OR9VjlW4JX2EaJgCRTy/Qqzmy7HCGhQIhAMQcfdIm1+6N+gNVHccalaWg++FPP2Ot4i+L5OF+Y1z5"}]},"_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/address_1.0.0_1789134615642_0.8951238971901831"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-11T13:50:15.502Z","1.0.0":"2026-09-11T13:50:15.780Z","modified":"2026-09-11T13:50:16.004Z"},"maintainers":[{"name":"arielff03","email":"arielfrancoferreira5@gmail.com"}],"description":"Parse, format and validate Brazilian postal addresses","homepage":"https://github.com/arielff3/br-geo-kit/tree/main/packages/address#readme","keywords":["endereco","address","logradouro","cep","brasil","br-geo-kit"],"repository":{"type":"git","url":"git+https://github.com/arielff3/br-geo-kit.git","directory":"packages/address"},"bugs":{"url":"https://github.com/arielff3/br-geo-kit/issues"},"license":"MIT","readme":"# @br-geo-kit/address\n\n> Parse, render and validate a Brazilian postal address. Pure, offline,\n> no dependencies beyond the kit.\n\n```bash\npnpm add @br-geo-kit/address\n```\n\n---\n\n## Parsing a street line\n\nBrazilian addresses are written `logradouro, número, complemento`, but\nthe separators are not reliable: the comma before the number is often\nmissing, the complement is sometimes introduced with a dash, and a\nbuilding may be `s/n`.\n\n```ts\nimport { parseStreetLine } from '@br-geo-kit/address'\n\nparseStreetLine('Av. Paulista, 1578 - apto 42')\n// { street: 'Avenida Paulista', type: 'Avenida', name: 'Paulista',\n//   number: '1578', complement: 'apto 42', withoutNumber: false }\n\nparseStreetLine('Rua das Flores 123')      // number: '123'\nparseStreetLine('Rua XV de Novembro, s/n') // number: null, withoutNumber: true\nparseStreetLine('Rodovia BR 101')          // the 101 belongs to the road\n```\n\nAbbreviations are expanded — `Av.`, `av`, `AVENIDA` all become\n`Avenida` — because the same street arrives written four ways across\nfour systems, and a lookup keyed on the raw string finds none of them.\n\n**`withoutNumber` is not the same as `number === null`.** The first\nmeans the line said \"no number\" outright; the second means it did not\nmention one. A shipping form needs to tell a complete address from an\nincomplete one.\n\nIt never invents a number and never corrects spelling. Guessing that\n`Paulsta` meant `Paulista` is how a parcel ends up on the wrong street\nwith nobody having approved it.\n\n---\n\n## Rendering\n\nThe order is fixed by the Correios, not a matter of taste.\n\n```ts\nimport { formatAddress, formatAddressLines } from '@br-geo-kit/address'\n\nformatAddress(address)\n// 'Avenida Paulista, 1578, apto 42, Bela Vista, São Paulo - SP, 01310-100'\n\nformatAddressLines(address)\n// ['Avenida Paulista, 1578, apto 42', 'Bela Vista', 'São Paulo - SP', '01310-100']\n\nformatAddressLine(address)   // the one-line form a delivery app shows\n```\n\nMissing parts are dropped, never rendered as `null` or as an empty\nsegment with stray punctuation around it. A *CEP único* with no street\ncomes out as `Porto Velho - RO, 76800-000`, not\n`, , Porto Velho - RO, 76800-000`.\n\n---\n\n## Validating\n\n```ts\nimport { validateAddress, isValidAddress } from '@br-geo-kit/address'\n\nvalidateAddress(address)\n// [] — nothing wrong\n\nvalidateAddress({ cep: '123', city: '', state: 'XX' })\n// [ { field: 'cep', code: 'malformed', message: '...' },\n//   { field: 'city', code: 'required', ... },\n//   { field: 'state', code: 'malformed', ... } ]\n```\n\nReturns every issue, not the first — a form that reveals one problem per\nsubmission is a form people abandon. And returns them rather than\nthrowing, because a failed validation is an expected outcome.\n\nTwo defaults that look wrong and are not:\n\n- **A street is not required.** Roughly 1 200 municipalities are\n  addressed by a single CEP with no street. Requiring one rejects their\n  residents. Turn it on with `{ requireStreet: true }`.\n- **A number is not required.** A CEP lookup never returns one, so\n  validating a freshly-resolved address would report every one of them\n  as invalid. Turn it on with `{ requireNumber: true }` when checking\n  what a user submitted.\n\nThis validates *shape*, not existence. See\n[API conventions](https://github.com/arielff3/br-geo-kit/blob/main/docs/api-conventions.md)\nfor the three levels of \"valid\".\n\n---\n\n## Also here\n\nRe-exported from `@br-geo-kit/core` so a form needs one import:\n\n```ts\nimport { maskCep, formatCep, normalizeCep, isWellFormedCep, toUF } from '@br-geo-kit/address'\n\nmaskCep('013101')      // '01310-1' — progressive, for an input field\nformatCep('01310100')  // '01310-100'\nnormalizeCep(1310100)  // '01310100' — the leading zero a spreadsheet dropped\n```\n\n`maskCep` never returns `null`: a partial CEP is not an error while the\nuser is mid-keystroke.\n\n## Licence\n\nMIT\n","readmeFilename":"README.md","_rev":"1-a44c5bb620dcf5ae50b552cbdfd034bf"}