@code-plate/iran-cities 1.0.0 → 1.0.2

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { F as FlatCity, C as City, P as Province, S as SearchOptions } from './types--eoWJy5A.mjs';
-export { L as Locale } from './types--eoWJy5A.mjs';
+import { F as FlatCity, C as City, a as CityKey, P as Province, S as SearchOptions } from './types-DwFZSr9I.mjs';
+export { L as Locale } from './types-DwFZSr9I.mjs';
 
 /** لیست کامل استان‌ها به همراه شهرهای هرکدام */
 declare function getProvinces(): Province[];
@@ -8,19 +8,32 @@ declare function getProvincesList(): {
     en: string;
     fa: string;
 }[];
-/** پیدا کردن یک استان با شناسه انگلیسی یا نام فارسی (دقیق، نرمال‌شده) */
+/** پیدا کردن یک استان با شناسه انگلیسی یا نام فارسی (دقیق، نرمال‌شده) - O(1) */
 declare function getProvince(query: string): Province | undefined;
 /** لیست شهرهای یک استان بر اساس شناسه انگلیسی یا نام فارسی استان */
 declare function getCities(provinceQuery: string): City[];
 /** لیست تمام شهرهای کشور به صورت مسطح، همراه با اطلاعات استان مربوطه */
 declare function getAllCities(): FlatCity[];
-/** پیدا کردن یک شهر با شناسه انگلیسی یا نام فارسی (اختیاری: محدود به یک استان خاص) */
+/**
+ * پیدا کردن یک شهر با شناسه‌ی یکتای سراسری آن (City.slug، به‌فرم `provinceEn/cityEn`) - O(1)
+ * برای پکیج‌های وابسته که داده‌ی اضافه (کد تلفن، پلاک، پیش‌شماره کد ملی و ...) را بر اساس
+ * این کلید نگه می‌دارند، مسیر پیشنهادی همین تابع است چون بدون ابهامِ هم‌نامی کار می‌کند.
+ */
+declare function getCityBySlug(slug: CityKey): FlatCity | undefined;
+/** پیدا کردن یک شهر با شناسه انگلیسی یا نام فارسی (اختیاری: محدود به یک استان خاص) - O(1) / O(اندازه استان) */
 declare function getCity(cityQuery: string, provinceQuery?: string): FlatCity | undefined;
-/** استانی که یک شهر مشخص در آن قرار دارد را برمی‌گرداند */
+/** استانی که یک شهر مشخص در آن قرار دارد را برمی‌گرداند - O(1) */
 declare function getProvinceOfCity(cityQuery: string): Province | undefined;
-/** جستجوی fuzzy (شامل‌شونده) در بین استان‌ها بر اساس بخشی از نام */
+/**
+ * جستجوی رتبه‌بندی‌شده در بین استان‌ها بر اساس بخشی از نام.
+ * ترتیب نتایج: تطابق دقیق > شروع‌شونده‌با > شامل‌شونده > (در حالت fuzzy) نزدیک از نظر فاصله‌ی ادیت.
+ */
 declare function searchProvinces(query: string, options?: SearchOptions): Province[];
-/** جستجوی fuzzy (شامل‌شونده) در بین تمام شهرهای کشور بر اساس بخشی از نام */
+/**
+ * جستجوی رتبه‌بندی‌شده در بین تمام شهرهای کشور بر اساس بخشی از نام.
+ * ترتیب نتایج: تطابق دقیق > شروع‌شونده‌با > شامل‌شونده > (در حالت fuzzy) نزدیک از نظر فاصله‌ی ادیت.
+ * برای تحمل غلط تایپی، `{ fuzzy: true }` را در options پاس بده.
+ */
 declare function searchCities(query: string, options?: SearchOptions): FlatCity[];
 /** آمار کلی: تعداد استان‌ها و تعداد کل شهرها */
 declare function getStats(): {
@@ -28,4 +41,4 @@ declare function getStats(): {
     cityCount: number;
 };
 
-export { City, FlatCity, Province, SearchOptions, getAllCities, getCities, getCity, getProvince, getProvinceOfCity, getProvinces, getProvincesList, getStats, searchCities, searchProvinces };
+export { City, CityKey, FlatCity, Province, SearchOptions, getAllCities, getCities, getCity, getCityBySlug, getProvince, getProvinceOfCity, getProvinces, getProvincesList, getStats, searchCities, searchProvinces };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FlatCity, C as City, P as Province, S as SearchOptions } from './types--eoWJy5A.js';
-export { L as Locale } from './types--eoWJy5A.js';
+import { F as FlatCity, C as City, a as CityKey, P as Province, S as SearchOptions } from './types-DwFZSr9I.js';
+export { L as Locale } from './types-DwFZSr9I.js';
 
 /** لیست کامل استان‌ها به همراه شهرهای هرکدام */
 declare function getProvinces(): Province[];
@@ -8,19 +8,32 @@ declare function getProvincesList(): {
     en: string;
     fa: string;
 }[];
-/** پیدا کردن یک استان با شناسه انگلیسی یا نام فارسی (دقیق، نرمال‌شده) */
+/** پیدا کردن یک استان با شناسه انگلیسی یا نام فارسی (دقیق، نرمال‌شده) - O(1) */
 declare function getProvince(query: string): Province | undefined;
 /** لیست شهرهای یک استان بر اساس شناسه انگلیسی یا نام فارسی استان */
 declare function getCities(provinceQuery: string): City[];
 /** لیست تمام شهرهای کشور به صورت مسطح، همراه با اطلاعات استان مربوطه */
 declare function getAllCities(): FlatCity[];
-/** پیدا کردن یک شهر با شناسه انگلیسی یا نام فارسی (اختیاری: محدود به یک استان خاص) */
+/**
+ * پیدا کردن یک شهر با شناسه‌ی یکتای سراسری آن (City.slug، به‌فرم `provinceEn/cityEn`) - O(1)
+ * برای پکیج‌های وابسته که داده‌ی اضافه (کد تلفن، پلاک، پیش‌شماره کد ملی و ...) را بر اساس
+ * این کلید نگه می‌دارند، مسیر پیشنهادی همین تابع است چون بدون ابهامِ هم‌نامی کار می‌کند.
+ */
+declare function getCityBySlug(slug: CityKey): FlatCity | undefined;
+/** پیدا کردن یک شهر با شناسه انگلیسی یا نام فارسی (اختیاری: محدود به یک استان خاص) - O(1) / O(اندازه استان) */
 declare function getCity(cityQuery: string, provinceQuery?: string): FlatCity | undefined;
-/** استانی که یک شهر مشخص در آن قرار دارد را برمی‌گرداند */
+/** استانی که یک شهر مشخص در آن قرار دارد را برمی‌گرداند - O(1) */
 declare function getProvinceOfCity(cityQuery: string): Province | undefined;
-/** جستجوی fuzzy (شامل‌شونده) در بین استان‌ها بر اساس بخشی از نام */
+/**
+ * جستجوی رتبه‌بندی‌شده در بین استان‌ها بر اساس بخشی از نام.
+ * ترتیب نتایج: تطابق دقیق > شروع‌شونده‌با > شامل‌شونده > (در حالت fuzzy) نزدیک از نظر فاصله‌ی ادیت.
+ */
 declare function searchProvinces(query: string, options?: SearchOptions): Province[];
-/** جستجوی fuzzy (شامل‌شونده) در بین تمام شهرهای کشور بر اساس بخشی از نام */
+/**
+ * جستجوی رتبه‌بندی‌شده در بین تمام شهرهای کشور بر اساس بخشی از نام.
+ * ترتیب نتایج: تطابق دقیق > شروع‌شونده‌با > شامل‌شونده > (در حالت fuzzy) نزدیک از نظر فاصله‌ی ادیت.
+ * برای تحمل غلط تایپی، `{ fuzzy: true }` را در options پاس بده.
+ */
 declare function searchCities(query: string, options?: SearchOptions): FlatCity[];
 /** آمار کلی: تعداد استان‌ها و تعداد کل شهرها */
 declare function getStats(): {
@@ -28,4 +41,4 @@ declare function getStats(): {
     cityCount: number;
 };
 
-export { City, FlatCity, Province, SearchOptions, getAllCities, getCities, getCity, getProvince, getProvinceOfCity, getProvinces, getProvincesList, getStats, searchCities, searchProvinces };
+export { City, CityKey, FlatCity, Province, SearchOptions, getAllCities, getCities, getCity, getCityBySlug, getProvince, getProvinceOfCity, getProvinces, getProvincesList, getStats, searchCities, searchProvinces };

package/dist/index.mjs

@@ -5201,25 +5201,98 @@ var data_default = [
 ];
 
 // src/index.ts
-var provinces = data_default.map((p) => ({
-  en: p["province-en"],
-  fa: p["province-fa"],
-  cities: p.cities.map((c) => ({ en: c["city-en"], fa: c["city-fa"] }))
-}));
 function normalize(input) {
   return input.trim().toLowerCase().replace(/ي/g, "\u06CC").replace(/ك/g, "\u06A9").replace(/[\u200c\s-]+/g, "");
 }
-var _flatCache = null;
-function getFlatCitiesInternal() {
-  if (_flatCache) return _flatCache;
-  const flat = [];
-  for (const p of provinces) {
-    for (const c of p.cities) {
-      flat.push({ en: c.en, fa: c.fa, provinceEn: p.en, provinceFa: p.fa });
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  const al = a.length;
+  const bl = b.length;
+  if (al === 0) return bl;
+  if (bl === 0) return al;
+  let prev = new Array(bl + 1);
+  for (let j = 0; j <= bl; j++) prev[j] = j;
+  for (let i = 1; i <= al; i++) {
+    const curr = new Array(bl + 1);
+    curr[0] = i;
+    for (let j = 1; j <= bl; j++) {
+      const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+      curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
     }
+    prev = curr;
   }
-  _flatCache = flat;
-  return flat;
+  return prev[bl];
+}
+function matchScore(query, target, fuzzy, maxDistance) {
+  if (!target) return Infinity;
+  if (target === query) return 0;
+  if (target.startsWith(query)) return 1;
+  if (target.includes(query)) return 2;
+  if (fuzzy) {
+    const dist = levenshtein(query, target);
+    if (dist <= maxDistance) return 3 + dist;
+  }
+  return Infinity;
+}
+var provinces = data_default.map((p) => {
+  const provinceEn = p["province-en"];
+  const provinceFa = p["province-fa"];
+  return {
+    en: provinceEn,
+    fa: provinceFa,
+    cities: p.cities.map((c) => ({
+      en: c["city-en"],
+      fa: c["city-fa"],
+      slug: `${provinceEn}/${c["city-en"]}`
+    }))
+  };
+});
+var flatCities = [];
+var cityBySlug = /* @__PURE__ */ new Map();
+var cityByNormKey = /* @__PURE__ */ new Map();
+var provinceByNormKey = /* @__PURE__ */ new Map();
+var cityToProvinceByNormKey = /* @__PURE__ */ new Map();
+var searchableCities = [];
+var searchableProvinces = [];
+for (const p of provinces) {
+  const pNormEn = normalize(p.en);
+  const pNormFa = normalize(p.fa);
+  if (!provinceByNormKey.has(pNormEn)) provinceByNormKey.set(pNormEn, p);
+  if (!provinceByNormKey.has(pNormFa)) provinceByNormKey.set(pNormFa, p);
+  searchableProvinces.push({ item: p, normEn: pNormEn, normFa: pNormFa });
+  for (const c of p.cities) {
+    const flat = { en: c.en, fa: c.fa, slug: c.slug, provinceEn: p.en, provinceFa: p.fa };
+    flatCities.push(flat);
+    cityBySlug.set(flat.slug, flat);
+    const cNormEn = normalize(c.en);
+    const cNormFa = normalize(c.fa);
+    if (!cityByNormKey.has(cNormEn)) cityByNormKey.set(cNormEn, flat);
+    if (!cityByNormKey.has(cNormFa)) cityByNormKey.set(cNormFa, flat);
+    if (!cityToProvinceByNormKey.has(cNormEn)) cityToProvinceByNormKey.set(cNormEn, p);
+    if (!cityToProvinceByNormKey.has(cNormFa)) cityToProvinceByNormKey.set(cNormFa, p);
+    searchableCities.push({ item: flat, normEn: cNormEn, normFa: cNormFa });
+  }
+}
+function rankedSearch(pool, query, options) {
+  var _a, _b, _c;
+  const q = normalize(query);
+  if (!q) {
+    const all = pool.map((e) => e.item);
+    return options.limit ? all.slice(0, options.limit) : all;
+  }
+  const locale = (_a = options.locale) != null ? _a : "both";
+  const fuzzy = (_b = options.fuzzy) != null ? _b : false;
+  const maxDistance = (_c = options.maxDistance) != null ? _c : 2;
+  const scored = [];
+  for (const entry of pool) {
+    let score = Infinity;
+    if (locale !== "fa") score = Math.min(score, matchScore(q, entry.normEn, fuzzy, maxDistance));
+    if (locale !== "en") score = Math.min(score, matchScore(q, entry.normFa, fuzzy, maxDistance));
+    if (score !== Infinity) scored.push({ item: entry.item, score });
+  }
+  scored.sort((a, b) => a.score - b.score);
+  const results = scored.map((s) => s.item);
+  return options.limit ? results.slice(0, options.limit) : results;
 }
 function getProvinces() {
   return provinces;
@@ -5228,67 +5301,48 @@ function getProvincesList() {
   return provinces.map((p) => ({ en: p.en, fa: p.fa }));
 }
 function getProvince(query) {
-  const q = normalize(query);
-  return provinces.find((p) => normalize(p.en) === q || normalize(p.fa) === q);
+  return provinceByNormKey.get(normalize(query));
 }
 function getCities(provinceQuery) {
-  const province = getProvince(provinceQuery);
-  return province ? province.cities : [];
+  var _a, _b;
+  return (_b = (_a = getProvince(provinceQuery)) == null ? void 0 : _a.cities) != null ? _b : [];
 }
 function getAllCities() {
-  return getFlatCitiesInternal();
+  return flatCities;
+}
+function getCityBySlug(slug) {
+  return cityBySlug.get(slug);
 }
 function getCity(cityQuery, provinceQuery) {
   const q = normalize(cityQuery);
-  const pool = provinceQuery ? getCities(provinceQuery).map((c) => {
-    var _a, _b, _c, _d;
-    return {
-      ...c,
-      provinceEn: (_b = (_a = getProvince(provinceQuery)) == null ? void 0 : _a.en) != null ? _b : "",
-      provinceFa: (_d = (_c = getProvince(provinceQuery)) == null ? void 0 : _c.fa) != null ? _d : ""
-    };
-  }) : getFlatCitiesInternal();
-  return pool.find((c) => normalize(c.en) === q || normalize(c.fa) === q);
+  if (provinceQuery) {
+    const province = getProvince(provinceQuery);
+    if (!province) return void 0;
+    const city = province.cities.find((c) => normalize(c.en) === q || normalize(c.fa) === q);
+    return city ? { en: city.en, fa: city.fa, slug: city.slug, provinceEn: province.en, provinceFa: province.fa } : void 0;
+  }
+  return cityByNormKey.get(q);
 }
 function getProvinceOfCity(cityQuery) {
-  const q = normalize(cityQuery);
-  return provinces.find((p) => p.cities.some((c) => normalize(c.en) === q || normalize(c.fa) === q));
+  return cityToProvinceByNormKey.get(normalize(cityQuery));
 }
 function searchProvinces(query, options = {}) {
-  var _a;
-  const q = normalize(query);
-  if (!q) return options.limit ? provinces.slice(0, options.limit) : provinces;
-  const locale = (_a = options.locale) != null ? _a : "both";
-  const results = provinces.filter((p) => {
-    const matchEn = locale !== "fa" && normalize(p.en).includes(q);
-    const matchFa = locale !== "en" && normalize(p.fa).includes(q);
-    return matchEn || matchFa;
-  });
-  return options.limit ? results.slice(0, options.limit) : results;
+  return rankedSearch(searchableProvinces, query, options);
 }
 function searchCities(query, options = {}) {
-  var _a;
-  const q = normalize(query);
-  const all = getFlatCitiesInternal();
-  if (!q) return options.limit ? all.slice(0, options.limit) : all;
-  const locale = (_a = options.locale) != null ? _a : "both";
-  const results = all.filter((c) => {
-    const matchEn = locale !== "fa" && normalize(c.en).includes(q);
-    const matchFa = locale !== "en" && normalize(c.fa).includes(q);
-    return matchEn || matchFa;
-  });
-  return options.limit ? results.slice(0, options.limit) : results;
+  return rankedSearch(searchableCities, query, options);
 }
 function getStats() {
   return {
     provinceCount: provinces.length,
-    cityCount: getFlatCitiesInternal().length
+    cityCount: flatCities.length
   };
 }
 export {
   getAllCities,
   getCities,
   getCity,
+  getCityBySlug,
   getProvince,
   getProvinceOfCity,
   getProvinces,