@0xd33p/vietnam-divisions 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+import type { GeoUnit, GeoResult, GeoErrorResult, AddressLookupResult } from './types.js';
+export type { GeoUnit, GeoError, GeoResult, AddressLookupResult, } from './types.js';
+export declare const vn: {
+    /**
+     * Get administrative divisions.
+     * - No arguments → 34 provinces (v3 system)
+     * - With parentId → communes/wards under that province (v3 system)
+     */
+    divisions(parentId?: string): GeoResult<GeoUnit[]> | GeoErrorResult;
+    /**
+     * Look up a single unit by ID, code, or name.
+     * Auto-detects: province ID (2-char like "79"), commune ID (5-char like "00004"),
+     * province code ("HCM", "HNI"), or full name.
+     * Auto-resolves: old province IDs via merge/mapping data.
+     */
+    lookup(query: string): GeoResult<GeoUnit & {
+        kind: "province" | "ward";
+    }> | GeoErrorResult;
+    /**
+     * Search divisions by name (case-insensitive, partial match).
+     * - Without parentId → search in provinces
+     * - With parentId → search in communes of that province
+     */
+    search(name: string, parentId?: string): GeoResult<GeoUnit[]>;
+    /**
+     * Look up a full address string in both legacy and v3 systems.
+     *
+     * Parses a comma-separated address (e.g. "Xã Đông Hòa, TP Thái Bình, Thái Bình"
+     * or "Dong Hoa, Thai Binh"), resolves province/district/commune in the legacy
+     * system (63 tỉnh), then cross-references to the v3 system (34 tỉnh).
+     *
+     * **Strict mode (Option B):** Must find exactly one province — fails with
+     * `address_missing_province` or `address_ambiguous_province` otherwise.
+     */
+    addressLookup(raw: string): GeoResult<AddressLookupResult> | GeoErrorResult;
+    /**
+     * Legacy system (63 provinces, 3 levels: province → district → commune).
+     * Explicit opt-in for backward compatibility.
+     */
+    legacy: {
+        /**
+         * Get legacy divisions.
+         * - No arguments → 63 provinces
+         * - With parentId → districts under that province
+         */
+        divisions(parentId?: string): GeoResult<GeoUnit[]> | GeoErrorResult;
+        /**
+         * Look up a legacy unit by ID.
+         * Auto-detects: province ID (2-char), district ID (3-char), commune ID (5-char).
+         */
+        lookup(query: string): GeoResult<GeoUnit & {
+            kind: "province" | "district" | "ward";
+        }> | GeoErrorResult;
+        /**
+         * Search legacy divisions by name.
+         * - Without parentId → search in provinces
+         * - With parentId → search in districts of that province
+         */
+        search(name: string, parentId?: string): GeoResult<GeoUnit[]>;
+    };
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EACV,OAAO,EACP,SAAS,EACT,cAAc,EACd,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,OAAO,EACP,QAAQ,EACR,SAAS,EACT,mBAAmB,GACpB,MAAM,YAAY,CAAC;AA8CpB,eAAO,MAAM,EAAE;IACb;;;;OAIG;yBACkB,MAAM,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC,GAAG,cAAc;IAYnE;;;;;OAKG;kBAEM,MAAM,GACZ,SAAS,CAAC,OAAO,GAAG;QAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAAA;KAAE,CAAC,GAAG,cAAc;IA4DtE;;;;OAIG;iBACU,MAAM,aAAa,MAAM,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC;IAU7D;;;;;;;;;OASG;uBAEI,MAAM,GACV,SAAS,CAAC,mBAAmB,CAAC,GAAG,cAAc;IA0JlD;;;OAGG;;QAED;;;;WAIG;6BACkB,MAAM,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC,GAAG,cAAc;QAYnE;;;WAGG;sBAEM,MAAM,GAEX,SAAS,CAAC,OAAO,GAAG;YAAE,IAAI,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,CAAA;SAAE,CAAC,GAC/D,cAAc;QAwClB;;;;WAIG;qBACU,MAAM,aAAa,MAAM,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC;;CAehE,CAAC"}

package/dist/index.js

@@ -0,0 +1,332 @@
+import { v3 as v3Internal, provinceMerges, wardMappings, } from './internal/v3/index.js';
+import { legacy as legacyInternal } from './internal/legacy/index.js';
+import { normalizeProvince, normalizeCommune, normalizeDistrict, normalizeName, ok, fail, } from './internal/helpers.js';
+import { parseAddress, fuzzySearchProvinces } from './internal/address.js';
+// ─── Private helpers ────────────────────────────────────
+function resolveOldProvinceId(oldId) {
+    const trimmed = oldId.trim();
+    for (const merge of provinceMerges) {
+        const match = merge.mergedFrom.find((m) => m.oldProvinceId === trimmed);
+        if (match) {
+            const current = v3Internal.getProvinceById(merge.newProvinceId);
+            if (current) {
+                return { ...normalizeProvince(current), kind: 'province' };
+            }
+        }
+    }
+    return null;
+}
+function resolveOldCommuneId(oldId) {
+    const trimmed = oldId.trim();
+    const rawMappings = wardMappings;
+    for (const mapping of rawMappings) {
+        if (mapping.oldWardCode === trimmed) {
+            const c = v3Internal.getCommuneById(mapping.newWardCode);
+            if (c) {
+                return { ...normalizeCommune(c), kind: 'ward' };
+            }
+        }
+    }
+    return null;
+}
+// ─── Public API ─────────────────────────────────────────
+export const vn = {
+    /**
+     * Get administrative divisions.
+     * - No arguments → 34 provinces (v3 system)
+     * - With parentId → communes/wards under that province (v3 system)
+     */
+    divisions(parentId) {
+        if (parentId === undefined) {
+            const list = v3Internal.provinces();
+            if (list.length === 0)
+                return fail('empty_province_list');
+            return ok(list.map(normalizeProvince));
+        }
+        if (parentId.length === 0)
+            return fail('invalid_province_id');
+        const list = v3Internal.getCommunesByProvinceId(parentId);
+        if (list.length === 0)
+            return fail('empty_commune_list');
+        return ok(list.map(normalizeCommune));
+    },
+    /**
+     * Look up a single unit by ID, code, or name.
+     * Auto-detects: province ID (2-char like "79"), commune ID (5-char like "00004"),
+     * province code ("HCM", "HNI"), or full name.
+     * Auto-resolves: old province IDs via merge/mapping data.
+     */
+    lookup(query) {
+        if (!query || query.length === 0)
+            return fail('invalid_query');
+        const trimmed = query.trim();
+        // 1. Try as province ID (2 chars)
+        if (trimmed.length === 2 && /^\d+$/.test(trimmed)) {
+            const p = v3Internal.getProvinceById(trimmed);
+            if (p) {
+                return ok({ ...normalizeProvince(p), kind: 'province' });
+            }
+            // Try auto-resolve from old province ID via merge data
+            const resolved = resolveOldProvinceId(trimmed);
+            if (resolved) {
+                return ok(resolved);
+            }
+        }
+        // 1.5 Try as old commune ID via ward mappings
+        if (trimmed.length === 5) {
+            const resolvedCommune = resolveOldCommuneId(trimmed);
+            if (resolvedCommune) {
+                return ok(resolvedCommune);
+            }
+        }
+        // 2. Try as province code (3 uppercase letters)
+        if (trimmed.length === 3 && /^[A-Za-z]+$/.test(trimmed)) {
+            const p = v3Internal.getProvinceByCode(trimmed.toUpperCase());
+            if (p) {
+                return ok({ ...normalizeProvince(p), kind: 'province' });
+            }
+        }
+        // 3. Try as commune ID (5 chars)
+        if (trimmed.length === 5) {
+            const c = v3Internal.getCommuneById(trimmed);
+            if (c) {
+                return ok({ ...normalizeCommune(c), kind: 'ward' });
+            }
+        }
+        // 4. Try as full province name (exact match, case-insensitive)
+        const provinceByName = v3Internal.searchProvinceByName(trimmed);
+        if (provinceByName.length === 1) {
+            return ok({
+                ...normalizeProvince(provinceByName[0]),
+                kind: 'province',
+            });
+        }
+        // 5. Try auto-resolve old province/commune ID
+        const resolvedProv = resolveOldProvinceId(trimmed);
+        if (resolvedProv)
+            return ok(resolvedProv);
+        const resolvedCom = resolveOldCommuneId(trimmed);
+        if (resolvedCom)
+            return ok(resolvedCom);
+        return fail('province_not_found');
+    },
+    /**
+     * Search divisions by name (case-insensitive, partial match).
+     * - Without parentId → search in provinces
+     * - With parentId → search in communes of that province
+     */
+    search(name, parentId) {
+        if (!name)
+            return ok([]);
+        if (parentId) {
+            return ok(v3Internal.searchCommunesByName(parentId, name).map(normalizeCommune));
+        }
+        return ok(v3Internal.searchProvinceByName(name).map(normalizeProvince));
+    },
+    /**
+     * Look up a full address string in both legacy and v3 systems.
+     *
+     * Parses a comma-separated address (e.g. "Xã Đông Hòa, TP Thái Bình, Thái Bình"
+     * or "Dong Hoa, Thai Binh"), resolves province/district/commune in the legacy
+     * system (63 tỉnh), then cross-references to the v3 system (34 tỉnh).
+     *
+     * **Strict mode (Option B):** Must find exactly one province — fails with
+     * `address_missing_province` or `address_ambiguous_province` otherwise.
+     */
+    addressLookup(raw) {
+        if (!raw || raw.trim().length === 0)
+            return fail('invalid_query');
+        // 1. Parse address into parts
+        const parsed = parseAddress(raw);
+        if (!parsed.province) {
+            return fail('address_missing_province');
+        }
+        // 2. Build searchable lists
+        const legacyProvinceList = legacyInternal
+            .provinces()
+            .map(normalizeProvince);
+        const v3ProvinceList = v3Internal.provinces().map(normalizeProvince);
+        const nProvinceQuery = normalizeName(parsed.province);
+        // 3. Find province in legacy
+        const legacyProvinceMatches = fuzzySearchProvinces(parsed.province, legacyProvinceList);
+        if (legacyProvinceMatches.length === 0) {
+            return fail('address_ambiguous_province');
+        }
+        if (legacyProvinceMatches.length > 1) {
+            return fail('address_ambiguous_province');
+        }
+        const legacyProvince = legacyProvinceMatches[0];
+        // 4. Find province in v3
+        let v3Province = null;
+        const v3ProvinceMatches = fuzzySearchProvinces(parsed.province, v3ProvinceList);
+        if (v3ProvinceMatches.length === 1) {
+            v3Province = v3ProvinceMatches[0];
+        }
+        else if (v3ProvinceMatches.length > 1) {
+            return fail('address_ambiguous_province');
+        }
+        // 4b. Cross-resolve: legacy → v3 via provinceMerges
+        if (!v3Province) {
+            for (const merge of provinceMerges) {
+                const found = merge.mergedFrom.find((m) => m.oldProvinceId === legacyProvince.id);
+                if (found) {
+                    const resolved = v3Internal.getProvinceById(merge.newProvinceId);
+                    if (resolved) {
+                        v3Province = normalizeProvince(resolved);
+                    }
+                    break;
+                }
+            }
+        }
+        // 5. Resolve district + commune in legacy
+        let legacyDistrict = null;
+        let legacyCommune = null;
+        const legacyDistricts = legacyInternal.getDistrictsByProvinceId(legacyProvince.id);
+        if (parsed.district) {
+            const districtMatches = fuzzySearchProvinces(parsed.district, legacyDistricts.map(normalizeDistrict));
+            if (districtMatches.length > 0) {
+                legacyDistrict = districtMatches[0];
+            }
+        }
+        if (parsed.commune) {
+            // Search within district first (if found), then within whole province
+            if (legacyDistrict) {
+                const communeMatches = fuzzySearchProvinces(parsed.commune, legacyInternal
+                    .getCommunesByDistrictId(legacyDistrict.id)
+                    .map(normalizeCommune));
+                if (communeMatches.length > 0) {
+                    legacyCommune = communeMatches[0];
+                }
+            }
+            if (!legacyCommune) {
+                const communeMatches = fuzzySearchProvinces(parsed.commune, legacyInternal
+                    .getCommunesByProvinceId(legacyProvince.id)
+                    .map(normalizeCommune));
+                if (communeMatches.length > 0) {
+                    legacyCommune = communeMatches[0];
+                }
+            }
+        }
+        // 6. Resolve commune in v3
+        let v3Commune = null;
+        if (v3Province) {
+            // 6a. Try ward_mappings if we have a legacy commune
+            if (legacyCommune) {
+                const rawMappings = wardMappings;
+                const match = rawMappings.find((m) => m.oldWardCode === legacyCommune.id);
+                if (match) {
+                    const resolved = v3Internal.getCommuneById(match.newWardCode);
+                    if (resolved) {
+                        v3Commune = normalizeCommune(resolved);
+                    }
+                }
+            }
+            // 6b. Fall back to searching by name in v3 province communes
+            if (!v3Commune && parsed.commune) {
+                const v3Communes = v3Internal
+                    .getCommunesByProvinceId(v3Province.id)
+                    .map(normalizeCommune);
+                const communeMatches = fuzzySearchProvinces(parsed.commune, v3Communes);
+                if (communeMatches.length > 0) {
+                    v3Commune = communeMatches[0];
+                }
+            }
+        }
+        // 7. Build result
+        const result = {
+            legacy: {
+                province: legacyProvince,
+                district: legacyDistrict,
+                commune: legacyCommune,
+                hamlet: parsed.hamlet,
+            },
+            v3: {
+                province: v3Province,
+                commune: v3Commune,
+                hamlet: parsed.hamlet,
+            },
+        };
+        return ok(result);
+    },
+    /**
+     * Legacy system (63 provinces, 3 levels: province → district → commune).
+     * Explicit opt-in for backward compatibility.
+     */
+    legacy: {
+        /**
+         * Get legacy divisions.
+         * - No arguments → 63 provinces
+         * - With parentId → districts under that province
+         */
+        divisions(parentId) {
+            if (parentId === undefined) {
+                const list = legacyInternal.provinces();
+                if (list.length === 0)
+                    return fail('empty_province_list');
+                return ok(list.map(normalizeProvince));
+            }
+            if (parentId.length === 0)
+                return fail('invalid_province_id');
+            const list = legacyInternal.getDistrictsByProvinceId(parentId);
+            if (list.length === 0)
+                return fail('empty_district_list');
+            return ok(list.map(normalizeDistrict));
+        },
+        /**
+         * Look up a legacy unit by ID.
+         * Auto-detects: province ID (2-char), district ID (3-char), commune ID (5-char).
+         */
+        lookup(query) {
+            if (!query || query.length === 0)
+                return fail('invalid_query');
+            const trimmed = query.trim();
+            // Try province ID (2 chars)
+            if (trimmed.length === 2) {
+                const p = legacyInternal.getProvinceById(trimmed);
+                if (p) {
+                    return ok({ ...normalizeProvince(p), kind: 'province' });
+                }
+            }
+            // Try district ID (3 chars)
+            if (trimmed.length === 3) {
+                const d = legacyInternal.getDistrictById(trimmed);
+                if (d) {
+                    return ok({ ...normalizeDistrict(d), kind: 'district' });
+                }
+            }
+            // Try commune ID (5 chars)
+            if (trimmed.length === 5) {
+                const c = legacyInternal.getCommuneById(trimmed);
+                if (c) {
+                    return ok({ ...normalizeCommune(c), kind: 'ward' });
+                }
+            }
+            // Try province by name
+            const byName = legacyInternal.searchByName(trimmed);
+            if (byName.length === 1) {
+                return ok({
+                    ...normalizeProvince(byName[0]),
+                    kind: 'province',
+                });
+            }
+            return fail('province_not_found');
+        },
+        /**
+         * Search legacy divisions by name.
+         * - Without parentId → search in provinces
+         * - With parentId → search in districts of that province
+         */
+        search(name, parentId) {
+            if (!name)
+                return ok([]);
+            if (parentId) {
+                return ok(legacyInternal
+                    .getDistrictsByProvinceId(parentId)
+                    .filter((d) => d.name.toLowerCase().includes(name.toLowerCase().trim()))
+                    .map(normalizeDistrict));
+            }
+            return ok(legacyInternal.searchByName(name).map(normalizeProvince));
+        },
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/internal/address.d.ts

@@ -0,0 +1,37 @@
+import type { GeoUnit } from '../types.js';
+/**
+ * Detect level of an address part by its prefix.
+ * @param provinceFound — if true, treat ambiguous "Thành phố/TP" as district.
+ */
+export declare function detectLevel(part: string, provinceFound?: boolean): 'province' | 'district' | 'commune' | 'hamlet' | 'unknown';
+export interface ParsedAddress {
+    /** Deduplicated, trimmed, original-case parts (right-to-left order). */
+    parts: string[];
+    hamlet: string | null;
+    commune: string | null;
+    district: string | null;
+    province: string | null;
+}
+/**
+ * Split, trim, dedup (by normalized form), then classify each part.
+ * Returns structured parts without doing any DB lookup.
+ */
+export declare function parseAddress(raw: string): ParsedAddress;
+/**
+ * Expand common Vietnamese administrative abbreviations.
+ * "TP HCM" → "thành phố hồ chí minh", "TX" → "thị xã", etc.
+ */
+export declare function expandAbbreviations(name: string): string;
+/**
+ * Check if a query matches a target name.
+ * - Exact normalized match
+ * - Target contains query (token-level)
+ * - Query contains target
+ */
+export declare function fuzzyMatch(query: string, target: string): boolean;
+/**
+ * Find best matches in a list of GeoUnits.
+ * Returns exact matches first, then partial matches.
+ */
+export declare function fuzzySearchProvinces(query: string, items: GeoUnit[]): GeoUnit[];
+//# sourceMappingURL=address.d.ts.map

package/dist/internal/address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.d.ts","sourceRoot":"","sources":["../../src/internal/address.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAU3C;;;GAGG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,aAAa,CAAC,EAAE,OAAO,GACtB,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CA4B5D;AAED,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CA8DvD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOxD;AASD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAQjE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,OAAO,EAAE,GACf,OAAO,EAAE,CAkBX"}

package/dist/internal/address.js

@@ -0,0 +1,164 @@
+import { normalizeName } from './helpers.js';
+/** Level prefixes ordered from most specific to least. */
+const HAMLET_PREFIXES = ['thôn', 'ấp', 'tổ', 'xóm', 'bản', 'số'];
+const COMMUNE_PREFIXES = ['xã', 'phường', 'thị trấn', 'tt.', 'tt'];
+const DISTRICT_PREFIXES = ['huyện', 'quận', 'thị xã', 'tx.', 'tx'];
+/** "Thành phố" and "tp" are ambiguous — could be province or district. */
+const AMBIGUOUS_PREFIXES = ['thành phố', 'tp.', 'tp'];
+const PROVINCE_PREFIXES = ['tỉnh'];
+/**
+ * Detect level of an address part by its prefix.
+ * @param provinceFound — if true, treat ambiguous "Thành phố/TP" as district.
+ */
+export function detectLevel(part, provinceFound) {
+    const lower = part.toLowerCase().trim();
+    // Exclusive province prefix
+    for (const prefix of PROVINCE_PREFIXES) {
+        if (lower.startsWith(prefix) || lower.endsWith(prefix)) {
+            return 'province';
+        }
+    }
+    // Ambiguous: if province already found, treat as district
+    for (const prefix of AMBIGUOUS_PREFIXES) {
+        if (lower.startsWith(prefix) || lower.endsWith(prefix)) {
+            return provinceFound ? 'district' : 'province';
+        }
+    }
+    for (const prefix of DISTRICT_PREFIXES) {
+        if (lower.startsWith(prefix))
+            return 'district';
+    }
+    for (const prefix of COMMUNE_PREFIXES) {
+        if (lower.startsWith(prefix))
+            return 'commune';
+    }
+    for (const prefix of HAMLET_PREFIXES) {
+        if (lower.startsWith(prefix))
+            return 'hamlet';
+    }
+    return 'unknown';
+}
+/**
+ * Split, trim, dedup (by normalized form), then classify each part.
+ * Returns structured parts without doing any DB lookup.
+ */
+export function parseAddress(raw) {
+    if (!raw) {
+        return { parts: [], hamlet: null, commune: null, district: null, province: null };
+    }
+    // Split by comma, trim, filter empty
+    const rawParts = raw.split(',').map((s) => s.trim()).filter(Boolean);
+    if (rawParts.length === 0) {
+        return { parts: [], hamlet: null, commune: null, district: null, province: null };
+    }
+    // Dedup by normalized form (keep first occurrence)
+    const seen = new Set();
+    const deduped = [];
+    for (const p of rawParts) {
+        const norm = normalizeName(p);
+        if (norm && !seen.has(norm)) {
+            seen.add(norm);
+            deduped.push(p);
+        }
+    }
+    // Classify right-to-left
+    let hamlet = null;
+    let commune = null;
+    let district = null;
+    let province = null;
+    // Reverse order: rightmost = province (broadest scope in VN address format)
+    const reversed = [...deduped].reverse();
+    // Phase 1: rightmost part is ALWAYS the province
+    province = reversed[0];
+    // Phase 2: classify remaining parts (left of province)
+    const remaining = deduped.slice(0, -1); // all except the last (rightmost)
+    for (const part of remaining) {
+        const level = detectLevel(part, true); // province already found
+        if (level === 'hamlet' && !hamlet) {
+            hamlet = part;
+        }
+        else if (level === 'commune' && !commune) {
+            commune = part;
+        }
+        else if (level === 'district' && !district) {
+            district = part;
+        }
+        else if (!commune) {
+            // Unknown → treat as commune (most specific known level)
+            commune = part;
+        }
+        else if (!district) {
+            district = part;
+        }
+        else if (!hamlet) {
+            hamlet = part;
+        }
+    }
+    return {
+        parts: deduped,
+        hamlet,
+        commune,
+        district,
+        province,
+    };
+}
+/**
+ * Expand common Vietnamese administrative abbreviations.
+ * "TP HCM" → "thành phố hồ chí minh", "TX" → "thị xã", etc.
+ */
+export function expandAbbreviations(name) {
+    return name
+        .replace(/\btp\.?\b/gi, 'thành phố')
+        .replace(/\btx\.?\b/gi, 'thị xã')
+        .replace(/\btt\.?\b/gi, 'thị trấn')
+        .replace(/\bhcm\b/gi, 'hồ chí minh')
+        .replace(/\bhni\b/gi, 'hà nội');
+}
+/**
+* Normalize for search: expand abbreviations first, THEN remove diacritics.
+*/
+function normalizeForSearch(name) {
+    return normalizeName(expandAbbreviations(name));
+}
+/**
+ * Check if a query matches a target name.
+ * - Exact normalized match
+ * - Target contains query (token-level)
+ * - Query contains target
+ */
+export function fuzzyMatch(query, target) {
+    const nq = normalizeForSearch(query);
+    const nt = normalizeForSearch(target);
+    if (!nq || !nt)
+        return false;
+    if (nq === nt)
+        return true;
+    if (nt.includes(nq))
+        return true;
+    if (nq.includes(nt))
+        return true;
+    return false;
+}
+/**
+ * Find best matches in a list of GeoUnits.
+ * Returns exact matches first, then partial matches.
+ */
+export function fuzzySearchProvinces(query, items) {
+    const nq = normalizeForSearch(query);
+    if (!nq)
+        return [];
+    const exact = [];
+    const partial = [];
+    for (const item of items) {
+        const ni = normalizeForSearch(item.name);
+        if (ni === nq) {
+            exact.push(item);
+        }
+        else if (ni.includes(nq)) {
+            partial.push(item);
+        }
+    }
+    // Exact matches first
+    return [...exact, ...partial];
+}
+//# sourceMappingURL=address.js.map

package/dist/internal/address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.js","sourceRoot":"","sources":["../../src/internal/address.ts"],"names":[],"mappings":"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"}

package/dist/internal/helpers.d.ts

@@ -0,0 +1,24 @@
+import type { GeoUnit, GeoError } from '../types.js';
+/** Remove Vietnamese diacritics, lowercase, collapse whitespace. */
+export declare function normalizeName(name: string): string;
+export declare function normalizeProvince(p: {
+    idProvince: string;
+    name: string;
+}): GeoUnit;
+export declare function normalizeCommune(c: {
+    idCommune: string;
+    name: string;
+}): GeoUnit;
+export declare function normalizeDistrict(d: {
+    idDistrict: string;
+    name: string;
+}): GeoUnit;
+export declare function ok<T>(data: T): {
+    data: T;
+    error?: undefined;
+};
+export declare function fail(error: GeoError): {
+    data: null;
+    error: GeoError;
+};
+//# sourceMappingURL=helpers.d.ts.map

package/dist/internal/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/internal/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAgCrD,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQlD;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EAAE;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAEV;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAEV;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EAAE;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAEV;AAED,wBAAgB,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG;IAAE,IAAI,EAAE,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,CAE7D;AAED,wBAAgB,IAAI,CAAC,KAAK,EAAE,QAAQ,GAAG;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,CAErE"}