4.0.4 • Published 1 year ago

@persian-tools/persian-tools

Licence

MIT

Version

4.0.4

Deps

Size

973 kB

Vulns

Weekly

Stars

1.2K

Summary Dependency Versions

Persian Tools

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

GitHub contributors

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

# 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)

import { numberToWords, digitsEnToFa, verifyIranianNationalId } from '@persian-tools/persian-tools';

numberToWords(1234); // "یک هزار و دویست و سی و چهار"
digitsEnToFa("123"); // "۱۲۳"
verifyIranianNationalId("0499370899"); // true

CommonJS

const { numberToWords } = require('@persian-tools/persian-tools');

Browser CDN

<script src="https://cdn.jsdelivr.net/npm/@persian-tools/persian-tools/build/persian-tools.umd.js"></script>
<script>
  console.log(PersianTools.numberToWords(1234));
</script>

API Reference

Number Conversion

numberToWords - Convert numbers to Persian words

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

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

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

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

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

import { verifyCardNumber, getBankNameFromCardNumber } from '@persian-tools/persian-tools';

// Card validation
verifyCardNumber("6037701689095443"); // true

// Bank identification  
getBankNameFromCardNumber("6219861034529007"); // "بانک سامان"

IBAN/Sheba Validation - Iranian bank account validation

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

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

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

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

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

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

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

git clone https://github.com/persian-tools/persian-tools.git
cd persian-tools
pnpm install

Scripts

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 PWA}

_MyDong

_Melkba

Using Persian Tools in your project? Add it here!

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contribution Steps:

Fork & Clone the repository
Create a feature branch: git checkout -b my-feature
Make your changes with tests
Run pnpm test and pnpm lint
Commit with conventional commits
Submit a pull request

Contributors

Thanks to these amazing people (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}