thaizip 0.7.6 → 0.7.7

package/README.md

@@ -1,177 +1,56 @@
 # thaizip
 
 [![npm version](https://img.shields.io/npm/v/thaizip.svg)](https://www.npmjs.com/package/thaizip)
-[![npm downloads](https://img.shields.io/npm/dm/thaizip.svg)](https://www.npmjs.com/package/thaizip)
 [![license](https://img.shields.io/npm/l/thaizip.svg)](https://github.com/naay99999/thai-zip/blob/main/LICENSE)
 
-Fast fuzzy autocomplete for Thai addresses — subdistrict, district, province, postal code. Thai and English input, zero runtime dependencies, React optional.
+Fast fuzzy autocomplete for Thai addresses — subdistrict, district, province, postal code.
 
-**Docs:** https://naay99999.github.io/thai-zip/ (ไทย / [English](https://naay99999.github.io/thai-zip/en/))
+📚 **[Documentation](https://naay99999.github.io/thai-zip/)** (ไทย / [English](https://naay99999.github.io/thai-zip/en/)) · [Playground](https://naay99999.github.io/thai-zip/en/playground/)
 
-| Thai input | English input (romanization alias) |
-|---|---|
-| ![thaizip demo — typing "ลาดพร้าว" and getting fuzzy Thai suggestions](.github/assets/demo.png) | ![thaizip demo — typing "ladprao" and matching the same Thai suggestions](.github/assets/demo-en.png) |
+![thaizip demo — typing "ลาดพร้าว", "ladprao" and "10230" to get fuzzy Thai address suggestions, then resolving a selection](.github/assets/demo.gif)
+
+## Features
+
+- **Fuzzy search** in Thai or English — typos and common spellings like `ladprao` still match
+- **Postal code lookup** — exact or prefix (`10230`, `102`)
+- **Cascade dropdowns** — province → district → subdistrict
+- **Bundled data** — 77 provinces, 918 districts, 7,385 subdistricts, loaded lazily
+- **Zero runtime dependencies**, works anywhere JS runs; optional React hook
+
+## Install
 
 ```bash
 npm install thaizip
 ```
 
-| import path | contents |
-|---|---|
-| `thaizip` | core functions + types (no React code, 4.4 KB gzip) |
-| `thaizip/react` | `useThaiAddressAutocomplete` (ships `"use client"`) |
-| `thaizip/data` | `loadDefaultIndex`, `clearDefaultIndex`, `getDefaultIndexIfLoaded` (2.3 KB gzip, plus a 114 KB gzip data chunk fetched lazily on the first `loadDefaultIndex()` call) |
-
 ## Quick start
 
 ```ts
 import { loadDefaultIndex } from 'thaizip/data'
-import { searchThaiAddress, formatThaiAddressSuggestion, resolveThaiAddress } from 'thaizip'
+import { searchThaiAddress, resolveThaiAddress } from 'thaizip'
 
-const index = await loadDefaultIndex() // ~50ms on the measured device, cached after
+const index = await loadDefaultIndex()
 
-searchThaiAddress(index, 'ลาดพร้าว')
-searchThaiAddress(index, 'bang rak')
-searchThaiAddress(index, '10500')
-
-formatThaiAddressSuggestion(record)                  // for the dropdown
-formatThaiAddressSuggestion(record, { locale: 'en' })
-resolveThaiAddress(record)                           // for saving
+const [record] = searchThaiAddress(index, 'ลาดพร้าว')
+resolveThaiAddress(record)
+// { subdistrict: 'ลาดพร้าว', district: 'เขตลาดพร้าว', province: 'กรุงเทพมหานคร', postalCode: '10230', ... }
 ```
 
-Call `loadDefaultIndex()` at mount or route load — deferring it to the user's first keystroke can block the UI briefly.
-The cached default index is shared. Ordinary writes to its records and lookup structures throw; build a separate index with `buildThaiAddressIndex` if you need to edit address data. This is protection against accidental changes, not a security boundary against hostile code already running in the same JavaScript realm.
-
-## Search
-
-```ts
-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 เขตลาดพร้าว.
-
-> Combined text + zip in one query (`"ลาดพร้าว 10900"`) is not supported — search by name or zip separately.
-
-### Postal codes
-
-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 { lookupByZipCode } from 'thaizip'
-
-lookupByZipCode(index, '45000') // exact
-lookupByZipCode(index, '450')   // prefix
-```
-
-Direct ZIP lookup rejects raw inputs longer than 1000 characters before scanning them. A finite `zipLimit` also bounds how many matching records are collected.
-
-### English input
-
-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`.
-
-### Cascade dropdowns
-
-```ts
-import { listProvinces, listAmphures, listTambons } from 'thaizip'
-
-listProvinces(index)            // 77, sorted by Thai name
-listAmphures(index, provinceId)
-listTambons(index, amphureId)   // each with its zipCode
-```
-
-Backed by pre-built groupings, not scans over all 7,385 records. Unknown ids return `[]`.
-
-## React
+React:
 
 ```tsx
 import { useThaiAddressAutocomplete } from 'thaizip/react'
 
-const { query, setQuery, setQuerySilent, suggestions, isOpen, selectSuggestion, clear } =
-  useThaiAddressAutocomplete({ index })
-```
-
-Options: `index`, `limit`, `debounce` (200ms), `threshold`, `zipLimit`, `locale`, `initialQuery`, `onSelect`.
-
-| 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 |
-
-### Controlled forms
-
-`selectSuggestion` leaves `query` untouched by design. To echo the choice back into the input use `setQuerySilent` — plain `setQuery` would immediately reopen the dropdown:
-
-```tsx
-const handlePick = (s: ThaiAddressSuggestion) => {
-  const address = selectSuggestion(s)
-  if (!address) return
-  setQuerySilent(s.label)
-  form.setValue('address', address)
-}
-```
-
-Editing a saved address? Pass `initialQuery` rather than calling `setQuery` in an effect.
-
-### Accessibility
-
-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.
-
-## Custom data
-
-```ts
-import { buildThaiAddressIndex, validateRawData } from 'thaizip'
-
-const index = buildThaiAddressIndex({ provinces, amphures, tambons }, {
-  onSkip: (tambon) => console.warn('skipped:', tambon.id),
-  validate: true, // default
-})
-```
-
-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. `validateRawData(data)` runs the same checks standalone.
-
-Validation also rejects more than 50,000 total rows, names longer than 256 UTF-16 code units, ZIP values longer than 32 code units, or an estimated trigram posting cost above 1,000,000. The estimate counts each province/district's unique trigrams once for every active child subdistrict, so it catches parent-name fan-out. These bounds are suitable for the bundled-size dataset, not a guarantee that arbitrary uploads are safe to process. For larger trusted datasets, pass `{ validate: false }` and apply your own resource limits before building.
-
-Types: `RawData`, `RawProvince`, `RawAmphure`, `RawTambon`.
-
-## Types
-
-```ts
-type ThaiAddressSuggestion = {
-  id: 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;    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
-}
+const { query, setQuery, suggestions, selectSuggestion } = useThaiAddressAutocomplete({ index })
 ```
 
-## Data
+Need a ready-made UI component? [`react-thaizip`](https://github.com/naay99999/react-thai-zip) scaffolds one into your project.
 
-77 provinces, 918 districts, 7,385 subdistricts. Records whose parent district or province is soft-deleted are excluded automatically.
+## Learn more
 
-`searchThaiAddress` is pure and framework-free — it works unchanged in Node, Vue, Svelte, or vanilla JS.
+- [Getting started](https://naay99999.github.io/thai-zip/en/getting-started/)
+- [Guides](https://naay99999.github.io/thai-zip/en/guides/search/) — search, postal codes, cascades, English input, React, custom data
+- [API reference](https://naay99999.github.io/thai-zip/en/reference/search/)
 
 ## License
 

package/dist/data.cjs

@@ -42,6 +42,12 @@ var MAX_POSTING_BUDGET = 1e6;
 function typeErr(table, id, field, expected, value) {
   return new TypeError(`[thaizip] ${table} ${id}: expected ${expected} for ${field}, got ${typeof value}`);
 }
+function assertId(table, id, field, value) {
+  if (typeof value !== "number") throw typeErr(table, id, field, "number", value);
+  if (!Number.isSafeInteger(value)) {
+    throw new TypeError(`[thaizip] ${table} ${id}: expected safe integer for ${field}, got ${value}`);
+  }
+}
 function typeName(value) {
   return value === null ? "null" : typeof value;
 }
@@ -68,7 +74,7 @@ function validateRawData(data) {
     if (p === null || typeof p !== "object") {
       throw new TypeError(`[thaizip] province[${i}]: expected object, got ${typeName(p)}`);
     }
-    if (typeof p.id !== "number") throw typeErr("province", p.id, "id", "number", p.id);
+    assertId("province", p.id, "id", p.id);
     if (provinceById.has(p.id)) throw new TypeError(`[thaizip] duplicate province id: ${p.id}`);
     provinceById.set(p.id, p);
     if (typeof p.name_th !== "string") throw typeErr("province", p.id, "name_th", "string", p.name_th);
@@ -82,12 +88,12 @@ function validateRawData(data) {
     if (a === null || typeof a !== "object") {
       throw new TypeError(`[thaizip] amphure[${i}]: expected object, got ${typeName(a)}`);
     }
-    if (typeof a.id !== "number") throw typeErr("amphure", a.id, "id", "number", a.id);
+    assertId("amphure", a.id, "id", a.id);
     if (amphureById.has(a.id)) throw new TypeError(`[thaizip] duplicate amphure id: ${a.id}`);
     amphureById.set(a.id, a);
     if (typeof a.name_th !== "string") throw typeErr("amphure", a.id, "name_th", "string", a.name_th);
     if (typeof a.name_en !== "string") throw typeErr("amphure", a.id, "name_en", "string", a.name_en);
-    if (typeof a.province_id !== "number") throw typeErr("amphure", a.id, "province_id", "number", a.province_id);
+    assertId("amphure", a.id, "province_id", a.province_id);
     if (a.name_th.length > MAX_NAME_LENGTH) throw new RangeError(`[thaizip] amphure ${a.id}: name_th too long`);
     if (a.name_en.length > MAX_NAME_LENGTH) throw new RangeError(`[thaizip] amphure ${a.id}: name_en too long`);
   }
@@ -100,7 +106,7 @@ function validateRawData(data) {
     if (t === null || typeof t !== "object") {
       throw new TypeError(`[thaizip] tambon[${i}]: expected object, got ${typeName(t)}`);
     }
-    if (typeof t.id !== "number") throw typeErr("tambon", t.id, "id", "number", t.id);
+    assertId("tambon", t.id, "id", t.id);
     if (seenTambonIds.has(t.id)) throw new TypeError(`[thaizip] duplicate tambon id: ${t.id}`);
     seenTambonIds.add(t.id);
     if (typeof t.name_th !== "string") throw typeErr("tambon", t.id, "name_th", "string", t.name_th);
@@ -111,7 +117,7 @@ function validateRawData(data) {
     if (zipType !== "string" && zipType !== "number") {
       throw typeErr("tambon", t.id, "zip_code", "string or number", t.zip_code);
     }
-    if (typeof t.amphure_id !== "number") throw typeErr("tambon", t.id, "amphure_id", "number", t.amphure_id);
+    assertId("tambon", t.id, "amphure_id", t.amphure_id);
     const zipLength = String(t.zip_code).length;
     if (zipLength > MAX_ZIP_LENGTH) throw new RangeError(`[thaizip] tambon ${t.id}: zip_code too long`);
     if (t.deleted_at) continue;

package/dist/data.js

@@ -40,6 +40,12 @@ var MAX_POSTING_BUDGET = 1e6;
 function typeErr(table, id, field, expected, value) {
   return new TypeError(`[thaizip] ${table} ${id}: expected ${expected} for ${field}, got ${typeof value}`);
 }
+function assertId(table, id, field, value) {
+  if (typeof value !== "number") throw typeErr(table, id, field, "number", value);
+  if (!Number.isSafeInteger(value)) {
+    throw new TypeError(`[thaizip] ${table} ${id}: expected safe integer for ${field}, got ${value}`);
+  }
+}
 function typeName(value) {
   return value === null ? "null" : typeof value;
 }
@@ -66,7 +72,7 @@ function validateRawData(data) {
     if (p === null || typeof p !== "object") {
       throw new TypeError(`[thaizip] province[${i}]: expected object, got ${typeName(p)}`);
     }
-    if (typeof p.id !== "number") throw typeErr("province", p.id, "id", "number", p.id);
+    assertId("province", p.id, "id", p.id);
     if (provinceById.has(p.id)) throw new TypeError(`[thaizip] duplicate province id: ${p.id}`);
     provinceById.set(p.id, p);
     if (typeof p.name_th !== "string") throw typeErr("province", p.id, "name_th", "string", p.name_th);
@@ -80,12 +86,12 @@ function validateRawData(data) {
     if (a === null || typeof a !== "object") {
       throw new TypeError(`[thaizip] amphure[${i}]: expected object, got ${typeName(a)}`);
     }
-    if (typeof a.id !== "number") throw typeErr("amphure", a.id, "id", "number", a.id);
+    assertId("amphure", a.id, "id", a.id);
     if (amphureById.has(a.id)) throw new TypeError(`[thaizip] duplicate amphure id: ${a.id}`);
     amphureById.set(a.id, a);
     if (typeof a.name_th !== "string") throw typeErr("amphure", a.id, "name_th", "string", a.name_th);
     if (typeof a.name_en !== "string") throw typeErr("amphure", a.id, "name_en", "string", a.name_en);
-    if (typeof a.province_id !== "number") throw typeErr("amphure", a.id, "province_id", "number", a.province_id);
+    assertId("amphure", a.id, "province_id", a.province_id);
     if (a.name_th.length > MAX_NAME_LENGTH) throw new RangeError(`[thaizip] amphure ${a.id}: name_th too long`);
     if (a.name_en.length > MAX_NAME_LENGTH) throw new RangeError(`[thaizip] amphure ${a.id}: name_en too long`);
   }
@@ -98,7 +104,7 @@ function validateRawData(data) {
     if (t === null || typeof t !== "object") {
       throw new TypeError(`[thaizip] tambon[${i}]: expected object, got ${typeName(t)}`);
     }
-    if (typeof t.id !== "number") throw typeErr("tambon", t.id, "id", "number", t.id);
+    assertId("tambon", t.id, "id", t.id);
     if (seenTambonIds.has(t.id)) throw new TypeError(`[thaizip] duplicate tambon id: ${t.id}`);
     seenTambonIds.add(t.id);
     if (typeof t.name_th !== "string") throw typeErr("tambon", t.id, "name_th", "string", t.name_th);
@@ -109,7 +115,7 @@ function validateRawData(data) {
     if (zipType !== "string" && zipType !== "number") {
       throw typeErr("tambon", t.id, "zip_code", "string or number", t.zip_code);
     }
-    if (typeof t.amphure_id !== "number") throw typeErr("tambon", t.id, "amphure_id", "number", t.amphure_id);
+    assertId("tambon", t.id, "amphure_id", t.amphure_id);
     const zipLength = String(t.zip_code).length;
     if (zipLength > MAX_ZIP_LENGTH) throw new RangeError(`[thaizip] tambon ${t.id}: zip_code too long`);
     if (t.deleted_at) continue;

package/dist/index.cjs

@@ -42,6 +42,12 @@ var MAX_POSTING_BUDGET = 1e6;
 function typeErr(table, id, field, expected, value) {
   return new TypeError(`[thaizip] ${table} ${id}: expected ${expected} for ${field}, got ${typeof value}`);
 }
+function assertId(table, id, field, value) {
+  if (typeof value !== "number") throw typeErr(table, id, field, "number", value);
+  if (!Number.isSafeInteger(value)) {
+    throw new TypeError(`[thaizip] ${table} ${id}: expected safe integer for ${field}, got ${value}`);
+  }
+}
 function typeName(value) {
   return value === null ? "null" : typeof value;
 }
@@ -68,7 +74,7 @@ function validateRawData(data) {
     if (p === null || typeof p !== "object") {
       throw new TypeError(`[thaizip] province[${i}]: expected object, got ${typeName(p)}`);
     }
-    if (typeof p.id !== "number") throw typeErr("province", p.id, "id", "number", p.id);
+    assertId("province", p.id, "id", p.id);
     if (provinceById.has(p.id)) throw new TypeError(`[thaizip] duplicate province id: ${p.id}`);
     provinceById.set(p.id, p);
     if (typeof p.name_th !== "string") throw typeErr("province", p.id, "name_th", "string", p.name_th);
@@ -82,12 +88,12 @@ function validateRawData(data) {
     if (a === null || typeof a !== "object") {
       throw new TypeError(`[thaizip] amphure[${i}]: expected object, got ${typeName(a)}`);
     }
-    if (typeof a.id !== "number") throw typeErr("amphure", a.id, "id", "number", a.id);
+    assertId("amphure", a.id, "id", a.id);
     if (amphureById.has(a.id)) throw new TypeError(`[thaizip] duplicate amphure id: ${a.id}`);
     amphureById.set(a.id, a);
     if (typeof a.name_th !== "string") throw typeErr("amphure", a.id, "name_th", "string", a.name_th);
     if (typeof a.name_en !== "string") throw typeErr("amphure", a.id, "name_en", "string", a.name_en);
-    if (typeof a.province_id !== "number") throw typeErr("amphure", a.id, "province_id", "number", a.province_id);
+    assertId("amphure", a.id, "province_id", a.province_id);
     if (a.name_th.length > MAX_NAME_LENGTH) throw new RangeError(`[thaizip] amphure ${a.id}: name_th too long`);
     if (a.name_en.length > MAX_NAME_LENGTH) throw new RangeError(`[thaizip] amphure ${a.id}: name_en too long`);
   }
@@ -100,7 +106,7 @@ function validateRawData(data) {
     if (t === null || typeof t !== "object") {
       throw new TypeError(`[thaizip] tambon[${i}]: expected object, got ${typeName(t)}`);
     }
-    if (typeof t.id !== "number") throw typeErr("tambon", t.id, "id", "number", t.id);
+    assertId("tambon", t.id, "id", t.id);
     if (seenTambonIds.has(t.id)) throw new TypeError(`[thaizip] duplicate tambon id: ${t.id}`);
     seenTambonIds.add(t.id);
     if (typeof t.name_th !== "string") throw typeErr("tambon", t.id, "name_th", "string", t.name_th);
@@ -111,7 +117,7 @@ function validateRawData(data) {
     if (zipType !== "string" && zipType !== "number") {
       throw typeErr("tambon", t.id, "zip_code", "string or number", t.zip_code);
     }
-    if (typeof t.amphure_id !== "number") throw typeErr("tambon", t.id, "amphure_id", "number", t.amphure_id);
+    assertId("tambon", t.id, "amphure_id", t.amphure_id);
     const zipLength = String(t.zip_code).length;
     if (zipLength > MAX_ZIP_LENGTH) throw new RangeError(`[thaizip] tambon ${t.id}: zip_code too long`);
     if (t.deleted_at) continue;
@@ -421,7 +427,7 @@ function searchThaiAddress(index, query, options) {
   if (ZIP_CODE_RE.test(normalized)) {
     if (normalized.length < 2) return [];
     return lookupByZipCode(index, normalized, {
-      zipLimit: options?.zipLimit ?? Infinity
+      zipLimit: options?.zipLimit ?? (normalized.length >= 5 ? Infinity : limit)
     });
   }
   if (normalized.length < 3) return [];
@@ -583,5 +589,3 @@ exports.normalizeThaiAddressText = normalizeThaiAddressText;
 exports.resolveThaiAddress = resolveThaiAddress;
 exports.searchThaiAddress = searchThaiAddress;
 exports.validateRawData = validateRawData;
-//# sourceMappingURL=index.cjs.map
-//# sourceMappingURL=index.cjs.map

package/dist/index.d.cts

@@ -101,9 +101,11 @@ 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.
+     * Maximum results for all-digit (zip code) queries. When omitted, a complete
+     * 5-digit zip returns every matching tambon (at most a few dozen — capping
+     * those at the text-autocomplete `limit` would silently hide valid
+     * subdistricts), while a partial prefix (2–4 digits, which can match hundreds
+     * of records) is capped at `limit`. Pass `Infinity` to return every prefix match.
      */
     zipLimit?: number;
     /**
@@ -145,6 +147,10 @@ type BuildIndexOptions = {
      * 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).
+     *
+     * `false` also skips the row, name-length and posting-budget limits that bound
+     * memory and CPU use, so never disable it for data you do not control
+     * (user uploads, third-party APIs, a CMS editable by others).
      */
     validate?: boolean;
 };

package/dist/index.d.ts

@@ -101,9 +101,11 @@ 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.
+     * Maximum results for all-digit (zip code) queries. When omitted, a complete
+     * 5-digit zip returns every matching tambon (at most a few dozen — capping
+     * those at the text-autocomplete `limit` would silently hide valid
+     * subdistricts), while a partial prefix (2–4 digits, which can match hundreds
+     * of records) is capped at `limit`. Pass `Infinity` to return every prefix match.
      */
     zipLimit?: number;
     /**
@@ -145,6 +147,10 @@ type BuildIndexOptions = {
      * 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).
+     *
+     * `false` also skips the row, name-length and posting-budget limits that bound
+     * memory and CPU use, so never disable it for data you do not control
+     * (user uploads, third-party APIs, a CMS editable by others).
      */
     validate?: boolean;
 };

package/dist/index.js

@@ -40,6 +40,12 @@ var MAX_POSTING_BUDGET = 1e6;
 function typeErr(table, id, field, expected, value) {
   return new TypeError(`[thaizip] ${table} ${id}: expected ${expected} for ${field}, got ${typeof value}`);
 }
+function assertId(table, id, field, value) {
+  if (typeof value !== "number") throw typeErr(table, id, field, "number", value);
+  if (!Number.isSafeInteger(value)) {
+    throw new TypeError(`[thaizip] ${table} ${id}: expected safe integer for ${field}, got ${value}`);
+  }
+}
 function typeName(value) {
   return value === null ? "null" : typeof value;
 }
@@ -66,7 +72,7 @@ function validateRawData(data) {
     if (p === null || typeof p !== "object") {
       throw new TypeError(`[thaizip] province[${i}]: expected object, got ${typeName(p)}`);
     }
-    if (typeof p.id !== "number") throw typeErr("province", p.id, "id", "number", p.id);
+    assertId("province", p.id, "id", p.id);
     if (provinceById.has(p.id)) throw new TypeError(`[thaizip] duplicate province id: ${p.id}`);
     provinceById.set(p.id, p);
     if (typeof p.name_th !== "string") throw typeErr("province", p.id, "name_th", "string", p.name_th);
@@ -80,12 +86,12 @@ function validateRawData(data) {
     if (a === null || typeof a !== "object") {
       throw new TypeError(`[thaizip] amphure[${i}]: expected object, got ${typeName(a)}`);
     }
-    if (typeof a.id !== "number") throw typeErr("amphure", a.id, "id", "number", a.id);
+    assertId("amphure", a.id, "id", a.id);
     if (amphureById.has(a.id)) throw new TypeError(`[thaizip] duplicate amphure id: ${a.id}`);
     amphureById.set(a.id, a);
     if (typeof a.name_th !== "string") throw typeErr("amphure", a.id, "name_th", "string", a.name_th);
     if (typeof a.name_en !== "string") throw typeErr("amphure", a.id, "name_en", "string", a.name_en);
-    if (typeof a.province_id !== "number") throw typeErr("amphure", a.id, "province_id", "number", a.province_id);
+    assertId("amphure", a.id, "province_id", a.province_id);
     if (a.name_th.length > MAX_NAME_LENGTH) throw new RangeError(`[thaizip] amphure ${a.id}: name_th too long`);
     if (a.name_en.length > MAX_NAME_LENGTH) throw new RangeError(`[thaizip] amphure ${a.id}: name_en too long`);
   }
@@ -98,7 +104,7 @@ function validateRawData(data) {
     if (t === null || typeof t !== "object") {
       throw new TypeError(`[thaizip] tambon[${i}]: expected object, got ${typeName(t)}`);
     }
-    if (typeof t.id !== "number") throw typeErr("tambon", t.id, "id", "number", t.id);
+    assertId("tambon", t.id, "id", t.id);
     if (seenTambonIds.has(t.id)) throw new TypeError(`[thaizip] duplicate tambon id: ${t.id}`);
     seenTambonIds.add(t.id);
     if (typeof t.name_th !== "string") throw typeErr("tambon", t.id, "name_th", "string", t.name_th);
@@ -109,7 +115,7 @@ function validateRawData(data) {
     if (zipType !== "string" && zipType !== "number") {
       throw typeErr("tambon", t.id, "zip_code", "string or number", t.zip_code);
     }
-    if (typeof t.amphure_id !== "number") throw typeErr("tambon", t.id, "amphure_id", "number", t.amphure_id);
+    assertId("tambon", t.id, "amphure_id", t.amphure_id);
     const zipLength = String(t.zip_code).length;
     if (zipLength > MAX_ZIP_LENGTH) throw new RangeError(`[thaizip] tambon ${t.id}: zip_code too long`);
     if (t.deleted_at) continue;
@@ -419,7 +425,7 @@ function searchThaiAddress(index, query, options) {
   if (ZIP_CODE_RE.test(normalized)) {
     if (normalized.length < 2) return [];
     return lookupByZipCode(index, normalized, {
-      zipLimit: options?.zipLimit ?? Infinity
+      zipLimit: options?.zipLimit ?? (normalized.length >= 5 ? Infinity : limit)
     });
   }
   if (normalized.length < 3) return [];
@@ -571,5 +577,3 @@ function resolveThaiAddress(record) {
 }
 
 export { applyRomanizationAliases, buildThaiAddressIndex, formatThaiAddressSuggestion, listAmphures, listProvinces, listTambons, lookupByZipCode, normalizeThaiAddressText, resolveThaiAddress, searchThaiAddress, validateRawData };
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/react.cjs

@@ -225,7 +225,7 @@ function searchThaiAddress(index, query, options) {
   if (ZIP_CODE_RE.test(normalized)) {
     if (normalized.length < 2) return [];
     return lookupByZipCode(index, normalized, {
-      zipLimit: options?.zipLimit ?? Infinity
+      zipLimit: options?.zipLimit ?? (normalized.length >= 5 ? Infinity : limit)
     });
   }
   if (normalized.length < 3) return [];
@@ -402,5 +402,3 @@ function useThaiAddressAutocomplete(options) {
 }
 
 exports.useThaiAddressAutocomplete = useThaiAddressAutocomplete;
-//# sourceMappingURL=react.cjs.map
-//# sourceMappingURL=react.cjs.map

package/dist/react.d.cts

@@ -79,6 +79,7 @@ type UseThaiAddressAutocompleteOptions = {
     limit?: number;
     debounce?: number;
     threshold?: number;
+    /** Maximum results for zip code queries; see `SearchOptions.zipLimit` for the default. */
     zipLimit?: number;
     /** Seed value for `query` on first render. Defaults to `''`. */
     initialQuery?: string;

package/dist/react.d.ts

@@ -79,6 +79,7 @@ type UseThaiAddressAutocompleteOptions = {
     limit?: number;
     debounce?: number;
     threshold?: number;
+    /** Maximum results for zip code queries; see `SearchOptions.zipLimit` for the default. */
     zipLimit?: number;
     /** Seed value for `query` on first render. Defaults to `''`. */
     initialQuery?: string;

package/dist/react.js

@@ -223,7 +223,7 @@ function searchThaiAddress(index, query, options) {
   if (ZIP_CODE_RE.test(normalized)) {
     if (normalized.length < 2) return [];
     return lookupByZipCode(index, normalized, {
-      zipLimit: options?.zipLimit ?? Infinity
+      zipLimit: options?.zipLimit ?? (normalized.length >= 5 ? Infinity : limit)
     });
   }
   if (normalized.length < 3) return [];
@@ -400,5 +400,3 @@ function useThaiAddressAutocomplete(options) {
 }
 
 export { useThaiAddressAutocomplete };
-//# sourceMappingURL=react.js.map
-//# sourceMappingURL=react.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thaizip",
-  "version": "0.7.6",
+  "version": "0.7.7",
   "description": "Fast, fuzzy Thai address autocomplete library (headless + React)",
   "keywords": [
     "thai",