n2words 3.1.0 → 4.0.0

package/{lib/languages/it.js → src/it-IT.js}

@@ -1,7 +1,7 @@
 /**
- * Italian language converter - Functional Implementation
+ * Italian (Italy) language converter
  *
- * Self-contained module with its own input validation, ready for subpath exports.
+ * CLDR: it-IT | Italian as used in Italy
  *
  * Italian-specific rules:
  * - Concatenation without spaces within segments ("ventotto" not "venti otto")
@@ -12,7 +12,10 @@
  * - "e" connector before simple final remainder
  */
 
-import { parseNumericValue } from '../utils/parse-numeric.js'
+import { parseCardinalValue } from './utils/parse-cardinal.js'
+import { parseCurrencyValue } from './utils/parse-currency.js'
+import { parseOrdinalValue } from './utils/parse-ordinal.js'
+import { validateOptions } from './utils/validate-options.js'
 
 // ============================================================================
 // Vocabulary (module-level constants)
@@ -39,6 +42,24 @@ const THOUSAND_PLURAL_SUFFIX = 'mila'
 // Scale word generation
 const SCALE_PREFIXES = ['m', 'b', 'tr', 'quadr', 'quint', 'sest', 'sett', 'ott', 'nov', 'dec']
 
+// ============================================================================
+// Ordinal Vocabulary
+// ============================================================================
+
+// Irregular ordinals 1-10 (masculine form)
+const ORDINAL_ONES = ['', 'primo', 'secondo', 'terzo', 'quarto', 'quinto', 'sesto', 'settimo', 'ottavo', 'nono', 'decimo']
+
+// Ordinal suffix for 11+
+const ORDINAL_SUFFIX = 'esimo'
+
+// ============================================================================
+// Currency Vocabulary (Euro)
+// ============================================================================
+
+const EURO = 'euro'
+const CENTESIMO = 'centesimo'
+const CENTESIMI = 'centesimi'
+
 // ============================================================================
 // Segment Building
 // ============================================================================
@@ -56,8 +77,8 @@ function buildSegment (n) {
   if (n === 0) return ''
 
   const ones = n % 10
-  const tens = Math.floor(n / 10) % 10
-  const hundreds = Math.floor(n / 100)
+  const tens = Math.trunc(n / 10) % 10
+  const hundreds = Math.trunc(n / 100)
 
   let result = ''
 
@@ -139,7 +160,7 @@ function buildThousands (n) {
  */
 function getScaleWordSingular (scaleIndex) {
   if (scaleIndex < 2) return ''
-  const prefixIndex = Math.floor((scaleIndex - 2) / 2)
+  const prefixIndex = Math.trunc((scaleIndex - 2) / 2)
   const isIardo = (scaleIndex - 2) % 2 === 1
   const prefix = SCALE_PREFIXES[prefixIndex]
   if (!prefix) return ''
@@ -152,7 +173,7 @@ function getScaleWordSingular (scaleIndex) {
  */
 function getScaleWordPlural (scaleIndex) {
   if (scaleIndex < 2) return ''
-  const prefixIndex = Math.floor((scaleIndex - 2) / 2)
+  const prefixIndex = Math.trunc((scaleIndex - 2) / 2)
   const isIardo = (scaleIndex - 2) % 2 === 1
   const prefix = SCALE_PREFIXES[prefixIndex]
   if (!prefix) return ''
@@ -311,14 +332,14 @@ function decimalPartToWords (decimalPart) {
  * @throws {Error} If value is not a valid number format
  *
  * @example
- * toWords(28)           // 'ventotto'
- * toWords(23)           // 'ventitré'
- * toWords(1000)         // 'mille'
- * toWords(2000)         // 'duemila'
- * toWords(1000000)      // 'un milione'
+ * toCardinal(28)           // 'ventotto'
+ * toCardinal(23)           // 'ventitré'
+ * toCardinal(1000)         // 'mille'
+ * toCardinal(2000)         // 'duemila'
+ * toCardinal(1000000)      // 'un milione'
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
 
@@ -335,8 +356,151 @@ function toWords (value) {
   return result
 }
 
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Converts a cardinal word to ordinal form by dropping final vowel and adding -esimo.
+ *
+ * @param {string} cardinalWord - Cardinal word to convert
+ * @returns {string} Ordinal form
+ */
+function cardinalToOrdinal (cardinalWord) {
+  // Handle accented 'é' at end (tré → tre + esimo = treesimo)
+  if (cardinalWord.endsWith('é')) {
+    return cardinalWord.slice(0, -1) + 'e' + ORDINAL_SUFFIX
+  }
+
+  // Handle "mila" ending (duemila → duemillesimo, not duemilesimo)
+  // The ordinal of thousand is "millesimo" (from mille), not "milesimo"
+  if (cardinalWord.endsWith('mila')) {
+    return cardinalWord.slice(0, -4) + 'mill' + ORDINAL_SUFFIX
+  }
+
+  // Handle "mille" ending (mille → millesimo)
+  if (cardinalWord.endsWith('mille')) {
+    return cardinalWord.slice(0, -1) + ORDINAL_SUFFIX
+  }
+
+  // Handle -ardo/-ardi endings (miliardo → miliardiesimo)
+  // These scale words get -iesimo not -esimo
+  if (cardinalWord.endsWith('ardo') || cardinalWord.endsWith('ardi')) {
+    return cardinalWord.slice(0, -1) + 'i' + ORDINAL_SUFFIX
+  }
+
+  // Drop final regular vowel before adding -esimo
+  const lastChar = cardinalWord.slice(-1)
+  if ('aeiouàèìòù'.includes(lastChar)) {
+    return cardinalWord.slice(0, -1) + ORDINAL_SUFFIX
+  }
+
+  // If doesn't end in vowel, just add suffix
+  return cardinalWord + ORDINAL_SUFFIX
+}
+
+/**
+ * Converts a positive integer to Italian ordinal words.
+ *
+ * @param {bigint} n - Positive integer
+ * @returns {string} Italian ordinal words (masculine form)
+ */
+function integerToOrdinal (n) {
+  // Special cases: 1-10 have irregular forms
+  if (n <= 10n) {
+    return ORDINAL_ONES[Number(n)]
+  }
+
+  // For 11+, convert cardinal and apply -esimo
+  const cardinalWord = integerToWords(n)
+  return cardinalToOrdinal(cardinalWord)
+}
+
+/**
+ * Converts a numeric value to Italian ordinal words.
+ *
+ * Italian ordinals: primo, secondo, terzo... (1-10 irregular)
+ * For 11+: cardinal word (drop final vowel) + -esimo
+ *
+ * @param {number | string | bigint} value - The numeric value to convert (positive integer)
+ * @returns {string} The number as ordinal words (masculine form)
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {RangeError} If value is negative, zero, or has a decimal part
+ *
+ * @example
+ * toOrdinal(1)    // 'primo'
+ * toOrdinal(2)    // 'secondo'
+ * toOrdinal(11)   // 'undicesimo'
+ * toOrdinal(21)   // 'ventunesimo'
+ * toOrdinal(100)  // 'centesimo'
+ * toOrdinal(1000) // 'millesimo'
+ */
+function toOrdinal (value) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value, options?)
+// ============================================================================
+
+/**
+ * Converts a numeric value to Italian currency words (Euro).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @param {Object} [options] - Optional configuration
+ * @param {boolean} [options.and=true] - Use "e" between euros and centesimi
+ * @returns {string} The amount in Italian currency words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCurrency(42.50)                 // 'quarantadue euro e cinquanta centesimi'
+ * toCurrency(1)                     // 'un euro'
+ * toCurrency(0.99)                  // 'novantanove centesimi'
+ * toCurrency(0.01)                  // 'un centesimo'
+ * toCurrency(42.50, { and: false }) // 'quarantadue euro cinquanta centesimi'
+ */
+function toCurrency (value, options) {
+  options = validateOptions(options)
+  const { isNegative, dollars: euros, cents: centesimi } = parseCurrencyValue(value)
+  const { and: useAnd = true } = options
+
+  // Build result
+  let result = ''
+  if (isNegative) result = NEGATIVE + ' '
+
+  // Euros part
+  if (euros > 0n || centesimi === 0n) {
+    // Use "un" for 1 euro instead of "uno"
+    if (euros === 1n) {
+      result += 'un'
+    } else {
+      result += integerToWords(euros)
+    }
+    // Euro is invariable (doesn't change for plural in Italian)
+    result += ' ' + EURO
+  }
+
+  // Centesimi part
+  if (centesimi > 0n) {
+    if (euros > 0n) {
+      result += useAnd ? ' e ' : ' '
+    }
+    // Use "un" for 1 centesimo instead of "uno"
+    if (centesimi === 1n) {
+      result += 'un'
+    } else {
+      result += integerToWords(centesimi)
+    }
+    result += ' ' + (centesimi === 1n ? CENTESIMO : CENTESIMI)
+  }
+
+  return result
+}
+
 // ============================================================================
 // Public API
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/ja-JP.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Converts a numeric value to Japanese words.
+ *
+ * This is the main public API. It accepts any valid numeric input
+ * (number, string, or bigint) and handles parsing internally.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Japanese kanji words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCardinal(42)           // '四十二'
+ * toCardinal(10000)        // '一万'
+ * toCardinal(100000000)    // '一億'
+ */
+export function toCardinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Japanese ordinal words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert (positive integer)
+ * @returns {string} The number as ordinal words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {RangeError} If value is negative, zero, or has a decimal part
+ *
+ * @example
+ * toOrdinal(1)    // '第一'
+ * toOrdinal(10)   // '第十'
+ * toOrdinal(100)  // '第百'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Japanese currency words (Yen).
+ *
+ * Note: Sen (銭, 1/100 yen) is included for completeness but is rarely used
+ * in modern Japan. Most transactions are in whole yen.
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Japanese currency words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCurrency(42)     // '四十二円'
+ * toCurrency(1)      // '一円'
+ * toCurrency(0.50)   // '五十銭'
+ * toCurrency(42.50)  // '四十二円五十銭'
+ */
+export function toCurrency(value: number | string | bigint): string;

package/{lib/languages/ja.js → src/ja-JP.js}

@@ -1,7 +1,7 @@
 /**
- * Japanese language converter - Functional Implementation
+ * Japanese (Japan) language converter
  *
- * Self-contained module with its own input validation, ready for subpath exports.
+ * CLDR: ja-JP | Japanese as used in Japan
  *
  * Japanese-specific rules:
  * - Myriad (万-based) grouping: 4 digits per segment instead of 3
@@ -10,7 +10,9 @@
  * - No spaces between characters
  */
 
-import { parseNumericValue } from '../utils/parse-numeric.js'
+import { parseCardinalValue } from './utils/parse-cardinal.js'
+import { parseCurrencyValue } from './utils/parse-currency.js'
+import { parseOrdinalValue } from './utils/parse-ordinal.js'
 
 // ============================================================================
 // Vocabulary (module-level constants)
@@ -45,6 +47,23 @@ const ZERO = '零'
 const NEGATIVE = 'マイナス'
 const DECIMAL_SEP = '点'
 
+// ============================================================================
+// Ordinal Vocabulary
+// ============================================================================
+
+// Ordinal prefix
+const ORDINAL_PREFIX = '第'
+
+// ============================================================================
+// Currency Vocabulary (Japanese Yen)
+// ============================================================================
+
+// Yen (main unit)
+const YEN = '円'
+
+// Sen (1/100 yen) - historically used, now rare
+const SEN = '銭'
+
 // Internal scale words (within 4-digit segments)
 const TEN = '十'
 const HUNDRED = '百'
@@ -62,9 +81,9 @@ function buildSegment (n) {
   if (n === 0) return ''
 
   const ones = n % 10
-  const tens = Math.floor(n / 10) % 10
-  const hundreds = Math.floor(n / 100) % 10
-  const thousands = Math.floor(n / 1000)
+  const tens = Math.trunc(n / 10) % 10
+  const hundreds = Math.trunc(n / 100) % 10
+  const thousands = Math.trunc(n / 1000)
 
   let result = ''
 
@@ -218,12 +237,12 @@ function decimalPartToWords (decimalPart) {
  * @throws {Error} If value is not a valid number format
  *
  * @example
- * toWords(42)           // '四十二'
- * toWords(10000)        // '一万'
- * toWords(100000000)    // '一億'
+ * toCardinal(42)           // '四十二'
+ * toCardinal(10000)        // '一万'
+ * toCardinal(100000000)    // '一億'
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
 
@@ -240,8 +259,88 @@ function toWords (value) {
   return result
 }
 
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Converts a positive integer to Japanese ordinal words.
+ *
+ * Japanese ordinals: 第 prefix + cardinal number.
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Japanese ordinal words
+ */
+function integerToOrdinal (n) {
+  return ORDINAL_PREFIX + integerToWords(n)
+}
+
+/**
+ * Converts a numeric value to Japanese ordinal words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert (positive integer)
+ * @returns {string} The number as ordinal words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {RangeError} If value is negative, zero, or has a decimal part
+ *
+ * @example
+ * toOrdinal(1)    // '第一'
+ * toOrdinal(10)   // '第十'
+ * toOrdinal(100)  // '第百'
+ */
+function toOrdinal (value) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value, options?)
+// ============================================================================
+
+/**
+ * Converts a numeric value to Japanese currency words (Yen).
+ *
+ * Note: Sen (銭, 1/100 yen) is included for completeness but is rarely used
+ * in modern Japan. Most transactions are in whole yen.
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Japanese currency words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCurrency(42)     // '四十二円'
+ * toCurrency(1)      // '一円'
+ * toCurrency(0.50)   // '五十銭'
+ * toCurrency(42.50)  // '四十二円五十銭'
+ */
+function toCurrency (value) {
+  const { isNegative, dollars: yen, cents: sen } = parseCurrencyValue(value)
+
+  // Build result
+  let result = ''
+  if (isNegative) result = NEGATIVE
+
+  // Yen part
+  if (yen > 0n) {
+    result += integerToWords(yen) + YEN
+  }
+
+  // Sen part (1/100 yen)
+  if (sen > 0n) {
+    result += integerToWords(sen) + SEN
+  }
+
+  // Handle zero case
+  if (yen === 0n && sen === 0n) {
+    result += ZERO + YEN
+  }
+
+  return result
+}
+
 // ============================================================================
 // Public API
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/ka-GE.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Converts a numeric value to Georgian words.
+ *
+ * This is the main public API. It accepts any valid numeric input
+ * (number, string, or bigint) and handles parsing internally.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Georgian words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCardinal(21)           // 'ოცდაერთი'
+ * toCardinal(100)          // 'ასი'
+ * toCardinal(1000)         // 'ათასი'
+ */
+export function toCardinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Georgian ordinal words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The ordinal in Georgian words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a positive integer
+ *
+ * @example
+ * toOrdinal(1)   // 'პირველი'
+ * toOrdinal(10)  // 'მეათე'
+ * toOrdinal(21)  // 'მეოცდაერთე'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Georgian Lari currency words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The currency in Georgian words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCurrency(1)     // 'ერთი ლარი'
+ * toCurrency(2.50)  // 'ორი ლარი ორმოცდაათი თეთრი'
+ */
+export function toCurrency(value: number | string | bigint): string;

package/{lib/languages/ka.js → src/ka-GE.js}

@@ -1,7 +1,7 @@
 /**
- * Georgian language converter - Functional Implementation
+ * Georgian (Georgia) language converter
  *
- * Self-contained module with its own input validation, ready for subpath exports.
+ * CLDR: ka-GE | Georgian as used in Georgia
  *
  * Georgian-specific rules:
  * - Vigesimal (base-20) system for 20-99
@@ -12,7 +12,9 @@
  * - Short scale for large numbers (მილიონი, მილიარდი, ტრილიონი)
  */
 
-import { parseNumericValue } from '../utils/parse-numeric.js'
+import { parseCardinalValue } from './utils/parse-cardinal.js'
+import { parseCurrencyValue } from './utils/parse-currency.js'
+import { parseOrdinalValue } from './utils/parse-ordinal.js'
 
 // ============================================================================
 // Vocabulary (module-level constants)
@@ -43,6 +45,16 @@ const ZERO = 'ნული'
 const NEGATIVE = 'მინუს'
 const DECIMAL_SEP = 'მთელი'
 
+// Ordinal suffix (Georgian adds -ე to form ordinals)
+const ORDINAL_SUFFIX = 'ე'
+
+// Ordinal forms for 1-9 (these are special)
+const ORDINAL_ONES = ['', 'პირველი', 'მეორე', 'მესამე', 'მეოთხე', 'მეხუთე', 'მეექვსე', 'მეშვიდე', 'მერვე', 'მეცხრე']
+
+// Currency (Georgian Lari)
+const LARI = 'ლარი'
+const TETRI = 'თეთრი'
+
 // ============================================================================
 // Segment Building
 // ============================================================================
@@ -56,7 +68,7 @@ function buildTens (n) {
   if (n < 10) return ONES[n]
   if (n < 20) return TEENS[n - 10]
 
-  const vigesimalGroup = Math.floor(n / 20)
+  const vigesimalGroup = Math.trunc(n / 20)
   const remainder = n % 20
 
   if (remainder === 0) {
@@ -87,7 +99,7 @@ function buildSegment (n) {
     return { full: word, stem }
   }
 
-  const hundreds = Math.floor(n / 100)
+  const hundreds = Math.trunc(n / 100)
   const remainder = n % 100
 
   // Build hundreds: ასი (100), ორასი (200), etc.
@@ -262,12 +274,12 @@ function decimalPartToWords (decimalPart) {
  * @throws {Error} If value is not a valid number format
  *
  * @example
- * toWords(21)           // 'ოცდაერთი'
- * toWords(100)          // 'ასი'
- * toWords(1000)         // 'ათასი'
+ * toCardinal(21)           // 'ოცდაერთი'
+ * toCardinal(100)          // 'ასი'
+ * toCardinal(1000)         // 'ათასი'
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
 
@@ -284,8 +296,98 @@ function toWords (value) {
   return result
 }
 
+// ============================================================================
+// Ordinal Functions
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Georgian ordinal words.
+ * Georgian ordinals are formed by:
+ * - 1-9: special forms (პირველი, მეორე, მესამე, etc.)
+ * - 10+: მე- prefix + cardinal + -ე suffix
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} Georgian ordinal words
+ */
+function integerToOrdinal (n) {
+  if (n === 0n) return ''
+  if (n <= 9n) return ORDINAL_ONES[Number(n)]
+
+  // For 10+, use მე- + cardinal stem + -ე
+  const cardinal = integerToWords(n)
+
+  // Remove final vowel and add -ე suffix
+  const lastChar = cardinal.slice(-1)
+  let stem
+  if (lastChar === 'ი' || lastChar === 'ა') {
+    stem = cardinal.slice(0, -1)
+  } else {
+    stem = cardinal
+  }
+
+  return 'მე' + stem + ORDINAL_SUFFIX
+}
+
+/**
+ * Converts a numeric value to Georgian ordinal words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The ordinal in Georgian words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a positive integer
+ *
+ * @example
+ * toOrdinal(1)   // 'პირველი'
+ * toOrdinal(10)  // 'მეათე'
+ * toOrdinal(21)  // 'მეოცდაერთე'
+ */
+function toOrdinal (value) {
+  const n = parseOrdinalValue(value)
+  return integerToOrdinal(n)
+}
+
+// ============================================================================
+// Currency Functions
+// ============================================================================
+
+/**
+ * Converts a numeric value to Georgian Lari currency words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The currency in Georgian words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCurrency(1)     // 'ერთი ლარი'
+ * toCurrency(2.50)  // 'ორი ლარი ორმოცდაათი თეთრი'
+ */
+function toCurrency (value) {
+  const { isNegative, dollars, cents } = parseCurrencyValue(value)
+
+  const parts = []
+
+  if (isNegative) {
+    parts.push(NEGATIVE)
+  }
+
+  // Lari
+  if (dollars > 0n || cents === 0n) {
+    const lariWord = integerToWords(dollars)
+    parts.push(lariWord + ' ' + LARI)
+  }
+
+  // Tetri
+  if (cents > 0n) {
+    const tetriWord = integerToWords(cents)
+    parts.push(tetriWord + ' ' + TETRI)
+  }
+
+  return parts.join(' ')
+}
+
 // ============================================================================
 // Public API
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }