@0xd33p/vietnam-divisions 0.2.0

package/dist/__tests__/vn.test.js

@@ -0,0 +1,1107 @@
+import { describe, it, expect } from 'vitest';
+import { vn } from '../index.js';
+import { provinceMerges, wardMappings } from '../internal/v3/index.js';
+// ─── Helper: type guards ──────────────────────────────
+function isSuccess(r) {
+    return r.data !== null && !('error' in r);
+}
+function isError(r) {
+    return r.data === null && 'error' in r;
+}
+// ─── vn.divisions() ────────────────────────────────────
+describe('vn.divisions()', () => {
+    it('returns 34 provinces (v3 system) when called without args', () => {
+        const r = vn.divisions();
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data).toHaveLength(34);
+        }
+    });
+    it('each province has id and name string', () => {
+        const r = vn.divisions();
+        if (isSuccess(r)) {
+            for (const p of r.data) {
+                expect(p).toHaveProperty('id');
+                expect(p).toHaveProperty('name');
+                expect(typeof p.id).toBe('string');
+                expect(typeof p.name).toBe('string');
+                expect(p.id.length).toBeGreaterThan(0);
+                expect(p.name.length).toBeGreaterThan(0);
+            }
+        }
+    });
+    it('first province is Hà Nội (id: 01)', () => {
+        const r = vn.divisions();
+        if (isSuccess(r)) {
+            expect(r.data[0]).toEqual({ id: '01', name: 'Thành phố Hà Nội' });
+        }
+    });
+    it('last province is Cà Mau (id: 96)', () => {
+        const r = vn.divisions();
+        if (isSuccess(r)) {
+            const last = r.data[r.data.length - 1];
+            expect(last).toEqual({ id: '96', name: 'Cà Mau' });
+        }
+    });
+    it('includes HCM (id: 79)', () => {
+        const r = vn.divisions();
+        if (isSuccess(r)) {
+            expect(r.data).toContainEqual({
+                id: '79',
+                name: 'Thành phố Hồ Chí Minh',
+            });
+        }
+    });
+    it('includes Đà Nẵng (id: 48)', () => {
+        const r = vn.divisions();
+        if (isSuccess(r)) {
+            expect(r.data).toContainEqual({ id: '48', name: 'Thành phố Đà Nẵng' });
+        }
+    });
+});
+// ─── vn.divisions(parentId) ────────────────────────────
+describe('vn.divisions(parentId)', () => {
+    it('returns communes for a valid provinceId', () => {
+        const r = vn.divisions('79');
+        expect(isSuccess(r)).toBe(true);
+    });
+    it('HCM (79) has ~168 communes', () => {
+        const r = vn.divisions('79');
+        if (isSuccess(r)) {
+            expect(r.data.length).toBeGreaterThan(100);
+            expect(r.data.length).toBeLessThan(300);
+        }
+    });
+    it('each commune has id and name', () => {
+        const r = vn.divisions('79');
+        if (isSuccess(r)) {
+            for (const c of r.data) {
+                expect(c).toHaveProperty('id');
+                expect(c).toHaveProperty('name');
+                expect(typeof c.id).toBe('string');
+                expect(typeof c.name).toBe('string');
+                expect(c.id.length).toBeGreaterThan(0);
+                expect(c.name.length).toBeGreaterThan(0);
+            }
+        }
+    });
+    it('Hà Nội (01) communes start with "Phường Ba Đình"', () => {
+        const r = vn.divisions('01');
+        if (isSuccess(r)) {
+            expect(r.data[0].name).toContain('Ba Đình');
+        }
+    });
+    it('returns error for invalid provinceId', () => {
+        const r = vn.divisions('invalid_id');
+        expect(isError(r)).toBe(true);
+        if (isError(r)) {
+            expect(r.error).toBe('empty_commune_list');
+        }
+    });
+    it('returns error for empty string', () => {
+        const r = vn.divisions('');
+        expect(isError(r)).toBe(true);
+        if (isError(r)) {
+            expect(r.error).toBe('invalid_province_id');
+        }
+    });
+});
+// ─── vn.lookup() ──────────────────────────────────────
+describe('vn.lookup()', () => {
+    it('finds province by numeric ID "79" → HCM', () => {
+        const r = vn.lookup('79');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data).toEqual({
+                id: '79',
+                name: 'Thành phố Hồ Chí Minh',
+                kind: 'province',
+            });
+        }
+    });
+    it('finds province by 3-letter code "HCM"', () => {
+        const r = vn.lookup('HCM');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data).toEqual({
+                id: '79',
+                name: 'Thành phố Hồ Chí Minh',
+                kind: 'province',
+            });
+        }
+    });
+    it('finds province by lowercase code "hcm"', () => {
+        const r = vn.lookup('hcm');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data.id).toBe('79');
+        }
+    });
+    it('finds Hà Nội by ID "01"', () => {
+        const r = vn.lookup('01');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data).toEqual({
+                id: '01',
+                name: 'Thành phố Hà Nội',
+                kind: 'province',
+            });
+        }
+    });
+    it('finds Hà Nội by code "HNI"', () => {
+        const r = vn.lookup('HNI');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data.id).toBe('01');
+        }
+    });
+    it('finds HCM by full name', () => {
+        const r = vn.lookup('Thành phố Hồ Chí Minh');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data).toEqual({
+                id: '79',
+                name: 'Thành phố Hồ Chí Minh',
+                kind: 'province',
+            });
+        }
+    });
+    it('returns error for invalid query', () => {
+        const r = vn.lookup('NONEXISTENT');
+        expect(isError(r)).toBe(true);
+        if (isError(r)) {
+            expect(r.error).toBe('province_not_found');
+        }
+    });
+    it('returns error for empty string', () => {
+        const r = vn.lookup('');
+        expect(isError(r)).toBe(true);
+        if (isError(r)) {
+            expect(r.error).toBe('invalid_query');
+        }
+    });
+});
+// ─── vn.legacy.divisions() ─────────────────────────────
+describe('vn.legacy.divisions()', () => {
+    it('returns 63 provinces when called without args', () => {
+        const r = vn.legacy.divisions();
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data).toHaveLength(63);
+        }
+    });
+    it('each has id and name string', () => {
+        const r = vn.legacy.divisions();
+        if (isSuccess(r)) {
+            for (const p of r.data) {
+                expect(p).toHaveProperty('id');
+                expect(p).toHaveProperty('name');
+                expect(typeof p.id).toBe('string');
+                expect(typeof p.name).toBe('string');
+            }
+        }
+    });
+    it('includes old provinces like "Tỉnh Hà Giang"', () => {
+        const r = vn.legacy.divisions();
+        if (isSuccess(r)) {
+            expect(r.data).toContainEqual({ id: '02', name: 'Tỉnh Hà Giang' });
+        }
+    });
+});
+// ─── vn.legacy.divisions(parentId) ─────────────────────
+describe('vn.legacy.divisions(parentId)', () => {
+    it('Hà Nội (01) has 30 districts', () => {
+        const r = vn.legacy.divisions('01');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data).toHaveLength(30);
+        }
+    });
+    it('each district has id and name', () => {
+        const r = vn.legacy.divisions('01');
+        if (isSuccess(r)) {
+            for (const d of r.data) {
+                expect(d).toHaveProperty('id');
+                expect(d).toHaveProperty('name');
+                expect(typeof d.id).toBe('string');
+                expect(typeof d.name).toBe('string');
+            }
+        }
+    });
+    it('first district is "Quận Ba Đình"', () => {
+        const r = vn.legacy.divisions('01');
+        if (isSuccess(r)) {
+            expect(r.data[0]).toEqual({ id: '001', name: 'Quận Ba Đình' });
+        }
+    });
+    it('returns error for invalid provinceId', () => {
+        const r = vn.legacy.divisions('invalid');
+        expect(isError(r)).toBe(true);
+        if (isError(r)) {
+            expect(r.error).toBe('empty_district_list');
+        }
+    });
+    it('returns error for empty string', () => {
+        const r = vn.legacy.divisions('');
+        expect(isError(r)).toBe(true);
+        if (isError(r)) {
+            expect(r.error).toBe('invalid_province_id');
+        }
+    });
+});
+// ─── Data integrity ───────────────────────────────────
+describe('data integrity', () => {
+    describe('v3 provinces', () => {
+        it('all province IDs are unique', () => {
+            const r = vn.divisions();
+            if (isSuccess(r)) {
+                const ids = r.data.map((p) => p.id);
+                expect(new Set(ids).size).toBe(ids.length);
+            }
+        });
+    });
+    describe('v3 communes', () => {
+        it('all commune IDs are unique', () => {
+            const r = vn.divisions();
+            if (isSuccess(r)) {
+                const allIds = [];
+                for (const p of r.data) {
+                    const divisions = vn.divisions(p.id);
+                    if (isSuccess(divisions)) {
+                        allIds.push(...divisions.data.map((c) => c.id));
+                    }
+                }
+                expect(new Set(allIds).size).toBe(allIds.length);
+                expect(allIds.length).toBe(3321);
+            }
+        });
+        it('every commune belongs to a valid province', () => {
+            const r = vn.divisions();
+            if (isSuccess(r)) {
+                for (const p of r.data) {
+                    const divisions = vn.divisions(p.id);
+                    if (isSuccess(divisions)) {
+                        expect(divisions.data.length).toBeGreaterThan(0);
+                    }
+                }
+            }
+        });
+    });
+    describe('legacy provinces', () => {
+        it('all legacy province IDs are unique', () => {
+            const r = vn.legacy.divisions();
+            if (isSuccess(r)) {
+                const ids = r.data.map((p) => p.id);
+                expect(new Set(ids).size).toBe(ids.length);
+            }
+        });
+    });
+    describe('legacy districts', () => {
+        it('all district IDs within a province are unique', () => {
+            const rp = vn.legacy.divisions();
+            if (isSuccess(rp)) {
+                for (const p of rp.data) {
+                    const rd = vn.legacy.divisions(p.id);
+                    if (isSuccess(rd)) {
+                        const ids = rd.data.map((d) => d.id);
+                        expect(new Set(ids).size).toBe(ids.length);
+                    }
+                }
+            }
+        });
+        it('every district belongs to a valid province', () => {
+            const rp = vn.legacy.divisions();
+            if (isSuccess(rp)) {
+                const provinceIds = new Set(rp.data.map((p) => p.id));
+                for (const p of rp.data) {
+                    const rd = vn.legacy.divisions(p.id);
+                    if (isSuccess(rd)) {
+                        for (const d of rd.data) {
+                            expect(d.id.length).toBeGreaterThan(0);
+                        }
+                    }
+                }
+            }
+        });
+    });
+    describe('legacy communes', () => {
+        it('every district lookup by 3-char ID returns district kind', () => {
+            const rp = vn.legacy.divisions();
+            if (isSuccess(rp)) {
+                for (const p of rp.data) {
+                    const rd = vn.legacy.divisions(p.id);
+                    if (isSuccess(rd) && rd.data.length > 0) {
+                        const firstDistrict = rd.data[0];
+                        const lookup = vn.legacy.lookup(firstDistrict.id);
+                        expect(isSuccess(lookup)).toBe(true);
+                        if (isSuccess(lookup)) {
+                            expect(lookup.data.kind).toBe('district');
+                        }
+                    }
+                }
+            }
+        });
+    });
+});
+// ─── Discriminated union shape ─────────────────────────
+describe('GeoResult / GeoErrorResult type shape', () => {
+    it('success result has data but no error property', () => {
+        const r = vn.divisions();
+        if (isSuccess(r)) {
+            expect(r).toHaveProperty('data');
+            expect(r).not.toHaveProperty('error');
+        }
+    });
+    it('error result has data=null and string error', () => {
+        const r = vn.divisions('');
+        if (isError(r)) {
+            expect(r.data).toBeNull();
+            expect(typeof r.error).toBe('string');
+        }
+    });
+});
+// ─── Block A: vn.divisions() — edge cases ───────────────
+describe('vn.divisions() — edge cases and boundary inputs', () => {
+    it('REGRESSION: null parentId → throws TypeError (TypeScript prevents at compile time)', () => {
+        expect(() => vn.divisions(null)).toThrow(TypeError);
+    });
+    it('EDGE: undefined parentId → treated as no-arg, returns 34 provinces', () => {
+        const r = vn.divisions(undefined);
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r))
+            expect(r.data).toHaveLength(34);
+    });
+    it('EDGE: whitespace "   " parentId → empty_commune_list (not trimmed)', () => {
+        const r = vn.divisions('   ');
+        expect(isError(r)).toBe(true);
+        if (isError(r))
+            expect(r.error).toBe('empty_commune_list');
+    });
+    it('EDGE: padded " 79 " parentId → empty_commune_list (NOT trimmed to "79")', () => {
+        const r = vn.divisions(' 79 ');
+        expect(isError(r)).toBe(true);
+        if (isError(r))
+            expect(r.error).toBe('empty_commune_list');
+    });
+    it('EDGE: "0" parentId → empty_commune_list', () => {
+        const r = vn.divisions('0');
+        expect(isError(r)).toBe(true);
+        if (isError(r))
+            expect(r.error).toBe('empty_commune_list');
+    });
+    it('EDGE: 100-char parentId → empty_commune_list', () => {
+        const r = vn.divisions('a'.repeat(100));
+        expect(isError(r)).toBe(true);
+        if (isError(r))
+            expect(r.error).toBe('empty_commune_list');
+    });
+    it('EDGE: special chars "!@#$%" parentId → empty_commune_list', () => {
+        const r = vn.divisions('!@#$%');
+        expect(isError(r)).toBe(true);
+        if (isError(r))
+            expect(r.error).toBe('empty_commune_list');
+    });
+    it('DATA_INTEGRITY: all 34 provinces → each has ≥1 commune', () => {
+        const r = vn.divisions();
+        if (isSuccess(r)) {
+            for (const p of r.data) {
+                const communes = vn.divisions(p.id);
+                expect(isSuccess(communes)).toBe(true);
+                if (isSuccess(communes)) {
+                    expect(communes.data.length).toBeGreaterThan(0);
+                }
+            }
+        }
+    });
+});
+// ─── Block B: vn.lookup() — complete branch coverage ────
+describe('vn.lookup() — complete branch coverage', () => {
+    // === Happy paths (already in existing tests, adding more) ===
+    // === Auto-resolve: old province ID merge ===
+    it('MAPPING: old province ID "74" (Bình Dương) → resolves to HCM (79)', () => {
+        const r = vn.lookup('74');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data.id).toBe('79');
+            expect(r.data.name).toBe('Thành phố Hồ Chí Minh');
+            expect(r.data.kind).toBe('province');
+        }
+    });
+    it('MAPPING: old province ID "77" (Bà Rịa-Vũng Tàu) → resolves to HCM (79)', () => {
+        const r = vn.lookup('77');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data.id).toBe('79');
+            expect(r.data.name).toBe('Thành phố Hồ Chí Minh');
+            expect(r.data.kind).toBe('province');
+        }
+    });
+    it('MAPPING: old province ID "58" (Ninh Thuận) → resolves to Khánh Hòa (56)', () => {
+        const r = vn.lookup('58');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data.id).toBe('56');
+            expect(r.data.name).toBe('Khánh Hòa');
+            expect(r.data.kind).toBe('province');
+        }
+    });
+    // === Auto-resolve: old commune ID mapping ===
+    it('MAPPING: old ward code "26881" → resolves to new ward "26882"', () => {
+        const r = vn.lookup('26881');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data.id).toBe('26882');
+            expect(r.data.kind).toBe('ward');
+        }
+    });
+    // === Direct commune ID lookup ===
+    it('EXACT MATCH: commune ID "00004" → Phường Ba Đình (ward)', () => {
+        const r = vn.lookup('00004');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data).toEqual({
+                id: '00004',
+                name: 'Phường Ba Đình',
+                kind: 'ward',
+            });
+        }
+    });
+    it('EXACT MATCH: commune ID "00008" → Phường Ngọc Hà (ward)', () => {
+        const r = vn.lookup('00008');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data).toEqual({
+                id: '00008',
+                name: 'Phường Ngọc Hà',
+                kind: 'ward',
+            });
+        }
+    });
+    // === Edge inputs ===
+    it('EDGE: null query → invalid_query', () => {
+        const r = vn.lookup(null);
+        expect(isError(r)).toBe(true);
+        if (isError(r))
+            expect(r.error).toBe('invalid_query');
+    });
+    it('EDGE: undefined query → invalid_query', () => {
+        const r = vn.lookup(undefined);
+        expect(isError(r)).toBe(true);
+        if (isError(r))
+            expect(r.error).toBe('invalid_query');
+    });
+    it('KNOWN_DATA_QUIRK: whitespace "   " trims to "" and matches empty oldWardCode mapping → unexpected ward', () => {
+        // NOTE: There is a ward mapping with oldWardCode="" in the data,
+        // so lookup("   ") accidentally resolves to that ward.
+        const r = vn.lookup('   ');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data.kind).toBe('ward');
+            expect(r.data.id).toBe('11948');
+        }
+    });
+    it('EDGE: padded valid code "  HCM  " → trims to "HCM" → HCM', () => {
+        const r = vn.lookup('  HCM  ');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data.id).toBe('79');
+            expect(r.data.name).toBe('Thành phố Hồ Chí Minh');
+        }
+    });
+    it('EDGE: padded valid ID " 79 " → trims to "79" → HCM', () => {
+        const r = vn.lookup(' 79 ');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data.id).toBe('79');
+            expect(r.data.name).toBe('Thành phố Hồ Chí Minh');
+        }
+    });
+    // === Non-standard lengths ===
+    it('EDGE: 1-char "a" → province_not_found', () => {
+        const r = vn.lookup('a');
+        expect(isError(r)).toBe(true);
+        if (isError(r))
+            expect(r.error).toBe('province_not_found');
+    });
+    it('EDGE: 2-char non-numeric "ab" → province_not_found', () => {
+        const r = vn.lookup('ab');
+        expect(isError(r)).toBe(true);
+        if (isError(r))
+            expect(r.error).toBe('province_not_found');
+    });
+    it('EDGE: 3-char nonexistent code "ABC" → province_not_found', () => {
+        const r = vn.lookup('ABC');
+        expect(isError(r)).toBe(true);
+        if (isError(r))
+            expect(r.error).toBe('province_not_found');
+    });
+    it('EDGE: 4-char "abcd" → falls through to name search → province_not_found', () => {
+        const r = vn.lookup('abcd');
+        expect(isError(r)).toBe(true);
+        if (isError(r))
+            expect(r.error).toBe('province_not_found');
+    });
+    it('EDGE: 6-char "abcdef" → falls through to name search → province_not_found', () => {
+        const r = vn.lookup('abcdef');
+        expect(isError(r)).toBe(true);
+        if (isError(r))
+            expect(r.error).toBe('province_not_found');
+    });
+    it('EDGE: very long string (100 chars) → province_not_found', () => {
+        const r = vn.lookup('x'.repeat(100));
+        expect(isError(r)).toBe(true);
+        if (isError(r))
+            expect(r.error).toBe('province_not_found');
+    });
+    // === Unicode/case ===
+    it('UNICODE: "hồ chí minh" lowercase with diacritics → finds HCM via name search', () => {
+        const r = vn.lookup('hồ chí minh');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data.id).toBe('79');
+            expect(r.data.name).toBe('Thành phố Hồ Chí Minh');
+        }
+    });
+    it('UNICODE: "HÀ NỘI" uppercase with diacritics → finds Hà Nội via name search', () => {
+        const r = vn.lookup('HÀ NỘI');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data.id).toBe('01');
+            expect(r.data.name).toBe('Thành phố Hà Nội');
+        }
+    });
+    // === Special characters ===
+    it('EDGE: "HCM!" with trailing special char → province_not_found', () => {
+        const r = vn.lookup('HCM!');
+        expect(isError(r)).toBe(true);
+        if (isError(r))
+            expect(r.error).toBe('province_not_found');
+    });
+    // === 2-digit numeric not in any data ===
+    it('EDGE: nonexistent 2-char "99" → province_not_found', () => {
+        const r = vn.lookup('99');
+        expect(isError(r)).toBe(true);
+        if (isError(r))
+            expect(r.error).toBe('province_not_found');
+    });
+});
+// ─── Block C: vn.search() — complete from scratch ───────
+describe('vn.search() — complete test suite', () => {
+    // === Empty/edge inputs ===
+    it('EDGE: "" → ok([])', () => {
+        const r = vn.search('');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r))
+            expect(r.data).toEqual([]);
+    });
+    it('EDGE: "   " (whitespace) → ok([])', () => {
+        const r = vn.search('   ');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r))
+            expect(r.data).toEqual([]);
+    });
+    it('EDGE: null → ok([])', () => {
+        const r = vn.search(null);
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r))
+            expect(r.data).toEqual([]);
+    });
+    // === Search provinces (no parentId) ===
+    it('EXACT MATCH: "Cà Mau" → returns exactly 1 province', () => {
+        const r = vn.search('Cà Mau');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data).toHaveLength(1);
+            expect(r.data[0].name).toBe('Cà Mau');
+        }
+    });
+    it('PARTIAL MATCH: "Hà" → returns provinces containing "Hà" (multiple)', () => {
+        const r = vn.search('Hà');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data.length).toBeGreaterThanOrEqual(3);
+            const names = r.data.map((d) => d.name);
+            expect(names).toContain('Thành phố Hà Nội');
+            expect(names).toContain('Hà Tĩnh');
+        }
+    });
+    it('NO MATCH: "XYZXYZ" → ok([])', () => {
+        const r = vn.search('XYZXYZ');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r))
+            expect(r.data).toEqual([]);
+    });
+    it('UNICODE: "HÀ NỘI" uppercase diacritics → returns Hà Nội', () => {
+        const r = vn.search('HÀ NỘI');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data).toHaveLength(1);
+            expect(r.data[0].name).toBe('Thành phố Hà Nội');
+        }
+    });
+    // === Search communes (with parentId) ===
+    it('PARTIAL MATCH: "Phường" with parentId "79" → returns matching wards in HCM', () => {
+        const r = vn.search('Phường', '79');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data.length).toBeGreaterThan(0);
+        }
+    });
+    it('EXACT MATCH: "Ba Đình" with parentId "01" → returns matching commune in Hà Nội', () => {
+        const r = vn.search('Ba Đình', '01');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data.length).toBeGreaterThanOrEqual(1);
+            expect(r.data[0].name).toBe('Phường Ba Đình');
+        }
+    });
+    it('NO MATCH: "XYZXYZ" with parentId "79" → ok([])', () => {
+        const r = vn.search('XYZXYZ', '79');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r))
+            expect(r.data).toEqual([]);
+    });
+    it('EDGE: "" with parentId "79" → ok([])', () => {
+        const r = vn.search('', '79');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r))
+            expect(r.data).toEqual([]);
+    });
+    it('EDGE: search with invalid parentId "99" → ok([]) because no communes', () => {
+        const r = vn.search('Phường', '99');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r))
+            expect(r.data).toEqual([]);
+    });
+});
+// ─── Block D: vn.legacy.divisions() — edge cases ────────
+describe('vn.legacy.divisions() — edge cases and boundary inputs', () => {
+    it('REGRESSION: null parentId → throws TypeError', () => {
+        expect(() => vn.legacy.divisions(null)).toThrow(TypeError);
+    });
+    it('EDGE: undefined parentId → treated as no-arg, returns 63 provinces', () => {
+        const r = vn.legacy.divisions(undefined);
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r))
+            expect(r.data).toHaveLength(63);
+    });
+    it('EDGE: whitespace " 01 " parentId → empty_district_list', () => {
+        const r = vn.legacy.divisions(' 01 ');
+        expect(isError(r)).toBe(true);
+        if (isError(r))
+            expect(r.error).toBe('empty_district_list');
+    });
+    it('EDGE: "0" parentId → empty_district_list', () => {
+        const r = vn.legacy.divisions('0');
+        expect(isError(r)).toBe(true);
+        if (isError(r))
+            expect(r.error).toBe('empty_district_list');
+    });
+    it('EDGE: special chars "!@#$%" parentId → empty_district_list', () => {
+        const r = vn.legacy.divisions('!@#$%');
+        expect(isError(r)).toBe(true);
+        if (isError(r))
+            expect(r.error).toBe('empty_district_list');
+    });
+    it('EDGE: 100-char parentId → empty_district_list', () => {
+        const r = vn.legacy.divisions('a'.repeat(100));
+        expect(isError(r)).toBe(true);
+        if (isError(r))
+            expect(r.error).toBe('empty_district_list');
+    });
+});
+// ─── Block E: vn.legacy.lookup() — complete from scratch ─
+describe('vn.legacy.lookup() — complete test suite', () => {
+    // === Province ID (2-char) ===
+    it('EXACT MATCH: "01" → Hà Nội, kind: province', () => {
+        const r = vn.legacy.lookup('01');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data).toEqual({
+                id: '01',
+                name: 'Thành phố Hà Nội',
+                kind: 'province',
+            });
+        }
+    });
+    it('EXACT MATCH: "79" → HCM, kind: province', () => {
+        const r = vn.legacy.lookup('79');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data).toEqual({
+                id: '79',
+                name: 'Thành phố Hồ Chí Minh',
+                kind: 'province',
+            });
+        }
+    });
+    // === District ID (3-char) ===
+    it('EXACT MATCH: "001" → Quận Ba Đình, kind: district', () => {
+        const r = vn.legacy.lookup('001');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data).toEqual({
+                id: '001',
+                name: 'Quận Ba Đình',
+                kind: 'district',
+            });
+        }
+    });
+    it('EXACT MATCH: "002" → Quận Hoàn Kiếm, kind: district', () => {
+        const r = vn.legacy.lookup('002');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data).toEqual({
+                id: '002',
+                name: 'Quận Hoàn Kiếm',
+                kind: 'district',
+            });
+        }
+    });
+    // === Commune ID (5-char) ===
+    it('EXACT MATCH: "00001" → Phường Phúc Xá, kind: ward', () => {
+        const r = vn.legacy.lookup('00001');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data).toEqual({
+                id: '00001',
+                name: 'Phường Phúc Xá',
+                kind: 'ward',
+            });
+        }
+    });
+    it('EXACT MATCH: "00004" → Phường Trúc Bạch, kind: ward', () => {
+        const r = vn.legacy.lookup('00004');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data).toEqual({
+                id: '00004',
+                name: 'Phường Trúc Bạch',
+                kind: 'ward',
+            });
+        }
+    });
+    // === Name lookup ===
+    it('EXACT MATCH: "Thành phố Hà Nội" → exact match by name, kind: province', () => {
+        const r = vn.legacy.lookup('Thành phố Hà Nội');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data.id).toBe('01');
+            expect(r.data.kind).toBe('province');
+        }
+    });
+    it('EXACT MATCH: "Tỉnh Hà Giang" → exact match by name, kind: province', () => {
+        const r = vn.legacy.lookup('Tỉnh Hà Giang');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data.id).toBe('02');
+            expect(r.data.kind).toBe('province');
+        }
+    });
+    // === Edge/error ===
+    it('EDGE: "" → invalid_query', () => {
+        const r = vn.legacy.lookup('');
+        expect(isError(r)).toBe(true);
+        if (isError(r))
+            expect(r.error).toBe('invalid_query');
+    });
+    it('EDGE: "99" nonexistent 2-char → province_not_found', () => {
+        const r = vn.legacy.lookup('99');
+        expect(isError(r)).toBe(true);
+        if (isError(r))
+            expect(r.error).toBe('province_not_found');
+    });
+    it('EDGE: "999" nonexistent 3-char → province_not_found', () => {
+        const r = vn.legacy.lookup('999');
+        expect(isError(r)).toBe(true);
+        if (isError(r))
+            expect(r.error).toBe('province_not_found');
+    });
+    it('EDGE: "99999" nonexistent 5-char → province_not_found', () => {
+        const r = vn.legacy.lookup('99999');
+        expect(isError(r)).toBe(true);
+        if (isError(r))
+            expect(r.error).toBe('province_not_found');
+    });
+    it('EDGE: "XYZXYZ" → province_not_found', () => {
+        const r = vn.legacy.lookup('XYZXYZ');
+        expect(isError(r)).toBe(true);
+        if (isError(r))
+            expect(r.error).toBe('province_not_found');
+    });
+});
+// ─── Block F: vn.legacy.search() — complete from scratch ─
+describe('vn.legacy.search() — complete test suite', () => {
+    it('EDGE: "" → ok([])', () => {
+        const r = vn.legacy.search('');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r))
+            expect(r.data).toEqual([]);
+    });
+    it('EDGE: "   " → ok([])', () => {
+        const r = vn.legacy.search('   ');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r))
+            expect(r.data).toEqual([]);
+    });
+    it('EDGE: null → ok([])', () => {
+        const r = vn.legacy.search(null);
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r))
+            expect(r.data).toEqual([]);
+    });
+    // Search provinces (no parentId)
+    it('PARTIAL MATCH: "Hà" → multiple provinces', () => {
+        const r = vn.legacy.search('Hà');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data.length).toBeGreaterThanOrEqual(3);
+            const names = r.data.map((d) => d.name);
+            expect(names).toContain('Thành phố Hà Nội');
+            expect(names).toContain('Tỉnh Hà Giang');
+        }
+    });
+    it('EXACT MATCH: "Cà Mau" → 1 province matches legacy name', () => {
+        const r = vn.legacy.search('Cà Mau');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data).toHaveLength(1);
+            expect(r.data[0].name).toBe('Tỉnh Cà Mau');
+        }
+    });
+    it('NO MATCH: "XYZXYZ" → ok([])', () => {
+        const r = vn.legacy.search('XYZXYZ');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r))
+            expect(r.data).toEqual([]);
+    });
+    // Search districts (with parentId)
+    it('PARTIAL MATCH: "Ba" with parentId "01" → districts containing "Ba"', () => {
+        const r = vn.legacy.search('Ba', '01');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data.length).toBeGreaterThanOrEqual(2);
+            const names = r.data.map((d) => d.name);
+            expect(names).toContain('Quận Ba Đình');
+            expect(names).toContain('Huyện Ba Vì');
+        }
+    });
+    it('EXACT MATCH: "Quận Ba Đình" with parentId "01" → exactly Ba Đình', () => {
+        const r = vn.legacy.search('Quận Ba Đình', '01');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r)) {
+            expect(r.data).toHaveLength(1);
+            expect(r.data[0].id).toBe('001');
+        }
+    });
+    it('NO MATCH: "XYZ" with parentId "01" → ok([])', () => {
+        const r = vn.legacy.search('XYZ', '01');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r))
+            expect(r.data).toEqual([]);
+    });
+    it('EDGE: "" with parentId "01" → ok([])', () => {
+        const r = vn.legacy.search('', '01');
+        expect(isSuccess(r)).toBe(true);
+        if (isSuccess(r))
+            expect(r.data).toEqual([]);
+    });
+});
+// ─── Block G: Merge/mapping data integrity ──────────────
+describe('data integrity — merge and mapping data', () => {
+    it('DATA_INTEGRITY: merge entries → all newProvinceId values exist in v3 provinces', () => {
+        const r = vn.divisions();
+        if (isSuccess(r)) {
+            const provIds = new Set(r.data.map((p) => p.id));
+            for (const merge of provinceMerges) {
+                expect(provIds.has(merge.newProvinceId)).toBe(true);
+            }
+        }
+    });
+    it('DATA_INTEGRITY: merge entries → no duplicate old province IDs', () => {
+        const oldIds = [];
+        for (const merge of provinceMerges) {
+            for (const item of merge.mergedFrom) {
+                oldIds.push(item.oldProvinceId);
+            }
+        }
+        expect(new Set(oldIds).size).toBe(oldIds.length);
+    });
+    it('DATA_INTEGRITY: ward mappings sample → first 100 newWardCode values exist in communes', () => {
+        const r = vn.divisions();
+        if (isSuccess(r)) {
+            const communeIds = new Set();
+            for (const p of r.data) {
+                const communes = vn.divisions(p.id);
+                if (isSuccess(communes)) {
+                    for (const c of communes.data)
+                        communeIds.add(c.id);
+                }
+            }
+            const rawMappings = wardMappings;
+            for (let i = 0; i < Math.min(100, rawMappings.length); i++) {
+                expect(communeIds.has(rawMappings[i].newWardCode)).toBe(true);
+            }
+        }
+    });
+    it('DATA_INTEGRITY: province_merges.json → non-empty dataset', () => {
+        expect(provinceMerges.length).toBeGreaterThan(0);
+    });
+    it('DATA_INTEGRITY: ward_mappings.json → non-empty dataset with expected fields', () => {
+        expect(wardMappings.length).toBeGreaterThan(0);
+    });
+});
+// ─── Block H: Regression — input typesafety ─────────────
+describe('regression — runtime safety for JavaScript callers', () => {
+    it('DOCUMENTED: vn.divisions(null) → throws TypeError (JS caller without TS)', () => {
+        expect(() => vn.divisions(null)).toThrow(TypeError);
+    });
+    it('DOCUMENTED: vn.legacy.divisions(null) → throws TypeError (JS caller without TS)', () => {
+        expect(() => vn.legacy.divisions(null)).toThrow(TypeError);
+    });
+});
+// ─── Block I: vn.addressLookup() ──────────────────────────
+describe('vn.addressLookup()', () => {
+    function ok(r) {
+        return r.data !== null && !('error' in r);
+    }
+    function err(r) {
+        return r.data === null && 'error' in r;
+    }
+    describe('full address — legacy 63 tỉnh', () => {
+        it('resolves "Thôn Nghĩa Thắng, Đông Hòa, TP Thái Bình, Thái Bình" → full legacy + v3', () => {
+            const r = vn.addressLookup('Thôn Nghĩa Thắng, Đông Hòa, TP Thái Bình, Thái Bình');
+            expect(ok(r)).toBe(true);
+            if (!ok(r))
+                return;
+            // Legacy
+            expect(r.data.legacy.province).toEqual({
+                id: '34',
+                name: 'Tỉnh Thái Bình',
+            });
+            expect(r.data.legacy.district).toEqual({
+                id: '336',
+                name: 'Thành phố Thái Bình',
+            });
+            expect(r.data.legacy.commune).toEqual({
+                id: '12457',
+                name: 'Xã Đông Hòa',
+            });
+            expect(r.data.legacy.hamlet).toBe('Thôn Nghĩa Thắng');
+            // V3 — cross-resolved via province_merges
+            expect(r.data.v3.province).toEqual({
+                id: '33',
+                name: 'Hưng Yên',
+            });
+            // Đông Hòa mapped to Trà Lý via ward_mappings
+            expect(r.data.v3.commune).toEqual({
+                id: '12817',
+                name: 'Phường Trà Lý',
+            });
+            expect(r.data.v3.hamlet).toBe('Thôn Nghĩa Thắng');
+        });
+        it('resolves without diacritics "Dong Hoa, TP Thai Binh, Thai Binh"', () => {
+            const r = vn.addressLookup('Dong Hoa, TP Thai Binh, Thai Binh');
+            expect(ok(r)).toBe(true);
+            if (!ok(r))
+                return;
+            expect(r.data.legacy.province.id).toBe('34');
+            expect(r.data.legacy.district.id).toBe('336');
+            expect(r.data.legacy.commune.id).toBe('12457');
+            expect(r.data.v3.province.id).toBe('33');
+        });
+        it('resolves province only "Thái Bình"', () => {
+            const r = vn.addressLookup('Thái Bình');
+            expect(ok(r)).toBe(true);
+            if (!ok(r))
+                return;
+            expect(r.data.legacy.province.id).toBe('34');
+            expect(r.data.legacy.district).toBeNull();
+            expect(r.data.legacy.commune).toBeNull();
+            expect(r.data.v3.province.id).toBe('33');
+        });
+        it('resolves province + district "TP Thái Bình, Thái Bình"', () => {
+            const r = vn.addressLookup('TP Thái Bình, Thái Bình');
+            expect(ok(r)).toBe(true);
+            if (!ok(r))
+                return;
+            expect(r.data.legacy.province.id).toBe('34');
+            expect(r.data.legacy.district.id).toBe('336');
+            expect(r.data.legacy.commune).toBeNull();
+        });
+    });
+    describe('cross-resolution — legacy province merged into v3', () => {
+        it('"Bình Dương" → legacy 74 → v3 Hồ Chí Minh (79)', () => {
+            const r = vn.addressLookup('Bình Dương');
+            expect(ok(r)).toBe(true);
+            if (!ok(r))
+                return;
+            expect(r.data.legacy.province.id).toBe('74');
+            expect(r.data.v3.province.id).toBe('79');
+            expect(r.data.v3.province.name).toBe('Thành phố Hồ Chí Minh');
+        });
+        it('"Ninh Thuận" → legacy 58 → v3 Khánh Hòa (56)', () => {
+            const r = vn.addressLookup('Ninh Thuận');
+            expect(ok(r)).toBe(true);
+            if (!ok(r))
+                return;
+            expect(r.data.legacy.province.id).toBe('58');
+            expect(r.data.v3.province.id).toBe('56');
+        });
+    });
+    describe('strict error handling (Option B)', () => {
+        it('empty string → invalid_query', () => {
+            const r = vn.addressLookup('');
+            expect(err(r)).toBe(true);
+            if (err(r))
+                expect(r.error).toBe('invalid_query');
+        });
+        it('whitespace only → invalid_query', () => {
+            const r = vn.addressLookup('   ');
+            expect(err(r)).toBe(true);
+            if (err(r))
+                expect(r.error).toBe('invalid_query');
+        });
+        it('no province in address → address_missing_province', () => {
+            const r = vn.addressLookup('Xã ABC, Huyện XYZ');
+            expect(err(r)).toBe(true);
+            if (err(r))
+                expect(r.error).toBe('address_ambiguous_province');
+            // Note: "Xã ABC" has no detectable province, province is "ABC"
+            // which doesn't match any real province → ambiguous
+        });
+        it('nonexistent province → address_ambiguous_province', () => {
+            const r = vn.addressLookup('Somewhere, Nowhereland');
+            expect(err(r)).toBe(true);
+            if (err(r))
+                expect(r.error).toBe('address_ambiguous_province');
+        });
+    });
+    describe('v3 direct match — province exists in both systems', () => {
+        it('"Hồ Chí Minh" → legacy 79 + v3 79 (same)', () => {
+            const r = vn.addressLookup('Hồ Chí Minh');
+            expect(ok(r)).toBe(true);
+            if (!ok(r))
+                return;
+            expect(r.data.legacy.province.id).toBe('79');
+            expect(r.data.v3.province.id).toBe('79');
+            expect(r.data.v3.province.name).toBe('Thành phố Hồ Chí Minh');
+        });
+        it('"Hà Nội" → legacy 01 + v3 01', () => {
+            const r = vn.addressLookup('Hà Nội');
+            expect(ok(r)).toBe(true);
+            if (!ok(r))
+                return;
+            expect(r.data.legacy.province.id).toBe('01');
+            expect(r.data.v3.province.id).toBe('01');
+        });
+        it('"HNI" → v3 01 (Hà Nội) via abbreviation expansion', () => {
+            const r = vn.addressLookup('HNI');
+            expect(ok(r)).toBe(true);
+            if (!ok(r))
+                return;
+            expect(r.data.v3.province.id).toBe('01');
+        });
+    });
+});
+//# sourceMappingURL=vn.test.js.map