ข้ามไปยังเนื้อหา
thaizip

เริ่มต้นใช้งาน

thaizip เป็นไลบรารีค้นหาที่อยู่ไทยแบบ headless — ไม่มี runtime dependency และไม่ผูกกับเฟรมเวิร์กใด ๆ หน้านี้พาไปตั้งแต่ติดตั้งจนค้นหาได้ผลลัพธ์แรก

ติดตั้ง

หัวข้อ “ติดตั้ง”
Terminal window
npm install thaizip

ต้องใช้ Node.js เวอร์ชัน 18 ขึ้นไป ส่วน React เป็น peer dependency แบบ optional — ใช้เฉพาะถ้าต้องการ hook useThaiAddressAutocomplete จาก thaizip/react เท่านั้น ไม่ใช้ React ก็เรียกใช้ API หลักได้ตามปกติ

สาม entry points

หัวข้อ “สาม entry points”

แพ็กเกจแบ่งออกเป็นสาม entry points เพื่อให้ import เฉพาะส่วนที่ใช้จริง:

import path เนื้อหา
thaizip ฟังก์ชันและ type หลัก (ไม่มีโค้ด React, 4.4 KB gzip)
thaizip/react useThaiAddressAutocomplete (แนบ "use client" มาให้)
thaizip/data loadDefaultIndex, clearDefaultIndex, getDefaultIndexIfLoaded (2.3 KB gzip + ก้อนข้อมูลอีก 114 KB gzip ที่ดึงทีหลัง)

thaizip/data แยกออกมาต่างหากเพราะเป็นก้อนข้อมูลที่ใหญ่ที่สุด — ตัว bundler ที่รองรับ tree-shaking จะไม่ดึงเข้ามาถ้าไม่ได้ import

ตัวชุดข้อมูลเองยังถูกแยกเป็นไฟล์ของมันเองอีกชั้น ดังนั้น bundler ที่แยก chunk ตาม dynamic import ได้ (webpack, Turbopack, Vite/Rollup) จะยังไม่ดาวน์โหลด 114 KB นั้นจนกว่าจะเรียก loadDefaultIndex() จริง ๆ — แค่ import thaizip/data เฉย ๆ ยังไม่ทำให้โหลด ทั้งนี้เป็นการรับประกันแบบ best-effort: bundler หรือโหมด build บางแบบ (เช่น SSR/CJS บางกรณี) ที่ inline dynamic import ทั้งหมดจะยังรวมมันเข้า chunk แรกอยู่ดี

โหลด index แล้วค้นหา

หัวข้อ “โหลด index แล้วค้นหา”
import { loadDefaultIndex } from 'thaizip/data'
import { searchThaiAddress, formatThaiAddressSuggestion, resolveThaiAddress } from 'thaizip'


const index = await loadDefaultIndex() // ~40ms of synchronous work, cached after


searchThaiAddress(index, 'ลาดพร้าว')
searchThaiAddress(index, 'bang rak')
searchThaiAddress(index, '10500')

loadDefaultIndex() โหลดข้อมูล tambon/amphure/province ทั้งหมดแล้วสร้าง trigram index ในหน่วยความจำ ผลลัพธ์จะถูก cache ไว้เป็น singleton ระดับโมดูล เรียกซ้ำครั้งต่อไปจึงได้ index เดิมกลับมาทันทีโดยไม่ต้องสร้างใหม่

เคล็ดลับ performance

หัวข้อ “เคล็ดลับ performance”

เรียก loadDefaultIndex() ตอน mount คอมโพเนนต์หรือตอนโหลด route ไว้ล่วงหน้า อย่ารอให้ผู้ใช้พิมพ์ตัวอักษรแรกก่อนค่อยเรียก เพราะงานสร้าง index กินเวลาราว 40ms แบบ synchronous บน main thread — ถ้าไปเกิดขึ้นตอนกดคีย์บอร์ดจะรู้สึกได้ถึงเฟรมที่หลุดไปประมาณ 2 เฟรม

ไปต่อ

หัวข้อ “ไปต่อ”