thaizip 0.6.0 → 0.7.3

package/dist/index.d.cts

@@ -14,10 +14,46 @@ type TrigramIndex = {
     map: Map<string, Set<number>>;
     records: ThaiAddressRecord[];
     zipIndex: Map<string, number[]>;
+    /**
+     * Zip codes of `zipIndex` in ascending lexical order, with postings
+     * parallel in `sortedZipPostings`. Used by `lookupByZipCode` for
+     * O(log n + matches) prefix lookup instead of scanning every zip code.
+     * Optional: older-shaped or hand-built indexes without these fields fall
+     * back to the O(n_zips) scan.
+     */
+    sortedZipKeys?: string[];
+    sortedZipPostings?: number[][];
+    /**
+     * Normalized Thai tambon names, parallel to `records` (same index).
+     * Used by the search ranker for exact/prefix match detection without
+     * re-normalizing on every query.
+     */
+    normTambon: string[];
+    /**
+     * Normalized English (RTGS) tambon names, parallel to `records`. Needed so
+     * romanized queries get the same own-name-beats-parent-name ranking that
+     * Thai queries get.
+     */
+    normTambonEn: string[];
+    /** Record indices grouped by `provinceId`, in insertion order. */
+    byProvince: Map<number, number[]>;
+    /** Record indices grouped by `amphureId`, in insertion order. */
+    byAmphure: Map<number, number[]>;
+};
+/** Which language a formatted label should be rendered in. */
+type AddressLocale = 'th' | 'en';
+type FormatSuggestionOptions = {
+    /** Language for the `label` field. Defaults to `'th'`. */
+    locale?: AddressLocale;
 };
 type ThaiAddressSuggestion = {
     id: string;
+    /** Human-readable label in the requested locale (Thai by default). */
     label: string;
+    /** Human-readable label in Thai, regardless of the requested locale. */
+    labelTh: string;
+    /** Human-readable label in English, regardless of the requested locale. */
+    labelEn: string;
     tambon: string;
     tambonEn: string;
     amphure: string;
@@ -26,6 +62,27 @@ type ThaiAddressSuggestion = {
     provinceEn: string;
     zipCode: string;
 };
+/** A province entry returned by the enumeration API. */
+type ProvinceSummary = {
+    id: number;
+    nameTh: string;
+    nameEn: string;
+};
+/** An amphure (district) entry returned by the enumeration API. */
+type AmphureSummary = {
+    id: number;
+    nameTh: string;
+    nameEn: string;
+    provinceId: number;
+};
+/** A tambon (subdistrict) entry returned by the enumeration API. */
+type TambonSummary = {
+    id: number;
+    nameTh: string;
+    nameEn: string;
+    amphureId: number;
+    zipCode: string;
+};
 type ResolvedThaiAddress = {
     tambon: string;
     tambonEn: string;
@@ -43,6 +100,17 @@ type ResolvedThaiAddress = {
 type SearchOptions = {
     limit?: number;
     threshold?: number;
+    /**
+     * Maximum results for all-digit (zip code) queries. A zip code maps to at most
+     * a few dozen tambons, so this defaults to `Infinity` — capping zip results at
+     * the text-autocomplete `limit` silently hides valid subdistricts.
+     */
+    zipLimit?: number;
+    /**
+     * Expand common romanization variants (e.g. `lardprao` → `lat phrao`) before
+     * searching. Only affects Latin-script queries. Defaults to `true`.
+     */
+    romanizationAliases?: boolean;
 };
 type RawGeography = {
     id: number;
@@ -73,6 +141,12 @@ type RawTambon = {
 };
 type BuildIndexOptions = {
     onSkip?: (tambon: RawTambon) => void;
+    /**
+     * Validate that every consumed field has the expected runtime type and throw a
+     * descriptive `TypeError` if not. Defaults to `true`; set to `false` to skip
+     * the checks when the data source is already trusted (e.g. the bundled index).
+     */
+    validate?: boolean;
 };
 type RawData = {
     geographies?: RawGeography[];
@@ -81,14 +155,125 @@ type RawData = {
     tambons: RawTambon[];
 };
 
+/**
+ * Validate that a `RawData` payload has the runtime shapes `buildThaiAddressIndex`
+ * expects. Intended for consumers building an index from their own data (CSV, CMS,
+ * private datasets) who want to fail fast with a descriptive error instead of an
+ * opaque crash deep inside the normalizer, or silent `"undefined"` labels.
+ *
+ * Throws a `TypeError` (message prefixed `[thaizip]`) naming the table, the
+ * offending record's `id`, the field, and the actual `typeof` on the first bad
+ * field found. Does not filter soft-deleted rows first — validates every row as
+ * provided.
+ *
+ * IDs must be unique within each table (duplicates throw, they are not silently
+ * discarded — two suggestions sharing an id would resolve to the wrong record).
+ * Referential integrity (amphure→province, tambon→amphure) is intentionally NOT
+ * enforced: dangling references — including soft-deleted parents — are handled at
+ * build time, where the tambon is skipped and reported via `options.onSkip`.
+ */
+declare function validateRawData(data: RawData): void;
 declare function buildThaiAddressIndex(data: RawData, options?: BuildIndexOptions): TrigramIndex;
 
+/**
+ * Look up records by zip code (exact or prefix match). Exact matches are
+ * returned before prefix matches; ties are ordered by ascending zip code.
+ *
+ * Uses the build-time `sortedZipKeys`/`sortedZipPostings` arrays with a
+ * binary search for the first key ≥ the query, then walks the contiguous
+ * prefix range — O(log n_zips + matches). Ascending key order places an
+ * exact match before any longer prefix match automatically, so no explicit
+ * exact-first sort is needed. Indexes without the sorted arrays (older
+ * shape, hand-built) fall back to the original O(n_zips) scan + sort.
+ *
+ * Returned records are shallow copies: mutating them cannot corrupt the
+ * shared index (see `searchThaiAddress`).
+ *
+ * Unlike `searchThaiAddress`, results are NOT capped by `options.limit` —
+ * only by `options.zipLimit` (defaults to `Infinity`), since a zip code can
+ * legitimately map to dozens of tambons (e.g. `45000` → 33 records).
+ *
+ * Malformed runtime input (non-string `zip`, missing index shape) returns
+ * `[]` rather than crashing deep inside the library.
+ */
+declare function lookupByZipCode(index: TrigramIndex, zip: string, options?: SearchOptions): ThaiAddressRecord[];
 declare function searchThaiAddress(index: TrigramIndex, query: string, options?: SearchOptions): ThaiAddressRecord[];
 
-declare function formatThaiAddressSuggestion(record: ThaiAddressRecord): ThaiAddressSuggestion;
+/**
+ * All provinces present in the index, deduplicated and sorted by Thai name.
+ * Backed by `index.byProvince` (O(unique provinces)); falls back to scanning
+ * `index.records` if an older-shaped index lacks that map. A missing/junk
+ * index returns `[]` rather than throwing.
+ */
+declare function listProvinces(index: TrigramIndex): ProvinceSummary[];
+/**
+ * Amphures (districts) within a given province, deduplicated and sorted by
+ * Thai name. Unknown `provinceId` returns `[]`. Backed by `index.byProvince`;
+ * falls back to scanning `index.records` if an older-shaped index lacks it.
+ * A missing/junk index returns `[]` rather than throwing.
+ */
+declare function listAmphures(index: TrigramIndex, provinceId: number): AmphureSummary[];
+/**
+ * Tambons (subdistricts) within a given amphure, sorted by Thai name.
+ * Unknown `amphureId` returns `[]`. Backed by `index.byAmphure`; falls back
+ * to scanning `index.records` if an older-shaped index lacks it. Each
+ * `byAmphure` entry already maps to exactly one tambon record, so no
+ * deduplication is needed here. A missing/junk index returns `[]` rather
+ * than throwing.
+ */
+declare function listTambons(index: TrigramIndex, amphureId: number): TambonSummary[];
+
+declare function formatThaiAddressSuggestion(record: ThaiAddressRecord, options?: FormatSuggestionOptions): ThaiAddressSuggestion;
 
 declare function resolveThaiAddress(record: ThaiAddressRecord): ResolvedThaiAddress;
 
 declare function normalizeThaiAddressText(input: string): string;
 
-export { type BuildIndexOptions, type RawAmphure, type RawData, type RawGeography, type RawProvince, type RawTambon, type ResolvedThaiAddress, type SearchOptions, type ThaiAddressRecord, type ThaiAddressSuggestion, type TrigramIndex, buildThaiAddressIndex, formatThaiAddressSuggestion, normalizeThaiAddressText, resolveThaiAddress, searchThaiAddress };
+/**
+ * Romanization alias expansion for Latin-script queries.
+ *
+ * The bundled dataset indexes only the official RTGS transliteration of each
+ * name (`name_en`), so common but non-RTGS spellings a user actually types
+ * ("lardprao", "krungthep", "sukumvit") miss the index entirely. This module
+ * rewrites such a query into its RTGS form before trigram extraction.
+ *
+ * Contract:
+ * - Input is an ALREADY-NORMALIZED query (lowercased, prefixes and tone marks
+ *   stripped) as produced by `normalizeThaiAddressText`.
+ * - Output is a normalized query too — safe to hand straight to
+ *   `extractTrigramsNormalized`.
+ * - Thai-script input must be returned unchanged.
+ * - Must be a pure function; it runs on every keystroke.
+ *
+ * Design (two layers, cheapest/most-reliable first):
+ *
+ * 1. A curated dictionary of non-RTGS spelling -> exact RTGS string, as it
+ *    literally appears in a `name_en` field of the bundled dataset. Targets
+ *    were read off the real generated index (see the romanize benchmark
+ *    harness used to build this list), not guessed — a couple of entries
+ *    intentionally map onto data typos already baked into the dataset
+ *    (`loburi`, `buogkan`) because that is what is actually indexed.
+ *
+ * 2. A tiny, conservative cleanup pass used only when the dictionary misses:
+ *    collapse runs of whitespace, and strip a few English administrative
+ *    words (`district`, `province`, ...) that never occur inside a real
+ *    `name_en` value. Both were verified against the full dataset before
+ *    being added — see the "rejected rules" note below for transformations
+ *    that were tried and thrown out because they collide with real names.
+ *
+ * Rejected systematic rules (measured against the real dataset, not
+ * hypothetical): a blanket `klong` -> `khlong` rewrite would break the real
+ * tambons "Mae Klong" and "Ho Klong"; `muang` -> `mueang` would break ~122
+ * real tambons that legitimately contain "Muang" as a name component (e.g.
+ * "Bang Muang", "Khok Muang"); `huay` -> `huai` would break the real tambon
+ * "Huay Lueg"; a blanket hyphen -> space rewrite would break the ~70 real
+ * names that use a hyphen on purpose (e.g. "Bang Pa-in", the Ayutthaya
+ * palace town). None of the classic AUA-vs-RTGS letter swaps (`oo` -> `u`,
+ * trailing `-rd` -> `-t`, `dt` -> `t`, `bp` -> `p`, doubled consonants) had
+ * any real occurrence in the traffic-prioritized query set used to validate
+ * this module, so none were added — see the harness report for the
+ * before/after numbers this file was tuned against.
+ */
+declare function applyRomanizationAliases(normalized: string): string;
+
+export { type AddressLocale, type AmphureSummary, type BuildIndexOptions, type FormatSuggestionOptions, type ProvinceSummary, type RawAmphure, type RawData, type RawGeography, type RawProvince, type RawTambon, type ResolvedThaiAddress, type SearchOptions, type TambonSummary, type ThaiAddressRecord, type ThaiAddressSuggestion, type TrigramIndex, applyRomanizationAliases, buildThaiAddressIndex, formatThaiAddressSuggestion, listAmphures, listProvinces, listTambons, lookupByZipCode, normalizeThaiAddressText, resolveThaiAddress, searchThaiAddress, validateRawData };

package/dist/index.d.ts

@@ -14,10 +14,46 @@ type TrigramIndex = {
     map: Map<string, Set<number>>;
     records: ThaiAddressRecord[];
     zipIndex: Map<string, number[]>;
+    /**
+     * Zip codes of `zipIndex` in ascending lexical order, with postings
+     * parallel in `sortedZipPostings`. Used by `lookupByZipCode` for
+     * O(log n + matches) prefix lookup instead of scanning every zip code.
+     * Optional: older-shaped or hand-built indexes without these fields fall
+     * back to the O(n_zips) scan.
+     */
+    sortedZipKeys?: string[];
+    sortedZipPostings?: number[][];
+    /**
+     * Normalized Thai tambon names, parallel to `records` (same index).
+     * Used by the search ranker for exact/prefix match detection without
+     * re-normalizing on every query.
+     */
+    normTambon: string[];
+    /**
+     * Normalized English (RTGS) tambon names, parallel to `records`. Needed so
+     * romanized queries get the same own-name-beats-parent-name ranking that
+     * Thai queries get.
+     */
+    normTambonEn: string[];
+    /** Record indices grouped by `provinceId`, in insertion order. */
+    byProvince: Map<number, number[]>;
+    /** Record indices grouped by `amphureId`, in insertion order. */
+    byAmphure: Map<number, number[]>;
+};
+/** Which language a formatted label should be rendered in. */
+type AddressLocale = 'th' | 'en';
+type FormatSuggestionOptions = {
+    /** Language for the `label` field. Defaults to `'th'`. */
+    locale?: AddressLocale;
 };
 type ThaiAddressSuggestion = {
     id: string;
+    /** Human-readable label in the requested locale (Thai by default). */
     label: string;
+    /** Human-readable label in Thai, regardless of the requested locale. */
+    labelTh: string;
+    /** Human-readable label in English, regardless of the requested locale. */
+    labelEn: string;
     tambon: string;
     tambonEn: string;
     amphure: string;
@@ -26,6 +62,27 @@ type ThaiAddressSuggestion = {
     provinceEn: string;
     zipCode: string;
 };
+/** A province entry returned by the enumeration API. */
+type ProvinceSummary = {
+    id: number;
+    nameTh: string;
+    nameEn: string;
+};
+/** An amphure (district) entry returned by the enumeration API. */
+type AmphureSummary = {
+    id: number;
+    nameTh: string;
+    nameEn: string;
+    provinceId: number;
+};
+/** A tambon (subdistrict) entry returned by the enumeration API. */
+type TambonSummary = {
+    id: number;
+    nameTh: string;
+    nameEn: string;
+    amphureId: number;
+    zipCode: string;
+};
 type ResolvedThaiAddress = {
     tambon: string;
     tambonEn: string;
@@ -43,6 +100,17 @@ type ResolvedThaiAddress = {
 type SearchOptions = {
     limit?: number;
     threshold?: number;
+    /**
+     * Maximum results for all-digit (zip code) queries. A zip code maps to at most
+     * a few dozen tambons, so this defaults to `Infinity` — capping zip results at
+     * the text-autocomplete `limit` silently hides valid subdistricts.
+     */
+    zipLimit?: number;
+    /**
+     * Expand common romanization variants (e.g. `lardprao` → `lat phrao`) before
+     * searching. Only affects Latin-script queries. Defaults to `true`.
+     */
+    romanizationAliases?: boolean;
 };
 type RawGeography = {
     id: number;
@@ -73,6 +141,12 @@ type RawTambon = {
 };
 type BuildIndexOptions = {
     onSkip?: (tambon: RawTambon) => void;
+    /**
+     * Validate that every consumed field has the expected runtime type and throw a
+     * descriptive `TypeError` if not. Defaults to `true`; set to `false` to skip
+     * the checks when the data source is already trusted (e.g. the bundled index).
+     */
+    validate?: boolean;
 };
 type RawData = {
     geographies?: RawGeography[];
@@ -81,14 +155,125 @@ type RawData = {
     tambons: RawTambon[];
 };
 
+/**
+ * Validate that a `RawData` payload has the runtime shapes `buildThaiAddressIndex`
+ * expects. Intended for consumers building an index from their own data (CSV, CMS,
+ * private datasets) who want to fail fast with a descriptive error instead of an
+ * opaque crash deep inside the normalizer, or silent `"undefined"` labels.
+ *
+ * Throws a `TypeError` (message prefixed `[thaizip]`) naming the table, the
+ * offending record's `id`, the field, and the actual `typeof` on the first bad
+ * field found. Does not filter soft-deleted rows first — validates every row as
+ * provided.
+ *
+ * IDs must be unique within each table (duplicates throw, they are not silently
+ * discarded — two suggestions sharing an id would resolve to the wrong record).
+ * Referential integrity (amphure→province, tambon→amphure) is intentionally NOT
+ * enforced: dangling references — including soft-deleted parents — are handled at
+ * build time, where the tambon is skipped and reported via `options.onSkip`.
+ */
+declare function validateRawData(data: RawData): void;
 declare function buildThaiAddressIndex(data: RawData, options?: BuildIndexOptions): TrigramIndex;
 
+/**
+ * Look up records by zip code (exact or prefix match). Exact matches are
+ * returned before prefix matches; ties are ordered by ascending zip code.
+ *
+ * Uses the build-time `sortedZipKeys`/`sortedZipPostings` arrays with a
+ * binary search for the first key ≥ the query, then walks the contiguous
+ * prefix range — O(log n_zips + matches). Ascending key order places an
+ * exact match before any longer prefix match automatically, so no explicit
+ * exact-first sort is needed. Indexes without the sorted arrays (older
+ * shape, hand-built) fall back to the original O(n_zips) scan + sort.
+ *
+ * Returned records are shallow copies: mutating them cannot corrupt the
+ * shared index (see `searchThaiAddress`).
+ *
+ * Unlike `searchThaiAddress`, results are NOT capped by `options.limit` —
+ * only by `options.zipLimit` (defaults to `Infinity`), since a zip code can
+ * legitimately map to dozens of tambons (e.g. `45000` → 33 records).
+ *
+ * Malformed runtime input (non-string `zip`, missing index shape) returns
+ * `[]` rather than crashing deep inside the library.
+ */
+declare function lookupByZipCode(index: TrigramIndex, zip: string, options?: SearchOptions): ThaiAddressRecord[];
 declare function searchThaiAddress(index: TrigramIndex, query: string, options?: SearchOptions): ThaiAddressRecord[];
 
-declare function formatThaiAddressSuggestion(record: ThaiAddressRecord): ThaiAddressSuggestion;
+/**
+ * All provinces present in the index, deduplicated and sorted by Thai name.
+ * Backed by `index.byProvince` (O(unique provinces)); falls back to scanning
+ * `index.records` if an older-shaped index lacks that map. A missing/junk
+ * index returns `[]` rather than throwing.
+ */
+declare function listProvinces(index: TrigramIndex): ProvinceSummary[];
+/**
+ * Amphures (districts) within a given province, deduplicated and sorted by
+ * Thai name. Unknown `provinceId` returns `[]`. Backed by `index.byProvince`;
+ * falls back to scanning `index.records` if an older-shaped index lacks it.
+ * A missing/junk index returns `[]` rather than throwing.
+ */
+declare function listAmphures(index: TrigramIndex, provinceId: number): AmphureSummary[];
+/**
+ * Tambons (subdistricts) within a given amphure, sorted by Thai name.
+ * Unknown `amphureId` returns `[]`. Backed by `index.byAmphure`; falls back
+ * to scanning `index.records` if an older-shaped index lacks it. Each
+ * `byAmphure` entry already maps to exactly one tambon record, so no
+ * deduplication is needed here. A missing/junk index returns `[]` rather
+ * than throwing.
+ */
+declare function listTambons(index: TrigramIndex, amphureId: number): TambonSummary[];
+
+declare function formatThaiAddressSuggestion(record: ThaiAddressRecord, options?: FormatSuggestionOptions): ThaiAddressSuggestion;
 
 declare function resolveThaiAddress(record: ThaiAddressRecord): ResolvedThaiAddress;
 
 declare function normalizeThaiAddressText(input: string): string;
 
-export { type BuildIndexOptions, type RawAmphure, type RawData, type RawGeography, type RawProvince, type RawTambon, type ResolvedThaiAddress, type SearchOptions, type ThaiAddressRecord, type ThaiAddressSuggestion, type TrigramIndex, buildThaiAddressIndex, formatThaiAddressSuggestion, normalizeThaiAddressText, resolveThaiAddress, searchThaiAddress };
+/**
+ * Romanization alias expansion for Latin-script queries.
+ *
+ * The bundled dataset indexes only the official RTGS transliteration of each
+ * name (`name_en`), so common but non-RTGS spellings a user actually types
+ * ("lardprao", "krungthep", "sukumvit") miss the index entirely. This module
+ * rewrites such a query into its RTGS form before trigram extraction.
+ *
+ * Contract:
+ * - Input is an ALREADY-NORMALIZED query (lowercased, prefixes and tone marks
+ *   stripped) as produced by `normalizeThaiAddressText`.
+ * - Output is a normalized query too — safe to hand straight to
+ *   `extractTrigramsNormalized`.
+ * - Thai-script input must be returned unchanged.
+ * - Must be a pure function; it runs on every keystroke.
+ *
+ * Design (two layers, cheapest/most-reliable first):
+ *
+ * 1. A curated dictionary of non-RTGS spelling -> exact RTGS string, as it
+ *    literally appears in a `name_en` field of the bundled dataset. Targets
+ *    were read off the real generated index (see the romanize benchmark
+ *    harness used to build this list), not guessed — a couple of entries
+ *    intentionally map onto data typos already baked into the dataset
+ *    (`loburi`, `buogkan`) because that is what is actually indexed.
+ *
+ * 2. A tiny, conservative cleanup pass used only when the dictionary misses:
+ *    collapse runs of whitespace, and strip a few English administrative
+ *    words (`district`, `province`, ...) that never occur inside a real
+ *    `name_en` value. Both were verified against the full dataset before
+ *    being added — see the "rejected rules" note below for transformations
+ *    that were tried and thrown out because they collide with real names.
+ *
+ * Rejected systematic rules (measured against the real dataset, not
+ * hypothetical): a blanket `klong` -> `khlong` rewrite would break the real
+ * tambons "Mae Klong" and "Ho Klong"; `muang` -> `mueang` would break ~122
+ * real tambons that legitimately contain "Muang" as a name component (e.g.
+ * "Bang Muang", "Khok Muang"); `huay` -> `huai` would break the real tambon
+ * "Huay Lueg"; a blanket hyphen -> space rewrite would break the ~70 real
+ * names that use a hyphen on purpose (e.g. "Bang Pa-in", the Ayutthaya
+ * palace town). None of the classic AUA-vs-RTGS letter swaps (`oo` -> `u`,
+ * trailing `-rd` -> `-t`, `dt` -> `t`, `bp` -> `p`, doubled consonants) had
+ * any real occurrence in the traffic-prioritized query set used to validate
+ * this module, so none were added — see the harness report for the
+ * before/after numbers this file was tuned against.
+ */
+declare function applyRomanizationAliases(normalized: string): string;
+
+export { type AddressLocale, type AmphureSummary, type BuildIndexOptions, type FormatSuggestionOptions, type ProvinceSummary, type RawAmphure, type RawData, type RawGeography, type RawProvince, type RawTambon, type ResolvedThaiAddress, type SearchOptions, type TambonSummary, type ThaiAddressRecord, type ThaiAddressSuggestion, type TrigramIndex, applyRomanizationAliases, buildThaiAddressIndex, formatThaiAddressSuggestion, listAmphures, listProvinces, listTambons, lookupByZipCode, normalizeThaiAddressText, resolveThaiAddress, searchThaiAddress, validateRawData };