@0xd33p/vietnam-divisions 0.2.0

package/README.md

@@ -0,0 +1,80 @@
+# @0xd33p/vietnam-divisions — Dữ liệu hành chính Việt Nam
+
+Package nội bộ — zero runtime dependencies. Quản lý 2 hệ thống dữ liệu (v3 hiện tại &
+legacy cũ) với auto-detect và auto-resolve ID.
+
+## API
+
+1 object `vn` — unified deep module. 3 methods, 3 types.
+
+```typescript
+import { vn } from '@0xd33p/vietnam-divisions';
+import type { GeoUnit, GeoError, GeoResult } from '@0xd33p/vietnam-divisions';
+```
+
+| Method                               | Input            | Output                                     |
+| ------------------------------------ | ---------------- | ------------------------------------------ |
+| `vn.divisions()`                     | —                | 34 tỉnh (v3)                               |
+| `vn.divisions(provinceId)`           | `string`         | Xã/phường theo tỉnh                        |
+| `vn.lookup(query)`                   | `string`         | Tra cứu ID/mã/tên — auto-resolve legacy ID |
+| `vn.search(name)`                    | `string`         | Tìm tỉnh theo tên                          |
+| `vn.search(name, provinceId)`        | `string, string` | Tìm xã theo tên trong tỉnh                 |
+| `vn.legacy.divisions()`              | —                | 63 tỉnh (legacy)                           |
+| `vn.legacy.divisions(provinceId)`    | `string`         | Huyện theo tỉnh                            |
+| `vn.legacy.lookup(query)`            | `string`         | Tra cứu legacy ID (tỉnh/huyện/xã)          |
+| `vn.legacy.search(name)`             | `string`         | Tìm tỉnh legacy theo tên                   |
+| `vn.legacy.search(name, provinceId)` | `string, string` | Tìm huyện theo tên trong tỉnh              |
+
+Output type cho tất cả method: `GeoResult<T> | GeoErrorResult` (legacy methods cũng
+vậy — unified error handling).
+
+## Types
+
+| Type             | Mô tả                                                           |
+| ---------------- | --------------------------------------------------------------- |
+| `GeoUnit`        | `{ id: string; name: string }`                                  |
+| `GeoError`       | `'province_not_found' \| 'commune_not_found' \| ...` (9 errors) |
+| `GeoResult<T>`   | `{ data: T }` — success                                         |
+| `GeoErrorResult` | `{ data: null; error: GeoError }` — failure                     |
+
+## Ví dụ
+
+```typescript
+// 34 tỉnh mới
+const { data: provinces } = vn.divisions();
+
+// Xã/phường theo tỉnh (cần 2-char ID)
+const { data: communes } = vn.divisions('79');
+
+// Tra cứu — auto-resolve old ID → new ID
+const result = vn.lookup('79'); // province by ID → { name: 'Hồ Chí Minh', kind: 'province' }
+const hcm = vn.lookup('HCM'); // province by code
+const hn = vn.lookup('01'); // province by ID
+const ward = vn.lookup('27148'); // commune by ID
+
+// Tìm kiếm
+const found = vn.search('Hồ Chí Minh');
+const wards = vn.search('Phường', '79');
+
+// Legacy — 63 tỉnh, 3 cấp (province → district → commune)
+const { data: oldProvinces } = vn.legacy.divisions();
+const { data: huyen } = vn.legacy.divisions('01');
+const { data: oldWard } = vn.legacy.lookup('00100');
+```
+
+## Hidden
+
+- **Auto-detect**: `lookup()` nhận ID 2-char (tỉnh), 3-char (mã), 5-char (xã), hoặc tên
+- **Auto-resolve**: old province/commune IDs → new IDs qua merge/mapping data
+
+## File structure
+
+```
+src/
+├── index.ts          # vn object (public API)
+├── types.ts          # GeoUnit, GeoError, GeoResult, GeoErrorResult
+├── data/
+│   ├── v3/           # 34 tỉnh (NQ 202/2025/QH15)
+│   └── legacy/       # 63 tỉnh, 696 huyện, 10,051 xã (cũ)
+└── internal/         # Implementation
+```

package/dist/__tests__/vn.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=vn.test.d.ts.map

package/dist/__tests__/vn.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vn.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/vn.test.ts"],"names":[],"mappings":""}