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