number-to-words-converter

A simple and lightweight utility to convert numbers to their word representations in English and Persian (Farsi), and vice versa. Also supports conversion between English and Persian numerals.

Installation

npm install @mahmud002/number-to-words-converter

Usage

English Number Conversion

import {
  numberToWords,
  wordsToNumber,
  stringToNumber,
  numberToString,
} from '@mahmud002/number-to-words-converter'

// Number to words
console.log(numberToWords(2)) // "two"
console.log(numberToWords(42)) // "forty-two"
console.log(numberToWords(112)) // "one hundred and twelve"
console.log(numberToWords(1234)) // "one thousand two hundred and thirty-four"
console.log(numberToWords(-5)) // "negative five"

// Words to number
console.log(wordsToNumber('two')) // 2
console.log(wordsToNumber('forty-two')) // 42
console.log(wordsToNumber('one hundred and twelve')) // 112
console.log(wordsToNumber('one thousand two hundred thirty-four')) // 1234
console.log(wordsToNumber('negative five')) // -5

Persian (Farsi) Number Conversion

import {
  numberToPersianWords,
  persianWordsToNumber,
  numberToPersianNumerals,
  persianNumeralsToNumber,
} from '@mahmud002/number-to-words-converter'

// Number to Persian words
console.log(numberToPersianWords(2)) // "دو"
console.log(numberToPersianWords(42)) // "چهل و دو"
console.log(numberToPersianWords(345)) // "سیصد و چهل و پنج"

// Persian words to number
console.log(persianWordsToNumber('دو')) // 2
console.log(persianWordsToNumber('چهل و دو')) // 42
console.log(persianWordsToNumber('سیصد و چهل و پنج')) // 345

// Number to Persian numerals
console.log(numberToPersianNumerals(220)) // "۲۲۰"
console.log(numberToPersianNumerals(1234)) // "۱۲۳۴"
console.log(numberToPersianNumerals(-567)) // "-۵۶۷"

// Persian numerals to number
console.log(persianNumeralsToNumber('۲۲۰')) // 220
console.log(persianNumeralsToNumber('۱۲۳۴')) // 1234
console.log(persianNumeralsToNumber('۱2۳')) // 123 (mixed numerals)

Universal String-to-Number Conversion

The stringToNumber function can handle various input formats:

import { stringToNumber } from '@mahmud002/number-to-words-converter'

// Regular numbers
console.log(stringToNumber('123')) // 123
console.log(stringToNumber('-456')) // -456

// English words
console.log(stringToNumber('one hundred twenty-three')) // 123
console.log(stringToNumber('negative four hundred fifty-six')) // -456

// Persian words
console.log(stringToNumber('صد و بیست و سه')) // 123
console.log(stringToNumber('منفی چهارصد و پنجاه و شش')) // -456

// Persian numerals
console.log(stringToNumber('۱۲۳')) // 123
console.log(stringToNumber('۴۵۶')) // 456

Flexible Number-to-String Conversion

The numberToString function can convert numbers to either English or Persian words:

import { numberToString } from '@mahmud002/number-to-words-converter'

// Convert to English (default)
console.log(numberToString(123)) // "one hundred and twenty-three"
console.log(numberToString(456, 'english')) // "four hundred and fifty-six"

// Convert to Persian
console.log(numberToString(123, 'persian')) // "صد و بیست و سه"
console.log(numberToString(456, 'persian')) // "چهارصد و پنجاه و شش"

Features

• Converts numbers to English and Persian words
• Converts English and Persian words back to numbers
• Converts numbers to Persian numerals (۰۱۲۳...)
• Converts Persian numerals back to numbers
• Handles numbers from -999,999,999,999,999 to 999,999,999,999,999
• Properly formats numbers with appropriate conjunctions ("and" in English, "و" in Persian)
• Supports negative numbers
• Accepts both English and Persian numerals
• Written in TypeScript with full type definitions
• Zero dependencies
• Comprehensive test coverage

API

numberToWords(num: number): string

Converts a number to its English word representation.

numberToPersianWords(input: string | number): string

Converts a number to its Persian word representation.

wordsToNumber(words: string): number

Converts English words to a number.

persianWordsToNumber(words: string): number

Converts Persian words to a number.

numberToPersianNumerals(num: number): string

Converts a number to Persian numerals (e.g., 220 → "۲۲۰").

persianNumeralsToNumber(persianNumerals: string): number

Converts Persian numerals to a number (e.g., "۲۲۰" → 220).

stringToNumber(input: string): number

Universal converter that handles various input formats (numbers, English words, Persian words, Persian numerals).

numberToString(num: number, format: 'english' | 'persian' = 'english'): string

Converts a number to its word representation in the specified language.

License

MIT