@mahmud002/number-to-words-converter/README.md

A simple utility to convert numbers to their word representations in English and Persian, and vice versa. Includes Persian numerals conversion.

# 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

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

## Usage

### English Number Conversion

```typescript
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

```typescript
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:

```typescript
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:

```typescript
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