n2words 2.0.0 → 3.1.0

package/lib/languages/ro.js

@@ -1,273 +1,257 @@
-import { AbstractLanguage } from '../classes/abstract-language.js'
-
 /**
- * Romanian language converter.
+ * Romanian language converter - Functional Implementation
+ *
+ * A performance-optimized number-to-words converter using precomputed lookup tables.
  *
- * Supports:
+ * Key features:
  * - Gender agreement (unu/una, doi/două)
- * - Complex pluralization (singular/plural forms)
  * - "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'
-
-  onesWords = {
-    1: 'unu',
-    2: 'doi',
-    3: 'trei',
-    4: 'patru',
-    5: 'cinci',
-    6: 'șase',
-    7: 'șapte',
-    8: 'opt',
-    9: 'nouă'
-  }
 
-  onesFeminineWords = {
-    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'
 
-  teensWords = {
-    0: 'zece',
-    1: 'unsprezece',
-    2: 'douăsprezece',
-    3: 'treisprezece',
-    4: 'paisprezece',
-    5: 'cincisprezece',
-    6: 'șaisprezece',
-    7: 'șaptesprezece',
-    8: 'optsprezece',
-    9: 'nouăsprezece'
-  }
+// ============================================================================
+// Vocabulary (module-level constants)
+// ============================================================================
 
-  teensMasculineWords = {
-    0: 'zece',
-    1: 'unsprezece',
-    2: 'doisprezece',
-    3: 'treisprezece',
-    4: 'paisprezece',
-    5: 'cincisprezece',
-    6: 'șaisprezece',
-    7: 'șaptesprezece',
-    8: 'optsprezece',
-    9: 'nouăsprezece'
-  }
+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']
 
-  twentiesWords = {
-    2: 'douăzeci',
-    3: 'treizeci',
-    4: 'patruzeci',
-    5: 'cincizeci',
-    6: 'șaizeci',
-    7: 'șaptezeci',
-    8: 'optzeci',
-    9: 'nouăzeci'
+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
+// ============================================================================
+
+/**
+ * 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]
+  }
+  if (n < 20) {
+    return masculineTeens ? TEENS_MASC[n - 10] : TEENS[n - 10]
   }
+  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
+}
 
-  hundredsWords = {
-    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)
+
+  const h = Math.floor(n / 100)
+  const r = n % 100
+  const hundredWord = HUNDREDS[h]
+
+  if (r === 0) return hundredWord
+  return hundredWord + ' ' + spellUnder100(r, feminine, masculineTeens)
+}
+
+/**
+ * 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)
+
+  if (segment === 1) {
+    return meta.article + ' ' + meta.singular
   }
 
-  /**
-   * Romanian big units.
-   * For each power group we keep: singular, plural, feminineUnits?, needsDe?
-   * - 10^3: mie/mii (feminine units in segment; "de" for segment >= 20)
-   * - 10^6: milion/milioane ("de" for segment >= 20)
-   * - 10^9: miliard/miliarde ("de" for segment >= 20)
-   */
-  scaleMetadata = {
-    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
+  // Special case: 21 with scale words uses feminine "una"
+  if (segment === 21 && meta.needsDe) {
+    return 'douăzeci și una de ' + meta.plural
   }
 
-  constructor (options = {}) {
-    super()
+  // Romanian always uses feminine when counting scale words (două milioane, not doi milioane)
+  const words = spellUnder1000(segment, true)
 
-    this.setOptions({
-      gender: 'masculine'
-    }, options)
-  }
+  // "de" after >= 20
+  const needsDe = meta.needsDe && segment >= 20
+  const separator = needsDe ? ' de ' : ' '
 
-  /** Split numeric string into BigInt segments of specified size from left to right. */
-  splitToSegments (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
+  return words + separator + meta.plural
+}
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+/**
+ * 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
+
+  // Fast path: numbers < 1000
+  if (n < 1000n) {
+    const feminine = options.gender === 'feminine'
+    return spellUnder1000(Number(n), feminine)
   }
 
-  extractDigits (value) {
-    const stringValue = value.toString().padStart(3, '0').slice(-3)
-    const a = [...stringValue].toReversed()
-    return a.map(BigInt)
+  return buildLargeNumberWords(n, options)
+}
+
+/**
+ * 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
   }
 
-  /** Romanian pluralization & "de" rule for big units. */
-  romanianPluralize (segment, form) {
-    const n = Number(segment)
+  // Build result string directly (avoid regex cleanup)
+  let result = ''
 
-    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}`
+  for (let i = segmentValues.length - 1; i >= 0; i--) {
+    const segment = segmentValues[i]
+    if (segment === 0) continue
+
+    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)
     }
 
-    // For 21 with big units, use feminine "una" with plural nouns
-    if (n === 21 && form.needsDe) {
-      return `douăzeci și una de ${form.plural}`
+    if (result && segmentWords) {
+      result += ' ' + segmentWords
+    } else if (segmentWords) {
+      result = segmentWords
     }
+  }
 
-    // spell the segment itself (use feminine units for big numbers)
-    const words = this.spellUnder1000(n, true)
+  return result
+}
 
-    // "de" after >= 20 (covers 20, 21, 100, 101, 999, etc.)
-    const needsDe = form.needsDe && n >= 20
-    const de = needsDe ? ' de ' : ' '
+/**
+ * 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
 
-    return `${words}${de}${form.plural}`
+  // Handle leading zeros
+  while (i < decimalPart.length && decimalPart[i] === '0') {
+    if (result) result += ' '
+    result += ZERO
+    i++
   }
 
-  spellUnder100 (n, feminineUnits = false, masculineTeens = false) {
-    if (n < 10) {
-      return (feminineUnits ? this.onesFeminineWords : this.onesWords)[n]
-    }
-    if (n < 20) {
-      return (masculineTeens ? this.teensMasculineWords : this.teensWords)[n - 10]
+  // 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' })
     }
-    const t = Math.floor(n / 10)
-    const u = n % 10
-    return u
-      ? `${this.twentiesWords[t]} și ${(feminineUnits ? this.onesFeminineWords : this.onesWords)[u]}`
-      : this.twentiesWords[t]
   }
 
-  spellUnder1000 (n, feminineUnits = false, masculineTeens = false) {
-    if (n < 100) return this.spellUnder100(n, feminineUnits, masculineTeens)
-    const h = Math.floor(n / 100)
-    const r = n % 100
-    const hundredWords = this.hundredsWords[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, masculineTeens)}`
-  }
+  return result
+}
 
-  /** Decimals always use masculine forms regardless of gender option. */
-  decimalIntegerToWords (integerPart) {
-    if (integerPart === 0n) return this.zeroWord
-    // Use spellUnder1000 with masculine forms (feminineUnits=false, masculineTeens=true)
-    if (integerPart < 1000n) return this.spellUnder1000(Number(integerPart), false, true)
-    // For larger decimals, process segments with masculine forms
-    const words = []
-    const segments = this.splitToSegments(integerPart.toString(), 3)
-    let index = segments.length
-    for (const x of segments) {
-      index = index - 1
-      if (x === 0n) continue
-      const [n1, n2, n3] = this.extractDigits(x)
-      if (n3 > 0n) words.push(this.hundredsWords[Number(n3)])
-      if (n2 > 1n) words.push(this.twentiesWords[Number(n2)])
-      if (n2 === 1n) {
-        words.push(this.teensMasculineWords[Number(n1)])
-      } else if (n1 > 0n) {
-        if (n2 > 1n) words.push('și')
-        words.push(this.onesWords[Number(n1)])
-      }
-      if (index > 0) {
-        const form = this.scaleMetadata[index]
-        if (form) {
-          words.push(this.romanianPluralize(x, form))
-        } else {
-          words.push(this.spellUnder1000(Number(x), false))
-        }
-      }
-    }
-    return words.join(' ').replaceAll(/\s+/g, ' ').trim()
+/**
+ * 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
+ *
+ * @example
+ * toWords(21)                        // 'douăzeci și unu'
+ * toWords(1, { gender: 'feminine' }) // 'una'
+ * toWords(1000)                      // 'o mie'
+ */
+function toWords (value, options) {
+  options = validateOptions(options)
+  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+
+  let result = ''
+
+  if (isNegative) {
+    result = NEGATIVE + ' '
   }
 
-  integerToWords (integerPart) {
-    if (integerPart === 0n) {
-      return this.zeroWord
-    }
-    const words = []
-    const segments = this.splitToSegments(integerPart.toString(), 3)
-    let index = segments.length
-    for (const x of segments) {
-      let onesMap = []
-      index = index - 1
-      if (x === 0n) continue
-      const [n1, n2, n3] = this.extractDigits(x) // units, tens, hundreds (as BigInt)
-      // hundreds (only for the last group, not for thousands)
-      if (n3 > 0n && index === 0) {
-        words.push(this.hundredsWords[Number(n3)])
-      }
-      // tens & teens (only for the last group, not for thousands)
-      if (index === 0) {
-        if (n2 > 1n) {
-          words.push(this.twentiesWords[Number(n2)])
-        }
-        if (n2 === 1n) {
-          words.push(this.teensWords[Number(n1)])
-        } else if (n1 > 0n) {
-          // pick masculine/feminine units (only for the last group, not for thousands)
-          const feminineUnits = this.options.gender === 'feminine' && index === 0
-          onesMap = feminineUnits ? this.onesFeminineWords : this.onesWords
-          // 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.scaleMetadata[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))
-        }
-      }
-    }
-    return words.join(' ').replaceAll(/\s+/g, ' ').trim()
+  result += integerToWords(integerPart, options)
+
+  if (decimalPart) {
+    result += ' ' + DECIMAL_SEP + ' ' + decimalPartToWords(decimalPart)
   }
+
+  return result
 }
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+export { toWords }

package/lib/languages/ru.d.ts

@@ -1,85 +1,11 @@
 /**
- * Russian language converter.
+ * Converts a numeric value to Russian words.
  *
- * Supports:
- * - Gender agreement (masculine/feminine forms)
- * - Three-form pluralization (one/few/many)
- * - Large numbers up to nonillions
+ * @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 class Russian extends SlavicLanguage {
-    onesWords: {
-        1: string;
-        2: string;
-        3: string;
-        4: string;
-        5: string;
-        6: string;
-        7: string;
-        8: string;
-        9: string;
-    };
-    onesFeminineWords: {
-        1: string;
-        2: string;
-        3: string;
-        4: string;
-        5: string;
-        6: string;
-        7: string;
-        8: string;
-        9: string;
-    };
-    teensWords: {
-        0: string;
-        1: string;
-        2: string;
-        3: string;
-        4: string;
-        5: string;
-        6: string;
-        7: string;
-        8: string;
-        9: string;
-    };
-    twentiesWords: {
-        2: string;
-        3: string;
-        4: string;
-        5: string;
-        6: string;
-        7: string;
-        8: string;
-        9: string;
-    };
-    hundredsWords: {
-        1: string;
-        2: string;
-        3: string;
-        4: string;
-        5: string;
-        6: string;
-        7: string;
-        8: string;
-        9: string;
-    };
-    pluralForms: {
-        1: string[];
-        2: string[];
-        3: string[];
-        4: string[];
-        5: string[];
-        6: string[];
-        7: string[];
-        8: string[];
-        9: string[];
-        10: string[];
-    };
-    /**
-     * Russian thousands (тысяча) are feminine, requiring одна/две forms.
-     * Other scales (million, billion, etc.) are masculine.
-     */
-    scaleGenders: {
-        1: boolean;
-    };
-}
-import { SlavicLanguage } from '../classes/slavic-language.js';
+export function toWords(value: number | string | bigint, options?: {
+    gender?: "masculine" | "feminine" | undefined;
+}): string;