{"_id":"@0xd33p/vietnam-divisions","_rev":"2-8ab5ec4a41a11e838e845809a2d44b8e","name":"@0xd33p/vietnam-divisions","dist-tags":{"latest":"0.3.0"},"versions":{"0.2.0":{"name":"@0xd33p/vietnam-divisions","version":"0.2.0","_id":"@0xd33p/vietnam-divisions@0.2.0","maintainers":[{"name":"0xd33p","email":"hello.0xd33p@gmail.com"}],"dist":{"shasum":"6cfd0d4939fd9bd78a335a5a8d882044f0556309","tarball":"https://registry.npmjs.org/@0xd33p/vietnam-divisions/-/vietnam-divisions-0.2.0.tgz","fileCount":45,"integrity":"sha512-rz8bwNImcd/lS93chR5pbsD8In+3yL4W+WDiL8elt5b72bibCcT2OFhMDlNQkT/xsuOvriPziOq6yyVd+oDVxA==","signatures":[{"sig":"MEUCICI7uKRNo6H6jmSZ4Rjhbi1XwdKFIbJZUjJ8zwZxvM5ZAiEAwKNtFLXHbJTbjtXdtWiMTCfnxiOEEEzJh/ftKBr7dgY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":4756468},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"gitHead":"3a209c9f57211d14cdabd5e34f00562728a52e9b","scripts":{"dev":"tsx --watch src/index.ts","test":"vitest run","build":"tsc","test:watch":"vitest","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"0xd33p","email":"hello.0xd33p@gmail.com"},"_npmVersion":"11.13.0","description":"Vietnam administrative divisions — raw seed data + sync helpers (34 provinces, 3,321 communes, v3)","directories":{},"_nodeVersion":"24.17.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.22.4","vitest":"catalog:","typescript":"catalog:","@vitest/coverage-v8":"catalog:"},"_npmOperationalInternal":{"tmp":"tmp/vietnam-divisions_0.2.0_1783885540776_0.9391590431250847","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@0xd33p/vietnam-divisions","version":"0.3.0","publishConfig":{"access":"public"},"description":"Vietnam administrative divisions — raw seed data + sync helpers (34 provinces, 3,321 communes, v3)","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"scripts":{"dev":"tsx --watch src/index.ts","build":"tsc","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage"},"devDependencies":{"@vitest/coverage-v8":"catalog:","tsx":"^4.22.4","typescript":"catalog:","vitest":"catalog:"},"gitHead":"dc429fda1c17888227227f25fb0593245e6ab2ad","_id":"@0xd33p/vietnam-divisions@0.3.0","_nodeVersion":"24.17.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-AxVI5IhAKgt0OyH1bFE/y6Uq05cDlQlgMuelvFx26J/8Hsst3G0KQjnJzqKo6stnYtxQYta6c5SOeUgaYEwIaQ==","shasum":"7557efaa5a293ee66a676020d5ad77c42fbb436e","tarball":"https://registry.npmjs.org/@0xd33p/vietnam-divisions/-/vietnam-divisions-0.3.0.tgz","fileCount":49,"unpackedSize":4781720,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIB9cCjFUSTGjQENgHc5gsjPfTSnL76BAOi+iZtoIZfuuAiEAjDQTTfoo99+WbWpyC0YKk1jkohNKVRq7TXqOA7HrdDY="}]},"_npmUser":{"name":"0xd33p","email":"hello.0xd33p@gmail.com"},"directories":{},"maintainers":[{"name":"0xd33p","email":"hello.0xd33p@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/vietnam-divisions_0.3.0_1783893553385_0.9696755976916478"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-12T19:45:40.603Z","modified":"2026-07-12T21:59:13.646Z","0.2.0":"2026-07-12T19:45:40.953Z","0.3.0":"2026-07-12T21:59:13.557Z"},"description":"Vietnam administrative divisions — raw seed data + sync helpers (34 provinces, 3,321 communes, v3)","maintainers":[{"name":"0xd33p","email":"hello.0xd33p@gmail.com"}],"readme":"# @0xd33p/vietnam-divisions\n\nDữ liệu hành chính Việt Nam — không phụ thuộc runtime nào.\n\nCung cấp cả hệ thống **hiện tại** (34 tỉnh, sau sáp nhập 2025) và **cũ** (63 tỉnh) kèm tự động tra cứu ID giữa hai hệ thống.\n\n---\n\n## Cài đặt\n\n```bash\nnpm install @0xd33p/vietnam-divisions\n```\n\n## Bắt đầu nhanh\n\n```typescript\nimport { vn } from '@0xd33p/vietnam-divisions';\n\n// Danh sách tỉnh hiện tại\nconst { data: tinh } = vn.divisions();\n\n// Danh sách xã/phường theo tỉnh\nconst { data: xa } = vn.divisions('79'); // TP.HCM\n\n// Tra cứu theo ID, mã, hoặc tên (tự động resolve ID cũ)\nconst tinhTra = vn.lookup('HCM');\nconst phuong = vn.lookup('00004');\n\n// Tìm kiếm theo tên\nconst ketQua = vn.search('Hồ Chí Minh');\n\n// Hệ thống cũ (63 tỉnh, 3 cấp)\nconst { data: tinhCu } = vn.legacy.divisions();\nconst { data: huyen } = vn.legacy.divisions('01');\n```\n\n---\n\n## API\n\n### `vn.divisions(maTinh?)`\n\n| Đầu vào   | Kết quả                 |\n| --------- | ----------------------- |\n| _(không)_ | 34 tỉnh hiện tại        |\n| `\"79\"`    | Xã/phường thuộc tỉnh đó |\n\n### `vn.lookup(truyVan)`\n\nChấp nhận: ID tỉnh (`\"79\"`), mã tỉnh (`\"HCM\"`), ID xã (`\"00004\"`), hoặc tên đầy đủ.\n\nTự động resolve ID cũ sang ID mới.\n\n### `vn.search(ten, maTinh?)`\n\nTìm mờ theo tên (không phân biệt hoa thường). Có `maTinh` thì giới hạn trong tỉnh đó.\n\n### `vn.addressLookup(diaChi)`\n\nPhân tích địa chỉ dạng chuỗi và trả về kết quả khớp ở **cả hai** hệ thống.\n\n```typescript\nconst ketQua = vn.addressLookup(\n  'Thôn Nghĩa Thắng, Đông Hòa, TP Thái Bình, Thái Bình',\n);\n// {\n//   legacy: { province: { id: '34', name: 'Tỉnh Thái Bình' }, ... },\n//   v3:     { province: { id: '33', name: 'Hưng Yên' }, ... },\n// }\n```\n\nTính năng:\n\n- Tự động tách thành phần (dấu phẩy, nhận diện cấp)\n- Không phân biệt có dấu / không dấu (`\"Thai Binh\"` → `\"Thái Bình\"`)\n- Mở rộng viết tắt (`\"TP\"` → `\"Thành phố\"`)\n- Chế độ chặt: báo lỗi nếu thiếu hoặc không xác định được tỉnh\n\n### `vn.legacy.*`\n\n3 phương thức tương tự (`divisions`, `lookup`, `search`) cho hệ thống 63 tỉnh cũ với 3 cấp (tỉnh → huyện → xã).\n\n---\n\n## Kiểu dữ liệu\n\n| Kiểu                  | Mô tả                                        |\n| --------------------- | -------------------------------------------- |\n| `GeoUnit`             | `{ id: string; name: string }`               |\n| `GeoResult<T>`        | `{ data: T }` — thành công                   |\n| `GeoErrorResult`      | `{ data: null; error: GeoError }` — thất bại |\n| `GeoError`            | 11 mã lỗi dạng discriminated union           |\n| `AddressLookupResult` | `{ legacy: {...}, v3: {...} }`               |\n\n---\n\n## Dữ liệu\n\n| Hệ thống      | Tỉnh | Huyện | Xã     |\n| ------------- | ---- | ----- | ------ |\n| v3 (hiện tại) | 34   | —     | 3.321  |\n| Cũ            | 63   | 696   | 10.051 |\n\nHệ thống v3 áp dụng theo Nghị quyết 202/2025/QH15 (sáp nhập tỉnh có hiệu lực từ 2025).\n\n---\n\n## Ứng dụng\n\n- **Form địa chỉ** — đổ dữ liệu tỉnh/xã vào dropdown\n- **Xác thực địa chỉ** — kiểm tra địa chỉ nhập vào có hợp lệ không\n- **Chuyển đổi dữ liệu** — map địa chỉ cũ sang hệ thống mới\n","readmeFilename":"README.md"}