az-number-to-words

Convert numbers and AZN money amounts into Azerbaijani words.

Useful for invoices, contracts, bank documents and anywhere you need the written form of an amount — for example 1250.50 → min iki yüz əlli manat əlli qəpik.

• No dependencies
• ESM and CommonJS
• TypeScript types included
• Works with number, string and bigint

Install

npm install az-number-to-words

Usage

import { numberToWords, manatToWords } from "az-number-to-words";

numberToWords(1250); // "min iki yüz əlli"
numberToWords(1_000_000); // "bir milyon"
numberToWords(-7); // "mənfi yeddi"

manatToWords(1250.5); // "min iki yüz əlli manat əlli qəpik"
manatToWords(0.99); // "doxsan doqquz qəpik"

API

numberToWords(value, options?)

Converts a whole number into words. It throws if you pass a decimal value — use manatToWords for amounts with qəpik.

| Option | Type | Default | Description | | ------------ | --------- | ------- | ----------------------------------------------------------------------------- | | capitalize | boolean | false | Makes the first letter uppercase using Azerbaijani rules, so i becomes İ. |

numberToWords(20, { capitalize: true }); // "İyirmi"

manatToWords(value, options?)

Converts a money amount into words with the units manat and qəpik.

| Option | Type | Default | Description | | ----------------- | --------- | ------- | --------------------------------------------------------------------------------------------- | | capitalize | boolean | false | Same as above. | | alwaysShowMinor | boolean | false | Always prints both parts, even when they are zero. Official documents often need this format. |

manatToWords(1250, { alwaysShowMinor: true });
// "min iki yüz əlli manat sıfır qəpik"

Language rules

The library follows normal Azerbaijani usage:

• 100 is yüz, not bir yüz
• 1000 is min, not bir min
• but 1000000 is bir milyon, because milyon and larger scales keep the bir

Empty groups are skipped, so 1_000_005 gives bir milyon beş.

Large numbers and precision

Floating point numbers lose precision above about 15 digits, and 0.1 + 0.2 problems are common with money. To stay safe, pass large or exact values as a string or a bigint:

numberToWords("1234567890123456"); // works
numberToWords(1234567890123456n); // works
manatToWords("1250.05"); // exact, no rounding surprise

The largest supported scale is kvadrilyon (1015).

Rounding

Amounts are rounded to two decimal places, based on the third digit. The manat part goes up when the qəpik part reaches 100:

manatToWords("10.994"); // "on manat doxsan doqquz qəpik"
manatToWords("10.995"); // "on bir manat"
manatToWords("0.999"); // "bir manat"

Errors

| Case | Error | | --------------------------------------------------------------- | ------------ | | NaN, Infinity, unsafe integer, exponential form like 1e21 | RangeError | | Decimal value passed to numberToWords | RangeError | | Number larger than kvadrilyon | RangeError | | Text that is not a number, such as "abc" | TypeError |

License

MIT