n2words 1.24.0 → 2.0.0

package/lib/languages/pt.js

@@ -1,11 +1,10 @@
-import GreedyScaleLanguage from '../classes/greedy-scale-language.js'
+import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js'
 
 /**
  * (European) Portuguese language converter.
  *
- * Features:
- * - Gender-aware hundreds (hundredos, duzentos, etc.)
- * - Million/Billion pluralization
+ * Supports:
+ * - Gender-aware hundreds (duzentos, trezentos)
  * - "e" (and) conjunction for number combinations
  * - Post-processing to normalize word flow
  */
@@ -13,7 +12,8 @@ export class Portuguese extends GreedyScaleLanguage {
   negativeWord = 'menos'
   decimalSeparatorWord = 'vírgula'
   zeroWord = 'zero'
-  scaleWordPairs = [
+
+  scaleWords = [
     [1_000_000_000_000_000_000_000_000n, 'quatrilião'],
     [1_000_000_000_000_000_000n, 'trilião'],
     [1_000_000_000_000n, 'bilião'],
@@ -50,7 +50,7 @@ export class Portuguese extends GreedyScaleLanguage {
     [0n, 'zero']
   ]
 
-  hundreds = {
+  hundredsWords = {
     1: 'cento',
     2: 'duzentos',
     3: 'trezentos',
@@ -69,79 +69,44 @@ export class Portuguese extends GreedyScaleLanguage {
     return words.replaceAll(Portuguese.POSTCLEAN_REGEX, ' $1 ')
   }
 
-  /**
-   * Merges two adjacent word-number pairs according to Portuguese grammar rules.
-   *
-   * Portuguese-specific rules:
-   * - Implicit "um": `mergeScales({ 'um': 1n }, { 'mil': 1000n })` → `{ 'mil': 1000n }`
-   * - "e" (and) between most combinations: `mergeScales({ 'vinte': 20n }, { 'três': 3n })` → `{ 'vinte e três': 23n }`
-   * - Special handling: "cem" (100) becomes "cento" when followed by non-thousands
-   * - Gender-aware hundreds: "duzentos", "trezentos", etc.
-   * - Million pluralization: "milhões" instead of "milhão" when coefficient > 1
-   * - Post-processing with postClean() to normalize word flow
-   *
-   * @param {Object} current The left operand as `{ word: BigInt }`.
-   * @param {Object} next The right operand as `{ word: BigInt }`.
-   * @returns {Object} Merged pair with combined word and resulting numeric value.
-   *
-   * @example
-   * mergeScales({ 'um': 1n }, { 'mil': 1000n }); // { 'mil': 1000n }
-   * mergeScales({ 'vinte': 20n }, { 'dois': 2n }); // { 'vinte e dois': 22n }
-   */
-  mergeScales (current, next) {
+  /** Combines two word-sets according to Portuguese grammar rules. */
+  combineWordSets (preceding, following) {
     // Extract words and numeric values
-    let cText = Object.keys(current)[0]
-    let nText = Object.keys(next)[0]
-    const cNumber = Object.values(current)[0] // BigInt
-    const nNumber = Object.values(next)[0] // BigInt
+    let precedingWord = Object.keys(preceding)[0]
+    let followingWord = Object.keys(following)[0]
+    const precedingValue = Object.values(preceding)[0] // BigInt
+    const followingValue = Object.values(following)[0] // BigInt
 
     // Implicit "um": omit before millions ("um milhão" → "milhão")
-    if (cNumber === 1n) {
-      if (nNumber < 1_000_000n) return { [nText]: nNumber }
-      cText = 'um'
-    } else if (cNumber === 100n && nNumber % 1000n !== 0n) {
+    if (precedingValue === 1n) {
+      if (followingValue < 1_000_000n) return { [followingWord]: followingValue }
+      precedingWord = 'um'
+    } else if (precedingValue === 100n && followingValue % 1000n !== 0n) {
       // Special handling: "cem" (100) becomes "cento" when followed by non-thousands
-      cText = 'cento'
+      precedingWord = 'cento'
     }
 
-    if (nNumber < cNumber) {
-      return { [`${cText} e ${nText}`]: cNumber + nNumber }
+    if (followingValue < precedingValue) {
+      return { [`${precedingWord} e ${followingWord}`]: precedingValue + followingValue }
     }
 
     // Handle "milião" -> "milhão" conversion
-    if (nText === 'milião') nText = 'milhão'
+    if (followingWord === 'milião') followingWord = 'milhão'
 
     // Pluralization logic for large numbers
-    if (cNumber > 1n) {
-      if (nNumber % 1_000_000_000n === 0n) {
-        nText = nText.replace('bilião', 'biliões')
-      } else if (nNumber % 1_000_000n === 0n) {
-        nText = nText.replace('milhão', 'milhões')
+    if (precedingValue > 1n) {
+      if (followingValue % 1_000_000_000n === 0n) {
+        followingWord = followingWord.replace('bilião', 'biliões')
+      } else if (followingValue % 1_000_000n === 0n) {
+        followingWord = followingWord.replace('milhão', 'milhões')
       }
     }
 
-    if (nNumber === 100n) {
-      cText = this.hundreds[cNumber]
-      return { [`${cText}`]: cNumber * nNumber }
+    if (followingValue === 100n) {
+      precedingWord = this.hundredsWords[precedingValue]
+      return { [`${precedingWord}`]: precedingValue * followingValue }
     }
 
-    return { [`${cText} ${nText}`]: cNumber * nNumber }
+    return { [`${precedingWord} ${followingWord}`]: precedingValue * followingValue }
   }
 }
-
-/**
- * Converts a number to Portuguese cardinal (written) form.
- *
- * @param {number|string|bigint} value The number to convert.
- * @param {Object} [options] Conversion options (see Portuguese class options).
- * @returns {string} The number expressed in Portuguese words.
- * @throws {TypeError} If value is NaN or invalid type.
- * @throws {Error} If value is an invalid number string.
- *
- * @example
- * convertToWords(42); // 'quarenta e dois'
- * convertToWords('100.5'); // 'cem vírgula cinco'
- */
-export default function convertToWords (value, options = {}) {
-  return new Portuguese(options).convertToWords(value)
-}

package/lib/languages/ro.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Romanian language converter.
+ *
+ * Supports:
+ * - Gender agreement (unu/una, doi/două)
+ * - Complex pluralization (singular/plural forms)
+ * - "De" preposition insertion for groups >= 20
+ */
+export class Romanian extends AbstractLanguage {
+    constructor(options?: {});
+    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;
+    };
+    teensMasculineWords: {
+        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;
+    };
+    /**
+     * 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: string;
+            plural: string;
+            feminine: boolean;
+            needsDe: boolean;
+        };
+        2: {
+            singular: string;
+            plural: string;
+            feminine: boolean;
+            needsDe: boolean;
+        };
+        3: {
+            singular: string;
+            plural: string;
+            feminine: boolean;
+            needsDe: boolean;
+        };
+        4: {
+            singular: string;
+            plural: string;
+            feminine: boolean;
+            needsDe: boolean;
+        };
+        5: {
+            singular: string;
+            plural: string;
+            feminine: boolean;
+            needsDe: boolean;
+        };
+        6: {
+            singular: string;
+            plural: string;
+            feminine: boolean;
+            needsDe: boolean;
+        };
+        7: {
+            singular: string;
+            plural: string;
+            feminine: boolean;
+            needsDe: boolean;
+        };
+        8: {
+            singular: string;
+            plural: string;
+            feminine: boolean;
+            needsDe: boolean;
+        };
+        9: {
+            singular: string;
+            plural: string;
+            feminine: boolean;
+            needsDe: boolean;
+        };
+        10: {
+            singular: string;
+            plural: string;
+            feminine: boolean;
+            needsDe: boolean;
+        };
+    };
+    /** Split numeric string into BigInt segments of specified size from left to right. */
+    splitToSegments(n: any, x: any): bigint[];
+    extractDigits(value: any): any;
+    /** Romanian pluralization & "de" rule for big units. */
+    romanianPluralize(segment: any, form: any): string;
+    spellUnder100(n: any, feminineUnits?: boolean, masculineTeens?: boolean): any;
+    spellUnder1000(n: any, feminineUnits?: boolean, masculineTeens?: boolean): any;
+    /** Decimals always use masculine forms regardless of gender option. */
+    decimalIntegerToWords(integerPart: any): any;
+    integerToWords(integerPart: any): string;
+}
+import { AbstractLanguage } from '../classes/abstract-language.js';

package/lib/languages/ro.js

@@ -1,43 +1,19 @@
-import AbstractLanguage from '../classes/abstract-language.js'
-
-/**
- * @typedef {Object} RomanianOptions
- * @property {boolean} [feminine=false] Use feminine forms for numbers.
- */
+import { AbstractLanguage } from '../classes/abstract-language.js'
 
 /**
  * Romanian language converter.
  *
- * Converts numbers to Romanian words with full grammatical support:
- * - Gender agreement (masculine/feminine forms)
+ * Supports:
+ * - Gender agreement (unu/una, doi/două)
  * - 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)
- *
- * Features:
- * - Feminine units for thousands group
- * - Support for very large numbers (up to decillions)
  */
 export class Romanian extends AbstractLanguage {
   negativeWord = 'minus'
   decimalSeparatorWord = 'virgulă'
   zeroWord = 'zero'
 
-  ones = {
+  onesWords = {
     1: 'unu',
     2: 'doi',
     3: 'trei',
@@ -49,7 +25,7 @@ export class Romanian extends AbstractLanguage {
     9: 'nouă'
   }
 
-  onesFeminine = {
+  onesFeminineWords = {
     1: 'una',
     2: 'două',
     3: 'trei',
@@ -61,7 +37,7 @@ export class Romanian extends AbstractLanguage {
     9: 'nouă'
   }
 
-  tens = {
+  teensWords = {
     0: 'zece',
     1: 'unsprezece',
     2: 'douăsprezece',
@@ -74,7 +50,7 @@ export class Romanian extends AbstractLanguage {
     9: 'nouăsprezece'
   }
 
-  tensMasculine = {
+  teensMasculineWords = {
     0: 'zece',
     1: 'unsprezece',
     2: 'doisprezece',
@@ -87,7 +63,7 @@ export class Romanian extends AbstractLanguage {
     9: 'nouăsprezece'
   }
 
-  twenties = {
+  twentiesWords = {
     2: 'douăzeci',
     3: 'treizeci',
     4: 'patruzeci',
@@ -98,7 +74,7 @@ export class Romanian extends AbstractLanguage {
     9: 'nouăzeci'
   }
 
-  hundreds = {
+  hundredsWords = {
     1: 'o sută',
     2: 'două sute',
     3: 'trei sute',
@@ -113,11 +89,11 @@ export class Romanian extends AbstractLanguage {
   /**
    * 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)
+   * - 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)
    */
-  thousands = {
+  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
@@ -130,24 +106,16 @@ export class Romanian extends AbstractLanguage {
     10: { singular: 'decilion', plural: 'decilioane', feminine: false, needsDe: true } // 10^33
   }
 
-  /**
-   * Initializes the Romanian converter with language-specific options.
-   *
-   * @param {RomanianOptions} [options={}] Configuration options.
-   */
-  constructor ({ feminine = false } = {}) {
+  constructor (options = {}) {
     super()
 
-    this.feminine = feminine
+    this.setOptions({
+      gender: 'masculine'
+    }, options)
   }
 
-  /**
-   * 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) {
+  /** Split numeric string into BigInt segments of specified size from left to right. */
+  splitToSegments (n, x) {
     const results = []
     const l = n.length
     let result
@@ -168,23 +136,15 @@ export class Romanian extends AbstractLanguage {
     return results
   }
 
-  getDigits (value) {
+  extractDigits (value) {
     const stringValue = value.toString().padStart(3, '0').slice(-3)
     const a = [...stringValue].toReversed()
     return a.map(BigInt)
   }
 
-  /**
-   * 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)
+  /** Romanian pluralization & "de" rule for big units. */
+  romanianPluralize (segment, form) {
+    const n = Number(segment)
 
     if (n === 1) {
       // article differs for feminine "mie" (o mie) vs the rest (un milion/miliard…)
@@ -197,7 +157,7 @@ export class Romanian extends AbstractLanguage {
       return `douăzeci și una de ${form.plural}`
     }
 
-    // spell the chunk itself (use feminine units for big numbers)
+    // spell the segment itself (use feminine units for big numbers)
     const words = this.spellUnder1000(n, true)
 
     // "de" after >= 20 (covers 20, 21, 100, 101, 999, etc.)
@@ -207,144 +167,91 @@ export class Romanian extends AbstractLanguage {
     return `${words}${de}${form.plural}`
   }
 
-  spellUnder100 (n, feminineUnits = false) {
+  spellUnder100 (n, feminineUnits = false, masculineTeens = false) {
     if (n < 10) {
-      return (feminineUnits ? this.onesFeminine : this.ones)[n]
+      return (feminineUnits ? this.onesFeminineWords : this.onesWords)[n]
     }
     if (n < 20) {
-      return this.tens[n - 10]
+      return (masculineTeens ? this.teensMasculineWords : this.teensWords)[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]
+      ? `${this.twentiesWords[t]} și ${(feminineUnits ? this.onesFeminineWords : this.onesWords)[u]}`
+      : this.twentiesWords[t]
   }
 
-  spellUnder1000 (n, feminineUnits = false) {
-    if (n < 100) return this.spellUnder100(n, feminineUnits)
+  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.hundreds[h]
+    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)}`
+    return `${hundredWords}${separator}${this.spellUnder100(r, feminineUnits, masculineTeens)}`
   }
 
-  /**
-   * 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++
-    }
-
-    // Prevent further processing if entire string was zeros
-    if (index === chars.length) {
-      return words
-    }
-
-    // Convert and add remaining using masculine forms for decimal places
-    const decimalNumber = BigInt(decimal)
-    const masculineWords = this.toCardinalWithMasculine(decimalNumber)
-    return [...words, masculineWords]
-  }
-
-  /**
-   * 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
-    }
-
+  /** 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 chunks = this.splitByX(number.toString(), 3)
-    let index = chunks.length
-
-    for (const x of chunks) {
-      let onesMap = []
+    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.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)])
-      }
-
+      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.tensMasculine[Number(n1)])
+        words.push(this.teensMasculineWords[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)])
+        words.push(this.onesWords[Number(n1)])
       }
-
-      // big unit name (mie/mii, milion/milioane, …)
       if (index > 0) {
-        const form = this.thousands[index]
+        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), false))
         }
       }
     }
-
     return words.join(' ').replaceAll(/\s+/g, ' ').trim()
   }
 
-  convertWholePart (number) {
-    if (number === 0n) {
+  integerToWords (integerPart) {
+    if (integerPart === 0n) {
       return this.zeroWord
     }
     const words = []
-    const chunks = this.splitByX(number.toString(), 3)
-    let index = chunks.length
-    for (const x of chunks) {
+    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.getDigits(x) // units, tens, hundreds (as BigInt)
+      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.hundreds[Number(n3)])
+        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.twenties[Number(n2)])
+          words.push(this.twentiesWords[Number(n2)])
         }
         if (n2 === 1n) {
-          words.push(this.tens[Number(n1)])
+          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.feminine && index === 0
-          onesMap = feminineUnits ? this.onesFeminine : this.ones
+          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)])
@@ -352,7 +259,7 @@ export class Romanian extends AbstractLanguage {
       }
       // big unit name (mie/mii, milion/milioane, …)
       if (index > 0) {
-        const form = this.thousands[index]
+        const form = this.scaleMetadata[index]
         if (form) {
           words.push(this.romanianPluralize(x, form))
         } else {
@@ -364,17 +271,3 @@ export class Romanian extends AbstractLanguage {
     return words.join(' ').replaceAll(/\s+/g, ' ').trim()
   }
 }
-
-/**
- * Converts a number to Romanian cardinal (written) form.
- *
- * @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.
- */
-export default function convertToWords (value, options = {}) {
-  return new Romanian(options).convertToWords(value)
-}