thaizip 0.6.0 → 0.7.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Narathip Thakham
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,337 +1,166 @@
 # thaizip
 
-ไลบรารี autocomplete ที่อยู่ไทยแบบ fuzzy search รวดเร็ว รองรับทั้ง Vanilla JS และ React
+Fast fuzzy autocomplete for Thai addresses — subdistrict, district, province, postal code. Thai and English input, zero runtime dependencies, React optional.
 
-- ค้นหาได้ทั้งภาษาไทย ภาษาอังกฤษ และรหัสไปรษณีย์
-- Fuzzy search — ไม่ต้องใส่วรรณยุกต์ก็ค้นหาได้ เช่น "ลาดพราว" เจอ "ลาดพร้าว"
-- ไม่มี dependency นอกจาก React (optional)
-- โหลดข้อมูลแบบ async — ไม่บล็อก initial bundle (~132 KB gzip)
-- รองรับ ESM และ CJS
-
----
-
-## ติดตั้ง
+**Docs:** https://naay99999.github.io/thai-zip/ (ไทย / [English](https://naay99999.github.io/thai-zip/en/))
 
 ```bash
 npm install thaizip
 ```
 
-ถ้าใช้กับ React ต้องมี React >= 18 เป็น peer dependency อยู่แล้ว ไม่ต้องติดตั้งเพิ่ม
-
----
-
-## Package exports
-
-| import path | เนื้อหา |
+| import path | contents |
 |---|---|
-| `thaizip` | core functions + types ทั้งหมด (ไม่มี React) |
-| `thaizip/react` | `useThaiAddressAutocomplete` hook + types |
-| `thaizip/data` | `loadDefaultIndex`, `clearDefaultIndex` |
-
----
+| `thaizip` | core functions + types (no React code, 4.4 KB gzip) |
+| `thaizip/react` | `useThaiAddressAutocomplete` (ships `"use client"`) |
+| `thaizip/data` | `loadDefaultIndex`, `clearDefaultIndex` (132 KB gzip) |
 
-## การใช้งานพื้นฐาน (Vanilla JS / TypeScript)
-
-### โหลด index และค้นหาที่อยู่
+## Quick start
 
 ```ts
 import { loadDefaultIndex } from 'thaizip/data'
-import { searchThaiAddress } from 'thaizip'
-
-// โหลด index ครั้งแรก ~200ms (cached หลังจากนั้น)
-const index = await loadDefaultIndex()
+import { searchThaiAddress, formatThaiAddressSuggestion, resolveThaiAddress } from 'thaizip'
 
-// ค้นหาด้วยชื่อตำบล/อำเภอ/จังหวัด
-const results = searchThaiAddress(index, 'ลาดพร้าว')
+const index = await loadDefaultIndex() // ~40ms of synchronous work, cached after
 
-// ค้นหาด้วยรหัสไปรษณีย์
-const results2 = searchThaiAddress(index, '10900')
+searchThaiAddress(index, 'ลาดพร้าว')
+searchThaiAddress(index, 'bang rak')
+searchThaiAddress(index, '10500')
 
-// ค้นหาด้วยภาษาอังกฤษ
-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
+import { lookupByZipCode } from 'thaizip'
 
-### `useThaiAddressAutocomplete`
-
-Hook นี้จัดการ state ของ query, suggestions, debounce ให้ทั้งหมด **import จาก `thaizip/react`**
+lookupByZipCode(index, '45000') // exact
+lookupByZipCode(index, '450')   // prefix
+```
 
-```tsx
-import { useState, useEffect } from 'react'
-import { loadDefaultIndex } from 'thaizip/data'
-import { useThaiAddressAutocomplete } from 'thaizip/react'
-import type { TrigramIndex, ResolvedThaiAddress } from 'thaizip/react'
+### 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. 87 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<ResolvedThaiAddress | null>(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
+Backed by pre-built groupings, not scans over all 7,385 records. Unknown ids return `[]`.
 
-| ค่า | ประเภท | คำอธิบาย |
-|---|---|---|
-| `query` | `string` | ข้อความที่ผู้ใช้พิมพ์อยู่ |
-| `setQuery` | `(value: string) => void` | อัปเดต query |
-| `suggestions` | `ThaiAddressSuggestion[]` | รายการผลลัพธ์ที่แสดงใน dropdown |
-| `isOpen` | `boolean` | `true` เมื่อมี query และมี suggestions |
-| `selectSuggestion` | `(item) => ResolvedThaiAddress` | เลือก suggestion แล้วได้ข้อมูลที่อยู่ครบ |
-| `clear` | `() => void` | ล้าง query และ suggestions ทั้งหมด |
+## React
 
----
-
-## การใช้งานกับ Node.js / Express
-
-```ts
-import express from 'express'
-import { loadDefaultIndex } from 'thaizip/data'
-import { searchThaiAddress, formatThaiAddressSuggestion } from 'thaizip'
+```tsx
+import { useThaiAddressAutocomplete } from 'thaizip/react'
 
-const app = express()
+const { query, setQuery, setQuerySilent, suggestions, isOpen, selectSuggestion, clear } =
+  useThaiAddressAutocomplete({ index })
+```
 
-// โหลด index ครั้งเดียวตอน startup
-const index = await loadDefaultIndex()
+Options: `index`, `limit`, `debounce` (200ms), `threshold`, `zipLimit`, `locale`, `initialQuery`, `onSelect`.
 
-app.get('/address/search', (req, res) => {
-  const query = String(req.query.q ?? '')
-  if (!query) return res.json([])
+| 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 |
 
-  const results = searchThaiAddress(index, query, { limit: 10 })
-  res.json(results.map(formatThaiAddressSuggestion))
-})
+### Controlled forms
 
-app.listen(3000)
-```
+`selectSuggestion` leaves `query` untouched by design. To echo the choice back into the input use `setQuerySilent` — plain `setQuery` would immediately reopen the dropdown:
 
-เรียกใช้งาน:
-```
-GET /address/search?q=ลาดพร้าว
-GET /address/search?q=10900
+```tsx
+const handlePick = (s: ThaiAddressSuggestion) => {
+  const address = selectSuggestion(s)
+  if (!address) return
+  setQuerySilent(s.label)
+  form.setValue('address', address)
+}
 ```
 
----
-
-## ใช้ข้อมูล Index ของตัวเอง
+Editing a saved address? Pass `initialQuery` rather than calling `setQuery` in an effect.
 
-หากต้องการสร้าง index จากข้อมูลที่กำหนดเอง
+### Accessibility
 
-```ts
-import { buildThaiAddressIndex } from 'thaizip'
-
-const index = buildThaiAddressIndex({
-  provinces: [...],
-  amphures: [...],
-  tambons: [...],
-  // geographies ไม่จำเป็นต้องระบุ (ไม่ได้ใช้งานโดย indexer)
-}, {
-  // รับ callback เมื่อ tambon ถูกข้ามเนื่องจากไม่พบ amphure/province
-  onSkip: (tambon) => console.warn('skipped tambon:', tambon.id),
-})
-```
+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.
 
-### reset cache (สำหรับ test isolation)
+## Custom data
 
 ```ts
-import { clearDefaultIndex } from 'thaizip/data'
+import { buildThaiAddressIndex, validateRawData } from 'thaizip'
 
-clearDefaultIndex() // รีเซ็ต singleton cache ของ loadDefaultIndex
+const index = buildThaiAddressIndex({ provinces, amphures, tambons }, {
+  onSkip: (tambon) => console.warn('skipped:', tambon.id),
+  validate: true, // default
+})
 ```
 
-รูปแบบข้อมูล raw ดูได้จาก type `RawData`, `RawProvince`, `RawAmphure`, `RawTambon` ที่ export มาจาก `thaizip`
+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.
 
----
+`RawData` is meant to be trusted, application-controlled input — your own dataset, not arbitrary end-user uploads. `buildThaiAddressIndex` has no built-in cap on row count or field length; build cost scales linearly with total input size, but an unbounded or maliciously oversized payload (e.g. an admin importer fed directly to this function) can still cost real time and memory with nothing to stop it. If you ever build an index from untrusted input, enforce your own size limits (row count, field length) before calling `buildThaiAddressIndex`.
 
-## Types หลัก
+Types: `RawData`, `RawProvince`, `RawAmphure`, `RawTambon`.
 
-Types ทั้งหมดสามารถ import ได้จาก `thaizip` หรือ `thaizip/react` (React-specific types)
+## Types
 
 ```ts
-// จาก thaizip หรือ thaizip/react
 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
 }
 
-// จาก thaizip หรือ thaizip/react
 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.5.x → v1.0.0
-
-### hook ย้ายไปอยู่ที่ `thaizip/react`
-
-```ts
-// v0.5.x
-import { useThaiAddressAutocomplete } from 'thaizip'
-import type { TrigramIndex } from 'thaizip'
-
-// v1.0.0
-import { useThaiAddressAutocomplete } from 'thaizip/react'
-import type { TrigramIndex, ResolvedThaiAddress, ThaiAddressSuggestion } from 'thaizip/react'
-// หรือยังคง import types จาก 'thaizip' ได้เช่นเดิม
-```
-
-### `clearDefaultIndex` ย้ายไปอยู่ที่ `thaizip/data`
-
-```ts
-// v0.5.x
-import { clearDefaultIndex } from 'thaizip'
-
-// v1.0.0
-import { clearDefaultIndex } from 'thaizip/data'
-```
-
----
-
-## 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 โดยอัตโนมัติ ใช้ `onSkip` callback ใน `buildThaiAddressIndex` เพื่อรับแจ้ง
+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