n2words 1.24.0 → 2.0.0

package/lib/languages/nl.js

@@ -1,25 +1,19 @@
-import GreedyScaleLanguage from '../classes/greedy-scale-language.js'
-
-/**
- * @typedef {Object} DutchOptions
- * @property {boolean} [includeOptionalAnd=false] Include optional "en" separator.
- * @property {boolean} [noHundredPairs=false] Disable comma before hundreds.
- * @property {boolean} [accentOne=true] Use accented "één" for one.
- */
+import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js'
 
 /**
  * Dutch language converter.
  *
- * Features:
- * - Optional "en" (and) separator for tens (includeOptionalAnd)
- * - Optional comma before hundreds (noHundredPairs)
+ * Supports:
+ * - Optional "en" (and) separator for tens
+ * - Optional comma before hundreds
  * - Compound word formation without hyphenation
  */
 export class Dutch extends GreedyScaleLanguage {
   negativeWord = 'min'
   decimalSeparatorWord = 'komma'
   zeroWord = 'nul'
-  scaleWordPairs = [
+
+  scaleWords = [
     [1_000_000_000_000_000_000_000_000_000n, 'quadriljard'],
     [1_000_000_000_000_000_000_000_000n, 'quadriljoen'],
     [1_000_000_000_000_000_000_000n, 'triljard'],
@@ -60,147 +54,102 @@ export class Dutch extends GreedyScaleLanguage {
     [0n, 'nul']
   ]
 
-  /**
-   * Initializes the Dutch converter with language-specific options.
-   *
-   * @param {DutchOptions} [options={}] Configuration options.
-   */
-  constructor ({ includeOptionalAnd = false, noHundredPairs = false, accentOne = true } = {}) {
+  constructor (options = {}) {
     super()
 
-    this.includeOptionalAnd = includeOptionalAnd
-
-    this.noHundredPairs = noHundredPairs
+    this.setOptions({
+      includeOptionalAnd: false,
+      noHundredPairing: false,
+      accentOne: true
+    }, options)
 
-    this.accentOne = accentOne
-    if (!this.accentOne) {
-      this.scaleWordPairs[this.scaleWordPairs.length - 2][1] = 'een'
+    if (!this.options.accentOne) {
+      this.scaleWords[this.scaleWords.length - 2][1] = 'een'
     }
   }
 
-  /**
-   * Merges two adjacent word-number pairs according to Dutch grammar rules.
-   *
-   * Dutch-specific rules:
-   * - Implicit "één": `mergeScales({ 'één': 1n }, { 'duizend': 1000n })` → `{ 'duizend': 1000n }`
-   * - Reversed digit order for tens + units: `mergeScales({ 'twintig': 20n }, { 'één': 1n })` → `{ 'ééntwintig': 21n }`
-   * - Optional "en" separator based on includeOptionalAnd option
-   * - Compound words without separators for most combinations
-   * - Converts 'één' to 'een' in compound words (no accent in compounds)
-   * - Space separators for large numbers (millions+)
-   *
-   * @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({ 'één': 1n }, { 'duizend': 1000n }); // { 'duizend': 1000n }
-   * mergeScales({ 'twintig': 20n }, { 'drie': 3n }); // { 'drieentwintig': 23n }
-   */
-  mergeScales (current, next) {
-    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
+  /** Combines two word-sets according to Dutch grammar rules. */
+  combineWordSets (preceding, following) {
+    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 "een": omit before large multipliers ("miljoen" not "een miljoen")
-    if (cNumber === 1n) {
-      if (nNumber < 1_000_000n) {
-        return next
+    if (precedingValue === 1n) {
+      if (followingValue < 1_000_000n) {
+        return following
       }
-      cText = this.accentOne ? 'één' : 'een'
+      precedingWord = this.options.accentOne ? 'één' : 'een'
     }
 
     // Handle multiplication and spacing
-    if (nNumber > cNumber) {
+    if (followingValue > precedingValue) {
       let hadSpace = false
       // Large scale words (millions+): add space before multiplier
-      if (nNumber >= 1_000_000n) {
-        cText += ' '
+      if (followingValue >= 1_000_000n) {
+        precedingWord += ' '
         hadSpace = true
-      } else if (nNumber > 100n) {
+      } else if (followingValue > 100n) {
         // Hundreds and above: add space after multiplier
-        nText += ' '
+        followingWord += ' '
         hadSpace = true
       }
       // Convert 'één' to 'een' in compounds (when no space or accentOne disabled)
-      if (!hadSpace || !this.accentOne) {
-        cText = cText.replace(/één/g, 'een')
-        nText = nText.replace(/één/g, 'een')
+      if (!hadSpace || !this.options.accentOne) {
+        precedingWord = precedingWord.replace(/één/g, 'een')
+        followingWord = followingWord.replace(/één/g, 'een')
       }
-      return { [`${cText}${nText}`]: cNumber * nNumber }
+      return { [`${precedingWord}${followingWord}`]: precedingValue * followingValue }
     }
 
     // Track if we're adding a space (which keeps words separate)
     let hasSpace = false
 
-    if (nNumber < 10n && cNumber > 10n && cNumber < 100n) {
-      const temporary = nText
-      nText = cText
+    if (followingValue < 10n && precedingValue > 10n && precedingValue < 100n) {
+      const temporary = followingWord
+      followingWord = precedingWord
       const andTxt = temporary.endsWith('e') ? 'ën' : 'en'
-      cText = `${temporary}${andTxt}`
-    } else if (nNumber < 13n && cNumber < 1000n && this.includeOptionalAnd) {
-      cText = `${cText}en`
-    } else if (nNumber < 13n && cNumber >= 1000n && this.includeOptionalAnd) {
-      nText = ` en ${nText}`
+      precedingWord = `${temporary}${andTxt}`
+    } else if (followingValue < 13n && precedingValue < 1000n && this.options.includeOptionalAnd) {
+      precedingWord = `${precedingWord}en`
+    } else if (followingValue < 13n && precedingValue >= 1000n && this.options.includeOptionalAnd) {
+      followingWord = ` en ${followingWord}`
       hasSpace = true
-    } else if (cNumber >= 1_000_000n) {
-      cText += ' '
+    } else if (precedingValue >= 1_000_000n) {
+      precedingWord += ' '
       hasSpace = true
-    } else if (cNumber === 1000n) {
-      cText += ' '
+    } else if (precedingValue === 1000n) {
+      precedingWord += ' '
       hasSpace = true
     }
 
     // Convert 'één' to 'een' in direct compounds (no space)
     // Keep 'één' only if there's a space AND accentOne=true
     if (!hasSpace) {
-      cText = cText.replace(/één/g, 'een')
-      nText = nText.replace(/één/g, 'een')
-    } else if (!this.accentOne) {
-      cText = cText.replace(/één/g, 'een')
-      nText = nText.replace(/één/g, 'een')
+      precedingWord = precedingWord.replace(/één/g, 'een')
+      followingWord = followingWord.replace(/één/g, 'een')
+    } else if (!this.options.accentOne) {
+      precedingWord = precedingWord.replace(/één/g, 'een')
+      followingWord = followingWord.replace(/één/g, 'een')
     }
 
-    return { [`${cText}${nText}`]: cNumber + nNumber }
+    return { [`${precedingWord}${followingWord}`]: precedingValue + followingValue }
   }
 
-  convertWholePart (value) {
-    if (value >= 1100n && value < 10_000n && !this.noHundredPairs) {
-      const high = value / 100n
-      const low = value % 100n
+  integerToWords (integerPart) {
+    if (integerPart >= 1100n && integerPart < 10_000n && !this.options.noHundredPairing) {
+      const high = integerPart / 100n
+      const low = integerPart % 100n
       if (high % 10n !== 0n) {
-        let result = super.convertWholePart(high) + 'honderd'
+        let result = super.integerToWords(high) + 'honderd'
         if (low) {
           result +=
-            (this.includeOptionalAnd ? ' en ' : ' ') + super.convertWholePart(low)
+            (this.options.includeOptionalAnd ? ' en ' : ' ') + super.integerToWords(low)
         }
         return result
       }
     }
-    return super.convertWholePart(value)
+    return super.integerToWords(integerPart)
   }
 }
-
-/**
- * Converts a number to Dutch cardinal (written) form.
- *
- * @param {number|string|bigint} value The number to convert.
- * @param {Object} [options] Conversion options (see Dutch class options).
- * @param {boolean} [options.includeOptionalAnd=false] Include optional 'en' (and) separator.
- * @param {boolean} [options.noHundredPairs=false] Don't combine hundreds with tens/units.
- * @param {boolean} [options.accentOne=true] Use accented 'één' for standalone 1.
- * @returns {string} The number expressed in Dutch words.
- * @throws {TypeError} If value is NaN or invalid type.
- * @throws {Error} If value is an invalid number string.
- *
- * @example
- * convertToWords(1); // 'één' (default accent)
- * convertToWords(1, { accentOne: false }); // 'een'
- * convertToWords(21); // 'eenentwintig' (no accent in compounds)
- * convertToWords(42); // 'tweeenveertig'
- * convertToWords('1.5'); // 'één komma vijf'
- */
-export default function convertToWords (value, options = {}) {
-  return new Dutch(options).convertToWords(value)
-}

package/lib/languages/pa.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Punjabi language converter.
+ *
+ * Supports:
+ * - Indian numbering system (ਹਜ਼ਾਰ, ਲੱਖ, ਕਰੋੜ)
+ * - Gurmukhi script
+ * - Complete word forms for 0-99
+ */
+export class Punjabi extends SouthAsianLanguage {
+}
+import { SouthAsianLanguage } from '../classes/south-asian-language.js';

package/lib/languages/{pa-Guru.js → pa.js}

@@ -1,11 +1,20 @@
-import SouthAsianLanguage from '../classes/south-asian-language.js'
+import { SouthAsianLanguage } from '../classes/south-asian-language.js'
 
-class Punjabi extends SouthAsianLanguage {
+/**
+ * Punjabi language converter.
+ *
+ * Supports:
+ * - Indian numbering system (ਹਜ਼ਾਰ, ਲੱਖ, ਕਰੋੜ)
+ * - Gurmukhi script
+ * - Complete word forms for 0-99
+ */
+export class Punjabi extends SouthAsianLanguage {
   negativeWord = 'ਮਾਇਨਸ'
   decimalSeparatorWord = 'ਦਸ਼ਮਲਵ'
   zeroWord = 'ਸਿਫ਼ਰ'
   hundredWord = 'ਸੌ'
-  belowHundred = [
+
+  belowHundredWords = [
     'ਸਿਫ਼ਰ',
     'ਇੱਕ',
     'ਦੋ',
@@ -120,7 +129,3 @@ class Punjabi extends SouthAsianLanguage {
     'ਸ਼ੰਖ'
   ]
 }
-
-export default function convertToWords (value, options = {}) {
-  return new Punjabi(options).convertToWords(value)
-}

package/lib/languages/pl.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Polish language converter.
+ *
+ * Supports:
+ * - Three-form pluralization (one/few/many)
+ * - Polish-specific declension patterns
+ * - Distinctive Polish phonology and orthography
+ */
+export class Polish 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[];
+    };
+    /** Implements Polish-specific three-form pluralization rules. */
+    pluralize(n: any, forms: any): any;
+}
+import { SlavicLanguage } from '../classes/slavic-language.js';

package/lib/languages/pl.js

@@ -1,39 +1,19 @@
-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'
 
 /**
  * Polish language converter.
  *
- * Implements Polish number words using the Slavic language pattern:
- * - Polish number words (jeden, dwa, trzy, cztery, pięć...)
- * - Complex Slavic three-form pluralization (tysiąc/tysiące/tysięcy)
+ * Supports:
+ * - Three-form pluralization (one/few/many)
  * - Polish-specific declension patterns
  * - Distinctive Polish phonology and orthography
- *
- * Key Features:
- * - Three-form pluralization system shared across Slavic languages
- *   * Form 1 (singular): 1 (e.g., "tysiąc")
- *   * Form 2 (few): 2-4, 22-24, 32-34... excluding teens (e.g., "tysiące")
- *   * Form 3 (many): all other numbers (e.g., "tysięcy")
- * - 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
- *
- * Features:
- * - Polish diacritical marks (ą, ć, ę, ł, ń, ś, ź, ż)
- * - Gender and case agreement
- * - Polish-specific number word endings
- *
- * Inherits from SlavicLanguage for complex pluralization algorithms.
  */
 export class Polish extends SlavicLanguage {
   negativeWord = 'minus'
   decimalSeparatorWord = 'przecinek'
   zeroWord = 'zero'
-  ones = {
+
+  onesWords = {
     1: 'jeden',
     2: 'dwa',
     3: 'trzy',
@@ -45,7 +25,19 @@ export class Polish extends SlavicLanguage {
     9: 'dziewięć'
   }
 
-  tens = {
+  onesFeminineWords = {
+    1: 'jedna',
+    2: 'dwie',
+    3: 'trzy',
+    4: 'cztery',
+    5: 'pięć',
+    6: 'sześć',
+    7: 'siedem',
+    8: 'osiem',
+    9: 'dziewięć'
+  }
+
+  teensWords = {
     0: 'dziesięć',
     1: 'jedenaście',
     2: 'dwanaście',
@@ -58,7 +50,7 @@ export class Polish extends SlavicLanguage {
     9: 'dziewiętnaście'
   }
 
-  twenties = {
+  twentiesWords = {
     2: 'dwadzieścia',
     3: 'trzydzieści',
     4: 'czterdzieści',
@@ -69,7 +61,7 @@ export class Polish extends SlavicLanguage {
     9: 'dziewięćdziesiąt'
   }
 
-  hundreds = {
+  hundredsWords = {
     1: 'sto',
     2: 'dwieście',
     3: 'trzysta',
@@ -81,7 +73,7 @@ export class Polish extends SlavicLanguage {
     9: 'dziewięćset'
   }
 
-  thousands = {
+  pluralForms = {
     1: ['tysiąc', 'tysiące', 'tysięcy'], // 10^ 3
     2: ['milion', 'miliony', 'milionów'], // 10^ 6
     3: ['miliard', 'miliardy', 'miliardów'], // 10^ 9
@@ -95,17 +87,12 @@ export class Polish extends SlavicLanguage {
   }
 
   /**
-   * Implements Polish-specific three-form pluralization rules.
-   *
-   * Polish three-form system:
-   * - Form 1 (singular): exactly n=1 (e.g., "tysiąc")
-   * - Form 2 (few): n ends in 2-4, excluding teens (22-24, 32-34...) (e.g., "tysiące")
-   * - Form 3 (many): all other numbers (e.g., "tysięcy")
-   *
-   * @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.
+   * Polish omits "one" before scale words.
+   * e.g., 1000 is "tysiąc" not "jeden tysiąc"
    */
+  omitOneBeforeScale = true
+
+  /** Implements Polish-specific three-form pluralization rules. */
   pluralize (n, forms) {
     if (n === 1n) {
       return forms[0]
@@ -120,70 +107,4 @@ export class Polish extends SlavicLanguage {
 
     return forms[2]
   }
-
-  /**
-   * Converts a whole number to Polish 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", "dwieście")
-   *    c. Add tens/ones (handles teens 10-19 separately from compound tens)
-   *    d. Add pluralized magnitude word (e.g., "tysiące", "miliony")
-   * 3. Join all words with spaces
-   *
-   * Example: 1234 → chunks [1, 234] → "jeden tysiąc dwieście trzydzieści cztery"
-   *   - Chunk 1 (index=1, thousands): "jeden" + "tysiąc"
-   *   - Chunk 234 (index=0): "dwieście" + "trzydzieści" + "cztery"
-   *
-   * Special case: When chunk=1 at thousands+ levels, omit the ones word to avoid
-   * redundancy with the pluralized magnitude (e.g., just "tysiąc" not "jeden tysiąc").
-   *
-   * @param {bigint} number The whole number to convert.
-   * @returns {string} The number expressed in Polish 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 = index - 1
-      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 Polish cardinal (written) form.
- *
- * @param {number|string|bigint} value The number to convert.
- * @param {SlavicOptions} [options={}] Configuration options.
- * @returns {string} The number expressed in Polish 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 Polish(options).convertToWords(value)
 }

package/lib/languages/pt.d.ts

@@ -0,0 +1,29 @@
+/**
+ * (European) Portuguese language converter.
+ *
+ * Supports:
+ * - Gender-aware hundreds (duzentos, trezentos)
+ * - "e" (and) conjunction for number combinations
+ * - Post-processing to normalize word flow
+ */
+export class Portuguese extends GreedyScaleLanguage {
+    static POSTCLEAN_REGEX: RegExp;
+    scaleWords: (string | bigint)[][];
+    hundredsWords: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+    };
+    finalizeWords(words: any): any;
+    /** Combines two word-sets according to Portuguese grammar rules. */
+    combineWordSets(preceding: any, following: any): {
+        [x: string]: any;
+    };
+}
+import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js';