to-arabic-numbers

Lightweight, zero-dependency utility to convert numbers between Western (English), Arabic-Indic, and Persian (Farsi) numeral systems.

أداة خفيفة الوزن، لا تعتمد على أي مكتبات خارجية، لتحويل الأرقام بين الأنظمة الغربية (الإنجليزية)، العربية-الهندية، والفارسية.

✨ Features / المميزات

• 🔄 Convert between Western ↔ Arabic-Indic ↔ Persian digits (تحويل متبادل بين الأرقام الإنجليزية ↔ العربية والهندية ↔ الفارسية)
• 🔍 Detect the presence of Arabic or Persian digits in a string (اكتشاف وجود أرقام عربية أو فارسية في النصوص)
• 🛡️ Safe input handling — null, undefined, and numbers are handled gracefully (معالجة آمنة للمدخلات)
• 📦 Zero dependencies (لا يعتمد على أي مكتبات خارجية)
• 📝 Full TypeScript support out of the box (دعم كامل لـ TypeScript)
• 🔀 Dual CommonJS / ESM module support (يدعم كلا من CommonJS و ESM)

📦 Installation / التثبيت

# npm
npm install to-arabic-numbers

# yarn
yarn add to-arabic-numbers

# pnpm
pnpm add to-arabic-numbers

🚀 Usage / الاستخدام

CommonJS

const {
  convertNumbers2English,
  convertNumbers2Arabic,
  convertNumbers2Persian,
  convertPersian2English,
  hasArabicNumbers,
  hasPersianNumbers,
} = require('to-arabic-numbers');

ES Modules

import {
  convertNumbers2English,
  convertNumbers2Arabic,
  convertNumbers2Persian,
  convertPersian2English,
  hasArabicNumbers,
  hasPersianNumbers,
} from 'to-arabic-numbers';

📖 API / الواجهة البرمجية

convertNumbers2English(input)

Converts Arabic-Indic (٠-٩) and Persian (۰-۹) digits to Western (0-9) digits.

convertNumbers2English('١٢٣');          // '123'
convertNumbers2English('۴۵۶');          // '456'
convertNumbers2English('١٢٣ abc ۴۵۶'); // '123 abc 456'

convertNumbers2Arabic(input)

Converts Western (0-9) digits to Arabic-Indic (٠-٩) digits.

convertNumbers2Arabic('123');           // '١٢٣'
convertNumbers2Arabic('item 1, item 2'); // 'item ١, item ٢'

convertNumbers2Persian(input)

Converts Western (0-9) digits to Persian/Farsi (۰-۹) digits.

convertNumbers2Persian('123');          // '۱۲۳'
convertNumbers2Persian('price: 100');   // 'price: ۱۰۰'

convertPersian2English(input)

Converts Persian (۰-۹) digits to Western (0-9) digits. Does not touch Arabic-Indic digits.

convertPersian2English('۱۲۳');          // '123'
convertPersian2English('٠١٢');          // '٠١٢' (unchanged — these are Arabic-Indic)

hasArabicNumbers(input)

Returns true if the string contains any Arabic-Indic digits.

hasArabicNumbers('hello ١٢٣');  // true
hasArabicNumbers('hello 123');  // false
hasArabicNumbers('hello ۱۲۳');  // false (these are Persian)

hasPersianNumbers(input)

Returns true if the string contains any Persian digits.

hasPersianNumbers('hello ۱۲۳');  // true
hasPersianNumbers('hello 123');  // false
hasPersianNumbers('hello ١٢٣');  // false (these are Arabic-Indic)

🛡️ Input Handling

All functions handle edge cases gracefully:

| Input | Behavior | |-------|----------| | string | Converted normally | | number | Auto-converted to string first | | null | Returns '' (empty string) | | undefined | Returns '' (empty string) |

🏗️ TypeScript

This package includes built-in type declarations. No need to install @types/to-arabic-numbers.

import { convertNumbers2Arabic } from 'to-arabic-numbers';

const result: string = convertNumbers2Arabic('123'); // '١٢٣'

🤝 Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

📄 License

MIT © Mohamed Nashaat