n2words 1.24.0 → 2.0.0

package/lib/languages/el.js

@@ -1,21 +1,20 @@
-/**
- * Converts numbers to their word representation in Greek (Ελληνικά).
- * @module languages/el
- */
-
-import GreedyScaleLanguage from '../classes/greedy-scale-language.js'
+import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js'
 
 /**
- * Greek language implementation using scale-based number conversion.
- * @extends GreedyScaleLanguage
+ * Greek language converter.
+ *
+ * Supports:
+ * - Space-separated number composition
+ * - Implicit "one" (ένα) omission before scale words
+ * - Digit-by-digit decimal reading
  */
-class GreekLanguage extends GreedyScaleLanguage {
+export class Greek extends GreedyScaleLanguage {
   negativeWord = 'μείον'
   decimalSeparatorWord = 'κόμμα'
   zeroWord = 'μηδέν'
-  convertDecimalsPerDigit = true
+  usePerDigitDecimals = true
 
-  scaleWordPairs = [
+  scaleWords = [
     // Large numbers (limited set for now)
     [1_000_000_000n, 'δισεκατομμύριο'],
     [1_000_000n, 'εκατομμύριο'],
@@ -65,52 +64,27 @@ class GreekLanguage extends GreedyScaleLanguage {
     [0n, 'μηδέν']
   ]
 
-  /**
-   * Merges two adjacent word-number pairs according to Greek grammar rules.
-   *
-   * Greek-specific rules:
-   * - Implicit "one": χίλια (thousand), not ένα χίλια
-   * - Space-separated composites
-   * - Multiplication for scales (e.g., δύο χίλια = two thousand)
-   *
-   * @param {Object} leftPair - Left word-number pair (e.g., { 'δύο': 2n })
-   * @param {Object} rightPair - Right word-number pair (e.g., { 'χίλια': 1000n })
-   * @returns {Object} Merged word-number pair
-   */
-  mergeScales (leftPair, rightPair) {
-    const leftWord = Object.keys(leftPair)[0]
-    const leftNumber = Object.values(leftPair)[0]
-    const rightWord = Object.keys(rightPair)[0]
-    const rightNumber = Object.values(rightPair)[0]
+  /** Combines two word-sets with Greek space-separation rules. */
+  combineWordSets (preceding, following) {
+    const precedingWord = Object.keys(preceding)[0]
+    const precedingValue = Object.values(preceding)[0]
+    const followingWord = Object.keys(following)[0]
+    const followingValue = Object.values(following)[0]
 
     // Implicit one: omit "ένα" before any following value (> 0)
-    if (leftNumber === 1n) {
-      return rightPair
+    if (precedingValue === 1n) {
+      return following
     }
 
     // No special handling needed for trailing 'ένα';
     // nested merge will first collapse {1, 'ένα'} -> 'ένα'.
 
-    // Multiplication: larger right scale multiplied by left number
-    if (rightNumber > leftNumber) {
-      return { [`${leftWord} ${rightWord}`]: leftNumber * rightNumber }
+    // Multiplication: larger following scale multiplied by preceding number
+    if (followingValue > precedingValue) {
+      return { [`${precedingWord} ${followingWord}`]: precedingValue * followingValue }
     }
 
     // Addition: smaller numbers added together
-    return { [`${leftWord} ${rightWord}`]: leftNumber + rightNumber }
+    return { [`${precedingWord} ${followingWord}`]: precedingValue + followingValue }
   }
 }
-
-/**
- * Converts a number to its word representation in Greek.
- * @param {number|string|bigint} value - The number to convert
- * @param {Object} [options={}] - Conversion options
- * @returns {string} The word representation of the number
- * @example
- * convertToWords(42) // 'σαράντα δύο'
- * convertToWords(1000) // 'χίλια'
- * convertToWords(2000) // 'δύο χίλια'
- */
-export default function convertToWords (value, options = {}) {
-  return new GreekLanguage(options).convertToWords(value)
-}

package/lib/languages/en.d.ts

@@ -0,0 +1,16 @@
+/**
+ * English language converter.
+ *
+ * Supports:
+ * - Hyphenated compounds (e.g., "twenty-three")
+ * - "and" after hundreds (e.g., "one hundred and one")
+ * - Numbers up to octillions
+ */
+export class English extends GreedyScaleLanguage {
+    scaleWords: (string | bigint)[][];
+    /** Combines two word-sets with English hyphenation and "and" rules. */
+    combineWordSets(preceding: any, following: any): {
+        [x: string]: any;
+    };
+}
+import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js';

package/lib/languages/en.js

@@ -1,23 +1,19 @@
-import GreedyScaleLanguage from '../classes/greedy-scale-language.js'
+import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js'
 
 /**
  * English language converter.
  *
- * Converts numbers to English words, supporting:
- * - Negative numbers (prepended with "minus")
- * - Decimal numbers (word "point" between whole and fractional parts)
- * - Numbers up to octillions
- *
- * Merge rules:
- * - Hyphenated for compound tens (e.g., "twenty-three")
+ * Supports:
+ * - Hyphenated compounds (e.g., "twenty-three")
  * - "and" after hundreds (e.g., "one hundred and one")
- * - Space-separated for larger composites (e.g., "one thousand twenty-three")
+ * - Numbers up to octillions
  */
 export class English extends GreedyScaleLanguage {
   negativeWord = 'minus'
   decimalSeparatorWord = 'point'
   zeroWord = 'zero'
-  scaleWordPairs = [
+
+  scaleWords = [
     [1_000_000_000_000_000_000_000_000_000n, 'octillion'],
     [1_000_000_000_000_000_000_000_000n, 'septillion'],
     [1_000_000_000_000_000_000_000n, 'sextillion'],
@@ -58,66 +54,33 @@ export class English extends GreedyScaleLanguage {
     [0n, 'zero']
   ]
 
-  /**
-   * Merges two adjacent word-number pairs according to English grammar rules.
-   *
-   * English-specific rules:
-   * - Implicit "one": `mergeScales({ 'one': 1n }, { 'hundred': 100n })` → `{ 'one hundred': 100n }`
-   * - Hyphenated compounds: `mergeScales({ 'twenty': 20n }, { 'three': 3n })` → `{ 'twenty-three': 23n }`
-   * - "and" after hundreds: `mergeScales({ 'one hundred': 100n }, { 'one': 1n })` → `{ 'one hundred and one': 101n }`
-   * - Multiplication: `mergeScales({ 'one': 1n }, { 'thousand': 1000n })` → `{ 'one thousand': 1000n }`
-   *
-   * @param {Object} leftPair Left word-set as `{ word: BigInt }`.
-   * @param {Object} rightPair Right word-set as `{ word: BigInt }`.
-   * @returns {Object} Merged pair with combined word and resulting numeric value.
-   *
-   * @example
-   * mergeScales({ 'one': 1n }, { 'hundred': 100n }); // { 'one hundred': 100n }
-   * mergeScales({ 'twenty': 20n }, { 'three': 3n }); // { 'twenty-three': 23n }
-   */
-  mergeScales (leftPair, rightPair) {
-    const leftWord = Object.keys(leftPair)[0]
-    const leftNumber = Object.values(leftPair)[0]
-    const rightWord = Object.keys(rightPair)[0]
-    const rightNumber = Object.values(rightPair)[0]
+  /** Combines two word-sets with English hyphenation and "and" rules. */
+  combineWordSets (preceding, following) {
+    const precedingWord = Object.keys(preceding)[0]
+    const precedingValue = Object.values(preceding)[0]
+    const followingWord = Object.keys(following)[0]
+    const followingValue = Object.values(following)[0]
 
     // Rule 1: Implicit "one" - omit when multiplying ("one hundred" → "hundred")
-    if (leftNumber === 1n && rightNumber < 100n) {
-      return { [rightWord]: rightNumber }
+    if (precedingValue === 1n && followingValue < 100n) {
+      return { [followingWord]: followingValue }
     }
 
     // Rule 2: Hyphenate compounds under 100 ("twenty-three")
-    if (leftNumber < 100n && leftNumber > rightNumber) {
-      return { [`${leftWord}-${rightWord}`]: leftNumber + rightNumber }
+    if (precedingValue < 100n && precedingValue > followingValue) {
+      return { [`${precedingWord}-${followingWord}`]: precedingValue + followingValue }
     }
 
     // Rule 3: Add "and" before units after hundreds ("one hundred and one")
-    if (leftNumber >= 100n && rightNumber < 100n) {
-      return { [`${leftWord} and ${rightWord}`]: leftNumber + rightNumber }
+    if (precedingValue >= 100n && followingValue < 100n) {
+      return { [`${precedingWord} and ${followingWord}`]: precedingValue + followingValue }
     }
 
-    // Rule 4: Multiply when right > left ("one thousand")
-    if (rightNumber > leftNumber) {
-      return { [`${leftWord} ${rightWord}`]: leftNumber * rightNumber }
+    // Rule 4: Multiply when following > preceding ("one thousand")
+    if (followingValue > precedingValue) {
+      return { [`${precedingWord} ${followingWord}`]: precedingValue * followingValue }
     }
 
-    return { [`${leftWord} ${rightWord}`]: leftNumber + rightNumber }
+    return { [`${precedingWord} ${followingWord}`]: precedingValue + followingValue }
   }
 }
-
-/**
- * Converts a number to English cardinal (written) form.
- *
- * @param {number|string|bigint} value The number to convert.
- * @param {Object} [options] Conversion options (see English class options).
- * @returns {string} The number expressed in English words.
- * @throws {TypeError} If value is NaN or invalid type.
- * @throws {Error} If value is an invalid number string.
- *
- * @example
- * convertToWords(42); // 'forty-two'
- * convertToWords('1.5'); // 'one point five'
- */
-export default function convertToWords (value, options = {}) {
-  return new English(options).convertToWords(value)
-}

package/lib/languages/es.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Spanish language converter.
+ *
+ * Supports:
+ * - Gender agreement (masculine/feminine via genderStem option)
+ * - "y" conjunction between tens and units
+ * - Special hundred forms (cien/ciento)
+ */
+export class Spanish extends GreedyScaleLanguage {
+    constructor(options?: {});
+    scaleWords: (string | bigint)[][];
+    /** Combines two word-sets with Spanish gender and conjunction rules. */
+    combineWordSets(preceding: any, following: any): any;
+}
+import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js';

package/lib/languages/es.js

@@ -1,24 +1,19 @@
-import GreedyScaleLanguage from '../classes/greedy-scale-language.js'
-
-/**
- * @typedef {Object} SpanishOptions
- * @property {string} [genderStem='o'] Masculine 'o' or feminine 'a' ending.
- */
+import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js'
 
 /**
  * Spanish language converter.
  *
- * Handles Spanish grammatical features:
- * - Gender agreement for numbers (masculine by default, feminine via `genderStem`)
- * - "y" (and) between tens and units (e.g., "veinte y uno")
- * - Special forms for hundreds (e.g., "cien", "ciento", "doscientos")
- * - Million pluralization
+ * Supports:
+ * - Gender agreement (masculine/feminine via genderStem option)
+ * - "y" conjunction between tens and units
+ * - Special hundred forms (cien/ciento)
  */
 export class Spanish extends GreedyScaleLanguage {
   negativeWord = 'menos'
   decimalSeparatorWord = 'punto'
   zeroWord = 'cero'
-  scaleWordPairs = [
+
+  scaleWords = [
     [1_000_000_000_000_000_000_000_000n, 'cuatrillón'],
     [1_000_000_000_000_000_000n, 'trillón'],
     [1_000_000_000_000n, 'billón'],
@@ -64,90 +59,63 @@ export class Spanish extends GreedyScaleLanguage {
     [0n, 'cero']
   ]
 
-  /**
-   * Initializes the Spanish converter.
-   *
-   * @param {SpanishOptions} [options={}] Configuration options.
-   */
-  constructor ({ genderStem = 'o' } = {}) {
+  constructor (options = {}) {
     super()
 
-    this.genderStem = genderStem
+    this.setOptions({
+      gender: 'masculine'
+    }, options)
+
+    // Apply gender agreement to scale words if feminine
+    if (this.options.gender === 'feminine') {
+      this.scaleWords = this.scaleWords.map(([value, word]) => {
+        if (word === 'veintiuno') return [value, 'veintiuna']
+        if (word === 'uno') return [value, 'una']
+        return [value, word]
+      })
+    }
   }
 
-  /**
-   * Merges two adjacent word-number pairs according to Spanish grammar rules.
-   *
-   * Spanish-specific rules:
-   * - Implicit "uno": `mergeScales({ 'uno': 1n }, { 'mil': 1000n })` → `{ 'mil': 1000n }`
-   * - "y" (and) between tens and units: `mergeScales({ 'veinte': 20n }, { 'uno': 1n })` → `{ 'veinte y uno': 21n }`
-   * - Gender agreement for hundreds: "cien" + suffix based on genderStem
-   * - Special forms for hundreds (cien/ciento/quinientos/setecientos/novecientos)
-   * - Million pluralization when coefficient > 1: "millones" instead of "millón"
-   *
-   * @param {Object} currentPair The left operand as `{ word: BigInt }`.
-   * @param {Object} nextPair The right operand as `{ word: BigInt }`.
-   * @returns {Object} Merged pair with combined word and resulting numeric value.
-   *
-   * @example
-   * mergeScales({ 'uno': 1n }, { 'mil': 1000n }); // { 'mil': 1000n }
-   * mergeScales({ 'veinte': 20n }, { 'tres': 3n }); // { 'veinte y tres': 23n }
-   */
-  mergeScales (currentPair, nextPair) {
-    let currentWord = Object.keys(currentPair)[0]
-    let nextWord = Object.keys(nextPair)[0]
-    const currentNumber = Object.values(currentPair)[0]
-    const nextNumber = Object.values(nextPair)[0]
+  /** Combines two word-sets with Spanish gender and conjunction rules. */
+  combineWordSets (preceding, following) {
+    let precedingWord = Object.keys(preceding)[0]
+    let followingWord = Object.keys(following)[0]
+    const precedingValue = Object.values(preceding)[0]
+    const followingValue = Object.values(following)[0]
+    const genderStem = this.options.gender === 'feminine' ? 'a' : 'o'
 
-    if (currentNumber === 1n) {
-      if (nextNumber < 1_000_000n) return nextPair
-      currentWord = 'un'
-    } else if (currentNumber === 100n && nextNumber % 1000n !== 0n) {
-      currentWord += 't' + this.genderStem
+    if (precedingValue === 1n) {
+      if (followingValue < 1_000_000n) return following
+      precedingWord = 'un'
+    } else if (precedingValue === 100n && followingValue % 1000n !== 0n) {
+      precedingWord += 't' + genderStem
     }
 
-    if (nextNumber < currentNumber) {
-      if (currentNumber < 100n) {
-        return { [`${currentWord} y ${nextWord}`]: currentNumber + nextNumber }
+    if (followingValue < precedingValue) {
+      if (precedingValue < 100n) {
+        return { [`${precedingWord} y ${followingWord}`]: precedingValue + followingValue }
       }
-      return { [`${currentWord} ${nextWord}`]: currentNumber + nextNumber }
+      return { [`${precedingWord} ${followingWord}`]: precedingValue + followingValue }
     }
 
-    if (nextNumber % 1_000_000n === 0n && currentNumber > 1n) {
-      nextWord = nextWord.slice(0, -3) + 'lones'
+    if (followingValue % 1_000_000n === 0n && precedingValue > 1n) {
+      followingWord = followingWord.slice(0, -3) + 'lones'
     }
 
-    if (nextNumber === 100n) {
-      if (currentNumber === 5n) {
-        currentWord = 'quinien'
-        nextWord = ''
-      } else if (currentNumber === 7n) {
-        currentWord = 'sete'
-      } else if (currentNumber === 9n) {
-        currentWord = 'nove'
+    if (followingValue === 100n) {
+      if (precedingValue === 5n) {
+        precedingWord = 'quinien'
+        followingWord = ''
+      } else if (precedingValue === 7n) {
+        precedingWord = 'sete'
+      } else if (precedingValue === 9n) {
+        precedingWord = 'nove'
       }
-      nextWord += 't' + this.genderStem + 's'
+      followingWord += 't' + genderStem + 's'
     } else {
-      nextWord = ' ' + nextWord
+      followingWord = ' ' + followingWord
     }
 
-    return { [`${currentWord}${nextWord}`]: currentNumber * nextNumber }
+    return { [`${precedingWord}${followingWord}`]: precedingValue * followingValue }
   }
 }
-
-/**
- * Converts a number to Spanish cardinal (written) form.
- *
- * @param {number|string|bigint} value The number to convert.
- * @param {Object} [options] Conversion options (see ES class).
- * @returns {string} The number expressed in Spanish words.
- * @throws {TypeError} If value is NaN or invalid type.
- * @throws {Error} If value is an invalid number string.
- *
- * @example
- * convertToWords(42, { lang: 'es' }); // 'cuarenta y dos'
- * convertToWords(100, { lang: 'es' }); // 'cien'
- */
-export default function convertToWords (value, options = {}) {
-  return new Spanish(options).convertToWords(value)
-}

package/lib/languages/fa.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Persian language converter.
+ *
+ * Supports:
+ * - "و" (and) conjunction for compound numbers
+ * - Recursive conversion for larger numbers
+ */
+export class Persian extends AbstractLanguage {
+    /**
+     * Words for digits 1-9.
+     * @type {Object.<number, string>}
+     */
+    onesWords: {
+        [x: number]: string;
+    };
+    /**
+     * Words for teen numbers (10-19).
+     * @type {Object.<number, string>}
+     */
+    teensWords: {
+        [x: number]: string;
+    };
+    /**
+     * Words for multiples of ten (20-90).
+     * @type {Object.<number, string>}
+     */
+    tensWords: {
+        [x: number]: string;
+    };
+    /**
+     * Words for hundreds (100-900).
+     * @type {Object.<number, string>}
+     */
+    hundredsWords: {
+        [x: number]: string;
+    };
+    /**
+     * Scale magnitude words.
+     * @type {Object.<number, string>}
+     */
+    scaleWords: {
+        [x: number]: string;
+    };
+    /** Converts integer part using categorized word tables. */
+    integerToWords(integerPart: any): any;
+}
+import { AbstractLanguage } from '../classes/abstract-language.js';