thaizip 0.5.1 → 0.7.2

package/README.md

@@ -1,285 +1,162 @@
 # thaizip
 
-ไลบรารี autocomplete ที่อยู่ไทยแบบ fuzzy search รวดเร็ว รองรับทั้ง Vanilla JS และ React
-
-- ค้นหาได้ทั้งภาษาไทย ภาษาอังกฤษ และรหัสไปรษณีย์
-- Fuzzy search — ไม่ต้องใส่วรรณยุกต์ก็ค้นหาได้ เช่น "ลาดพราว" เจอ "ลาดพร้าว"
-- ไม่มี dependency นอกจาก React (optional)
-- โหลดข้อมูลแบบ async — ไม่บล็อก initial bundle (~132 KB gzip)
-- รองรับ ESM และ CJS
-
----
-
-## ติดตั้ง
+Fast fuzzy autocomplete for Thai addresses — subdistrict, district, province, postal code. Thai and English input, zero runtime dependencies, React optional.
 
 ```bash
 npm install thaizip
 ```
 
-ถ้าใช้กับ React ต้องมี React >= 18 เป็น peer dependency อยู่แล้ว ไม่ต้องติดตั้งเพิ่ม
-
----
-
-## การใช้งานพื้นฐาน (Vanilla JS / TypeScript)
+| import path | contents |
+|---|---|
+| `thaizip` | core functions + types (no React code, 4.4 KB gzip) |
+| `thaizip/react` | `useThaiAddressAutocomplete` (ships `"use client"`) |
+| `thaizip/data` | `loadDefaultIndex`, `clearDefaultIndex` (132 KB gzip) |
 
-### โหลด index และค้นหาที่อยู่
+## Quick start
 
 ```ts
 import { loadDefaultIndex } from 'thaizip/data'
-import { searchThaiAddress } from 'thaizip'
+import { searchThaiAddress, formatThaiAddressSuggestion, resolveThaiAddress } from 'thaizip'
 
-// โหลด index ครั้งแรก ~200ms (cached หลังจากนั้น)
-const index = await loadDefaultIndex()
+const index = await loadDefaultIndex() // ~40ms of synchronous work, cached after
 
-// ค้นหาด้วยชื่อตำบล/อำเภอ/จังหวัด
-const results = searchThaiAddress(index, 'ลาดพร้าว')
+searchThaiAddress(index, 'ลาดพร้าว')
+searchThaiAddress(index, 'bang rak')
+searchThaiAddress(index, '10500')
 
-// ค้นหาด้วยรหัสไปรษณีย์
-const results2 = searchThaiAddress(index, '10900')
-
-// ค้นหาด้วยภาษาอังกฤษ
-const results3 = searchThaiAddress(index, 'chiang mai')
-
-// ⚠️ ไม่รองรับ: ค้นหาแบบรวม text + รหัสไปรษณีย์ในครั้งเดียว (เช่น "ลาดพร้าว 10900")
-// ให้ค้นหาด้วยชื่อสถานที่ หรือรหัสไปรษณีย์ แยกกัน
-
-console.log(results)
-// [{ tambonId, tambonNameTh, tambonNameEn, amphureId, amphureNameTh, ... zipCode }, ...]
+formatThaiAddressSuggestion(record)                  // for the dropdown
+formatThaiAddressSuggestion(record, { locale: 'en' })
+resolveThaiAddress(record)                           // for saving
 ```
 
-### ตัวเลือก (options)
+Call `loadDefaultIndex()` at mount or route load — deferring it to the user's first keystroke costs ~2 dropped frames.
+
+## Search
 
 ```ts
-const results = searchThaiAddress(index, 'ลาดพร้าว', {
-  limit: 5,       // จำนวนผลลัพธ์สูงสุด (default: 10)
-  threshold: 0.4, // ความแม่นยำขั้นต่ำ 0–1 (default: 0.4)
+searchThaiAddress(index, query, {
+  limit: 10,                 // text queries only
+  threshold: 0.4,            // match quality 0–1
+  zipLimit: Infinity,        // all-digit queries — unlimited by default
+  romanizationAliases: true, // expand non-RTGS spellings
 })
 ```
 
-### แปลงผลลัพธ์เป็นรูปแบบต่าง ๆ
+Results rank by trigram score, then by how well the query matches the subdistrict's **own** name (exact → prefix → substring), then alphabetically. That second key is what keeps ตำบลลาดพร้าว above the other subdistricts that merely sit inside เขตลาดพร้าว.
 
-**`formatThaiAddressSuggestion`** — ใช้แสดงใน dropdown
+> Combined text + zip in one query (`"ลาดพร้าว 10900"`) is not supported — search by name or zip separately.
 
-```ts
-import { formatThaiAddressSuggestion } from 'thaizip'
-
-const suggestion = formatThaiAddressSuggestion(results[0])
-// {
-//   id: '100101',
-//   label: 'ลาดพร้าว > ลาดพร้าว > กรุงเทพมหานคร 10230',
-//   tambon: 'ลาดพร้าว',     tambonEn: 'Lat Phrao',
-//   amphure: 'ลาดพร้าว',    amphureEn: 'Lat Phrao',
-//   province: 'กรุงเทพมหานคร', provinceEn: 'Bangkok',
-//   zipCode: '10230',
-// }
-```
+### Postal codes
 
-**`resolveThaiAddress`** — ใช้บันทึกข้อมูลหลังผู้ใช้เลือก
+One Thai postal code can cover many subdistricts — `45000` covers 33, and 230 of the 953 codes cover more than 10 — so `zipLimit` defaults to unlimited rather than silently truncating at `limit`.
 
 ```ts
-import { resolveThaiAddress } from 'thaizip'
-
-const resolved = resolveThaiAddress(results[0])
-// {
-//   tambon: 'ลาดพร้าว',        tambonEn: 'Lat Phrao',
-//   amphure: 'ลาดพร้าว',       amphureEn: 'Lat Phrao',
-//   province: 'กรุงเทพมหานคร', provinceEn: 'Bangkok',
-//   zipCode: '10230',
-//   subdistrict: 'ลาดพร้าว',   subdistrictEn: 'Lat Phrao',
-//   district: 'ลาดพร้าว',      districtEn: 'Lat Phrao',
-//   postalCode: '10230',
-// }
-```
-
----
-
-## การใช้งานกับ React
-
-### `useThaiAddressAutocomplete`
+import { lookupByZipCode } from 'thaizip'
 
-Hook นี้จัดการ state ของ query, suggestions, debounce ให้ทั้งหมด
+lookupByZipCode(index, '45000') // exact
+lookupByZipCode(index, '450')   // prefix
+```
 
-```tsx
-import { useState, useEffect } from 'react'
-import { loadDefaultIndex } from 'thaizip/data'
-import { useThaiAddressAutocomplete } from 'thaizip'
-import type { TrigramIndex } from 'thaizip'
+### English input
 
-// แนะนำ: แยก loading และ form ออกจากกัน เพื่อให้ hook เรียกหลัง index พร้อมแล้วเสมอ
-function AddressPage() {
-  const [index, setIndex] = useState<TrigramIndex | null>(null)
+The dataset indexes official RTGS spellings, so `bang rak` and `chatuchak` work directly. 84 common non-RTGS spellings are mapped on first: `lardprao` → `lat phrao`, `ladkrabang` → `lat krabang`, `krungthep` → `bangkok`. It is a curated dictionary, not a transliterator — unlisted spellings still miss. Opt out with `romanizationAliases: false`.
 
-  useEffect(() => {
-    loadDefaultIndex().then(setIndex)
-  }, [])
+### Cascade dropdowns
 
-  if (!index) return <p>กำลังโหลด...</p>
-  return <AddressForm index={index} />
-}
+```ts
+import { listProvinces, listAmphures, listTambons } from 'thaizip'
 
-function AddressForm({ index }: { index: TrigramIndex }) {
-  const { query, setQuery, suggestions, isOpen, selectSuggestion, clear } =
-    useThaiAddressAutocomplete({
-      index,
-      limit: 10,       // default: 10
-      debounce: 200,   // default: 200ms
-      threshold: 0.4,  // default: 0.4
-    })
-
-  const [address, setAddress] = useState(null)
-
-  return (
-    <div>
-      <input
-        value={query}
-        onChange={(e) => setQuery(e.target.value)}
-        placeholder="พิมพ์ตำบล อำเภอ จังหวัด หรือรหัสไปรษณีย์"
-      />
-
-      {isOpen && (
-        <ul>
-          {suggestions.map((s) => (
-            <li key={s.id} onClick={() => {
-              const resolved = selectSuggestion(s)
-              setAddress(resolved)
-            }}>
-              {s.label}
-            </li>
-          ))}
-        </ul>
-      )}
-
-      {address && (
-        <div>
-          <p>ตำบล: {address.tambon} ({address.tambonEn})</p>
-          <p>อำเภอ: {address.amphure} ({address.amphureEn})</p>
-          <p>จังหวัด: {address.province} ({address.provinceEn})</p>
-          <p>รหัสไปรษณีย์: {address.zipCode}</p>
-        </div>
-      )}
-    </div>
-  )
-}
+listProvinces(index)            // 77, sorted by Thai name
+listAmphures(index, provinceId)
+listTambons(index, amphureId)   // each with its zipCode
 ```
 
-### Return ของ hook
-
-| ค่า | ประเภท | คำอธิบาย |
-|---|---|---|
-| `query` | `string` | ข้อความที่ผู้ใช้พิมพ์อยู่ |
-| `setQuery` | `(value: string) => void` | อัปเดต query |
-| `suggestions` | `ThaiAddressSuggestion[]` | รายการผลลัพธ์ที่แสดงใน dropdown |
-| `isOpen` | `boolean` | `true` เมื่อมี query และมี suggestions |
-| `selectSuggestion` | `(item) => ResolvedThaiAddress` | เลือก suggestion แล้วได้ข้อมูลที่อยู่ครบ |
-| `clear` | `() => void` | ล้าง query และ suggestions ทั้งหมด |
+Backed by pre-built groupings, not scans over all 7,385 records. Unknown ids return `[]`.
 
----
+## React
 
-## การใช้งานกับ Node.js / Express
+```tsx
+import { useThaiAddressAutocomplete } from 'thaizip/react'
 
-```ts
-import express from 'express'
-import { loadDefaultIndex } from 'thaizip/data'
-import { searchThaiAddress, formatThaiAddressSuggestion } from 'thaizip'
+const { query, setQuery, setQuerySilent, suggestions, isOpen, selectSuggestion, clear } =
+  useThaiAddressAutocomplete({ index })
+```
 
-const app = express()
+Options: `index`, `limit`, `debounce` (200ms), `threshold`, `zipLimit`, `locale`, `initialQuery`, `onSelect`.
 
-// โหลด index ครั้งเดียวตอน startup
-const index = await loadDefaultIndex()
+| value | description |
+|---|---|
+| `query` / `setQuery` | input value; `setQuery` searches |
+| `setQuerySilent` | set the value **without** searching or reopening the dropdown |
+| `suggestions` | `ThaiAddressSuggestion[]` |
+| `isOpen` | `query` is non-empty and suggestions exist |
+| `selectSuggestion` | `(item) => ResolvedThaiAddress \| null` — clears suggestions, leaves `query` alone; `null` if the item is stale |
+| `clear` | reset query and suggestions |
 
-app.get('/address/search', (req, res) => {
-  const query = String(req.query.q ?? '')
-  if (!query) return res.json([])
+### Controlled forms
 
-  const results = searchThaiAddress(index, query, { limit: 10 })
-  res.json(results.map(formatThaiAddressSuggestion))
-})
+`selectSuggestion` leaves `query` untouched by design. To echo the choice back into the input use `setQuerySilent` — plain `setQuery` would immediately reopen the dropdown:
 
-app.listen(3000)
+```tsx
+const handlePick = (s: ThaiAddressSuggestion) => {
+  const address = selectSuggestion(s)
+  if (!address) return
+  setQuerySilent(s.label)
+  form.setValue('address', address)
+}
 ```
 
-เรียกใช้งาน:
-```
-GET /address/search?q=ลาดพร้าว
-GET /address/search?q=10900
-```
+Editing a saved address? Pass `initialQuery` rather than calling `setQuery` in an effect.
 
----
+### Accessibility
 
-## ใช้ข้อมูล Index ของตัวเอง
+The hook owns query and suggestion state only. Keyboard navigation and ARIA combobox semantics are yours — `npx react-thaizip add autocomplete` scaffolds a component that already has them.
 
-หากต้องการสร้าง index จากข้อมูลที่กำหนดเอง
+## Custom data
 
 ```ts
-import { buildThaiAddressIndex } from 'thaizip'
+import { buildThaiAddressIndex, validateRawData } from 'thaizip'
 
-const index = buildThaiAddressIndex({
-  provinces: [...],
-  amphures: [...],
-  tambons: [...],
-  // geographies ไม่จำเป็นต้องระบุ (ไม่ได้ใช้งานโดย indexer)
+const index = buildThaiAddressIndex({ provinces, amphures, tambons }, {
+  onSkip: (tambon) => console.warn('skipped:', tambon.id),
+  validate: true, // default
 })
 ```
 
-รูปแบบข้อมูล raw ดูได้จาก type `RawData`, `RawProvince`, `RawAmphure`, `RawTambon` ที่ export มาจาก library
+Input is validated by default, so a stray non-string field fails with `[thaizip] tambon 100404: expected string for name_th, got number` instead of crashing inside the normalizer. It costs nothing measurable on a full-size dataset. `validateRawData(data)` runs the same checks standalone.
 
----
+Types: `RawData`, `RawProvince`, `RawAmphure`, `RawTambon`.
 
-## Types หลัก
+## Types
 
 ```ts
 type ThaiAddressSuggestion = {
   id: string
-  label: string        // "ตำบล > อำเภอ > จังหวัด XXXXX"
-  tambon: string
-  tambonEn: string
-  amphure: string
-  amphureEn: string
-  province: string
-  provinceEn: string
+  label: string      // follows `locale`, Thai by default
+  labelTh: string
+  labelEn: string
+  tambon: string;    tambonEn: string
+  amphure: string;   amphureEn: string
+  province: string;  provinceEn: string
   zipCode: string
 }
 
 type ResolvedThaiAddress = {
-  tambon: string        // alias: subdistrict
-  tambonEn: string      // alias: subdistrictEn
-  amphure: string       // alias: district
-  amphureEn: string     // alias: districtEn
-  province: string
-  provinceEn: string
-  zipCode: string       // alias: postalCode
-  subdistrict: string
-  subdistrictEn: string
-  district: string
-  districtEn: string
+  tambon: string;    tambonEn: string     // alias: subdistrict / subdistrictEn
+  amphure: string;   amphureEn: string    // alias: district / districtEn
+  province: string;  provinceEn: string
+  zipCode: string                         // alias: postalCode
+  subdistrict: string; subdistrictEn: string
+  district: string;    districtEn: string
   postalCode: string
 }
 ```
 
----
-
-## Migration จาก v0.2.x → v0.3.0+
-
-```ts
-// v0.2.x (sync, bundle ~630KB)
-import { defaultIndex } from 'thaizip/data'
-const results = searchThaiAddress(defaultIndex, query)
-
-// v0.3.0+ (async, bundle ~132KB gzip)
-import { loadDefaultIndex } from 'thaizip/data'
-const index = await loadDefaultIndex()  // cache อัตโนมัติ หลังจากโหลดครั้งแรก
-const results = searchThaiAddress(index, query)
-```
-
----
-
-## ข้อมูลที่อยู่
-
-ข้อมูลอ้างอิงจากการแบ่งเขตการปกครองของไทย (77 จังหวัด, 920 อำเภอ, ~7,385 ตำบล)
+## Data
 
-ตำบลที่ยังมีสถานะ active แต่อ้างอิงอำเภอที่ถูก soft-deleted จะถูกข้ามโดย index โดยอัตโนมัติ พร้อมแสดง `console.warn` ให้ทราบ
+77 provinces, 918 districts, 7,385 subdistricts. Records whose parent district or province is soft-deleted are excluded automatically.
 
----
+`searchThaiAddress` is pure and framework-free — it works unchanged in Node, Vue, Svelte, or vanilla JS.
 
 ## License
 

package/dist/data.cjs

@@ -27,8 +27,8 @@ var init_defaultData = __esm({
 });
 
 // src/core/normalizer.ts
-var TONE_MARKS = /[\u0E48-\u0E4B\u0E47\u0E4C]/g;
-var ADDRESS_PREFIXES = /^(จังหวัด|อำเภอ|ตำบล|แขวง|เขต)/;
+var TONE_MARKS = /[่-๋็์]/g;
+var ADDRESS_PREFIXES = /^(จังหวัด|อำเภอ|ตำบล|แขวง|เขต|จ\.|อ\.|ต\.|ข\.)/;
 function normalizeThaiAddressText(input) {
   if (!input) return "";
   let text = input.trim();
@@ -56,7 +56,56 @@ function extractTrigramsNormalized(text) {
 }
 
 // src/core/indexer.ts
-function buildThaiAddressIndex(data) {
+function typeErr(table, id, field, expected, value) {
+  return new TypeError(`[thaizip] ${table} ${id}: expected ${expected} for ${field}, got ${typeof value}`);
+}
+function validateRawData(data) {
+  const { provinces, amphures, tambons } = data;
+  for (let i = 0; i < provinces.length; i++) {
+    const p2 = provinces[i];
+    if (typeof p2.id !== "number") throw typeErr("province", p2.id, "id", "number", p2.id);
+    if (typeof p2.name_th !== "string") throw typeErr("province", p2.id, "name_th", "string", p2.name_th);
+    if (typeof p2.name_en !== "string") throw typeErr("province", p2.id, "name_en", "string", p2.name_en);
+  }
+  for (let i = 0; i < amphures.length; i++) {
+    const a2 = amphures[i];
+    if (typeof a2.id !== "number") throw typeErr("amphure", a2.id, "id", "number", a2.id);
+    if (typeof a2.name_th !== "string") throw typeErr("amphure", a2.id, "name_th", "string", a2.name_th);
+    if (typeof a2.name_en !== "string") throw typeErr("amphure", a2.id, "name_en", "string", a2.name_en);
+    if (typeof a2.province_id !== "number") throw typeErr("amphure", a2.id, "province_id", "number", a2.province_id);
+  }
+  for (let i = 0; i < tambons.length; i++) {
+    const t2 = tambons[i];
+    if (typeof t2.id !== "number") throw typeErr("tambon", t2.id, "id", "number", t2.id);
+    if (typeof t2.name_th !== "string") throw typeErr("tambon", t2.id, "name_th", "string", t2.name_th);
+    if (typeof t2.name_en !== "string") throw typeErr("tambon", t2.id, "name_en", "string", t2.name_en);
+    const zipType = typeof t2.zip_code;
+    if (zipType !== "string" && zipType !== "number") {
+      throw typeErr("tambon", t2.id, "zip_code", "string or number", t2.zip_code);
+    }
+    if (typeof t2.amphure_id !== "number") throw typeErr("tambon", t2.id, "amphure_id", "number", t2.amphure_id);
+  }
+}
+function addTrigrams(map, trigrams, idx) {
+  for (const trigram of trigrams) {
+    let set = map.get(trigram);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      map.set(trigram, set);
+    }
+    set.add(idx);
+  }
+}
+function combinedTrigrams(nameTh, nameEn) {
+  const s = /* @__PURE__ */ new Set();
+  for (const t2 of extractTrigrams(nameTh)) s.add(t2);
+  for (const t2 of extractTrigrams(nameEn)) s.add(t2);
+  return s;
+}
+function buildThaiAddressIndex(data, options) {
+  if (options?.validate !== false) {
+    validateRawData(data);
+  }
   const { provinces, amphures, tambons } = data;
   const provMap = new Map(
     provinces.filter((p2) => !p2.deleted_at).map((p2) => [p2.id, p2])
@@ -64,20 +113,33 @@ function buildThaiAddressIndex(data) {
   const ampMap = new Map(
     amphures.filter((a2) => !a2.deleted_at).map((a2) => [a2.id, a2])
   );
+  const provTrigrams = /* @__PURE__ */ new Map();
+  for (const [id, prov] of provMap) {
+    provTrigrams.set(id, combinedTrigrams(prov.name_th, prov.name_en));
+  }
+  const ampTrigrams = /* @__PURE__ */ new Map();
+  for (const [id, amp] of ampMap) {
+    ampTrigrams.set(id, combinedTrigrams(amp.name_th, amp.name_en));
+  }
   const records = [];
   const map = /* @__PURE__ */ new Map();
   const zipIndex = /* @__PURE__ */ new Map();
+  const normTambon = [];
+  const normTambonEn = [];
+  const byProvince = /* @__PURE__ */ new Map();
+  const byAmphure = /* @__PURE__ */ new Map();
   for (const tambon of tambons) {
     if (tambon.deleted_at) continue;
     const amphure = ampMap.get(tambon.amphure_id);
     if (!amphure) {
-      console.warn(
-        `[thaizip] skipping tambon id=${tambon.id} (${tambon.name_th}): amphure_id=${tambon.amphure_id} not found or deleted`
-      );
+      if (options?.onSkip) options.onSkip(tambon);
       continue;
     }
     const province = provMap.get(amphure.province_id);
-    if (!province) continue;
+    if (!province) {
+      if (options?.onSkip) options.onSkip(tambon);
+      continue;
+    }
     const record = {
       provinceId: province.id,
       provinceNameTh: province.name_th,
@@ -95,43 +157,55 @@ function buildThaiAddressIndex(data) {
     const existing = zipIndex.get(record.zipCode);
     if (existing) existing.push(idx);
     else zipIndex.set(record.zipCode, [idx]);
-    const fields = [
-      record.tambonNameTh,
-      record.tambonNameEn,
-      record.amphureNameTh,
-      record.amphureNameEn,
-      record.provinceNameTh,
-      record.provinceNameEn,
-      record.zipCode
-    ];
-    for (const field of fields) {
-      for (const trigram of extractTrigrams(field)) {
-        let set = map.get(trigram);
-        if (!set) {
-          set = /* @__PURE__ */ new Set();
-          map.set(trigram, set);
-        }
-        set.add(idx);
-      }
-    }
+    const provList = byProvince.get(province.id);
+    if (provList) provList.push(idx);
+    else byProvince.set(province.id, [idx]);
+    const ampList = byAmphure.get(amphure.id);
+    if (ampList) ampList.push(idx);
+    else byAmphure.set(amphure.id, [idx]);
+    const normTh = normalizeThaiAddressText(record.tambonNameTh);
+    normTambon.push(normTh);
+    addTrigrams(map, extractTrigramsNormalized(normTh), idx);
+    const normEn = normalizeThaiAddressText(record.tambonNameEn);
+    normTambonEn.push(normEn);
+    addTrigrams(map, extractTrigramsNormalized(normEn), idx);
+    addTrigrams(map, extractTrigrams(record.zipCode), idx);
+    addTrigrams(map, provTrigrams.get(province.id), idx);
+    addTrigrams(map, ampTrigrams.get(amphure.id), idx);
   }
-  return { map, records, zipIndex };
+  return { map, records, zipIndex, normTambon, normTambonEn, byProvince, byAmphure };
 }
 
 // src/data/loader.ts
 var cached = null;
+var inflightPromise = null;
+var loadGeneration = 0;
 function clearDefaultIndex() {
   cached = null;
+  inflightPromise = null;
+  loadGeneration++;
 }
 async function loadDefaultIndex() {
   if (cached) return cached;
-  const { p: p2, a: a2, t: t2 } = await Promise.resolve().then(() => (init_defaultData(), defaultData_exports));
-  cached = buildThaiAddressIndex({
-    provinces: p2.map(([id, name_th, name_en]) => ({ id, name_th, name_en, geography_id: 0, deleted_at: null })),
-    amphures: a2.map(([id, name_th, name_en, province_id]) => ({ id, name_th, name_en, province_id, deleted_at: null })),
-    tambons: t2.map(([id, name_th, name_en, amphure_id, zip_code]) => ({ id, name_th, name_en, amphure_id, zip_code: Number(zip_code), deleted_at: null }))
-  });
-  return cached;
+  if (!inflightPromise) {
+    const gen = loadGeneration;
+    inflightPromise = Promise.resolve().then(() => (init_defaultData(), defaultData_exports)).then(({ p: p2, a: a2, t: t2 }) => {
+      const index = buildThaiAddressIndex({
+        provinces: p2.map(([id, name_th, name_en]) => ({ id, name_th, name_en, geography_id: 0, deleted_at: null })),
+        amphures: a2.map(([id, name_th, name_en, province_id]) => ({ id, name_th, name_en, province_id, deleted_at: null })),
+        tambons: t2.map(([id, name_th, name_en, amphure_id, zip_code]) => ({ id, name_th, name_en, amphure_id, zip_code, deleted_at: null }))
+      }, { validate: false });
+      if (loadGeneration === gen) {
+        cached = index;
+        inflightPromise = null;
+      }
+      return index;
+    }).catch((err) => {
+      if (loadGeneration === gen) inflightPromise = null;
+      throw err;
+    });
+  }
+  return inflightPromise;
 }
 
 exports.clearDefaultIndex = clearDefaultIndex;

package/dist/data.d.cts

@@ -14,6 +14,22 @@ type TrigramIndex = {
     map: Map<string, Set<number>>;
     records: ThaiAddressRecord[];
     zipIndex: Map<string, 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[]>;
 };
 
 declare function clearDefaultIndex(): void;

package/dist/data.d.ts

@@ -14,6 +14,22 @@ type TrigramIndex = {
     map: Map<string, Set<number>>;
     records: ThaiAddressRecord[];
     zipIndex: Map<string, 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[]>;
 };
 
 declare function clearDefaultIndex(): void;