@code-plate/iran-cities 1.0.0 → 1.0.2

package/README.fa.md

@@ -0,0 +1,259 @@
+[English](./README.md) | فارسی
+
+# @code-plate/iran-cities
+
+لیست کامل و آماده‌ی **استان‌ها و شهرهای ایران** (فارسی + انگلیسی)، بسته‌بندی‌شده به شکل یک کتابخانه‌ی سبک، بدون هیچ وابستگی اجباری، که در **هر پروژه‌ی جاوااسکریپتی/تایپ‌اسکریپتی** قابل استفاده است:
+
+- ✅ React / Next.js (App Router و Pages Router)
+- ✅ Vue 2 / Vue 3
+- ✅ Angular
+- ✅ Svelte
+- ✅ Node.js / Express (بک‌اند خالص)
+- ✅ Vanilla JS (مرورگر یا هر باندلر دیگر)
+
+هسته‌ی اصلی پکیج **هیچ وابستگی‌ای** ندارد (zero-dependency) و هم به‌صورت **CJS** و هم **ESM** ارائه می‌شود. یک ساب‌پس اختیاری (`@code-plate/iran-cities/react`) هم برای کسانی که در React کار می‌کنند وجود دارد که چند هوک آماده می‌دهد؛ اگر پروژه‌تان React نیست، هرگز این فایل import نمی‌شود و React اصلاً لازم نیست نصب شود.
+
+## نصب
+
+```bash
+npm install @code-plate/iran-cities
+# یا
+yarn add @code-plate/iran-cities
+# یا
+pnpm add @code-plate/iran-cities
+```
+
+## داده‌ها
+
+- `۳۱` استان
+- `۱۲۵۳` شهر
+- هر رکورد شامل `en` (شناسه لاتین kebab-case، مثل `tehran`) و `fa` (نام فارسی، مثل `تهران`) است.
+
+---
+
+## استفاده در جاوااسکریپت / تایپ‌اسکریپت خالص (و Node.js/Express)
+
+```ts
+import {
+  getProvinces,
+  getProvincesList,
+  getProvince,
+  getCities,
+  getCity,
+  getAllCities,
+  getProvinceOfCity,
+  searchProvinces,
+  searchCities,
+  getStats,
+} from '@code-plate/iran-cities';
+
+// همه‌ی استان‌ها به همراه شهرهایشان
+getProvinces();
+// [{ en: 'alborz', fa: 'البرز', cities: [{ en: 'karaj', fa: 'کرج' }, ...] }, ...]
+
+// فقط لیست استان‌ها (بدون شهر) - برای Select/Dropdown
+getProvincesList();
+// [{ en: 'alborz', fa: 'البرز' }, { en: 'ardabil', fa: 'اردبیل' }, ...]
+
+// گرفتن یک استان با نام انگلیسی یا فارسی
+getProvince('tehran');
+getProvince('تهران'); // همین نتیجه را می‌دهد
+
+// شهرهای یک استان خاص
+getCities('fars');       // بر اساس شناسه انگلیسی
+getCities('فارس');       // یا بر اساس نام فارسی، هر دو یکسان کار می‌کنند
+
+// پیدا کردن یک شهر مشخص (در کل کشور یا محدود به یک استان)
+getCity('shiraz');
+getCity('شیراز', 'fars'); // محدود به استان فارس
+
+// لیست مسطح (flat) همه‌ی شهرهای کشور همراه با استان مربوطه
+getAllCities();
+// [{ en: 'karaj', fa: 'کرج', provinceEn: 'alborz', provinceFa: 'البرز' }, ...]
+
+// پیدا کردن استانِ یک شهر
+getProvinceOfCity('اصفهان'); // => { en: 'isfahan', fa: 'اصفهان', cities: [...] }
+
+// جستجوی زنده (autocomplete) در استان‌ها یا شهرها
+searchProvinces('خراسان');            // هر سه استان خراسان را برمی‌گرداند
+searchCities('شهر', { limit: 10 });   // ۱۰ نتیجه‌ی اول شامل «شهر»
+searchCities('mashhad', { locale: 'en' }); // جستجو فقط در نام انگلیسی
+
+// آمار کلی
+getStats(); // { provinceCount: 31, cityCount: 1253 }
+```
+
+### نکته‌ی مهم درباره‌ی جستجو
+تابع‌های `getProvince`, `getCities`, `getCity` و `getProvinceOfCity` به‌صورت **نرمال‌شده** مقایسه می‌کنند؛ یعنی تفاوت «ی» فارسی/«ي» عربی، «ک»/«ك»، نیم‌فاصله، فاصله و خط‌تیره را نادیده می‌گیرند. پس `getCity('كرج')` و `getCity('کرج')` هر دو کار می‌کنند.
+
+---
+
+## استفاده در Node.js / Express (بک‌اند)
+
+```js
+const express = require('express');
+const { getProvincesList, getCities, searchCities } = require('@code-plate/iran-cities');
+
+const app = express();
+
+app.get('/api/provinces', (req, res) => {
+  res.json(getProvincesList());
+});
+
+app.get('/api/cities/:province', (req, res) => {
+  res.json(getCities(req.params.province));
+});
+
+app.get('/api/cities/search', (req, res) => {
+  res.json(searchCities(req.query.q ?? '', { limit: 20 }));
+});
+```
+
+---
+
+## استفاده در React / Next.js
+
+برای React یک ساب‌پس اختیاری وجود دارد که چند هوک آماده ارائه می‌دهد:
+
+```tsx
+import { useProvinces, useCities, useProvinceCitySelect, useCitySearch } from '@code-plate/iran-cities/react';
+
+function AddressForm() {
+  const { provinces, cities, province, setProvince, city, setCity } = useProvinceCitySelect();
+
+  return (
+    <>
+      <select value={province} onChange={(e) => setProvince(e.target.value)}>
+        <option value="">انتخاب استان</option>
+        {provinces.map((p) => (
+          <option key={p.en} value={p.en}>{p.fa}</option>
+        ))}
+      </select>
+
+      <select value={city} onChange={(e) => setCity(e.target.value)} disabled={!province}>
+        <option value="">انتخاب شهر</option>
+        {cities.map((c) => (
+          <option key={c.en} value={c.en}>{c.fa}</option>
+        ))}
+      </select>
+    </>
+  );
+}
+```
+
+جستجوی زنده‌ی شهر (autocomplete):
+
+```tsx
+import { useCitySearch } from '@code-plate/iran-cities/react';
+
+function CityAutocomplete() {
+  const { query, setQuery, results } = useCitySearch('', { limit: 8 });
+
+  return (
+    <div>
+      <input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="نام شهر..." />
+      <ul>
+        {results.map((c) => (
+          <li key={`${c.provinceEn}-${c.en}`}>{c.fa} ({c.provinceFa})</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+هوک‌های در دسترس در ساب‌پس `react`:
+
+| هوک | کاربرد |
+|---|---|
+| `useProvinces()` | لیست استان‌ها |
+| `useCities(provinceQuery)` | شهرهای یک استان، وابسته به تغییر پارامتر |
+| `useProvinceCitySelect()` | state کامل یک فرم استان→شهر (با ریست خودکار شهر هنگام تغییر استان) |
+| `useCitySearch(initialQuery?, options?)` | state جستجوی زنده‌ی شهر |
+| `useProvinceSearch(initialQuery?, options?)` | state جستجوی زنده‌ی استان |
+
+> اگر پروژه‌تان Vue، Angular یا هر چیز دیگری است، فقط از مسیر اصلی (`@code-plate/iran-cities`) استفاده کنید و توابع خام (`getProvinces`, `getCities`, ...) را داخل computed/signal/observable خودتان قرار دهید — نیازی به هیچ ابزار اضافه‌ای نیست.
+
+---
+
+## استفاده در Vue 3 (نمونه)
+
+```vue
+<script setup>
+import { ref, computed } from 'vue';
+import { getProvincesList, getCities } from '@code-plate/iran-cities';
+
+const provinces = getProvincesList();
+const selectedProvince = ref('');
+const cities = computed(() => getCities(selectedProvince.value));
+</script>
+
+<template>
+  <select v-model="selectedProvince">
+    <option v-for="p in provinces" :key="p.en" :value="p.en">{{ p.fa }}</option>
+  </select>
+  <select :disabled="!selectedProvince">
+    <option v-for="c in cities" :key="c.en" :value="c.en">{{ c.fa }}</option>
+  </select>
+</template>
+```
+
+## استفاده در Angular (نمونه سرویس)
+
+```ts
+import { Injectable } from '@angular/core';
+import { getProvincesList, getCities, type City } from '@code-plate/iran-cities';
+
+@Injectable({ providedIn: 'root' })
+export class IranLocationsService {
+  getProvinces() {
+    return getProvincesList();
+  }
+  getCitiesOf(provinceEn: string): City[] {
+    return getCities(provinceEn);
+  }
+}
+```
+
+---
+
+## API کامل
+
+### توابع اصلی (import از `'@code-plate/iran-cities'`)
+
+| تابع | ورودی | خروجی | توضیح |
+|---|---|---|---|
+| `getProvinces()` | - | `Province[]` | همه‌ی استان‌ها به همراه شهرها |
+| `getProvincesList()` | - | `{en, fa}[]` | فقط لیست استان‌ها |
+| `getProvince(query)` | `string` | `Province \| undefined` | یک استان با en یا fa |
+| `getCities(provinceQuery)` | `string` | `City[]` | شهرهای یک استان |
+| `getCity(cityQuery, provinceQuery?)` | `string, string?` | `FlatCity \| undefined` | یک شهر مشخص |
+| `getAllCities()` | - | `FlatCity[]` | همه‌ی شهرها به‌صورت مسطح |
+| `getProvinceOfCity(cityQuery)` | `string` | `Province \| undefined` | استانِ یک شهر |
+| `searchProvinces(query, options?)` | `string, SearchOptions?` | `Province[]` | جستجوی fuzzy استان |
+| `searchCities(query, options?)` | `string, SearchOptions?` | `FlatCity[]` | جستجوی fuzzy شهر |
+| `getStats()` | - | `{provinceCount, cityCount}` | آمار کلی |
+
+`SearchOptions`: `{ limit?: number; locale?: 'en' | 'fa' | 'both' }`
+
+### تایپ‌ها
+
+```ts
+interface City { en: string; fa: string; }
+interface Province { en: string; fa: string; cities: City[]; }
+interface FlatCity extends City { provinceEn: string; provinceFa: string; }
+```
+
+---
+
+## توسعه
+
+```bash
+npm install
+npm run build     # خروجی dist/ (cjs + esm + d.ts)
+npm run typecheck
+```
+
+## لایسنس
+
+MIT

package/README.md

@@ -1,35 +1,37 @@
+English | [فارسی](./README.fa.md)
+
 # @code-plate/iran-cities
 
-لیست کامل و آماده‌ی **استان‌ها و شهرهای ایران** (فارسی + انگلیسی)، بسته‌بندی‌شده به شکل یک کتابخانه‌ی سبک، بدون هیچ وابستگی اجباری، که در **هر پروژه‌ی جاوااسکریپتی/تایپ‌اسکریپتی** قابل استفاده است:
+A complete, ready-to-use list of **Iran's provinces and cities** (Persian + English), packaged as a lightweight library with no forced dependencies, usable in **any JavaScript/TypeScript project**:
 
-- ✅ React / Next.js (App Router و Pages Router)
+- ✅ React / Next.js (App Router and Pages Router)
 - ✅ Vue 2 / Vue 3
 - ✅ Angular
 - ✅ Svelte
-- ✅ Node.js / Express (بک‌اند خالص)
-- ✅ Vanilla JS (مرورگر یا هر باندلر دیگر)
+- ✅ Node.js / Express (pure backend)
+- ✅ Vanilla JS (browser or any other bundler)
 
-هسته‌ی اصلی پکیج **هیچ وابستگی‌ای** ندارد (zero-dependency) و هم به‌صورت **CJS** و هم **ESM** ارائه می‌شود. یک ساب‌پس اختیاری (`@code-plate/iran-cities/react`) هم برای کسانی که در React کار می‌کنند وجود دارد که چند هوک آماده می‌دهد؛ اگر پروژه‌تان React نیست، هرگز این فایل import نمی‌شود و React اصلاً لازم نیست نصب شود.
+The core of the package has **zero dependencies** and ships as both **CJS** and **ESM**. There's also an optional subpath (`@code-plate/iran-cities/react`) for React users with a few ready-made hooks; if your project isn't React, that file is never imported and React doesn't need to be installed at all.
 
-## نصب
+## Installation
 
 ```bash
 npm install @code-plate/iran-cities
-# یا
+# or
 yarn add @code-plate/iran-cities
-# یا
+# or
 pnpm add @code-plate/iran-cities
 ```
 
-## داده‌ها
+## Data
 
-- `۳۱` استان
-- `۱۲۵۳` شهر
-- هر رکورد شامل `en` (شناسه لاتین kebab-case، مثل `tehran`) و `fa` (نام فارسی، مثل `تهران`) است.
+- `31` provinces
+- `1253` cities
+- Every record has an `en` field (latin, kebab-case identifier, e.g. `tehran`) and an `fa` field (Persian name, e.g. `تهران`).
 
 ---
 
-## استفاده در جاوااسکریپت / تایپ‌اسکریپت خالص (و Node.js/Express)
+## Usage in plain JavaScript / TypeScript (and Node.js/Express)
 
 ```ts
 import {
@@ -45,48 +47,48 @@ import {
   getStats,
 } from '@code-plate/iran-cities';
 
-// همه‌ی استان‌ها به همراه شهرهایشان
+// All provinces along with their cities
 getProvinces();
 // [{ en: 'alborz', fa: 'البرز', cities: [{ en: 'karaj', fa: 'کرج' }, ...] }, ...]
 
-// فقط لیست استان‌ها (بدون شهر) - برای Select/Dropdown
+// Just the list of provinces (no cities) - for a Select/Dropdown
 getProvincesList();
 // [{ en: 'alborz', fa: 'البرز' }, { en: 'ardabil', fa: 'اردبیل' }, ...]
 
-// گرفتن یک استان با نام انگلیسی یا فارسی
+// Get a single province by English id or Persian name
 getProvince('tehran');
-getProvince('تهران'); // همین نتیجه را می‌دهد
+getProvince('تهران'); // same result
 
-// شهرهای یک استان خاص
-getCities('fars');       // بر اساس شناسه انگلیسی
-getCities('فارس');       // یا بر اساس نام فارسی، هر دو یکسان کار می‌کنند
+// Cities of a specific province
+getCities('fars');       // by English id
+getCities('فارس');       // or by Persian name, both work the same way
 
-// پیدا کردن یک شهر مشخص (در کل کشور یا محدود به یک استان)
+// Find a specific city (across the whole country, or scoped to a province)
 getCity('shiraz');
-getCity('شیراز', 'fars'); // محدود به استان فارس
+getCity('شیراز', 'fars'); // scoped to Fars province
 
-// لیست مسطح (flat) همه‌ی شهرهای کشور همراه با استان مربوطه
+// Flat list of every city in the country, along with its province
 getAllCities();
 // [{ en: 'karaj', fa: 'کرج', provinceEn: 'alborz', provinceFa: 'البرز' }, ...]
 
-// پیدا کردن استانِ یک شهر
+// Find which province a city belongs to
 getProvinceOfCity('اصفهان'); // => { en: 'isfahan', fa: 'اصفهان', cities: [...] }
 
-// جستجوی زنده (autocomplete) در استان‌ها یا شهرها
-searchProvinces('خراسان');            // هر سه استان خراسان را برمی‌گرداند
-searchCities('شهر', { limit: 10 });   // ۱۰ نتیجه‌ی اول شامل «شهر»
-searchCities('mashhad', { locale: 'en' }); // جستجو فقط در نام انگلیسی
+// Live search (autocomplete) over provinces or cities
+searchProvinces('خراسان');             // returns all three "Khorasan" provinces
+searchCities('شهر', { limit: 10 });    // first 10 results containing "شهر"
+searchCities('mashhad', { locale: 'en' }); // search English names only
 
-// آمار کلی
+// Overall stats
 getStats(); // { provinceCount: 31, cityCount: 1253 }
 ```
 
-### نکته‌ی مهم درباره‌ی جستجو
-تابع‌های `getProvince`, `getCities`, `getCity` و `getProvinceOfCity` به‌صورت **نرمال‌شده** مقایسه می‌کنند؛ یعنی تفاوت «ی» فارسی/«ي» عربی، «ک»/«ك»، نیم‌فاصله، فاصله و خط‌تیره را نادیده می‌گیرند. پس `getCity('كرج')` و `getCity('کرج')` هر دو کار می‌کنند.
+### A note on search
+`getProvince`, `getCities`, `getCity` and `getProvinceOfCity` compare strings in a **normalized** way — differences between Persian «ی» and Arabic «ي», «ک» vs. «ك», zero-width non-joiners, spaces and hyphens are all ignored. So `getCity('كرج')` and `getCity('کرج')` both work.
 
 ---
 
-## استفاده در Node.js / Express (بک‌اند)
+## Usage in Node.js / Express (backend)
 
 ```js
 const express = require('express');
@@ -109,9 +111,9 @@ app.get('/api/cities/search', (req, res) => {
 
 ---
 
-## استفاده در React / Next.js
+## Usage in React / Next.js
 
-برای React یک ساب‌پس اختیاری وجود دارد که چند هوک آماده ارائه می‌دهد:
+An optional subpath is available for React with a few ready-made hooks:
 
 ```tsx
 import { useProvinces, useCities, useProvinceCitySelect, useCitySearch } from '@code-plate/iran-cities/react';
@@ -122,14 +124,14 @@ function AddressForm() {
   return (
     <>
       <select value={province} onChange={(e) => setProvince(e.target.value)}>
-        <option value="">انتخاب استان</option>
+        <option value="">Select a province</option>
         {provinces.map((p) => (
           <option key={p.en} value={p.en}>{p.fa}</option>
         ))}
       </select>
 
       <select value={city} onChange={(e) => setCity(e.target.value)} disabled={!province}>
-        <option value="">انتخاب شهر</option>
+        <option value="">Select a city</option>
         {cities.map((c) => (
           <option key={c.en} value={c.en}>{c.fa}</option>
         ))}
@@ -139,7 +141,7 @@ function AddressForm() {
 }
 ```
 
-جستجوی زنده‌ی شهر (autocomplete):
+Live city search (autocomplete):
 
 ```tsx
 import { useCitySearch } from '@code-plate/iran-cities/react';
@@ -149,7 +151,7 @@ function CityAutocomplete() {
 
   return (
     <div>
-      <input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="نام شهر..." />
+      <input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="City name..." />
       <ul>
         {results.map((c) => (
           <li key={`${c.provinceEn}-${c.en}`}>{c.fa} ({c.provinceFa})</li>
@@ -160,21 +162,21 @@ function CityAutocomplete() {
 }
 ```
 
-هوک‌های در دسترس در ساب‌پس `react`:
+Hooks available in the `react` subpath:
 
-| هوک | کاربرد |
+| Hook | Purpose |
 |---|---|
-| `useProvinces()` | لیست استان‌ها |
-| `useCities(provinceQuery)` | شهرهای یک استان، وابسته به تغییر پارامتر |
-| `useProvinceCitySelect()` | state کامل یک فرم استان→شهر (با ریست خودکار شهر هنگام تغییر استان) |
-| `useCitySearch(initialQuery?, options?)` | state جستجوی زنده‌ی شهر |
-| `useProvinceSearch(initialQuery?, options?)` | state جستجوی زنده‌ی استان |
+| `useProvinces()` | List of provinces |
+| `useCities(provinceQuery)` | Cities of a province, reacts to changes in the parameter |
+| `useProvinceCitySelect()` | Full state + logic for a province→city form field (auto-resets the city when the province changes) |
+| `useCitySearch(initialQuery?, options?)` | Live city search state |
+| `useProvinceSearch(initialQuery?, options?)` | Live province search state |
 
-> اگر پروژه‌تان Vue، Angular یا هر چیز دیگری است، فقط از مسیر اصلی (`@code-plate/iran-cities`) استفاده کنید و توابع خام (`getProvinces`, `getCities`, ...) را داخل computed/signal/observable خودتان قرار دهید — نیازی به هیچ ابزار اضافه‌ای نیست.
+> If your project is Vue, Angular, or anything else, just use the main entry point (`@code-plate/iran-cities`) and plug the raw functions (`getProvinces`, `getCities`, ...) into your own computed/signal/observable — no extra tooling required.
 
 ---
 
-## استفاده در Vue 3 (نمونه)
+## Usage in Vue 3 (example)
 
 ```vue
 <script setup>
@@ -196,7 +198,7 @@ const cities = computed(() => getCities(selectedProvince.value));
 </template>
 ```
 
-## استفاده در Angular (نمونه سرویس)
+## Usage in Angular (example service)
 
 ```ts
 import { Injectable } from '@angular/core';
@@ -215,26 +217,26 @@ export class IranLocationsService {
 
 ---
 
-## API کامل
+## Full API
 
-### توابع اصلی (import از `'@code-plate/iran-cities'`)
+### Core functions (import from `'@code-plate/iran-cities'`)
 
-| تابع | ورودی | خروجی | توضیح |
+| Function | Input | Output | Description |
 |---|---|---|---|
-| `getProvinces()` | - | `Province[]` | همه‌ی استان‌ها به همراه شهرها |
-| `getProvincesList()` | - | `{en, fa}[]` | فقط لیست استان‌ها |
-| `getProvince(query)` | `string` | `Province \| undefined` | یک استان با en یا fa |
-| `getCities(provinceQuery)` | `string` | `City[]` | شهرهای یک استان |
-| `getCity(cityQuery, provinceQuery?)` | `string, string?` | `FlatCity \| undefined` | یک شهر مشخص |
-| `getAllCities()` | - | `FlatCity[]` | همه‌ی شهرها به‌صورت مسطح |
-| `getProvinceOfCity(cityQuery)` | `string` | `Province \| undefined` | استانِ یک شهر |
-| `searchProvinces(query, options?)` | `string, SearchOptions?` | `Province[]` | جستجوی fuzzy استان |
-| `searchCities(query, options?)` | `string, SearchOptions?` | `FlatCity[]` | جستجوی fuzzy شهر |
-| `getStats()` | - | `{provinceCount, cityCount}` | آمار کلی |
+| `getProvinces()` | - | `Province[]` | All provinces with their cities |
+| `getProvincesList()` | - | `{en, fa}[]` | Provinces only |
+| `getProvince(query)` | `string` | `Province \| undefined` | A province by en or fa |
+| `getCities(provinceQuery)` | `string` | `City[]` | Cities of a province |
+| `getCity(cityQuery, provinceQuery?)` | `string, string?` | `FlatCity \| undefined` | A specific city |
+| `getAllCities()` | - | `FlatCity[]` | All cities, flattened |
+| `getProvinceOfCity(cityQuery)` | `string` | `Province \| undefined` | The province a city belongs to |
+| `searchProvinces(query, options?)` | `string, SearchOptions?` | `Province[]` | Fuzzy province search |
+| `searchCities(query, options?)` | `string, SearchOptions?` | `FlatCity[]` | Fuzzy city search |
+| `getStats()` | - | `{provinceCount, cityCount}` | Overall stats |
 
 `SearchOptions`: `{ limit?: number; locale?: 'en' | 'fa' | 'both' }`
 
-### تایپ‌ها
+### Types
 
 ```ts
 interface City { en: string; fa: string; }
@@ -244,14 +246,14 @@ interface FlatCity extends City { provinceEn: string; provinceFa: string; }
 
 ---
 
-## توسعه
+## Development
 
 ```bash
 npm install
-npm run build     # خروجی dist/ (cjs + esm + d.ts)
+npm run build     # outputs dist/ (cjs + esm + d.ts)
 npm run typecheck
 ```
 
-## لایسنس
+## License
 
 MIT