نسخه فارسی

Smart-Persian-Tools

A modern TypeScript utility library for Iranian applications. Includes Persian digit tools, Iranian phone utilities, national code validation, currency helpers, and Jalali date utilities.

Built for:

• Frontend apps
• Backend services
• Admin panels
• Fintech products
• E-commerce systems
• CRM dashboards
• Persian/Farsi applications

Features

• ☀ Persian / Arabic / English digit conversion
• 📱 Iranian mobile & landline utilities
• 🔍 Iranian national code validation
• 💰 Rial / Toman formatting & conversion
• 📅 Jalali (Persian) date utilities
• 🔒 TypeScript support
• ⚡ Zero dependencies
• 🌍 Browser & Node.js compatible
• 🧪 Fully tested

Installation

npm install smart-persian-tools

yarn add smart-persian-tools

pnpm add smart-persian-tools

Quick Start

import {
  toPersianDigits,
  validateIranianPhoneNumber,
  validateIranianNationalCode,
  formatCurrency,
  formatJalaliDate,
} from 'smart-persian-tools';

console.log(toPersianDigits(123456));
// ۱۲۳۴۵۶

console.log(validateIranianPhoneNumber('09121234567'));
// true

console.log(validateIranianNationalCode('0010350829'));
// true

console.log(formatCurrency(1500000));
// ۱٬۵۰۰٬۰۰۰ تومان

console.log(formatJalaliDate(new Date()));
// ۱۴۰۵/۰۲/۲۹

Modules

Digits Utilities

Utilities for converting and detecting Persian, Arabic, and English digits.

Import

import {
  toPersianDigits,
  toEnglishDigits,
  containsPersianDigits,
  containsEnglishDigits,
  containsArabicDigits,
  arabicToPersianDigits,
  arabicToEnglishDigits,
  normalizeDigits,
  detectDigitType,
  removeDigits,
  extractDigits,
  isDigitsOnly,
  persianPadStart,
} from 'smart-persian-tools';

Examples

Convert English digits to Persian

toPersianDigits(123456);
// ۱۲۳۴۵۶

Convert Persian digits to English

toEnglishDigits('۱۲۳۴۵۶');
// 123456

Normalize mixed digits

normalizeDigits('۱۲٣45');
// 12345

Detect digit type

detectDigitType('۱۲۳');
// persian

detectDigitType('123');
// english

detectDigitType('١٢٣');
// arabic

detectDigitType('۱۲3');
// mixed

Extract digits

extractDigits('Phone: ۰۹۱۲۱۲۳۴۵۶۷');
// 09121234567

Persian pad start

persianPadStart(25, 4);
// ۰۰۲۵

Phone Utilities

Utilities for Iranian mobile and landline numbers.

Import

import {
  normalizeIranianPhoneNumber,
  validateIranianPhoneNumber,
  formatIranianPhoneNumber,
  getOperator,
  isLandline,
  isMobile,
  getPhoneType,
  getLandlineProvince,
  toInternationalFormat,
  toE164Format,
  getPhoneInfo,
  maskPhoneNumber,
  isSamePhoneNumber,
  extractPhoneNumbers,
} from 'smart-persian-tools';

Examples

Validate mobile number

validateIranianPhoneNumber('09121234567');
// true

Normalize phone number

normalizeIranianPhoneNumber('+989121234567');
// 09121234567

Format phone number

formatIranianPhoneNumber('09121234567');
// 0912-123-4567

Detect operator

getOperator('09121234567');
// Hamrah Aval

Convert to international format

toInternationalFormat('09121234567');
// +98 912 123 4567

Convert to E164 format

toE164Format('09121234567');
// +989121234567

Get phone info

getPhoneInfo('09121234567');

Returns:

{
  original: '09121234567',
  normalized: '09121234567',
  formatted: '0912-123-4567',
  isValid: true,
  type: 'mobile',
  operator: 'Hamrah Aval',
  prefix: '0912',
  province: null
}

Extract phone numbers from text

extractPhoneNumbers(`
Call me:
09121234567
or +989351112233
`);

Returns:

[
  '09121234567',
  '09351112233'
]

National Code Utilities

Iranian national code validation and formatting helpers.

Import

import {
  validateIranianNationalCode,
  maskNationalCode,
  formatNationalCode,
  normalizeNationalCode,
  getProvinceByNationalCode,
  toPersianNationalCode,
  isSameNationalCode,
  isRepeatedDigits,
  extractNationalCodes,
  getNationalCodeInfo,
} from 'smart-persian-tools';

Examples

Validate national code

validateIranianNationalCode('0010350829');
// true

Format national code

formatNationalCode('0010350829');
// 001-035-0829

Mask national code

maskNationalCode('0010350829');
// 001***0829

Normalize national code

normalizeNationalCode('۱۲۳۴۵۶۷۸۹');
// 0123456789

Convert to Persian digits

toPersianNationalCode('0010350829');
// ۰۰۱۰۳۵۰۸۲۹

Extract national codes from text

extractNationalCodes(`
codes:
0010350829
0084575948
`);

Get national code info

getNationalCodeInfo('0010350829');

Returns:

{
  code: '0010350829',
  isValid: true,
  formatted: '001-035-0829',
  masked: '001***0829',
  province: {
    name: 'Tehran'
  }
}

Currency Utilities

Rial and Toman helpers for Iranian applications.

Import

import {
  rialToToman,
  tomanToRial,
  formatCurrency,
  addCurrencySuffix,
  toHumanReadable,
  formatCurrencyHuman,
  parseCurrencyString,
  detectCurrency,
  convertCurrency,
  calculatePercent,
  withTax,
  withoutTax,
  applyDiscount,
  getCurrencyInfo,
} from 'smart-persian-tools';

Examples

Convert Rial to Toman

rialToToman(100000);
// 10000

Format currency

formatCurrency(1500000);
// ۱٬۵۰۰٬۰۰۰ تومان

Human readable currency

formatCurrencyHuman(2500000);
// ۲.۵ میلیون تومان

Parse currency string

parseCurrencyString('۱٬۵۰۰٬۰۰۰ تومان');
// 1500000

Detect currency type

detectCurrency('۵۰۰ هزار تومان');
// toman

Apply discount

applyDiscount(1000000, 20);

Returns:

{
  amount: 800000,
  saved: 200000
}

Get currency info

getCurrencyInfo(1500000);

Returns:

{
  amount: 1500000,
  currency: 'toman',
  formatted: '۱٬۵۰۰٬۰۰۰ تومان',
  humanReadable: '۱.۵ میلیون تومان',
  inRial: 15000000,
  inToman: 1500000
}

Jalali Date Utilities

Persian calendar and Jalali date helpers.

Import

import {
  getCurrentJalaliDate,
  getPersianWeekday,
  getPersianMonthName,
  formatJalaliDate,
  toJalaliDate,
  formatJalaliPattern,
  getJalaliSeason,
  isIranianWeekend,
  isIranianHoliday,
  getDaysInJalaliMonth,
  isJalaliLeapYear,
  getRelativeJalaliDate,
  getJalaliDateInfo,
  getJalaliMonthRange,
  jalaliDateDiff,
} from 'smart-persian-tools';

Examples

Get current Jalali date

getCurrentJalaliDate();
// ۱۴۰۵/۰۲/۲۹

Convert Gregorian to Jalali

toJalaliDate(new Date('2024-03-20'));

Returns:

{
  year: 1403,
  month: 1,
  day: 1
}

Format Jalali pattern

formatJalaliPattern(
  new Date(),
  'WD DD Month YYYY'
);

// دوشنبه ۲۹ اردیبهشت ۱۴۰۵

Detect season

getJalaliSeason(new Date());
// بهار

Check holiday

isIranianHoliday(new Date('2024-03-20'));
// true

Relative date

getRelativeJalaliDate(
  new Date(Date.now() + 86400000)
);

// فردا

Get Jalali date info

getJalaliDateInfo();

Returns:

{
  jalali: {
    year: 1405,
    month: 2,
    day: 29
  },
  formatted: '۱۴۰۵/۰۲/۲۹',
  monthName: 'اردیبهشت',
  weekday: 'دوشنبه',
  isHoliday: false,
  isWeekend: false,
  season: 'بهار'
}

TypeScript Support

Fully written in TypeScript with complete type definitions.

import type {
  Currency,
  CurrencyInfo,
  JalaliDate,
  JalaliDateInfo,
  PhoneInfo,
  PhoneOperator,
  PhoneType,
} from 'smart-persian-tools';

Environment Support

• Node.js
• Bun
• Deno
• Browser
• React
• Next.js
• Vue
• Nuxt
• React Native

Contributing

Contributions, issues, and feature requests are welcome.

git clone https://github.com/ArefOrumiehei/smart-persian-tools.git

npm install

npm run test

License

MIT © Aref Orumiehei