n2words 3.1.0 → 4.0.0

package/{lib/languages/hu.js → src/hu-HU.js}

@@ -1,7 +1,7 @@
 /**
- * Hungarian language converter - Functional Implementation
+ * Hungarian (Hungary) language converter
  *
- * Self-contained converter with agglutinative word formation.
+ * CLDR: hu-HU | Hungarian as used in Hungary
  *
  * Key features:
  * - Agglutinative structure (no spaces between compound parts)
@@ -10,7 +10,9 @@
  * - "két" instead of "kettő" in compound forms
  */
 
-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
@@ -71,6 +73,42 @@ const ZERO = 'nulla'
 const NEGATIVE = 'mínusz'
 const DECIMAL_SEP = 'egész'
 
+// ============================================================================
+// Ordinal Vocabulary
+// ============================================================================
+
+// Hungarian ordinals: special forms 1-10, then cardinal + -dik/-ik suffix
+// Vowel harmony determines -dik vs -ik
+const ORDINAL_SPECIAL = {
+  1: 'első',
+  2: 'második',
+  3: 'harmadik',
+  4: 'negyedik',
+  5: 'ötödik',
+  6: 'hatodik',
+  7: 'hetedik',
+  8: 'nyolcadik',
+  9: 'kilencedik',
+  10: 'tizedik',
+  20: 'huszadik',
+  30: 'harmincadik',
+  40: 'negyvenedik',
+  50: 'ötvenedik',
+  60: 'hatvanadik',
+  70: 'hetvenedik',
+  80: 'nyolcvanadik',
+  90: 'kilencvenedik',
+  100: 'századik',
+  1000: 'ezredik'
+}
+
+// ============================================================================
+// Currency Vocabulary (Hungarian Forint)
+// ============================================================================
+
+const FORINT = 'forint' // same singular and plural
+const FILLER = 'fillér' // subunit (rarely used, same singular and plural)
+
 // ============================================================================
 // Conversion Functions
 // ============================================================================
@@ -191,8 +229,8 @@ function decimalPartToWords (decimalPart) {
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Hungarian words
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
 
@@ -209,8 +247,128 @@ function toWords (value) {
   return result
 }
 
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Hungarian ordinal words.
+ *
+ * Hungarian ordinals: első (1st), második (2nd), harmadik (3rd), etc.
+ * 1-10 have special forms, others use cardinal + -dik/-edik/-adik/-ödik suffix.
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Hungarian ordinal words
+ */
+function integerToOrdinal (n) {
+  const num = Number(n)
+
+  // Exact special forms
+  if (ORDINAL_SPECIAL[num]) {
+    return ORDINAL_SPECIAL[num]
+  }
+
+  // For compound numbers, get cardinal and add suffix
+  const cardinal = integerToWords(n)
+
+  // Determine suffix based on last vowel (vowel harmony)
+  // Back vowels (a,á,o,ó,u,ú) -> -adik
+  // Front unrounded (e,é,i,í) -> -edik
+  // Front rounded (ö,ő,ü,ű) -> -ödik
+  // If ends in consonant, add linking vowel + dik
+
+  const lastChar = cardinal[cardinal.length - 1]
+
+  // If ends in vowel, just add -dik
+  if ('aáoóuúeéiíöőüű'.includes(lastChar)) {
+    return cardinal + 'dik'
+  }
+
+  // If ends in consonant, find last vowel for harmony
+  const backVowels = 'aáoóuú'
+  const frontRoundedVowels = 'öőüű'
+
+  for (let i = cardinal.length - 1; i >= 0; i--) {
+    const char = cardinal[i]
+    if (backVowels.includes(char)) {
+      return cardinal + 'adik'
+    }
+    if (frontRoundedVowels.includes(char)) {
+      return cardinal + 'ödik'
+    }
+    if ('eéií'.includes(char)) {
+      return cardinal + 'edik'
+    }
+  }
+
+  // Default to -edik
+  return cardinal + 'edik'
+}
+
+/**
+ * Converts a numeric value to Hungarian 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)    // 'első'
+ * toOrdinal(2)    // 'második'
+ * toOrdinal(21)   // 'huszonegyedik'
+ */
+function toOrdinal (value) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value)
+// ============================================================================
+
+/**
+ * Converts a numeric value to Hungarian currency words (Hungarian Forint).
+ *
+ * Uses forint (no plural form needed in Hungarian).
+ * Fillér (1/100) is rarely used but included for completeness.
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Hungarian 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)     // 'negyvenkettő forint'
+ * toCurrency(1.50)   // 'egy forint ötven fillér'
+ * toCurrency(-5)     // 'mínusz öt forint'
+ */
+function toCurrency (value) {
+  const { isNegative, dollars: forint, cents: filler } = parseCurrencyValue(value)
+
+  let result = ''
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  // Forint part
+  if (forint > 0n || filler === 0n) {
+    result += integerToWords(forint) + ' ' + FORINT
+  }
+
+  // Fillér part
+  if (filler > 0n) {
+    if (forint > 0n) {
+      result += ' '
+    }
+    result += integerToWords(filler) + ' ' + FILLER
+  }
+
+  return result
+}
+
 // ============================================================================
 // Exports
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/id-ID.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Converts a numeric value to Indonesian words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Indonesian words
+ */
+export function toCardinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Indonesian 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)    // 'pertama'
+ * toOrdinal(2)    // 'kedua'
+ * toOrdinal(10)   // 'kesepuluh'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Indonesian currency words (Rupiah).
+ *
+ * Indonesian Rupiah has no subunit in modern usage (sen are historical).
+ * Amounts are rounded to whole rupiah.
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Indonesian 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)     // 'empat puluh dua rupiah'
+ * toCurrency(1000)   // 'seribu rupiah'
+ * toCurrency(-5)     // 'min lima rupiah'
+ */
+export function toCurrency(value: number | string | bigint): string;

package/{lib/languages/id.js → src/id-ID.js}

@@ -1,7 +1,7 @@
 /**
- * Indonesian language converter - Functional Implementation
+ * Indonesian (Indonesia) language converter
  *
- * Self-contained module with its own input validation, ready for subpath exports.
+ * CLDR: id-ID | Indonesian as used in Indonesia
  *
  * Key features:
  * - "Se-" prefix for 100 (seratus) and 1000 (seribu)
@@ -10,7 +10,9 @@
  * - Indonesian uses "satu juta" (not "sejuta") for millions+
  */
 
-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
@@ -28,6 +30,20 @@ const ZERO = 'nol'
 const NEGATIVE = 'min'
 const DECIMAL_SEP = 'koma'
 
+// ============================================================================
+// Ordinal Vocabulary
+// ============================================================================
+
+const ORDINAL_PREFIX = 'ke'
+// First is special: "pertama" (not "kesatu")
+const ORDINAL_FIRST = 'pertama'
+
+// ============================================================================
+// Currency Vocabulary (Indonesian Rupiah)
+// ============================================================================
+
+const RUPIAH = 'rupiah'
+
 // ============================================================================
 // Segment Building
 // ============================================================================
@@ -36,8 +52,8 @@ function buildSegment (n) {
   if (n === 0) return ''
 
   const onesDigit = n % 10
-  const tensDigit = Math.floor(n / 10) % 10
-  const hundredsDigit = Math.floor(n / 100)
+  const tensDigit = Math.trunc(n / 10) % 10
+  const hundredsDigit = Math.trunc(n / 100)
 
   const parts = []
 
@@ -171,8 +187,8 @@ function decimalPartToWords (decimalPart) {
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Indonesian words
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
 
@@ -189,8 +205,83 @@ function toWords (value) {
   return result
 }
 
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Indonesian ordinal words.
+ *
+ * Indonesian ordinals use "ke-" prefix + cardinal number.
+ * Special case: "pertama" for 1st (not "kesatu").
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Indonesian ordinal words
+ */
+function integerToOrdinal (n) {
+  // Special case: 1st is "pertama"
+  if (n === 1n) {
+    return ORDINAL_FIRST
+  }
+
+  // All others: "ke" + cardinal (no hyphen in Indonesian)
+  return ORDINAL_PREFIX + integerToWords(n)
+}
+
+/**
+ * Converts a numeric value to Indonesian 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)    // 'pertama'
+ * toOrdinal(2)    // 'kedua'
+ * toOrdinal(10)   // 'kesepuluh'
+ */
+function toOrdinal (value) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value)
+// ============================================================================
+
+/**
+ * Converts a numeric value to Indonesian currency words (Rupiah).
+ *
+ * Indonesian Rupiah has no subunit in modern usage (sen are historical).
+ * Amounts are rounded to whole rupiah.
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Indonesian 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)     // 'empat puluh dua rupiah'
+ * toCurrency(1000)   // 'seribu rupiah'
+ * toCurrency(-5)     // 'min lima rupiah'
+ */
+function toCurrency (value) {
+  const { isNegative, dollars: rupiah } = parseCurrencyValue(value)
+
+  let result = ''
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  result += integerToWords(rupiah)
+  result += ' ' + RUPIAH
+
+  return result
+}
+
 // ============================================================================
 // Exports
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/it-IT.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Converts a numeric value to Italian 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 Italian words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCardinal(28)           // 'ventotto'
+ * toCardinal(23)           // 'ventitré'
+ * toCardinal(1000)         // 'mille'
+ * toCardinal(2000)         // 'duemila'
+ * toCardinal(1000000)      // 'un milione'
+ */
+export function toCardinal(value: number | string | bigint): string;
+/**
+ * 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'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * 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'
+ */
+export function toCurrency(value: number | string | bigint, options?: {
+    and?: boolean | undefined;
+}): string;