thaizip 0.2.1 → 0.4.0

package/README.md

@@ -5,7 +5,7 @@
 - ค้นหาได้ทั้งภาษาไทย ภาษาอังกฤษ และรหัสไปรษณีย์
 - Fuzzy search — ไม่ต้องใส่วรรณยุกต์ก็ค้นหาได้ เช่น "ลาดพราว" เจอ "ลาดพร้าว"
 - ไม่มี dependency นอกจาก React (optional)
-- Index สร้างไว้ล่วงหน้า ไม่มีต้นทุนตอน runtime
+- โหลดข้อมูลแบบ async — ไม่บล็อก initial bundle (~132 KB gzip)
 - รองรับ ESM และ CJS
 
 ---
@@ -22,20 +22,26 @@ npm install thaizip
 
 ## การใช้งานพื้นฐาน (Vanilla JS / TypeScript)
 
-### ค้นหาที่อยู่
+### โหลด index และค้นหาที่อยู่
 
 ```ts
-import { defaultIndex } from 'thaizip/data'
+import { loadDefaultIndex } from 'thaizip/data'
 import { searchThaiAddress } from 'thaizip'
 
+// โหลด index ครั้งแรก ~200ms (cached หลังจากนั้น)
+const index = await loadDefaultIndex()
+
 // ค้นหาด้วยชื่อตำบล/อำเภอ/จังหวัด
-const results = searchThaiAddress(defaultIndex, 'ลาดพร้าว')
+const results = searchThaiAddress(index, 'ลาดพร้าว')
 
 // ค้นหาด้วยรหัสไปรษณีย์
-const results = searchThaiAddress(defaultIndex, '10900')
+const results2 = searchThaiAddress(index, '10900')
 
 // ค้นหาด้วยภาษาอังกฤษ
-const results = searchThaiAddress(defaultIndex, 'chiang mai')
+const results3 = searchThaiAddress(index, 'chiang mai')
+
+// ⚠️ ไม่รองรับ: ค้นหาแบบรวม text + รหัสไปรษณีย์ในครั้งเดียว (เช่น "ลาดพร้าว 10900")
+// ให้ค้นหาด้วยชื่อสถานที่ หรือรหัสไปรษณีย์ แยกกัน
 
 console.log(results)
 // [{ tambonId, tambonNameTh, tambonNameEn, amphureId, amphureNameTh, ... zipCode }, ...]
@@ -44,7 +50,7 @@ console.log(results)
 ### ตัวเลือก (options)
 
 ```ts
-const results = searchThaiAddress(defaultIndex, 'ลาดพร้าว', {
+const results = searchThaiAddress(index, 'ลาดพร้าว', {
   limit: 5,       // จำนวนผลลัพธ์สูงสุด (default: 10)
   threshold: 0.4, // ความแม่นยำขั้นต่ำ 0–1 (default: 0.4)
 })
@@ -61,9 +67,9 @@ const suggestion = formatThaiAddressSuggestion(results[0])
 // {
 //   id: '100101',
 //   label: 'ลาดพร้าว > ลาดพร้าว > กรุงเทพมหานคร 10230',
-//   tambon: 'ลาดพร้าว',
-//   amphure: 'ลาดพร้าว',
-//   province: 'กรุงเทพมหานคร',
+//   tambon: 'ลาดพร้าว',     tambonEn: 'Lat Phrao',
+//   amphure: 'ลาดพร้าว',    amphureEn: 'Lat Phrao',
+//   province: 'กรุงเทพมหานคร', provinceEn: 'Bangkok',
 //   zipCode: '10230',
 // }
 ```
@@ -75,10 +81,13 @@ import { resolveThaiAddress } from 'thaizip'
 
 const resolved = resolveThaiAddress(results[0])
 // {
-//   tambon: 'ลาดพร้าว',        subdistrict: 'ลาดพร้าว',
-//   amphure: 'ลาดพร้าว',       district: 'ลาดพร้าว',
-//   province: 'กรุงเทพมหานคร',
-//   zipCode: '10230',           postalCode: '10230',
+//   tambon: 'ลาดพร้าว',        tambonEn: 'Lat Phrao',
+//   amphure: 'ลาดพร้าว',       amphureEn: 'Lat Phrao',
+//   province: 'กรุงเทพมหานคร', provinceEn: 'Bangkok',
+//   zipCode: '10230',
+//   subdistrict: 'ลาดพร้าว',   subdistrictEn: 'Lat Phrao',
+//   district: 'ลาดพร้าว',      districtEn: 'Lat Phrao',
+//   postalCode: '10230',
 // }
 ```
 
@@ -91,13 +100,27 @@ const resolved = resolveThaiAddress(results[0])
 Hook นี้จัดการ state ของ query, suggestions, debounce ให้ทั้งหมด
 
 ```tsx
-import { defaultIndex } from 'thaizip/data'
+import { useState, useEffect } from 'react'
+import { loadDefaultIndex } from 'thaizip/data'
 import { useThaiAddressAutocomplete } from 'thaizip'
+import type { TrigramIndex } from 'thaizip'
+
+// แนะนำ: แยก loading และ form ออกจากกัน เพื่อให้ hook เรียกหลัง index พร้อมแล้วเสมอ
+function AddressPage() {
+  const [index, setIndex] = useState<TrigramIndex | null>(null)
 
-function AddressForm() {
+  useEffect(() => {
+    loadDefaultIndex().then(setIndex)
+  }, [])
+
+  if (!index) return <p>กำลังโหลด...</p>
+  return <AddressForm index={index} />
+}
+
+function AddressForm({ index }: { index: TrigramIndex }) {
   const { query, setQuery, suggestions, isOpen, selectSuggestion, clear } =
     useThaiAddressAutocomplete({
-      index: defaultIndex,
+      index,
       limit: 10,       // default: 10
       debounce: 200,   // default: 200ms
       threshold: 0.4,  // default: 0.4
@@ -128,9 +151,9 @@ function AddressForm() {
 
       {address && (
         <div>
-          <p>ตำบล: {address.tambon}</p>
-          <p>อำเภอ: {address.amphure}</p>
-          <p>จังหวัด: {address.province}</p>
+          <p>ตำบล: {address.tambon} ({address.tambonEn})</p>
+          <p>อำเภอ: {address.amphure} ({address.amphureEn})</p>
+          <p>จังหวัด: {address.province} ({address.provinceEn})</p>
           <p>รหัสไปรษณีย์: {address.zipCode}</p>
         </div>
       )}
@@ -156,16 +179,19 @@ function AddressForm() {
 
 ```ts
 import express from 'express'
-import { defaultIndex } from 'thaizip/data'
+import { loadDefaultIndex } from 'thaizip/data'
 import { searchThaiAddress, formatThaiAddressSuggestion } from 'thaizip'
 
 const app = express()
 
+// โหลด index ครั้งเดียวตอน startup
+const index = await loadDefaultIndex()
+
 app.get('/address/search', (req, res) => {
   const query = String(req.query.q ?? '')
   if (!query) return res.json([])
 
-  const results = searchThaiAddress(defaultIndex, query, { limit: 10 })
+  const results = searchThaiAddress(index, query, { limit: 10 })
   res.json(results.map(formatThaiAddressSuggestion))
 })
 
@@ -188,10 +214,10 @@ GET /address/search?q=10900
 import { buildThaiAddressIndex } from 'thaizip'
 
 const index = buildThaiAddressIndex({
-  geographies: [...],
   provinces: [...],
   amphures: [...],
   tambons: [...],
+  // geographies ไม่จำเป็นต้องระบุ (ไม่ได้ใช้งานโดย indexer)
 })
 ```
 
@@ -204,26 +230,57 @@ const index = buildThaiAddressIndex({
 ```ts
 type ThaiAddressSuggestion = {
   id: string
-  label: string       // "ตำบล > อำเภอ > จังหวัด XXXXX"
+  label: string        // "ตำบล > อำเภอ > จังหวัด XXXXX"
   tambon: string
+  tambonEn: string
   amphure: string
+  amphureEn: string
   province: string
+  provinceEn: string
   zipCode: string
 }
 
 type ResolvedThaiAddress = {
-  tambon: string      // alias: subdistrict
-  amphure: string     // alias: district
+  tambon: string        // alias: subdistrict
+  tambonEn: string      // alias: subdistrictEn
+  amphure: string       // alias: district
+  amphureEn: string     // alias: districtEn
   province: string
-  zipCode: string     // alias: postalCode
+  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 ตำบล)
+
+ตำบลที่ยังมีสถานะ active แต่อ้างอิงอำเภอที่ถูก soft-deleted จะถูกข้ามโดย index โดยอัตโนมัติ พร้อมแสดง `console.warn` ให้ทราบ
+
+---
+
 ## License
 
 MIT