italian-numbers

Converts numbers to Italian word representations and vice versa. Supports cardinal numbers, ordinal numbers, and Roman numerals.

Features

• Cardinal numbers (uno, due, tre...)
• Ordinal numbers with gender and plural support (primo/prima/primi/prime...)
• Italian words to numbers (reverse conversion)
• Roman numerals (Arabic to Roman and vice versa)
• Decimal support (cardinalConverter(10.45, { includeDecimals: true }) -> "dieci/45")
• Negative numbers (cardinalConverter(-34) -> "meno trentaquattro")
• Written in TypeScript with full type definitions included
• Ships as ESM, CJS, and IIFE (global: italianNumbers)

Installation

npm install italian-numbers

or

yarn add italian-numbers

Usage

import {
  cardinalConverter,
  ordinalConverter,
  italianConverter,
  romanConverter,
  arabicConverter,
} from 'italian-numbers';

// Cardinal numbers
cardinalConverter(1); // 'uno'
cardinalConverter(90); // 'novanta'
cardinalConverter(709); // 'settecentonove'

// Negative numbers
cardinalConverter(-34); // 'meno trentaquattro'

// Decimals
cardinalConverter(1000.05, { includeDecimals: true }); // 'mille/05'
cardinalConverter(9, { includeDecimals: true }); // 'nove/00'

// Ordinal numbers
ordinalConverter(1); // 'primo'
ordinalConverter(10); // 'decimo'
ordinalConverter(63); // 'sessantatreesimo'

// Ordinal — feminine
ordinalConverter(1, { female: true }); // 'prima'
ordinalConverter(15, { female: true }); // 'quindicesima'

// Ordinal — plural
ordinalConverter(1, { plural: true }); // 'primi'
ordinalConverter(18, { plural: true }); // 'diciottesimi'

// Ordinal — feminine plural
ordinalConverter(1, { plural: true, female: true }); // 'prime'
ordinalConverter(70, { plural: true, female: true }); // 'settantesime'

// Italian word to number
italianConverter('uno'); // 1
italianConverter('novantasette'); // 97
italianConverter('un milione tredicimila'); // 1013000
italianConverter('meno trentaquattro'); // -34
italianConverter('dieci/45'); // 10.45

// Ordinal word to number
italianConverter('zeresimo'); // 0
italianConverter('prima'); // 1
italianConverter('quattrocentotredicesime'); // 413
italianConverter('infinitesimi'); // Infinity

// Arabic to Roman
romanConverter(1); // 'I'
romanConverter(79); // 'LXXIX'
romanConverter(2317); // 'MMCCCXVII'

// Roman to Arabic
arabicConverter('MD'); // 1500
arabicConverter('CDXC'); // 490
arabicConverter('MCMXC'); // 1990

API Reference

cardinalConverter(number, options?)

Converts a number to its Italian cardinal word representation.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | number | number | — | The number to convert | | options.includeDecimals | boolean | false | Append decimals as /XX |

Returns: string

Range: -999999999999 to 999999999999, plus Infinity / -Infinity

Throws:

| Error | When | |-------|------| | not a number | Input is NaN | | greater than 999999999999 | Input exceeds upper bound | | lower than -999999999999 | Input exceeds lower bound |

ordinalConverter(number, options?)

Converts a number to its Italian ordinal word representation.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | number | number | — | The number to convert | | options.female | boolean | false | Feminine form | | options.plural | boolean | false | Plural form |

Returns: string

Range: 0 to 999999999999, plus Infinity

Throws:

| Error | When | |-------|------| | not a number | Input is NaN | | greater than 999999999999 | Input exceeds upper bound | | negative number not allowed | Input is negative |

italianConverter(word)

Converts an Italian word representation back to a number.

| Parameter | Type | Description | |-----------|------|-------------| | word | string | Italian word (cardinal, ordinal, or decimal format) |

Returns: number — Returns NaN for unrecognized input.

Handles cardinals ("ventuno" -> 21), ordinals in all forms ("prima" -> 1), decimals ("dieci/45" -> 10.45), negatives ("meno tre" -> -3), and infinity variants.

romanConverter(number)

Converts an Arabic number to a Roman numeral string.

| Parameter | Type | Description | |-----------|------|-------------| | number | number | The number to convert |

Returns: string

Range: 1 to 3999, plus Infinity ("infinitum")

Throws:

| Error | When | |-------|------| | not a number | Input is NaN | | greater than 3999 | Input exceeds upper bound | | lower than 1 | Input is less than 1 | | not an integer | Input is not a whole number |

arabicConverter(roman)

Converts a Roman numeral string to an Arabic number.

| Parameter | Type | Description | |-----------|------|-------------| | roman | string | Uppercase Roman numeral string |

Returns: number

Throws:

| Error | When | |-------|------| | invalid roman number | Input is not a valid Roman numeral |

Contributing

1. Fork the repository
2. Create your branch (git checkout -b feat/my-feature)
3. Install dependencies (yarn install)
4. Make your changes
5. Run lint and tests (yarn lint && yarn test)
6. Commit using conventional commits (feat:, fix:, docs:, etc.)
7. Open a Pull Request

License

MIT - Nicolo Zandarin