n2words 1.24.0 → 2.0.0

package/lib/languages/cs.js

@@ -1,36 +1,18 @@
-import SlavicLanguage from '../classes/slavic-language.js'
-
-/**
- * @typedef {Object} SlavicOptions
- * @property {boolean} [feminine=false] Use feminine forms for numbers.
- */
+import { SlavicLanguage } from '../classes/slavic-language.js'
 
 /**
  * Czech language converter.
  *
- * Implements Czech number words using the Slavic language pattern:
- * - Czech number words (jedna, dva, tři, čtyři, pět...)
- * - Slavic three-form pluralization (tisíc/tisíce/tisíc)
- * - Gender agreement for numbers 1-2
- * - Czech-specific number word endings
- *
- * Key Features:
- * - Three-form pluralization system shared across Slavic languages
- *   * Form 1 (singular): 1 (e.g., "tisíc")
- *   * Form 2 (few): 2-4, 22-24, 32-34... excluding teens (e.g., "tisíce")
- *   * Form 3 (many): all other numbers (e.g., "tisíc")
- * - Chunk-based decomposition (splits into groups of 3 digits: ones, thousands, millions, etc.)
- * - Large number handling via thousands[] array with indexed [singular, few, many] forms
- *
- * Inherits from SlavicLanguage:
- * - Complex pluralization rules (one/few/many forms)
- * - Group-based large number handling (chunk decomposition via splitByX())
- * - Proper declension patterns via pluralize() method
+ * Supports:
+ * - Three-form pluralization (one/few/many)
+ * - Dynamic decimal separator (celá/celé/celých)
+ * - Gender agreement in number words
  */
 export class Czech extends SlavicLanguage {
   negativeWord = 'mínus'
   zeroWord = 'nula'
-  ones = {
+
+  onesWords = {
     1: 'jedna',
     2: 'dva',
     3: 'tři',
@@ -42,7 +24,19 @@ export class Czech extends SlavicLanguage {
     9: 'devět'
   }
 
-  tens = {
+  onesFeminineWords = {
+    1: 'jedna',
+    2: 'dvě',
+    3: 'tři',
+    4: 'čtyři',
+    5: 'pět',
+    6: 'šest',
+    7: 'sedm',
+    8: 'osm',
+    9: 'devět'
+  }
+
+  teensWords = {
     0: 'deset',
     1: 'jedenáct',
     2: 'dvanáct',
@@ -55,7 +49,7 @@ export class Czech extends SlavicLanguage {
     9: 'devatenáct'
   }
 
-  twenties = {
+  twentiesWords = {
     2: 'dvacet',
     3: 'třicet',
     4: 'čtyřicet',
@@ -66,7 +60,7 @@ export class Czech extends SlavicLanguage {
     9: 'devadesát'
   }
 
-  hundreds = {
+  hundredsWords = {
     1: 'sto',
     2: 'dvě stě',
     3: 'tři sta',
@@ -78,7 +72,7 @@ export class Czech extends SlavicLanguage {
     9: 'devět set'
   }
 
-  thousands = {
+  pluralForms = {
     1: ['tisíc', 'tisíce', 'tisíc'], // 10^ 3
     2: ['milion', 'miliony', 'milionů'], // 10^ 6
     3: ['miliarda', 'miliardy', 'miliard'], // 10^ 9
@@ -92,25 +86,29 @@ export class Czech extends SlavicLanguage {
   }
 
   /**
-   * Returns the Czech word for the decimal separator based on the whole number.
-   *
-   * @returns {string} The Czech word for the decimal separator.
+   * Czech omits "one" before scale words.
+   * e.g., 1000 is "tisíc" not "jedna tisíc"
    */
+  omitOneBeforeScale = true
+
+  /**
+   * Cached integer part for decimal separator word selection.
+   * Set by toWords() before calling super.toWords().
+   * @private
+   */
+  #integerPart = 0n
+
+  /** Returns decimal separator word based on integer part (celá/celé/celých). */
   get decimalSeparatorWord () {
-    if (this.cachedWholeNumber === 0n || this.cachedWholeNumber === 1n) {
+    if (this.#integerPart === 0n || this.#integerPart === 1n) {
       return 'celá'
-    } else if (this.cachedWholeNumber >= 2n && this.cachedWholeNumber <= 4n) {
+    } else if (this.#integerPart >= 2n && this.#integerPart <= 4n) {
       return 'celé'
     } else {
       return 'celých'
     }
   }
 
-  /**
-   * Initializes the Czech converter with language-specific options.
-   *
-   * @param {SlavicOptions} [options={}] Configuration options (inherited from SlavicLanguage).
-   */
   constructor (options = {}) {
     super(options)
 
@@ -119,17 +117,14 @@ export class Czech extends SlavicLanguage {
   }
 
   /**
-   * Implements Czech-specific three-form pluralization rules.
-   *
-   * Czech three-form system:
-   * - Form 1 (singular): exactly n=1 (e.g., "tisíc")
-   * - Form 2 (few): n ends in 2-4, excluding teens (22-24, 32-34...) (e.g., "tisíce")
-   * - Form 3 (many): all other numbers (e.g., "tisíc" for 0, 5+)
-   *
-   * @param {bigint} n The number to classify.
-   * @param {Array<string>} forms Array of [singular, few, many] word forms.
-   * @returns {string} The appropriate form for the number n.
+   * Override toWords to cache integer part before decimal separator is accessed.
    */
+  toWords (isNegative, integerPart, decimalPart) {
+    this.#integerPart = integerPart
+    return super.toWords(isNegative, integerPart, decimalPart)
+  }
+
+  /** Selects Czech plural form: 1 = singular, 2-4 = few, else = many. */
   pluralize (n, forms) {
     if (n === 1n) {
       return forms[0]
@@ -145,68 +140,4 @@ export class Czech extends SlavicLanguage {
 
     return forms[2]
   }
-
-  /**
-   * Converts a whole number to Czech cardinal form.
-   *
-   * Algorithm (chunk-based decomposition):
-   * 1. Split number into chunks of 3 digits (right-to-left): ones, thousands, millions, etc.
-   * 2. For each non-zero chunk:
-   *    a. Extract hundreds digit (n3), tens digit (n2), ones digit (n1)
-   *    b. Add hundreds word (e.g., "sto", "dvě stě")
-   *    c. Add tens/ones (handles teens 10-19 separately from compound tens)
-   *    d. Add pluralized magnitude word (e.g., "tisíce", "miliony")
-   * 3. Join all words with spaces
-   *
-   * Example: 1234 → chunks [1, 234] → "jeden tisíc dvěstěčtyřicet"
-   *   - Chunk 1 (index=1, thousands): "jeden" + "tisíc"
-   *   - Chunk 234 (index=0): "dvě stě" + "třicet" + "čtyři"
-   *
-   * Special case: When chunk=1 at thousands+ levels, omit the ones word to avoid
-   * redundancy with the pluralized magnitude (e.g., just "tisíc" not "jeden tisíc").
-   *
-   * @param {bigint} number The whole number to convert.
-   * @returns {string} The number expressed in Czech words.
-   */
-  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) {
-      index--
-      if (x === 0n) continue
-      const [n1, n2, n3] = this.getDigits(x)
-      if (n3 > 0n) {
-        words.push(this.hundreds[n3])
-      }
-      if (n2 > 1n) {
-        words.push(this.twenties[n2])
-      }
-      if (n2 === 1n) {
-        words.push(this.tens[n1])
-      } else if (n1 > 0n && !(index > 0 && x === 1n)) {
-        words.push(this.ones[n1])
-      }
-      if (index > 0) {
-        words.push(this.pluralize(x, this.thousands[index]))
-      }
-    }
-    return words.join(' ')
-  }
-}
-
-/**
- * Converts a number to Czech cardinal (written) form.
- *
- * @param {number|string|bigint} value The number to convert.
- * @param {SlavicOptions} [options={}] Configuration options.
- * @returns {string} The number expressed in Czech 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 Czech(options).convertToWords(value)
 }

package/lib/languages/da.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Danish language converter.
+ *
+ * Supports:
+ * - Vigesimal (base-20) number system
+ * - Units-before-tens ordering (e.g., "tre-og-tyve" = 23)
+ * - Optional ordinal numbers via ordFlag option
+ */
+export class Danish extends GreedyScaleLanguage {
+    constructor(options?: {});
+    scaleWords: (string | bigint)[][];
+    /** Combines two word-sets with Danish vigesimal and reversal rules. */
+    combineWordSets(preceding: any, following: any): any;
+}
+import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js';

package/lib/languages/da.js

@@ -1,31 +1,19 @@
-import GreedyScaleLanguage from '../classes/greedy-scale-language.js'
-
-/**
- * @typedef {Object} DanishOptions
- * @property {boolean} [ordFlag=false] Enable ordinal number conversion.
- */
+import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js'
 
 /**
  * Danish language converter.
  *
- * GreedyScaleLanguage with Danish-specific extensions:
- * - Unique vigesimal (base-20) number system for 50-90
- * - Special composition rules ("og" for "and" between units and tens)
- * - Reverse digit order (e.g., "fem-og-tyve" = five-and-twenty = 25)
- * - Support for ordinal numbers via ordFlag option
- *
- * Key Features:
- * - Vigesimal tens: halvtreds (50), treds (60), halvfjerds (70), firs (80), halvfems (90)
- * - Units-before-tens pattern (e.g., "tre-og-tyve" = 23)
- * - "et" prefix for hundreds/thousands (not "en")
- * - Optional ordinal number conversion via ordFlag option
- * - Inline merge logic tailored for Danish ordering
+ * Supports:
+ * - Vigesimal (base-20) number system
+ * - Units-before-tens ordering (e.g., "tre-og-tyve" = 23)
+ * - Optional ordinal numbers via ordFlag option
  */
 export class Danish extends GreedyScaleLanguage {
   negativeWord = 'minus'
   decimalSeparatorWord = 'komma'
   zeroWord = 'nul'
-  scaleWordPairs = [
+
+  scaleWords = [
     [1_000_000_000_000_000_000_000_000_000n, 'quadrillarder'],
     [1_000_000_000_000_000_000_000_000n, 'quadrillioner'],
     [1_000_000_000_000_000_000_000n, 'trillarder'],
@@ -66,102 +54,67 @@ export class Danish extends GreedyScaleLanguage {
     [0n, 'nul']
   ]
 
-  /**
-   * Initializes the Danish converter with language-specific options.
-   *
-   * @param {DanishOptions} [options={}] Configuration options.
-   */
-  constructor ({ ordFlag = false } = {}) {
+  constructor (options = {}) {
     super()
 
-    this.ordFlag = ordFlag
+    this.setOptions({
+      ordFlag: false
+    }, options)
   }
 
-  /**
-   * Merges two adjacent word-number pairs according to Danish grammar rules.
-   * Danish uses complex vigesimal (base-20) patterns and reverse digit ordering.
-   *
-   * Key Danish patterns:
-   * - Vigesimal tens: halvtreds(50), treds(60), halvfjerds(70), firs(80), halvfems(90)
-   * - Units-before-tens order with "og" (and): "tre-og-tyve" (3 and 20 = 25)
-   * - "et" prefix for hundreds/thousands (not "en")
-   * - Space separators for large magnitudes (≥ millions)
-   * - Ordinal support via this.ordFlag
-   *
-   * @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 number (bigint).
-   */
-  mergeScales (current, next) {
-    let cText = Object.keys(current)[0]
-    let nText = Object.keys(next)[0]
-    const cNumber = Object.values(current)[0] // BigInt (e.g., 1n, 100n, 1000n)
-    const nNumber = Object.values(next)[0] // BigInt (e.g., magnitude level like 100n, 1000n)
+  /** Combines two word-sets with Danish vigesimal and reversal rules. */
+  combineWordSets (preceding, following) {
+    let precedingWord = Object.keys(preceding)[0]
+    let followingWord = Object.keys(following)[0]
+    const precedingValue = Object.values(preceding)[0] // BigInt (e.g., 1n, 100n, 1000n)
+    const followingValue = Object.values(following)[0] // BigInt (e.g., magnitude level like 100n, 1000n)
 
     // Prepend "et" to hundreds and thousands (not "en") for proper Danish form
-    if (nNumber === 100n || nNumber === 1000n) {
-      next = { [`et${nText}`]: nNumber }
+    if (followingValue === 100n || followingValue === 1000n) {
+      following = { [`et${followingWord}`]: followingValue }
     }
 
     // Implicit '1' handling: omit '1' before most magnitudes (except millions/ordinals)
-    if (cNumber === 1n) {
-      if (nNumber < 1_000_000n || this.ordFlag) {
-        return next // Just the magnitude word (e.g., "hundrede" not "en hundrede")
+    if (precedingValue === 1n) {
+      if (followingValue < 1_000_000n || this.options.ordFlag) {
+        return following // Just the magnitude word (e.g., "hundrede" not "en hundrede")
       }
-      cText = 'en' // Explicit "en" (one) for millions and above
+      precedingWord = 'en' // Explicit "en" (one) for millions and above
     }
 
     // Multiplication across magnitude boundaries
-    if (nNumber > cNumber) {
+    if (followingValue > precedingValue) {
       // Space for million+ (e.g., "en million", "to millioner")
-      if (nNumber >= 1_000_000n) {
-        cText += ' '
+      if (followingValue >= 1_000_000n) {
+        precedingWord += ' '
       }
-      return { [`${cText}${nText}`]: cNumber * nNumber }
+      return { [`${precedingWord}${followingWord}`]: precedingValue * followingValue }
     }
 
     // Addition with separator rules:
     // "og" (and) for hundreds + smaller numbers
-    if (cNumber >= 100n && cNumber < 1000n) {
-      cText += ' og '
-    } else if (cNumber >= 1000n && cNumber <= 100_000n) {
+    if (precedingValue >= 100n && precedingValue < 1000n) {
+      precedingWord += ' og '
+    } else if (precedingValue >= 1000n && precedingValue <= 100_000n) {
       // Special "e og" for thousands (e.g., "tusinde og tyve")
-      cText += 'e og '
+      precedingWord += 'e og '
     }
 
     // Units-before-tens reversal (Danish vigesimal pattern):
     // For small units (< 10) with tens (10-99), swap order: "tre og tyve" (25)
-    if (nNumber < 10n && cNumber > 10n && cNumber < 100n) {
-      if (nNumber === 1n) {
-        nText = 'en' // Convert 1 to "en" for vigesimal context
+    if (followingValue < 10n && precedingValue > 10n && precedingValue < 100n) {
+      if (followingValue === 1n) {
+        followingWord = 'en' // Convert 1 to "en" for vigesimal context
       }
       // Swap positions: units go after "og", tens go before
-      const temporary = nText
-      nText = cText
-      cText = temporary + 'og'
-    } else if (cNumber >= 1_000_000n) {
+      const temporary = followingWord
+      followingWord = precedingWord
+      precedingWord = temporary + 'og'
+    } else if (precedingValue >= 1_000_000n) {
       // Space for large magnitudes (millions+)
-      cText += ' '
+      precedingWord += ' '
     }
 
-    return { [`${cText}${nText}`]: cNumber + nNumber }
+    return { [`${precedingWord}${followingWord}`]: precedingValue + followingValue }
   }
 }
-
-/**
- * Converts a number to Danish cardinal (written) form.
- *
- * @param {number|string|bigint} value The number to convert.
- * @param {Object} [options] Conversion options (see Danish class options).
- * @param {boolean} [options.ordFlag=false] Enable ordinal number conversion.
- * @returns {string} The number expressed in Danish words.
- * @throws {TypeError} If value is NaN or invalid type.
- * @throws {Error} If value is an invalid number string.
- *
- * @example
- * convertToWords(25); // 'femogtyve' (five-and-twenty)
- * convertToWords(50); // 'halvtreds' (half-third-times-twenty)
- */
-export default function convertToWords (value, options = {}) {
-  return new Danish(options).convertToWords(value)
-}

package/lib/languages/de.d.ts

@@ -0,0 +1,14 @@
+/**
+ * German language converter.
+ *
+ * Supports:
+ * - Compound formation (no separators between words)
+ * - Three forms of 1 (eins/ein/eine)
+ * - Units-before-tens ordering (einundzwanzig = one and twenty)
+ */
+export class German extends GreedyScaleLanguage {
+    scaleWords: (string | bigint)[][];
+    /** Combines two word-sets with German compound formation and reversal rules. */
+    combineWordSets(preceding: any, following: any): any;
+}
+import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js';

package/lib/languages/de.js

@@ -1,19 +1,19 @@
-import GreedyScaleLanguage from '../classes/greedy-scale-language.js'
+import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js'
 
 /**
  * German language converter.
  *
- * Handles German grammatical features:
- * - "eins" vs "ein" and "eine" forms for 1
- * - Compound words without separators (e.g., "einundzwanzig" = 21)
- * - Million/Billion pluralization
- * - Special characters (e.g., "ü", "ö", "ß")
+ * Supports:
+ * - Compound formation (no separators between words)
+ * - Three forms of 1 (eins/ein/eine)
+ * - Units-before-tens ordering (einundzwanzig = one and twenty)
  */
 export class German extends GreedyScaleLanguage {
   negativeWord = 'minus'
   decimalSeparatorWord = 'komma'
   zeroWord = 'null'
-  scaleWordPairs = [
+
+  scaleWords = [
     [1_000_000_000_000_000_000_000_000_000n, 'Quadrilliarde'],
     [1_000_000_000_000_000_000_000_000n, 'Quadrillion'],
     [1_000_000_000_000_000_000_000n, 'Trilliarde'],
@@ -54,82 +54,48 @@ export class German extends GreedyScaleLanguage {
     [0n, 'null']
   ]
 
-  /**
-   * Merges two adjacent word-number pairs according to German grammar rules.
-   *
-   * German-specific rules:
-   * - Implicit "eins": `mergeScales({ 'eins': 1n }, { 'hundert': 100n })` → `{ 'einhundert': 100n }`
-   * - Compound words without separators (e.g., "einundzwanzig" = 21)
-   * - Special handling for forms of 1 (eins/ein/eine) depending on context
-   * - Pluralization of millions and higher: "Millionen", "Milliarden"
-   * - Reordering of tens and units: `mergeScales({ 'zwanzig': 20n }, { 'eins': 1n })` → `{ 'einundzwanzig': 21n }`
-   *
-   * @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({ 'eins': 1n }, { 'hundert': 100n }); // { 'einhundert': 100n }
-   * mergeScales({ 'zwanzig': 20n }, { 'drei': 3n }); // { 'dreiundzwanzig': 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 German compound formation and reversal 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]
 
     // Handle form of 1: "eins" → "ein(e)" in certain contexts
-    if (currentNumber === 1n) {
-      if (nextNumber === 100n || nextNumber === 1000n) {
-        return { [`ein${nextWord}`]: nextNumber }
+    if (precedingValue === 1n) {
+      if (followingValue === 100n || followingValue === 1000n) {
+        return { [`ein${followingWord}`]: followingValue }
       }
-      if (nextNumber < 1_000_000n) {
-        return nextPair
+      if (followingValue < 1_000_000n) {
+        return following
       }
-      currentWord = 'eine'
+      precedingWord = 'eine'
     }
 
-    if (nextNumber > currentNumber) {
+    if (followingValue > precedingValue) {
       // Multiply: apply pluralization rules for millions
-      if (nextNumber >= 1_000_000n) {
-        if (currentNumber > 1n) {
-          nextWord += nextWord.at(-1) === 'e' ? 'n' : 'en'
+      if (followingValue >= 1_000_000n) {
+        if (precedingValue > 1n) {
+          followingWord += followingWord.at(-1) === 'e' ? 'n' : 'en'
         }
-        currentWord += ' '
+        precedingWord += ' '
       }
-      return { [`${currentWord}${nextWord}`]: currentNumber * nextNumber }
+      return { [`${precedingWord}${followingWord}`]: precedingValue * followingValue }
     }
 
     // Add: handle special case of tens + units
-    if (nextNumber < 10n && currentNumber > 10n && currentNumber < 100n) {
+    if (followingValue < 10n && precedingValue > 10n && precedingValue < 100n) {
       // German reverses tens and units (einundzwanzig = one and twenty)
-      if (nextNumber === 1n) {
-        nextWord = 'ein'
+      if (followingValue === 1n) {
+        followingWord = 'ein'
       }
-      const temp = nextWord
-      nextWord = currentWord
-      currentWord = `${temp}und`
-    } else if (currentNumber >= 1_000_000n) {
-      currentWord += ' '
+      const temp = followingWord
+      followingWord = precedingWord
+      precedingWord = `${temp}und`
+    } else if (precedingValue >= 1_000_000n) {
+      precedingWord += ' '
     }
 
-    return { [`${currentWord}${nextWord}`]: currentNumber + nextNumber }
+    return { [`${precedingWord}${followingWord}`]: precedingValue + followingValue }
   }
 }
-
-/**
- * Converts a number to German cardinal (written) form.
- *
- * @param {number|string|bigint} value The number to convert.
- * @param {Object} [options] Conversion options (see German class options).
- * @returns {string} The number expressed in German words.
- * @throws {TypeError} If value is NaN or invalid type.
- * @throws {Error} If value is an invalid number string.
- *
- * @example
- * convertToWords(42); // 'zweiundvierzig'
- * convertToWords('1.5'); // 'eins komma fünf'
- */
-export default function convertToWords (value, options = {}) {
-  return new German(options).convertToWords(value)
-}

package/lib/languages/el.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Greek language converter.
+ *
+ * Supports:
+ * - Space-separated number composition
+ * - Implicit "one" (ένα) omission before scale words
+ * - Digit-by-digit decimal reading
+ */
+export class Greek extends GreedyScaleLanguage {
+    scaleWords: (string | bigint)[][];
+    /** Combines two word-sets with Greek space-separation rules. */
+    combineWordSets(preceding: any, following: any): any;
+}
+import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js';