n2words 3.0.0 → 4.0.0

package/{lib/languages/ro.js → src/ro-RO.js}

@@ -1,7 +1,7 @@
 /**
- * Romanian language converter - Functional Implementation
+ * Romanian (Romania) language converter
  *
- * A performance-optimized number-to-words converter using precomputed lookup tables.
+ * CLDR: ro-RO | Romanian as used in Romania
  *
  * Key features:
  * - Gender agreement (unu/una, doi/două)
@@ -10,8 +10,10 @@
  * - Feminine units for thousands
  */
 
-import { parseNumericValue } from '../utils/parse-numeric.js'
-import { validateOptions } from '../utils/validate-options.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)
@@ -31,6 +33,20 @@ const ZERO = 'zero'
 const NEGATIVE = 'minus'
 const DECIMAL_SEP = 'virgulă'
 
+// Ordinal vocabulary (masculine forms)
+const ORDINAL_ONES = ['', 'primul', 'al doilea', 'al treilea', 'al patrulea', 'al cincilea', 'al șaselea', 'al șaptelea', 'al optulea', 'al nouălea']
+const ORDINAL_TEENS = ['al zecelea', 'al unsprezecelea', 'al doisprezecelea', 'al treisprezecelea', 'al paisprezecelea', 'al cincisprezecelea', 'al șaisprezecelea', 'al șaptesprezecelea', 'al optsprezecelea', 'al nouăsprezecelea']
+const ORDINAL_TENS = ['', '', 'al douăzecilea', 'al treizecilea', 'al patruzecilea', 'al cincizecilea', 'al șaizecilea', 'al șaptezecilea', 'al optzecilea', 'al nouăzecilea']
+const ORDINAL_HUNDRED = 'al sutălea'
+const ORDINAL_THOUSAND = 'al miilea'
+const ORDINAL_MILLION = 'al milionulea'
+
+// Currency (Romanian Leu)
+const LEU_SINGULAR = 'leu'
+const LEU_PLURAL = 'lei'
+const BAN_SINGULAR = 'ban'
+const BAN_PLURAL = 'bani'
+
 // Scale metadata: [singular, plural, article, feminine, needsDe]
 // - singular: form for 1
 // - plural: form for 2+
@@ -64,7 +80,7 @@ function spellUnder100 (n, feminine = false, masculineTeens = false) {
   if (n < 20) {
     return masculineTeens ? TEENS_MASC[n - 10] : TEENS[n - 10]
   }
-  const t = Math.floor(n / 10)
+  const t = Math.trunc(n / 10)
   const u = n % 10
   if (u === 0) {
     return TWENTIES[t]
@@ -80,7 +96,7 @@ function spellUnder1000 (n, feminine = false, masculineTeens = false) {
   if (n === 0) return ''
   if (n < 100) return spellUnder100(n, feminine, masculineTeens)
 
-  const h = Math.floor(n / 100)
+  const h = Math.trunc(n / 100)
   const r = n % 100
   const hundredWord = HUNDREDS[h]
 
@@ -126,16 +142,16 @@ function buildScalePhrase (segment, scaleIndex) {
  * @param {Object} options - Conversion options
  * @returns {string} Romanian words
  */
-function integerToWords (n, options = {}) {
+function integerToWords (n, gender) {
   if (n === 0n) return ZERO
 
   // Fast path: numbers < 1000
   if (n < 1000n) {
-    const feminine = options.gender === 'feminine'
+    const feminine = gender === 'feminine'
     return spellUnder1000(Number(n), feminine)
   }
 
-  return buildLargeNumberWords(n, options)
+  return buildLargeNumberWords(n, gender)
 }
 
 /**
@@ -146,7 +162,7 @@ function integerToWords (n, options = {}) {
  * @param {Object} options - Conversion options
  * @returns {string} Romanian words
  */
-function buildLargeNumberWords (n, options) {
+function buildLargeNumberWords (n, gender) {
   // Extract segments using BigInt division (faster than string slicing)
   // Segments stored least-significant first (index 0 = ones, 1 = thousands, etc.)
   const segmentValues = []
@@ -166,7 +182,7 @@ function buildLargeNumberWords (n, options) {
     let segmentWords
     if (i === 0) {
       // Units segment - use gender from options
-      const feminine = options.gender === 'feminine'
+      const feminine = gender === 'feminine'
       segmentWords = spellUnder1000(segment, feminine)
     } else {
       // Scale segment
@@ -227,13 +243,16 @@ function decimalPartToWords (decimalPart) {
  * @throws {Error} If value is not a valid number format
  *
  * @example
- * toWords(21)                        // 'douăzeci și unu'
- * toWords(1, { gender: 'feminine' }) // 'una'
- * toWords(1000)                      // 'o mie'
+ * toCardinal(21)                        // 'douăzeci și unu'
+ * toCardinal(1, { gender: 'feminine' }) // 'una'
+ * toCardinal(1000)                      // 'o mie'
  */
-function toWords (value, options) {
+function toCardinal (value, options) {
   options = validateOptions(options)
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
+
+  // Apply option defaults
+  const { gender = 'masculine' } = options
 
   let result = ''
 
@@ -241,7 +260,7 @@ function toWords (value, options) {
     result = NEGATIVE + ' '
   }
 
-  result += integerToWords(integerPart, options)
+  result += integerToWords(integerPart, gender)
 
   if (decimalPart) {
     result += ' ' + DECIMAL_SEP + ' ' + decimalPartToWords(decimalPart)
@@ -250,8 +269,183 @@ function toWords (value, options) {
   return result
 }
 
+// ============================================================================
+// Ordinal Functions
+// ============================================================================
+
+/**
+ * Builds ordinal for tens and ones (0-99).
+ *
+ * @param {number} n - Number 0-99
+ * @returns {string} Ordinal word
+ */
+function buildOrdinalTensOnes (n) {
+  if (n === 0) return ''
+  if (n < 10) return ORDINAL_ONES[n]
+  if (n < 20) return ORDINAL_TEENS[n - 10]
+
+  const ones = n % 10
+  const tens = Math.trunc(n / 10)
+
+  if (ones === 0) {
+    return ORDINAL_TENS[tens]
+  }
+  // Compound: cardinal tens + ordinal ones (only last is ordinal)
+  return TWENTIES[tens] + ' și ' + ORDINAL_ONES[ones]
+}
+
+/**
+ * Converts a non-negative integer to Romanian ordinal words.
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} Romanian ordinal words
+ */
+function integerToOrdinal (n) {
+  if (n === 0n) return ''
+  if (n === 1n) return ORDINAL_ONES[1]
+
+  // Numbers < 100
+  if (n < 100n) {
+    return buildOrdinalTensOnes(Number(n))
+  }
+
+  // Numbers < 1000
+  if (n < 1000n) {
+    const hundreds = Number(n / 100n)
+    const remainder = Number(n % 100n)
+
+    if (remainder === 0) {
+      return ORDINAL_HUNDRED
+    }
+    return HUNDREDS[hundreds] + ' ' + buildOrdinalTensOnes(remainder)
+  }
+
+  // Numbers < 1,000,000
+  if (n < 1_000_000n) {
+    const thousands = Number(n / 1000n)
+    const remainder = Number(n % 1000n)
+
+    if (remainder === 0) {
+      if (thousands === 1) {
+        return ORDINAL_THOUSAND
+      }
+      return buildScalePhrase(thousands, 1) + ' ' + ORDINAL_THOUSAND
+    }
+
+    // Cardinal thousands + ordinal remainder
+    let result
+    if (thousands === 1) {
+      result = 'o mie'
+    } else {
+      result = buildScalePhrase(thousands, 1)
+    }
+
+    if (remainder < 100) {
+      return result + ' ' + buildOrdinalTensOnes(remainder)
+    }
+
+    const remHundreds = Math.trunc(remainder / 100)
+    const remTensOnes = remainder % 100
+
+    if (remTensOnes === 0) {
+      return result + ' ' + ORDINAL_HUNDRED
+    }
+    return result + ' ' + HUNDREDS[remHundreds] + ' ' + buildOrdinalTensOnes(remTensOnes)
+  }
+
+  // Numbers >= 1,000,000
+  const millions = Number(n / 1_000_000n)
+  const remainder = n % 1_000_000n
+
+  if (remainder === 0n) {
+    if (millions === 1) {
+      return ORDINAL_MILLION
+    }
+    return buildScalePhrase(millions, 2) + ' ' + ORDINAL_MILLION
+  }
+
+  // Cardinal millions + ordinal remainder
+  let result
+  if (millions === 1) {
+    result = 'un milion'
+  } else {
+    result = buildScalePhrase(millions, 2)
+  }
+
+  return result + ' ' + integerToOrdinal(remainder)
+}
+
+/**
+ * Converts a numeric value to Romanian ordinal words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The ordinal in Romanian words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a positive integer
+ *
+ * @example
+ * toOrdinal(1)   // 'primul'
+ * toOrdinal(21)  // 'douăzeci și primul'
+ */
+function toOrdinal (value) {
+  const n = parseOrdinalValue(value)
+  return integerToOrdinal(n)
+}
+
+// ============================================================================
+// Currency Functions
+// ============================================================================
+
+/**
+ * Converts a numeric value to Romanian Leu currency words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The currency in Romanian words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCurrency(1)     // 'un leu'
+ * toCurrency(2.50)  // 'doi lei cincizeci de bani'
+ */
+function toCurrency (value) {
+  const { isNegative, dollars, cents } = parseCurrencyValue(value)
+
+  const parts = []
+
+  if (isNegative) {
+    parts.push(NEGATIVE)
+  }
+
+  // Lei (masculine)
+  if (dollars > 0n || cents === 0n) {
+    if (dollars === 1n) {
+      parts.push('un ' + LEU_SINGULAR)
+    } else {
+      const leuWord = integerToWords(dollars, 'masculine')
+      parts.push(leuWord + ' ' + LEU_PLURAL)
+    }
+  }
+
+  // Bani (masculine)
+  if (cents > 0n) {
+    const centNum = Number(cents)
+    if (centNum === 1) {
+      parts.push('un ' + BAN_SINGULAR)
+    } else if (centNum >= 20) {
+      const banWord = spellUnder100(centNum, false)
+      parts.push(banWord + ' de ' + BAN_PLURAL)
+    } else {
+      const banWord = spellUnder100(centNum, false)
+      parts.push(banWord + ' ' + BAN_PLURAL)
+    }
+  }
+
+  return parts.join(' ')
+}
+
 // ============================================================================
 // Public API
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/ru-RU.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Converts a numeric value to Russian words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @param {Object} [options] - Optional configuration
+ * @param {('masculine'|'feminine')} [options.gender='masculine'] - Grammatical gender
+ * @returns {string} The number in Russian words
+ */
+export function toCardinal(value: number | string | bigint, options?: {
+    gender?: "masculine" | "feminine" | undefined;
+}): string;
+/**
+ * Converts a numeric value to Russian ordinal words (masculine nominative).
+ *
+ * @param {number | string | bigint} value - The numeric value to convert (must be a positive integer)
+ * @returns {string} The number as ordinal words (e.g., "первый", "сорок второй")
+ * @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(2)    // 'второй'
+ * toOrdinal(3)    // 'третий'
+ * toOrdinal(21)   // 'двадцать первый'
+ * toOrdinal(42)   // 'сорок второй'
+ * toOrdinal(100)  // 'сотый'
+ * toOrdinal(101)  // 'сто первый'
+ * toOrdinal(1000) // 'тысячный'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Russian currency words (Russian Ruble).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @param {Object} [options] - Optional configuration
+ * @param {boolean} [options.and=true] - Use "и" between rubles and kopecks
+ * @returns {string} The amount in Russian 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)                    // 'сорок два рубля и пятьдесят копеек'
+ * toCurrency(1)                        // 'один рубль'
+ * toCurrency(0.99)                     // 'девяносто девять копеек'
+ * toCurrency(0.01)                     // 'одна копейка'
+ * toCurrency(42.50, { and: false })    // 'сорок два рубля пятьдесят копеек'
+ */
+export function toCurrency(value: number | string | bigint, options?: {
+    and?: boolean | undefined;
+}): string;