A comprehensive, high-performance TypeScript toolkit for Persian (Farsi) text, numbers, validation, and locale utilities — works in Node.js, Bun, and the browse
A comprehensive, high-performance TypeScript toolkit for Persian (Farsi) text, numbers, validation, and locale utilities — works in Node.js, Bun, and the browse
Persian Tools provides 27+ utilities for Persian language processing:
# npm
npm install @persian-tools/persian-tools
# yarn
yarn add @persian-tools/persian-tools
# pnpm
pnpm add @persian-tools/persian-tools
# bun (recommended)
bun add @persian-tools/persian-toolsES Modules (Recommended)
import { numberToWords, digitsEnToFa, verifyIranianNationalId } from '@persian-tools/persian-tools';
numberToWords(1234); // "یک هزار و دویست و سی و چهار"
digitsEnToFa("123"); // "۱۲۳"
verifyIranianNationalId("0499370899"); // trueCommonJS
const { numberToWords } = require('@persian-tools/persian-tools');Browser CDN
Persian Tools ships first-class Agent Skills — focused, retrievable instruction files that let Claude Code, Cursor, Copilot, and other AI coding assistants understand the library's modules, conventions, and Persian-language nuances without you having to paste context every time.
# Bun
bunx skills add @persian-tools/persian-tools
# npm
npx skills add @persian-tools/persian-tools
# pnpm
pnpm dlx skills add @persian-tools/persian-toolsEach command pulls the skills/ directory into your project's local skills folder so your AI agent retrieves them automatically when you ask about a Persian Tools utility.
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 }); // 150000National 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
…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"]
// }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"); // "بانک سامان"Extract Card Numbers - Advanced card extraction with performance optimization
…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"
// }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("٧٨٩"); // "۷۸۹"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
…Text Analysis - Comprehensive Persian text analysis
…git clone https://github.com/persian-tools/persian-tools.git
cd persian-tools
bun installbun run build # Build the library
bun run test # Run tests
bun run test:watch # Watch mode testing
bun run lint # Lint code
bun run format # Format code
bun run lint:fix # Fix linting issues Maani
Pooleno Exchange
Bank Maskan PWA
MyDong
MelkbaUsing Persian Tools in your project? Add it here!
This project is dedicated to the memory of @mediv0,
a valued contributor whose passion and work helped shape Persian Tools.
Your code lives on, and you will always be remembered in our community. ❤️
We welcome contributions! Please see our Contributing Guide for details.
git checkout -b my-featurebun run test and bun run lint and bun run format to ensure everything passesfeat: add new utility function)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
Hamid Nasr
Sina Bayandorian
MIT License - see LICENSE for details.
No open issues yet, or sync has not completed.