thaizip 0.7.2 → 0.7.4

package/dist/index.cjs

@@ -4,8 +4,13 @@
 var TONE_MARKS = /[่-๋็์]/g;
 var ADDRESS_PREFIXES = /^(จังหวัด|อำเภอ|ตำบล|แขวง|เขต|จ\.|อ\.|ต\.|ข\.)/;
 function normalizeThaiAddressText(input) {
-  if (!input) return "";
-  let text = input.trim();
+  if (typeof input !== "string") {
+    throw new TypeError(
+      `[thaizip] normalizeThaiAddressText expected string, got ${input === null ? "null" : typeof input}`
+    );
+  }
+  if (input.length === 0) return "";
+  let text = input.normalize("NFC").trim();
   text = text.replace(ADDRESS_PREFIXES, "").trim();
   text = text.replace(TONE_MARKS, "");
   text = text.toLowerCase();
@@ -33,24 +38,57 @@ function extractTrigramsNormalized(text) {
 function typeErr(table, id, field, expected, value) {
   return new TypeError(`[thaizip] ${table} ${id}: expected ${expected} for ${field}, got ${typeof value}`);
 }
+function typeName(value) {
+  return value === null ? "null" : typeof value;
+}
 function validateRawData(data) {
+  if (data === null || typeof data !== "object") {
+    throw new TypeError(`[thaizip] validateRawData expected a RawData object, got ${typeName(data)}`);
+  }
   const { provinces, amphures, tambons } = data;
+  if (!Array.isArray(provinces)) {
+    throw new TypeError(`[thaizip] RawData.provinces must be an array, got ${typeName(provinces)}`);
+  }
+  if (!Array.isArray(amphures)) {
+    throw new TypeError(`[thaizip] RawData.amphures must be an array, got ${typeName(amphures)}`);
+  }
+  if (!Array.isArray(tambons)) {
+    throw new TypeError(`[thaizip] RawData.tambons must be an array, got ${typeName(tambons)}`);
+  }
+  const seenProvinceIds = /* @__PURE__ */ new Set();
   for (let i = 0; i < provinces.length; i++) {
     const p = provinces[i];
+    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);
+    if (seenProvinceIds.has(p.id)) throw new TypeError(`[thaizip] duplicate province id: ${p.id}`);
+    seenProvinceIds.add(p.id);
     if (typeof p.name_th !== "string") throw typeErr("province", p.id, "name_th", "string", p.name_th);
     if (typeof p.name_en !== "string") throw typeErr("province", p.id, "name_en", "string", p.name_en);
   }
+  const seenAmphureIds = /* @__PURE__ */ new Set();
   for (let i = 0; i < amphures.length; i++) {
     const a = amphures[i];
+    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);
+    if (seenAmphureIds.has(a.id)) throw new TypeError(`[thaizip] duplicate amphure id: ${a.id}`);
+    seenAmphureIds.add(a.id);
     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);
   }
+  const seenTambonIds = /* @__PURE__ */ new Set();
   for (let i = 0; i < tambons.length; i++) {
     const t = tambons[i];
+    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);
+    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);
     if (typeof t.name_en !== "string") throw typeErr("tambon", t.id, "name_en", "string", t.name_en);
     const zipType = typeof t.zip_code;
@@ -147,7 +185,9 @@ function buildThaiAddressIndex(data, options) {
     addTrigrams(map, provTrigrams.get(province.id), idx);
     addTrigrams(map, ampTrigrams.get(amphure.id), idx);
   }
-  return { map, records, zipIndex, normTambon, normTambonEn, byProvince, byAmphure };
+  const sortedZipKeys = [...zipIndex.keys()].sort();
+  const sortedZipPostings = sortedZipKeys.map((z) => zipIndex.get(z));
+  return { map, records, zipIndex, sortedZipKeys, sortedZipPostings, normTambon, normTambonEn, byProvince, byAmphure };
 }
 
 // src/core/romanize.ts
@@ -268,27 +308,44 @@ function compareZip(a, b) {
   if (a > b) return 1;
   return 0;
 }
-function sortZipMatches(matches, exactZip) {
-  matches.sort((a, b) => {
-    if (a.zipCode === exactZip && b.zipCode !== exactZip) return -1;
-    if (b.zipCode === exactZip && a.zipCode !== exactZip) return 1;
-    return compareZip(a.zipCode, b.zipCode);
-  });
-  return matches;
+function normalizeLimit(value) {
+  if (Number.isNaN(value) || value === -Infinity) return 0;
+  if (value === Infinity) return value;
+  return Math.max(0, Math.floor(value));
 }
 function lookupByZipCode(index, zip, options) {
-  if (!index || !zip) return [];
+  if (!index || !index.zipIndex || !index.records || typeof zip !== "string") return [];
+  if (zip.length > 1e3) return [];
+  const zipLimit = normalizeLimit(options?.zipLimit ?? Infinity);
+  if (zipLimit === 0) return [];
   const normalized = zip.trim();
   if (!ZIP_CODE_RE.test(normalized) || normalized.length < 2) return [];
-  const zipLimit = options?.zipLimit ?? Infinity;
   const matches = [];
-  for (const [z, indices] of index.zipIndex) {
-    if (z.startsWith(normalized)) {
-      for (const idx of indices) matches.push(index.records[idx]);
+  const keys = index.sortedZipKeys;
+  const postings = index.sortedZipPostings;
+  if (keys !== void 0 && postings !== void 0) {
+    let lo = 0;
+    let hi = keys.length;
+    while (lo < hi) {
+      const mid = lo + hi >> 1;
+      if (keys[mid] < normalized) lo = mid + 1;
+      else hi = mid;
+    }
+    for (let i = lo; i < keys.length && keys[i].startsWith(normalized) && matches.length < zipLimit; i++) {
+      const indices = postings[i];
+      for (let j = 0; j < indices.length && matches.length < zipLimit; j++) matches.push(index.records[indices[j]]);
+    }
+  } else {
+    const matchingKeys = [...index.zipIndex.keys()].filter((z) => z.startsWith(normalized)).sort(compareZip);
+    for (const z of matchingKeys) {
+      if (matches.length >= zipLimit) break;
+      for (const idx of index.zipIndex.get(z)) {
+        if (matches.length >= zipLimit) break;
+        matches.push(index.records[idx]);
+      }
     }
   }
-  sortZipMatches(matches, normalized);
-  return matches.slice(0, zipLimit);
+  return matches.slice(0, zipLimit).map((record) => ({ ...record }));
 }
 function rankAgainstName(name, query) {
   if (name === void 0 || name.length === 0) return 0;
@@ -303,10 +360,20 @@ function computeMatchRank(index, idx, query) {
   const en = rankAgainstName(index.normTambonEn?.[idx], query);
   return en > th ? en : th;
 }
+var scratchByIndex = /* @__PURE__ */ new WeakMap();
+function getScratch(index) {
+  const n = index.records.length;
+  let s = scratchByIndex.get(index);
+  if (s === void 0 || s.counts.length < n) {
+    s = { counts: new Uint32Array(n), touched: new Int32Array(n) };
+    scratchByIndex.set(index, s);
+  }
+  return s;
+}
 function searchThaiAddress(index, query, options) {
-  const limit = options?.limit ?? 10;
+  const limit = normalizeLimit(options?.limit ?? 10);
   const threshold = options?.threshold ?? 0.4;
-  if (!index || !query) return [];
+  if (!index || !index.map || !index.records || typeof query !== "string") return [];
   if (query.length > 1e3) return [];
   const normalized = normalizeThaiAddressText(query);
   if (normalized.length === 0) return [];
@@ -318,19 +385,25 @@ function searchThaiAddress(index, query, options) {
     });
   }
   if (normalized.length < 3) return [];
+  if (limit === 0) return [];
   const searchText = options?.romanizationAliases !== false && HAS_LATIN_RE.test(normalized) ? applyRomanizationAliases(normalized) : normalized;
   const queryTrigrams = extractTrigramsNormalized(searchText);
-  const hits = /* @__PURE__ */ new Map();
+  const { counts, touched } = getScratch(index);
+  let touchedLen = 0;
   for (const trigram of queryTrigrams) {
     const candidates = index.map.get(trigram);
     if (!candidates) continue;
     for (const idx of candidates) {
-      hits.set(idx, (hits.get(idx) ?? 0) + 1);
+      if (counts[idx] === 0) touched[touchedLen++] = idx;
+      counts[idx]++;
     }
   }
   const scored = [];
-  for (const [idx, count] of hits) {
-    const score = count / queryTrigrams.size;
+  const totalTrigrams = queryTrigrams.size;
+  for (let i = 0; i < touchedLen; i++) {
+    const idx = touched[i];
+    const score = counts[idx] / totalTrigrams;
+    counts[idx] = 0;
     if (score >= threshold) {
       scored.push({ idx, score, matchRank: computeMatchRank(index, idx, searchText) });
     }
@@ -339,7 +412,11 @@ function searchThaiAddress(index, query, options) {
     if (b.score !== a.score) return b.score - a.score;
     return b.matchRank - a.matchRank;
   });
-  const windowSize = Math.max(limit * 4, 50);
+  let windowSize = Math.min(limit, scored.length);
+  const boundary = scored[windowSize - 1];
+  while (windowSize < scored.length && scored[windowSize].score === boundary.score && scored[windowSize].matchRank === boundary.matchRank) {
+    windowSize++;
+  }
   const window = scored.slice(0, windowSize);
   window.sort((a, b) => {
     if (b.score !== a.score) return b.score - a.score;
@@ -348,7 +425,7 @@ function searchThaiAddress(index, query, options) {
     const rb = index.records[b.idx];
     return TH_COLLATOR.compare(ra.provinceNameTh, rb.provinceNameTh) || TH_COLLATOR.compare(ra.amphureNameTh, rb.amphureNameTh) || TH_COLLATOR.compare(ra.tambonNameTh, rb.tambonNameTh);
   });
-  return window.slice(0, limit).map(({ idx }) => index.records[idx]);
+  return window.slice(0, limit).map(({ idx }) => ({ ...index.records[idx] }));
 }
 
 // src/core/enumerate.ts
@@ -357,6 +434,7 @@ function byNameTh(a, b) {
   return thCollator.compare(a.nameTh, b.nameTh);
 }
 function listProvinces(index) {
+  if (!index || !index.records) return [];
   const seen = /* @__PURE__ */ new Map();
   if (index.byProvince) {
     for (const [provinceId, recordIndices] of index.byProvince) {
@@ -374,6 +452,7 @@ function listProvinces(index) {
   return Array.from(seen.values()).sort(byNameTh);
 }
 function listAmphures(index, provinceId) {
+  if (!index || !index.records) return [];
   const seen = /* @__PURE__ */ new Map();
   const addFrom = (r) => {
     if (!seen.has(r.amphureId)) {
@@ -397,6 +476,7 @@ function listAmphures(index, provinceId) {
   return Array.from(seen.values()).sort(byNameTh);
 }
 function listTambons(index, amphureId) {
+  if (!index || !index.records) return [];
   const toSummary = (r) => ({
     id: r.tambonId,
     nameTh: r.tambonNameTh,

package/dist/index.d.cts

@@ -14,6 +14,15 @@ type TrigramIndex = {
     map: Map<string, Set<number>>;
     records: ThaiAddressRecord[];
     zipIndex: Map<string, number[]>;
+    /**
+     * Zip codes of `zipIndex` in ascending lexical order, with postings
+     * parallel in `sortedZipPostings`. Used by `lookupByZipCode` for
+     * O(log n + matches) prefix lookup instead of scanning every zip code.
+     * Optional: older-shaped or hand-built indexes without these fields fall
+     * back to the O(n_zips) scan.
+     */
+    sortedZipKeys?: string[];
+    sortedZipPostings?: number[][];
     /**
      * Normalized Thai tambon names, parallel to `records` (same index).
      * Used by the search ranker for exact/prefix match detection without
@@ -156,6 +165,12 @@ type RawData = {
  * offending record's `id`, the field, and the actual `typeof` on the first bad
  * field found. Does not filter soft-deleted rows first — validates every row as
  * provided.
+ *
+ * IDs must be unique within each table (duplicates throw, they are not silently
+ * discarded — two suggestions sharing an id would resolve to the wrong record).
+ * Referential integrity (amphure→province, tambon→amphure) is intentionally NOT
+ * enforced: dangling references — including soft-deleted parents — are handled at
+ * build time, where the tambon is skipped and reported via `options.onSkip`.
  */
 declare function validateRawData(data: RawData): void;
 declare function buildThaiAddressIndex(data: RawData, options?: BuildIndexOptions): TrigramIndex;
@@ -164,9 +179,23 @@ declare function buildThaiAddressIndex(data: RawData, options?: BuildIndexOption
  * Look up records by zip code (exact or prefix match). Exact matches are
  * returned before prefix matches; ties are ordered by ascending zip code.
  *
+ * Uses the build-time `sortedZipKeys`/`sortedZipPostings` arrays with a
+ * binary search for the first key ≥ the query, then walks the contiguous
+ * prefix range — O(log n_zips + matches). Ascending key order places an
+ * exact match before any longer prefix match automatically, so no explicit
+ * exact-first sort is needed. Indexes without the sorted arrays (older
+ * shape, hand-built) scan and sort matching keys before collecting records.
+ * Both paths stop collecting when `zipLimit` is reached.
+ *
+ * Returned records are shallow copies: mutating them cannot corrupt the
+ * shared index (see `searchThaiAddress`).
+ *
  * Unlike `searchThaiAddress`, results are NOT capped by `options.limit` —
  * only by `options.zipLimit` (defaults to `Infinity`), since a zip code can
  * legitimately map to dozens of tambons (e.g. `45000` → 33 records).
+ *
+ * Malformed runtime input (non-string `zip`, missing index shape) and raw
+ * strings longer than 1000 characters return `[]`.
  */
 declare function lookupByZipCode(index: TrigramIndex, zip: string, options?: SearchOptions): ThaiAddressRecord[];
 declare function searchThaiAddress(index: TrigramIndex, query: string, options?: SearchOptions): ThaiAddressRecord[];
@@ -174,13 +203,15 @@ declare function searchThaiAddress(index: TrigramIndex, query: string, options?:
 /**
  * All provinces present in the index, deduplicated and sorted by Thai name.
  * Backed by `index.byProvince` (O(unique provinces)); falls back to scanning
- * `index.records` if an older-shaped index lacks that map.
+ * `index.records` if an older-shaped index lacks that map. A missing/junk
+ * index returns `[]` rather than throwing.
  */
 declare function listProvinces(index: TrigramIndex): ProvinceSummary[];
 /**
  * Amphures (districts) within a given province, deduplicated and sorted by
  * Thai name. Unknown `provinceId` returns `[]`. Backed by `index.byProvince`;
  * falls back to scanning `index.records` if an older-shaped index lacks it.
+ * A missing/junk index returns `[]` rather than throwing.
  */
 declare function listAmphures(index: TrigramIndex, provinceId: number): AmphureSummary[];
 /**
@@ -188,7 +219,8 @@ declare function listAmphures(index: TrigramIndex, provinceId: number): AmphureS
  * Unknown `amphureId` returns `[]`. Backed by `index.byAmphure`; falls back
  * to scanning `index.records` if an older-shaped index lacks it. Each
  * `byAmphure` entry already maps to exactly one tambon record, so no
- * deduplication is needed here.
+ * deduplication is needed here. A missing/junk index returns `[]` rather
+ * than throwing.
  */
 declare function listTambons(index: TrigramIndex, amphureId: number): TambonSummary[];
 

package/dist/index.d.ts

@@ -14,6 +14,15 @@ type TrigramIndex = {
     map: Map<string, Set<number>>;
     records: ThaiAddressRecord[];
     zipIndex: Map<string, number[]>;
+    /**
+     * Zip codes of `zipIndex` in ascending lexical order, with postings
+     * parallel in `sortedZipPostings`. Used by `lookupByZipCode` for
+     * O(log n + matches) prefix lookup instead of scanning every zip code.
+     * Optional: older-shaped or hand-built indexes without these fields fall
+     * back to the O(n_zips) scan.
+     */
+    sortedZipKeys?: string[];
+    sortedZipPostings?: number[][];
     /**
      * Normalized Thai tambon names, parallel to `records` (same index).
      * Used by the search ranker for exact/prefix match detection without
@@ -156,6 +165,12 @@ type RawData = {
  * offending record's `id`, the field, and the actual `typeof` on the first bad
  * field found. Does not filter soft-deleted rows first — validates every row as
  * provided.
+ *
+ * IDs must be unique within each table (duplicates throw, they are not silently
+ * discarded — two suggestions sharing an id would resolve to the wrong record).
+ * Referential integrity (amphure→province, tambon→amphure) is intentionally NOT
+ * enforced: dangling references — including soft-deleted parents — are handled at
+ * build time, where the tambon is skipped and reported via `options.onSkip`.
  */
 declare function validateRawData(data: RawData): void;
 declare function buildThaiAddressIndex(data: RawData, options?: BuildIndexOptions): TrigramIndex;
@@ -164,9 +179,23 @@ declare function buildThaiAddressIndex(data: RawData, options?: BuildIndexOption
  * Look up records by zip code (exact or prefix match). Exact matches are
  * returned before prefix matches; ties are ordered by ascending zip code.
  *
+ * Uses the build-time `sortedZipKeys`/`sortedZipPostings` arrays with a
+ * binary search for the first key ≥ the query, then walks the contiguous
+ * prefix range — O(log n_zips + matches). Ascending key order places an
+ * exact match before any longer prefix match automatically, so no explicit
+ * exact-first sort is needed. Indexes without the sorted arrays (older
+ * shape, hand-built) scan and sort matching keys before collecting records.
+ * Both paths stop collecting when `zipLimit` is reached.
+ *
+ * Returned records are shallow copies: mutating them cannot corrupt the
+ * shared index (see `searchThaiAddress`).
+ *
  * Unlike `searchThaiAddress`, results are NOT capped by `options.limit` —
  * only by `options.zipLimit` (defaults to `Infinity`), since a zip code can
  * legitimately map to dozens of tambons (e.g. `45000` → 33 records).
+ *
+ * Malformed runtime input (non-string `zip`, missing index shape) and raw
+ * strings longer than 1000 characters return `[]`.
  */
 declare function lookupByZipCode(index: TrigramIndex, zip: string, options?: SearchOptions): ThaiAddressRecord[];
 declare function searchThaiAddress(index: TrigramIndex, query: string, options?: SearchOptions): ThaiAddressRecord[];
@@ -174,13 +203,15 @@ declare function searchThaiAddress(index: TrigramIndex, query: string, options?:
 /**
  * All provinces present in the index, deduplicated and sorted by Thai name.
  * Backed by `index.byProvince` (O(unique provinces)); falls back to scanning
- * `index.records` if an older-shaped index lacks that map.
+ * `index.records` if an older-shaped index lacks that map. A missing/junk
+ * index returns `[]` rather than throwing.
  */
 declare function listProvinces(index: TrigramIndex): ProvinceSummary[];
 /**
  * Amphures (districts) within a given province, deduplicated and sorted by
  * Thai name. Unknown `provinceId` returns `[]`. Backed by `index.byProvince`;
  * falls back to scanning `index.records` if an older-shaped index lacks it.
+ * A missing/junk index returns `[]` rather than throwing.
  */
 declare function listAmphures(index: TrigramIndex, provinceId: number): AmphureSummary[];
 /**
@@ -188,7 +219,8 @@ declare function listAmphures(index: TrigramIndex, provinceId: number): AmphureS
  * Unknown `amphureId` returns `[]`. Backed by `index.byAmphure`; falls back
  * to scanning `index.records` if an older-shaped index lacks it. Each
  * `byAmphure` entry already maps to exactly one tambon record, so no
- * deduplication is needed here.
+ * deduplication is needed here. A missing/junk index returns `[]` rather
+ * than throwing.
  */
 declare function listTambons(index: TrigramIndex, amphureId: number): TambonSummary[];
 

package/dist/index.js

@@ -2,8 +2,13 @@
 var TONE_MARKS = /[่-๋็์]/g;
 var ADDRESS_PREFIXES = /^(จังหวัด|อำเภอ|ตำบล|แขวง|เขต|จ\.|อ\.|ต\.|ข\.)/;
 function normalizeThaiAddressText(input) {
-  if (!input) return "";
-  let text = input.trim();
+  if (typeof input !== "string") {
+    throw new TypeError(
+      `[thaizip] normalizeThaiAddressText expected string, got ${input === null ? "null" : typeof input}`
+    );
+  }
+  if (input.length === 0) return "";
+  let text = input.normalize("NFC").trim();
   text = text.replace(ADDRESS_PREFIXES, "").trim();
   text = text.replace(TONE_MARKS, "");
   text = text.toLowerCase();
@@ -31,24 +36,57 @@ function extractTrigramsNormalized(text) {
 function typeErr(table, id, field, expected, value) {
   return new TypeError(`[thaizip] ${table} ${id}: expected ${expected} for ${field}, got ${typeof value}`);
 }
+function typeName(value) {
+  return value === null ? "null" : typeof value;
+}
 function validateRawData(data) {
+  if (data === null || typeof data !== "object") {
+    throw new TypeError(`[thaizip] validateRawData expected a RawData object, got ${typeName(data)}`);
+  }
   const { provinces, amphures, tambons } = data;
+  if (!Array.isArray(provinces)) {
+    throw new TypeError(`[thaizip] RawData.provinces must be an array, got ${typeName(provinces)}`);
+  }
+  if (!Array.isArray(amphures)) {
+    throw new TypeError(`[thaizip] RawData.amphures must be an array, got ${typeName(amphures)}`);
+  }
+  if (!Array.isArray(tambons)) {
+    throw new TypeError(`[thaizip] RawData.tambons must be an array, got ${typeName(tambons)}`);
+  }
+  const seenProvinceIds = /* @__PURE__ */ new Set();
   for (let i = 0; i < provinces.length; i++) {
     const p = provinces[i];
+    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);
+    if (seenProvinceIds.has(p.id)) throw new TypeError(`[thaizip] duplicate province id: ${p.id}`);
+    seenProvinceIds.add(p.id);
     if (typeof p.name_th !== "string") throw typeErr("province", p.id, "name_th", "string", p.name_th);
     if (typeof p.name_en !== "string") throw typeErr("province", p.id, "name_en", "string", p.name_en);
   }
+  const seenAmphureIds = /* @__PURE__ */ new Set();
   for (let i = 0; i < amphures.length; i++) {
     const a = amphures[i];
+    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);
+    if (seenAmphureIds.has(a.id)) throw new TypeError(`[thaizip] duplicate amphure id: ${a.id}`);
+    seenAmphureIds.add(a.id);
     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);
   }
+  const seenTambonIds = /* @__PURE__ */ new Set();
   for (let i = 0; i < tambons.length; i++) {
     const t = tambons[i];
+    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);
+    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);
     if (typeof t.name_en !== "string") throw typeErr("tambon", t.id, "name_en", "string", t.name_en);
     const zipType = typeof t.zip_code;
@@ -145,7 +183,9 @@ function buildThaiAddressIndex(data, options) {
     addTrigrams(map, provTrigrams.get(province.id), idx);
     addTrigrams(map, ampTrigrams.get(amphure.id), idx);
   }
-  return { map, records, zipIndex, normTambon, normTambonEn, byProvince, byAmphure };
+  const sortedZipKeys = [...zipIndex.keys()].sort();
+  const sortedZipPostings = sortedZipKeys.map((z) => zipIndex.get(z));
+  return { map, records, zipIndex, sortedZipKeys, sortedZipPostings, normTambon, normTambonEn, byProvince, byAmphure };
 }
 
 // src/core/romanize.ts
@@ -266,27 +306,44 @@ function compareZip(a, b) {
   if (a > b) return 1;
   return 0;
 }
-function sortZipMatches(matches, exactZip) {
-  matches.sort((a, b) => {
-    if (a.zipCode === exactZip && b.zipCode !== exactZip) return -1;
-    if (b.zipCode === exactZip && a.zipCode !== exactZip) return 1;
-    return compareZip(a.zipCode, b.zipCode);
-  });
-  return matches;
+function normalizeLimit(value) {
+  if (Number.isNaN(value) || value === -Infinity) return 0;
+  if (value === Infinity) return value;
+  return Math.max(0, Math.floor(value));
 }
 function lookupByZipCode(index, zip, options) {
-  if (!index || !zip) return [];
+  if (!index || !index.zipIndex || !index.records || typeof zip !== "string") return [];
+  if (zip.length > 1e3) return [];
+  const zipLimit = normalizeLimit(options?.zipLimit ?? Infinity);
+  if (zipLimit === 0) return [];
   const normalized = zip.trim();
   if (!ZIP_CODE_RE.test(normalized) || normalized.length < 2) return [];
-  const zipLimit = options?.zipLimit ?? Infinity;
   const matches = [];
-  for (const [z, indices] of index.zipIndex) {
-    if (z.startsWith(normalized)) {
-      for (const idx of indices) matches.push(index.records[idx]);
+  const keys = index.sortedZipKeys;
+  const postings = index.sortedZipPostings;
+  if (keys !== void 0 && postings !== void 0) {
+    let lo = 0;
+    let hi = keys.length;
+    while (lo < hi) {
+      const mid = lo + hi >> 1;
+      if (keys[mid] < normalized) lo = mid + 1;
+      else hi = mid;
+    }
+    for (let i = lo; i < keys.length && keys[i].startsWith(normalized) && matches.length < zipLimit; i++) {
+      const indices = postings[i];
+      for (let j = 0; j < indices.length && matches.length < zipLimit; j++) matches.push(index.records[indices[j]]);
+    }
+  } else {
+    const matchingKeys = [...index.zipIndex.keys()].filter((z) => z.startsWith(normalized)).sort(compareZip);
+    for (const z of matchingKeys) {
+      if (matches.length >= zipLimit) break;
+      for (const idx of index.zipIndex.get(z)) {
+        if (matches.length >= zipLimit) break;
+        matches.push(index.records[idx]);
+      }
     }
   }
-  sortZipMatches(matches, normalized);
-  return matches.slice(0, zipLimit);
+  return matches.slice(0, zipLimit).map((record) => ({ ...record }));
 }
 function rankAgainstName(name, query) {
   if (name === void 0 || name.length === 0) return 0;
@@ -301,10 +358,20 @@ function computeMatchRank(index, idx, query) {
   const en = rankAgainstName(index.normTambonEn?.[idx], query);
   return en > th ? en : th;
 }
+var scratchByIndex = /* @__PURE__ */ new WeakMap();
+function getScratch(index) {
+  const n = index.records.length;
+  let s = scratchByIndex.get(index);
+  if (s === void 0 || s.counts.length < n) {
+    s = { counts: new Uint32Array(n), touched: new Int32Array(n) };
+    scratchByIndex.set(index, s);
+  }
+  return s;
+}
 function searchThaiAddress(index, query, options) {
-  const limit = options?.limit ?? 10;
+  const limit = normalizeLimit(options?.limit ?? 10);
   const threshold = options?.threshold ?? 0.4;
-  if (!index || !query) return [];
+  if (!index || !index.map || !index.records || typeof query !== "string") return [];
   if (query.length > 1e3) return [];
   const normalized = normalizeThaiAddressText(query);
   if (normalized.length === 0) return [];
@@ -316,19 +383,25 @@ function searchThaiAddress(index, query, options) {
     });
   }
   if (normalized.length < 3) return [];
+  if (limit === 0) return [];
   const searchText = options?.romanizationAliases !== false && HAS_LATIN_RE.test(normalized) ? applyRomanizationAliases(normalized) : normalized;
   const queryTrigrams = extractTrigramsNormalized(searchText);
-  const hits = /* @__PURE__ */ new Map();
+  const { counts, touched } = getScratch(index);
+  let touchedLen = 0;
   for (const trigram of queryTrigrams) {
     const candidates = index.map.get(trigram);
     if (!candidates) continue;
     for (const idx of candidates) {
-      hits.set(idx, (hits.get(idx) ?? 0) + 1);
+      if (counts[idx] === 0) touched[touchedLen++] = idx;
+      counts[idx]++;
     }
   }
   const scored = [];
-  for (const [idx, count] of hits) {
-    const score = count / queryTrigrams.size;
+  const totalTrigrams = queryTrigrams.size;
+  for (let i = 0; i < touchedLen; i++) {
+    const idx = touched[i];
+    const score = counts[idx] / totalTrigrams;
+    counts[idx] = 0;
     if (score >= threshold) {
       scored.push({ idx, score, matchRank: computeMatchRank(index, idx, searchText) });
     }
@@ -337,7 +410,11 @@ function searchThaiAddress(index, query, options) {
     if (b.score !== a.score) return b.score - a.score;
     return b.matchRank - a.matchRank;
   });
-  const windowSize = Math.max(limit * 4, 50);
+  let windowSize = Math.min(limit, scored.length);
+  const boundary = scored[windowSize - 1];
+  while (windowSize < scored.length && scored[windowSize].score === boundary.score && scored[windowSize].matchRank === boundary.matchRank) {
+    windowSize++;
+  }
   const window = scored.slice(0, windowSize);
   window.sort((a, b) => {
     if (b.score !== a.score) return b.score - a.score;
@@ -346,7 +423,7 @@ function searchThaiAddress(index, query, options) {
     const rb = index.records[b.idx];
     return TH_COLLATOR.compare(ra.provinceNameTh, rb.provinceNameTh) || TH_COLLATOR.compare(ra.amphureNameTh, rb.amphureNameTh) || TH_COLLATOR.compare(ra.tambonNameTh, rb.tambonNameTh);
   });
-  return window.slice(0, limit).map(({ idx }) => index.records[idx]);
+  return window.slice(0, limit).map(({ idx }) => ({ ...index.records[idx] }));
 }
 
 // src/core/enumerate.ts
@@ -355,6 +432,7 @@ function byNameTh(a, b) {
   return thCollator.compare(a.nameTh, b.nameTh);
 }
 function listProvinces(index) {
+  if (!index || !index.records) return [];
   const seen = /* @__PURE__ */ new Map();
   if (index.byProvince) {
     for (const [provinceId, recordIndices] of index.byProvince) {
@@ -372,6 +450,7 @@ function listProvinces(index) {
   return Array.from(seen.values()).sort(byNameTh);
 }
 function listAmphures(index, provinceId) {
+  if (!index || !index.records) return [];
   const seen = /* @__PURE__ */ new Map();
   const addFrom = (r) => {
     if (!seen.has(r.amphureId)) {
@@ -395,6 +474,7 @@ function listAmphures(index, provinceId) {
   return Array.from(seen.values()).sort(byNameTh);
 }
 function listTambons(index, amphureId) {
+  if (!index || !index.records) return [];
   const toSummary = (r) => ({
     id: r.tambonId,
     nameTh: r.tambonNameTh,