🇮🇷 Persian Tools

A modern, library-agnostic TypeScript utility for Persian language features.

[![CI/CD](https://github.com/persian-tools/persian-tools/workflows/Continuous%20Integration/badge.svg)](https://github.com/persian-tools/persian-tools/actions) [![codecov](https://codecov.io/gh/persian-tools/persian-tools/branch/master/graph/badge.svg)](https://codecov.io/gh/persian-tools/persian-tools) [![npm version](https://img.shields.io/npm/v/@persian-tools/persian-tools.svg)](https://npm.im/@persian-tools/persian-tools) [![npm downloads](https://img.shields.io/npm/dm/@persian-tools/persian-tools.svg)](https://npm.im/@persian-tools/persian-tools) [![bundle size](https://img.shields.io/bundlephobia/minzip/@persian-tools/persian-tools)](https://bundlephobia.com/package/@persian-tools/persian-tools) [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/persian-tools/persian-tools/blob/master/LICENSE) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-orange.svg)](https://github.com/persian-tools/persian-tools/compare) [![CodeFactor](https://www.codefactor.io/repository/github/persian-tools/persian-tools/badge)](https://www.codefactor.io/repository/github/persian-tools/persian-tools) ![GitHub contributors](https://img.shields.io/github/contributors/persian-tools/persian-tools.svg)

--- ## ✨ Features Persian Tools provides **27+ utilities** for Persian language processing: ### 🔢 Numbers & Text - **Number Conversion**: Persian words ↔ numbers with fuzzy matching - **Digit Conversion**: Persian ↔ Arabic ↔ English digits - **Comma Formatting**: Add/remove thousands separators - **Ordinal Numbers**: Convert to/from ordinal forms ### 🏛️ Validation & Verification - **National ID**: Validate & generate Iranian national codes (کد ملی) - **Legal ID**: Validate Iranian legal entity IDs (شناسه حقوقی) - **Phone Numbers**: Validate & extract operator info - **Bank Cards**: Validate & identify bank names - **IBAN/Sheba**: Validate Iranian bank account numbers ### 🌍 Geographic & Location - **Place Lookup**: Find city/province by national ID - **Capital Cities**: Get province capitals - **Coordinates**: Find province from GPS coordinates - **Vehicle Plates**: Parse Iranian license plates ### 💰 Financial & Utilities - **Bill Calculator**: Parse Iranian utility bills - **Bank Detection**: Identify banks from card numbers - **IBAN Tools**: Complete Iranian banking support ### 📝 Text Processing - **Persian Validation**: Detect pure Persian text - **Character Cleanup**: Remove Arabic chars from Persian - **URL Fixing**: Decode Persian URLs - **Half-Space**: Fix Persian typography - **Time Utilities**: Persian time-ago & remaining time - **Slugify**: Generate URL-safe slugs from Persian text - **Text Analysis**: Comprehensive Persian text analysis --- ## 🚀 Quick Start ### 📦 Installation ```bash # npm npm install @persian-tools/persian-tools # yarn yarn add @persian-tools/persian-tools # pnpm pnpm add @persian-tools/persian-tools ``` ### 💻 Usage **ES Modules (Recommended)** ```typescript import { numberToWords, digitsEnToFa, verifyIranianNationalId } from '@persian-tools/persian-tools'; numberToWords(1234); // "یک هزار و دویست و سی و چهار" digitsEnToFa("123"); // "۱۲۳" verifyIranianNationalId("0499370899"); // true ``` **CommonJS** ```javascript const { numberToWords } = require('@persian-tools/persian-tools'); ``` **Browser CDN** ```html ``` --- ## 📖 API Reference ### 🔢 Number Conversion

numberToWords - Convert numbers to Persian words

```typescript import { numberToWords } from '@persian-tools/persian-tools'; // Basic usage numberToWords(1234); // "یک هزار و دویست و سی و چهار" numberToWords("12,345"); // "دوازده هزار و سیصد و چهل و پنج" // Ordinal numbers numberToWords(3, { ordinal: true }); // "سوم" numberToWords(21, { ordinal: true }); // "بیست و یکم" // Supports up to MAX_SAFE_INTEGER (2^53 - 1) numberToWords(9007199254740991); // Works perfectly! ```

wordsToNumber - Convert Persian words to numbers

```typescript import { wordsToNumber } from '@persian-tools/persian-tools'; // Basic conversion wordsToNumber("سه هزار دویست و دوازده"); // 3212 wordsToNumber("منفی یک میلیون"); // -1000000 // Advanced options wordsToNumber("دوازده هزار", { digits: "fa", // Return Persian digits: "۱۲۰۰۰" addCommas: true // Add commas: "12,000" }); // Fuzzy matching (fixes typos) wordsToNumber("یگصد و بنجاه هزار", { fuzzy: true }); // 150000 ```

### 🏛️ Validation

National ID Validation - Validate Iranian national codes

```typescript import { verifyIranianNationalId, getPlaceByIranNationalId, createIranianNationalId } from '@persian-tools/persian-tools'; // Validation verifyIranianNationalId("0499370899"); // true verifyIranianNationalId("1234567890"); // false // Location lookup getPlaceByIranNationalId("0084575948"); // { city: "تهران مرکزی", province: "تهران" } // Generation createIranianNationalId(); // "0499370899" createIranianNationalId({ preventRepeatedDigits: true }); // "1234567890" ```

National ID Generation - Generate valid Iranian national codes

```typescript import { createIranianNationalId, createIranianNationalIdDetailed, validateNationalIdChecksum } from '@persian-tools/persian-tools'; // Basic generation createIranianNationalId(); // "0499370899" // Generate without repeated digits createIranianNationalId({ preventRepeatedDigits: true }); // "1234567890" // Detailed generation with metadata const result = createIranianNationalIdDetailed({ preventRepeatedDigits: true, maxRetries: 50 }); console.log(result.nationalId); // "1234567890" console.log(result.checkDigit); // 0 console.log(result.attempts); // 1 console.log(result.hasRepeatedDigits); // false console.log(result.digits); // [1, 2, 3, 4, 5, 6, 7, 8, 9, 0] // Validate generated IDs validateNationalIdChecksum(result.nationalId); // true // Custom random generator (for testing) createIranianNationalId({ randomGenerator: () => 0.5 // Always returns 0.5 }); ```

Phone Number Validation - Iranian mobile numbers

```typescript import { isPhoneNumberValid, phoneNumberDetail } from '@persian-tools/persian-tools'; // Validation isPhoneNumberValid("09123456789"); // true isPhoneNumberValid("+989123456789"); // true // Operator detection phoneNumberDetail("09123456789"); // { // province: ["البرز", "تهران", ...], // operator: "همراه اول", // type: ["permanent"] // } ```

### 💰 Banking & Finance

Bank Card Validation - Validate and identify Iranian bank cards

```typescript import { verifyCardNumber, getBankNameFromCardNumber } from '@persian-tools/persian-tools'; // Card validation verifyCardNumber("6037701689095443"); // true // Bank identification getBankNameFromCardNumber("6219861034529007"); // "بانک سامان" ```

IBAN/Sheba Validation - Iranian bank account validation

```typescript import { isShebaValid, getShebaInfo } from '@persian-tools/persian-tools'; // IBAN validation isShebaValid("IR820540102680020817909002"); // true // Bank info extraction getShebaInfo("IR820540102680020817909002"); // { // nickname: "parsian", // name: "Parsian Bank", // persianName: "بانک پارسیان", // accountNumber: "020817909002" // } ```

### 📝 Text Processing

Persian Text Validation - Validate and clean Persian text

```typescript import { isPersian, hasPersian, toPersianChars } from '@persian-tools/persian-tools'; // Persian detection isPersian("سلام دنیا"); // true isPersian("Hello World"); // false hasPersian("This has فارسی text"); // true // Character cleanup toPersianChars("علي"); // "علی" (fixes Arabic chars) ```

Digit Conversion - Convert between number systems

```typescript import { digitsEnToFa, digitsFaToEn, digitsArToFa } from '@persian-tools/persian-tools'; // English to Persian digitsEnToFa("123456"); // "۱۲۳۴۵۶" // Persian to English digitsFaToEn("۱۲۳۴۵۶"); // "123456" // Arabic to Persian digitsArToFa("٧٨٩"); // "۷۸۹" ```

### 🌍 Geographic & Utilities

Vehicle Plates - Parse Iranian license plates

```typescript import { getNumberPlateInfo } from '@persian-tools/persian-tools'; // Car plates getNumberPlateInfo("12D45147").info; // { // template: "12 D 451 ایران 47", // province: "مرکزی", // type: "Car", // category: "دیپلمات" // } // Motorcycle plates getNumberPlateInfo(12345678).info; // { // template: "123-45678", // province: "مرکز تهران", // type: "Motorcycle" // } ```

Time Utilities - Persian time formatting

```typescript import { timeAgo, remainingTime } from '@persian-tools/persian-tools'; // Time ago (Jalali calendar) timeAgo("1400/03/17 17:55:00"); // "5 دقیقه قبل" // Remaining time remainingTime("2025-12-31T23:59:59Z").toString(); // "۱ سال و ۲ ماه و ۱۵ روز" ```

Slugify - Generate URL-safe slugs from Persian text

```typescript import { slugify, createSlug, slugifySimple } from '@persian-tools/persian-tools'; // Basic usage slugify("سلام دنیا"); // "سلام-دنیا" slugify("چگونه برنامه‌نویسی یاد بگیریم؟"); // "چگونه-برنامه-نویسی-یاد-بگیریم" // Custom options slugify("سلام دنیا", { separator: "_", // Use underscore instead of dash maxLength: 20, // Limit length lowercase: false // Don't convert to lowercase }); // "سلام_دنیا" // Preserve numbers slugify("سال ۱۴۰۰", { preserveNumbers: true }); // "سال-۱۴۰۰" // Helper functions createSlug("مقاله جدید"); // "مقاله-جدید" slugifySimple("تست ساده"); // "تست-ساده" ```

Text Analysis - Comprehensive Persian text analysis

```typescript import { analyzeText, getTextSummary, getTextComplexity, cleanText } from '@persian-tools/persian-tools'; // Full analysis const analysis = analyzeText("این یک متن فارسی است."); // { // statistics: { // totalWords: 5, // totalCharacters: 20, // persianCharacters: 15, // // ... more stats // }, // language: { // primaryLanguage: "persian", // confidence: 95, // isPurePersian: true // }, // readability: { // complexity: "ساده", // readingTime: 1, // averageWordsPerSentence: 5 // }, // suggestions: [...] // } // Quick helpers getTextSummary("سلام دنیا"); // "متن شامل 2 کلمه در 1 جمله است. زبان اصلی: فارسی (100% اطمینان). زمان مطالعه تقریبی: 1 دقیقه." getTextComplexity("این جمله ساده است"); // "ساده" // Text cleaning cleanText("سَلامٌ 123 دنیا"); // "سلام ۱۲۳ دنیا" ```

--- ## 🏗️ Development ### Prerequisites - **Node.js** ≥ 14 - **pnpm** ≥ 9 (recommended package manager) ### Setup ```bash git clone https://github.com/persian-tools/persian-tools.git cd persian-tools pnpm install ``` ### Scripts ```bash pnpm build # Build the library pnpm test # Run tests pnpm test:watch # Watch mode testing pnpm lint # Lint code pnpm lint:fix # Fix linting issues ``` ### Architecture - **TypeScript**: Full type safety with strict mode - **Build**: Unbuild (dual ESM/CJS output) - **Testing**: Vitest with comprehensive coverage - **Quality**: ESLint + Prettier + Husky hooks --- ## 🌟 Who's Using Persian Tools?

_{Pooleno Exchange}

Bank Maskan

_{Bank Maskan PWA}

MyDong

Melkba

*Using Persian Tools in your project? [Add it here!](https://github.com/persian-tools/persian-tools/edit/master/README.md)* --- ## 🤝 Contributing We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details. ### Quick Contribution Steps: 1. **Fork & Clone** the repository 2. **Create** a feature branch: `git checkout -b my-feature` 3. **Make** your changes with tests 4. **Run** `pnpm test` and `pnpm lint` 5. **Commit** with conventional commits 6. **Submit** a pull request --- ## 👨‍💻 Contributors Thanks to these amazing people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

_{Ali Torki} 🚇 ⚠️ 💻	_mssoheil ⚠️ 💻	_Mohsen ⚠️ 💻	_{Hesam pourghazian} 💻	_{Amir Hossien Qasemi Moqaddam} 💻	_{SeyyedKhandon} 💻	_msdDaliriyan 💻 ⚠️
_Mahdi 💻 ⚠️ 📖	_PS-PARSA ⚠️ 💻 🤔	_{Amirhossein Douzandeh Zenoozi} 💻 ⚠️ 🤔	_M0rteza-M 💻 ⚠️	_mediv0 💻 ⚠️ 🤔	_{Poorshad Shaddel} 💻 ⚠️ 🤔	_{Seyed Masih Sajadi} 💻 ⚠️
_{Mohammad Ghonchesefidi} 💻 ⚠️	_{Saeed Hasani Borzadaran} 💻 ⚠️	_{Ali Madihi} 💻	_Amir 📖	_{Kaveh Karami} 💻	_{Mehdi Shah abbasian} 📖
_{amirali yavari} 💻	_{Taha Namdar} 💻	_{Alireza Sariri} 💻	_{Sajad Sohrabi} 💻	_{Pouriya Babaali} 💻	_{Mohammad norouzi} 💻	_{Mohamad Amin Mirzaei} 💻
_{Moein Moeinnia} 💻	_{Mostafa Ahangarha} 💻

*This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification.* --- ## 📄 License **MIT License** - see [LICENSE](./LICENSE) for details. ---

Made with ❤️ by the Persian developer community

⭐ Star us on GitHub • 🐦 Share on Twitter