n2words 1.24.0 → 3.0.0

package/lib/languages/ro.js

@@ -1,380 +1,257 @@
-import AbstractLanguage from '../classes/abstract-language.js'
-
-/**
- * @typedef {Object} RomanianOptions
- * @property {boolean} [feminine=false] Use feminine forms for numbers.
- */
-
 /**
- * Romanian language converter.
+ * Romanian language converter - Functional Implementation
  *
- * Converts numbers to Romanian words with full grammatical support:
- * - Gender agreement (masculine/feminine forms)
- * - Complex pluralization (singular/plural forms)
- * - "De" preposition insertion for groups >= 20
- * - Special feminine handling for thousands
- * - Proper case and agreement patterns
- *
- * Key Features:
- * - Gender-aware number forms (unu/una, doi/două, doisprezece/douăsprezece)
- * - Group-based algorithm:
- *   1. Split number into groups of 3 digits
- *   2. Convert each group using gender rules and special forms
- *   3. Insert "de" preposition for groups >= 20 (e.g., "douăzeci de mii")
- *   4. Append magnitude word with proper singular/plural form (mie/mii, milion/milioane)
- *   5. Join with spaces
- * - Special feminine units for thousands group
- * - Automatic "de" insertion rules (nouăsprezece mii vs douăzeci de mii)
- * - Proper singular/plural forms (mie/mii, milion/milioane)
- * - Support for very large numbers (up to decillions)
+ * A performance-optimized number-to-words converter using precomputed lookup tables.
  *
- * Features:
- * - Feminine units for thousands group
- * - Support for very large numbers (up to decillions)
+ * Key features:
+ * - Gender agreement (unu/una, doi/două)
+ * - "De" preposition insertion for groups >= 20
+ * - Complex scale word handling (mie/mii, milion/milioane)
+ * - Feminine units for thousands
  */
-export class Romanian extends AbstractLanguage {
-  negativeWord = 'minus'
-  decimalSeparatorWord = 'virgulă'
-  zeroWord = 'zero'
-
-  ones = {
-    1: 'unu',
-    2: 'doi',
-    3: 'trei',
-    4: 'patru',
-    5: 'cinci',
-    6: 'șase',
-    7: 'șapte',
-    8: 'opt',
-    9: 'nouă'
-  }
 
-  onesFeminine = {
-    1: 'una',
-    2: 'două',
-    3: 'trei',
-    4: 'patru',
-    5: 'cinci',
-    6: 'șase',
-    7: 'șapte',
-    8: 'opt',
-    9: 'nouă'
-  }
+import { parseNumericValue } from '../utils/parse-numeric.js'
+import { validateOptions } from '../utils/validate-options.js'
+
+// ============================================================================
+// Vocabulary (module-level constants)
+// ============================================================================
+
+const ONES_MASC = ['', 'unu', 'doi', 'trei', 'patru', 'cinci', 'șase', 'șapte', 'opt', 'nouă']
+const ONES_FEM = ['', 'una', 'două', 'trei', 'patru', 'cinci', 'șase', 'șapte', 'opt', 'nouă']
+
+const TEENS = ['zece', 'unsprezece', 'douăsprezece', 'treisprezece', 'paisprezece', 'cincisprezece', 'șaisprezece', 'șaptesprezece', 'optsprezece', 'nouăsprezece']
+const TEENS_MASC = ['zece', 'unsprezece', 'doisprezece', 'treisprezece', 'paisprezece', 'cincisprezece', 'șaisprezece', 'șaptesprezece', 'optsprezece', 'nouăsprezece']
+
+const TWENTIES = ['', '', 'douăzeci', 'treizeci', 'patruzeci', 'cincizeci', 'șaizeci', 'șaptezeci', 'optzeci', 'nouăzeci']
+
+const HUNDREDS = ['', 'o sută', 'două sute', 'trei sute', 'patru sute', 'cinci sute', 'șase sute', 'șapte sute', 'opt sute', 'nouă sute']
+
+const ZERO = 'zero'
+const NEGATIVE = 'minus'
+const DECIMAL_SEP = 'virgulă'
+
+// Scale metadata: [singular, plural, article, feminine, needsDe]
+// - singular: form for 1
+// - plural: form for 2+
+// - article: 'o' for feminine, 'un' for masculine
+// - feminine: whether units should be feminine
+// - needsDe: whether "de" is inserted for segment >= 20
+const SCALE_META = [
+  { singular: 'mie', plural: 'mii', article: 'o', feminine: true, needsDe: true },
+  { singular: 'milion', plural: 'milioane', article: 'un', feminine: false, needsDe: true },
+  { singular: 'miliard', plural: 'miliarde', article: 'un', feminine: false, needsDe: true },
+  { singular: 'trilion', plural: 'trilioane', article: 'un', feminine: false, needsDe: true },
+  { singular: 'cvadrilion', plural: 'cvadrilioane', article: 'un', feminine: false, needsDe: true },
+  { singular: 'cvintilion', plural: 'cvintilioane', article: 'un', feminine: false, needsDe: true },
+  { singular: 'sextilion', plural: 'sextilioane', article: 'un', feminine: false, needsDe: true },
+  { singular: 'septilion', plural: 'septilioane', article: 'un', feminine: false, needsDe: true },
+  { singular: 'octilion', plural: 'octilioane', article: 'un', feminine: false, needsDe: true }
+]
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
 
-  tens = {
-    0: 'zece',
-    1: 'unsprezece',
-    2: 'douăsprezece',
-    3: 'treisprezece',
-    4: 'paisprezece',
-    5: 'cincisprezece',
-    6: 'șaisprezece',
-    7: 'șaptesprezece',
-    8: 'optsprezece',
-    9: 'nouăsprezece'
+/**
+ * Spells number under 100.
+ */
+function spellUnder100 (n, feminine = false, masculineTeens = false) {
+  if (n === 0) return ''
+  if (n < 10) {
+    return feminine ? ONES_FEM[n] : ONES_MASC[n]
   }
-
-  tensMasculine = {
-    0: 'zece',
-    1: 'unsprezece',
-    2: 'doisprezece',
-    3: 'treisprezece',
-    4: 'paisprezece',
-    5: 'cincisprezece',
-    6: 'șaisprezece',
-    7: 'șaptesprezece',
-    8: 'optsprezece',
-    9: 'nouăsprezece'
+  if (n < 20) {
+    return masculineTeens ? TEENS_MASC[n - 10] : TEENS[n - 10]
   }
-
-  twenties = {
-    2: 'douăzeci',
-    3: 'treizeci',
-    4: 'patruzeci',
-    5: 'cincizeci',
-    6: 'șaizeci',
-    7: 'șaptezeci',
-    8: 'optzeci',
-    9: 'nouăzeci'
+  const t = Math.floor(n / 10)
+  const u = n % 10
+  if (u === 0) {
+    return TWENTIES[t]
   }
+  const onesWord = feminine ? ONES_FEM[u] : ONES_MASC[u]
+  return TWENTIES[t] + ' și ' + onesWord
+}
 
-  hundreds = {
-    1: 'o sută',
-    2: 'două sute',
-    3: 'trei sute',
-    4: 'patru sute',
-    5: 'cinci sute',
-    6: 'șase sute',
-    7: 'șapte sute',
-    8: 'opt sute',
-    9: 'nouă sute'
-  }
+/**
+ * Spells number under 1000.
+ */
+function spellUnder1000 (n, feminine = false, masculineTeens = false) {
+  if (n === 0) return ''
+  if (n < 100) return spellUnder100(n, feminine, masculineTeens)
 
-  /**
-   * Romanian big units.
-   * For each power group we keep: singular, plural, feminineUnits?, needsDe?
-   * - 10^3: mie/mii (feminine units in chunk; "de" for chunk >= 20)
-   * - 10^6: milion/milioane ("de" for chunk >= 20)
-   * - 10^9: miliard/miliarde ("de" for chunk >= 20)
-   */
-  thousands = {
-    1: { singular: 'mie', plural: 'mii', feminine: true, needsDe: true }, // 10^3
-    2: { singular: 'milion', plural: 'milioane', feminine: false, needsDe: true }, // 10^6
-    3: { singular: 'miliard', plural: 'miliarde', feminine: false, needsDe: true }, // 10^9
-    4: { singular: 'trilion', plural: 'trilioane', feminine: false, needsDe: true }, // 10^12
-    5: { singular: 'cvadrilion', plural: 'cvadrilioane', feminine: false, needsDe: true }, // 10^15
-    6: { singular: 'cvintilion', plural: 'cvintilioane', feminine: false, needsDe: true }, // 10^18
-    7: { singular: 'sextilion', plural: 'sextilioane', feminine: false, needsDe: true }, // 10^21
-    8: { singular: 'septilion', plural: 'septilioane', feminine: false, needsDe: true }, // 10^24
-    9: { singular: 'octilion', plural: 'octilioane', feminine: false, needsDe: true }, // 10^27
-    10: { singular: 'decilion', plural: 'decilioane', feminine: false, needsDe: true } // 10^33
-  }
+  const h = Math.floor(n / 100)
+  const r = n % 100
+  const hundredWord = HUNDREDS[h]
 
-  /**
-   * Initializes the Romanian converter with language-specific options.
-   *
-   * @param {RomanianOptions} [options={}] Configuration options.
-   */
-  constructor ({ feminine = false } = {}) {
-    super()
+  if (r === 0) return hundredWord
+  return hundredWord + ' ' + spellUnder100(r, feminine, masculineTeens)
+}
 
-    this.feminine = feminine
-  }
+/**
+ * Builds scale word with proper pluralization and "de" insertion.
+ * Romanian always uses feminine forms (două, not doi) when counting scale words.
+ */
+function buildScalePhrase (segment, scaleIndex) {
+  const meta = SCALE_META[scaleIndex - 1]
+  if (!meta) return spellUnder1000(segment, true)
 
-  /**
-   * Split numeric string into BigInt groups of size x from left to right.
-   * @param {string} n - The numeric string to split
-   * @param {number} x - The size of each group
-   * @returns {bigint[]} Array of BigInt groups
-   */
-  splitByX (n, x) {
-    const results = []
-    const l = n.length
-    let result
-
-    if (l > x) {
-      const start = l % x
-      if (start > 0) {
-        result = n.slice(0, start)
-        results.push(BigInt(result))
-      }
-      for (let index = start; index < l; index += x) {
-        result = n.slice(index, index + x)
-        results.push(BigInt(result))
-      }
-    } else {
-      results.push(BigInt(n))
-    }
-    return results
+  if (segment === 1) {
+    return meta.article + ' ' + meta.singular
   }
 
-  getDigits (value) {
-    const stringValue = value.toString().padStart(3, '0').slice(-3)
-    const a = [...stringValue].toReversed()
-    return a.map(BigInt)
+  // Special case: 21 with scale words uses feminine "una"
+  if (segment === 21 && meta.needsDe) {
+    return 'douăzeci și una de ' + meta.plural
   }
 
-  /**
-   * Romanian pluralization & "de" rule for big units.
-   * - 1 → singular with article ("o mie", "un milion", "un miliard", …)
-   * - otherwise → spell chunk + (optional "de") + plural
-   * "de" is inserted when chunk >= 20 (e.g., "douăzeci de mii/milioane/miliarde").
-   * @param {bigint} chunk - The chunk value
-   * @param {object} form - The form object with singular, plural, feminine, needsDe properties
-   * @returns {string} The pluralized form
-   */
-  romanianPluralize (chunk, form) {
-    const n = Number(chunk)
-
-    if (n === 1) {
-      // article differs for feminine "mie" (o mie) vs the rest (un milion/miliard…)
-      const article = form.feminine ? 'o' : 'un'
-      return `${article} ${form.singular}`
-    }
+  // Romanian always uses feminine when counting scale words (două milioane, not doi milioane)
+  const words = spellUnder1000(segment, true)
 
-    // For 21 with big units, use feminine "una" with plural nouns
-    if (n === 21 && form.needsDe) {
-      return `douăzeci și una de ${form.plural}`
-    }
+  // "de" after >= 20
+  const needsDe = meta.needsDe && segment >= 20
+  const separator = needsDe ? ' de ' : ' '
 
-    // spell the chunk itself (use feminine units for big numbers)
-    const words = this.spellUnder1000(n, true)
+  return words + separator + meta.plural
+}
 
-    // "de" after >= 20 (covers 20, 21, 100, 101, 999, etc.)
-    const needsDe = form.needsDe && n >= 20
-    const de = needsDe ? ' de ' : ' '
+// ============================================================================
+// Conversion Functions
+// ============================================================================
 
-    return `${words}${de}${form.plural}`
-  }
+/**
+ * Converts a non-negative integer to Romanian words.
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @param {Object} options - Conversion options
+ * @returns {string} Romanian words
+ */
+function integerToWords (n, options = {}) {
+  if (n === 0n) return ZERO
 
-  spellUnder100 (n, feminineUnits = false) {
-    if (n < 10) {
-      return (feminineUnits ? this.onesFeminine : this.ones)[n]
-    }
-    if (n < 20) {
-      return this.tens[n - 10]
-    }
-    const t = Math.floor(n / 10)
-    const u = n % 10
-    return u
-      ? `${this.twenties[t]} și ${(feminineUnits ? this.onesFeminine : this.ones)[u]}`
-      : this.twenties[t]
+  // Fast path: numbers < 1000
+  if (n < 1000n) {
+    const feminine = options.gender === 'feminine'
+    return spellUnder1000(Number(n), feminine)
   }
 
-  spellUnder1000 (n, feminineUnits = false) {
-    if (n < 100) return this.spellUnder100(n, feminineUnits)
-    const h = Math.floor(n / 100)
-    const r = n % 100
-    const hundredWords = this.hundreds[h]
-    if (!r) return hundredWords
-    // Standard readable form: "o sută unu" (for units) or "o sută cincizeci" (for tens)
-    const separator = ' '
-    return `${hundredWords}${separator}${this.spellUnder100(r, feminineUnits)}`
-  }
+  return buildLargeNumberWords(n, options)
+}
 
-  /**
-   * Override decimalDigitsToWords to use masculine forms for decimal places
-   * @param {string} decimal Decimal string to convert
-   * @returns {string} Value in written format
-   */
-  decimalDigitsToWords (decimal) {
-    const words = []
-
-    const chars = [...decimal]
-
-    // Loop through characters adding leading zeros to words array
-    let index = 0
-    while (index < chars.length && chars[index] === '0') {
-      words.push(this.zeroWord)
-      index++
-    }
+/**
+ * Builds words for numbers >= 1000.
+ * Uses BigInt division for faster segment extraction.
+ *
+ * @param {bigint} n - Number >= 1000
+ * @param {Object} options - Conversion options
+ * @returns {string} Romanian words
+ */
+function buildLargeNumberWords (n, options) {
+  // Extract segments using BigInt division (faster than string slicing)
+  // Segments stored least-significant first (index 0 = ones, 1 = thousands, etc.)
+  const segmentValues = []
+  let temp = n
+  while (temp > 0n) {
+    segmentValues.push(Number(temp % 1000n))
+    temp = temp / 1000n
+  }
 
-    // Prevent further processing if entire string was zeros
-    if (index === chars.length) {
-      return words
-    }
+  // Build result string directly (avoid regex cleanup)
+  let result = ''
 
-    // Convert and add remaining using masculine forms for decimal places
-    const decimalNumber = BigInt(decimal)
-    const masculineWords = this.toCardinalWithMasculine(decimalNumber)
-    return [...words, masculineWords]
-  }
+  for (let i = segmentValues.length - 1; i >= 0; i--) {
+    const segment = segmentValues[i]
+    if (segment === 0) continue
 
-  /**
-   * Convert number to cardinal form using masculine units
-   * @param {bigint} number Number to convert
-   * @returns {string} Value in written format
-   */
-  toCardinalWithMasculine (number) {
-    if (number === 0n) {
-      return this.zeroWord
+    let segmentWords
+    if (i === 0) {
+      // Units segment - use gender from options
+      const feminine = options.gender === 'feminine'
+      segmentWords = spellUnder1000(segment, feminine)
+    } else {
+      // Scale segment
+      segmentWords = buildScalePhrase(segment, i)
     }
 
-    const words = []
-    const chunks = this.splitByX(number.toString(), 3)
-    let index = chunks.length
-
-    for (const x of chunks) {
-      let onesMap = []
-      index = index - 1
-
-      if (x === 0n) continue
-
-      const [n1, n2, n3] = this.getDigits(x) // units, tens, hundreds (as BigInt)
-
-      // hundreds
-      if (n3 > 0n) {
-        words.push(this.hundreds[Number(n3)])
-      }
-
-      // tens & teens
-      if (n2 > 1n) {
-        words.push(this.twenties[Number(n2)])
-      }
-
-      if (n2 === 1n) {
-        words.push(this.tensMasculine[Number(n1)])
-      } else if (n1 > 0n) {
-        // Always use masculine units for decimal places
-        onesMap = this.ones
-
-        // if there is a twenty/treizeci/etc AND ones > 0 → add "și"
-        if (n2 > 1n) words.push('și')
-        words.push(onesMap[Number(n1)])
-      }
-
-      // big unit name (mie/mii, milion/milioane, …)
-      if (index > 0) {
-        const form = this.thousands[index]
-        if (form) {
-          words.push(this.romanianPluralize(x, form))
-        } else {
-          // For very large numbers beyond our defined units, just spell out the number
-          words.push(this.spellUnder1000(Number(x), false))
-        }
-      }
+    if (result && segmentWords) {
+      result += ' ' + segmentWords
+    } else if (segmentWords) {
+      result = segmentWords
     }
+  }
+
+  return result
+}
 
-    return words.join(' ').replaceAll(/\s+/g, ' ').trim()
+/**
+ * Converts decimal digits to Romanian words.
+ * Decimals always use masculine forms.
+ *
+ * @param {string} decimalPart - Decimal digits (without the point)
+ * @returns {string} Romanian words for decimal part
+ */
+function decimalPartToWords (decimalPart) {
+  let result = ''
+  let i = 0
+
+  // Handle leading zeros
+  while (i < decimalPart.length && decimalPart[i] === '0') {
+    if (result) result += ' '
+    result += ZERO
+    i++
   }
 
-  convertWholePart (number) {
-    if (number === 0n) {
-      return this.zeroWord
-    }
-    const words = []
-    const chunks = this.splitByX(number.toString(), 3)
-    let index = chunks.length
-    for (const x of chunks) {
-      let onesMap = []
-      index = index - 1
-      if (x === 0n) continue
-      const [n1, n2, n3] = this.getDigits(x) // units, tens, hundreds (as BigInt)
-      // hundreds (only for the last group, not for thousands)
-      if (n3 > 0n && index === 0) {
-        words.push(this.hundreds[Number(n3)])
-      }
-      // tens & teens (only for the last group, not for thousands)
-      if (index === 0) {
-        if (n2 > 1n) {
-          words.push(this.twenties[Number(n2)])
-        }
-        if (n2 === 1n) {
-          words.push(this.tens[Number(n1)])
-        } else if (n1 > 0n) {
-          // pick masculine/feminine units (only for the last group, not for thousands)
-          const feminineUnits = this.feminine && index === 0
-          onesMap = feminineUnits ? this.onesFeminine : this.ones
-          // if there is a twenty/treizeci/etc AND ones > 0 → add "și"
-          if (n2 > 1n) words.push('și')
-          words.push(onesMap[Number(n1)])
-        }
-      }
-      // big unit name (mie/mii, milion/milioane, …)
-      if (index > 0) {
-        const form = this.thousands[index]
-        if (form) {
-          words.push(this.romanianPluralize(x, form))
-        } else {
-          // For very large numbers beyond our defined units, just spell out the number
-          words.push(this.spellUnder1000(Number(x), true))
-        }
-      }
+  // Convert remainder as a single number (masculine, with masculine teens)
+  const remainder = decimalPart.slice(i)
+  if (remainder) {
+    if (result) result += ' '
+    const n = BigInt(remainder)
+    if (n < 1000n) {
+      result += spellUnder1000(Number(n), false, true)
+    } else {
+      result += integerToWords(n, { gender: 'masculine' })
     }
-    return words.join(' ').replaceAll(/\s+/g, ' ').trim()
   }
+
+  return result
 }
 
 /**
- * Converts a number to Romanian cardinal (written) form.
+ * Converts a numeric value to Romanian words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @param {Object} [options] - Conversion options
+ * @param {string} [options.gender='masculine'] - Gender for numbers
+ * @returns {string} The number in Romanian words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
  *
- * @param {number|string|bigint} value The number to convert.
- * @param {Object} [options={}] Configuration options.
- * @param {boolean} [options.feminine=false] Use feminine forms for numbers.
- * @returns {string} The number expressed in Romanian words.
- * @throws {TypeError} If value is NaN or invalid type.
- * @throws {Error} If value is an invalid number string.
+ * @example
+ * toWords(21)                        // 'douăzeci și unu'
+ * toWords(1, { gender: 'feminine' }) // 'una'
+ * toWords(1000)                      // 'o mie'
  */
-export default function convertToWords (value, options = {}) {
-  return new Romanian(options).convertToWords(value)
+function toWords (value, options) {
+  options = validateOptions(options)
+  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+
+  let result = ''
+
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  result += integerToWords(integerPart, options)
+
+  if (decimalPart) {
+    result += ' ' + DECIMAL_SEP + ' ' + decimalPartToWords(decimalPart)
+  }
+
+  return result
 }
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+export { toWords }

package/lib/languages/ru.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 toWords(value: number | string | bigint, options?: {
+    gender?: "masculine" | "feminine" | undefined;
+}): string;