n2words 1.24.0 → 2.0.0

package/lib/languages/hu.js

@@ -1,25 +1,19 @@
-import GreedyScaleLanguage from '../classes/greedy-scale-language.js'
+import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js'
 
 /**
  * Hungarian language converter.
  *
- * Converts numbers to Hungarian words following Hungarian conventions:
- * - Agglutinative structure for compound numbers
- * - No spaces between tens and units (e.g., "huszonegy" = twenty-one)
- * - Special handling for "egy" (one) - often omitted as multiplier
- * - Vowel harmony in compound words
- *
- * Features:
- * - Compact number representations (húsz, harminc, negyven)
+ * Supports:
+ * - Agglutinative structure (no spaces between compound parts)
+ * - Special handling for "egy" (one) omission
  * - Pre-composed twenties (huszonegy through huszonkilenc)
- * - "egész" as decimal separator (meaning "whole")
- * - Support for very large numbers (up to quadrilliards)
  */
 export class Hungarian extends GreedyScaleLanguage {
   negativeWord = 'mínusz'
   decimalSeparatorWord = 'egész'
   zeroWord = 'nulla'
-  scaleWordPairs = [
+
+  scaleWords = [
     [1_000_000_000_000_000_000_000_000_000n, 'quadrilliárd'],
     [1_000_000_000_000_000_000_000_000n, 'quadrillió'],
     [1_000_000_000_000_000_000_000n, 'trilliárd'],
@@ -69,87 +63,75 @@ export class Hungarian extends GreedyScaleLanguage {
     [0n, 'nulla']
   ]
 
+  /** Converts tens (30-99) with agglutinative composition. */
   tensToCardinal (number) {
-    // Expecting `number` as bigint when called from convertWholePart
-    if (this.getScaleWord(number)) {
-      return this.getScaleWord(number)
+    // Expecting `number` as bigint when called from integerToWords
+    if (this.wordForScale(number)) {
+      return this.wordForScale(number)
     } else {
       const tens = number / 10n
       const units = number % 10n
-      return this.getScaleWord(tens * 10n) + this.convertWholePart(units)
+      return this.wordForScale(tens * 10n) + this.integerToWords(units)
     }
   }
 
+  /** Converts hundreds (100-999) with "száz" composition. */
   hundredsToCardinal (number) {
     const hundreds = number / 100n
     let prefix = 'száz'
     if (hundreds !== 1n) {
-      prefix = this.convertWholePart(hundreds, '') + prefix
+      prefix = this.integerToWords(hundreds, '') + prefix
     }
-    const postfix = this.convertWholePart(number % 100n, '')
+    const postfix = this.integerToWords(number % 100n, '')
     return prefix + postfix
   }
 
+  /** Converts thousands (1000-999999) with "ezer" composition. */
   thousandsToCardinal (number) {
     const thousands = number / 1000n
     let prefix = 'ezer'
     if (thousands !== 1n) {
-      prefix = this.convertWholePart(thousands, '') + prefix
+      prefix = this.integerToWords(thousands, '') + prefix
     }
-    const postfix = this.convertWholePart(number % 1000n, '')
+    const postfix = this.integerToWords(number % 1000n, '')
     const middle = (number <= 2000n || postfix === '') ? '' : '-'
     return prefix + middle + postfix
   }
 
+  /** Converts large numbers (millions and above) with scale words. */
   bigNumberToCardinal (number) {
     const numberLength = number.toString().length
     const digits = (numberLength % 3 === 0) ? numberLength - 2 : numberLength
     const exp = 10 ** (Math.floor(digits / 3) * 3)
-    const prefix = this.convertWholePart(number / BigInt(exp), '')
-    const rest = this.convertWholePart(number % BigInt(exp), '')
+    const prefix = this.integerToWords(number / BigInt(exp), '')
+    const rest = this.integerToWords(number % BigInt(exp), '')
     const postfix = (rest === '') ? '' : ('-' + rest)
-    return prefix + this.getScaleWord(BigInt(exp)) + postfix
+    return prefix + this.wordForScale(BigInt(exp)) + postfix
   }
 
-  convertWholePart (number, zeroWord = this.zeroWord) {
+  /** Converts integer part using Hungarian agglutinative rules. */
+  integerToWords (integerPart, zeroWord = this.zeroWord) {
     let words = ''
 
     // Normalize to BigInt for consistent comparisons
-    if (typeof number !== 'bigint') number = BigInt(number)
+    if (typeof integerPart !== 'bigint') integerPart = BigInt(integerPart)
 
-    if (number === 0n) {
+    if (integerPart === 0n) {
       words = zeroWord
-    } else if (zeroWord === '' && number === 2n) {
+    } else if (zeroWord === '' && integerPart === 2n) {
       words = 'két'
-    } else if (number < 30n) {
-      words = this.getScaleWord(number)
-    } else if (number < 100n) {
-      words = this.tensToCardinal(number)
-    } else if (number < 1000n) {
-      words = this.hundredsToCardinal(number)
-    } else if (number < 1_000_000n) {
-      words = this.thousandsToCardinal(number)
+    } else if (integerPart < 30n) {
+      words = this.wordForScale(integerPart)
+    } else if (integerPart < 100n) {
+      words = this.tensToCardinal(integerPart)
+    } else if (integerPart < 1000n) {
+      words = this.hundredsToCardinal(integerPart)
+    } else if (integerPart < 1_000_000n) {
+      words = this.thousandsToCardinal(integerPart)
     } else {
-      words = this.bigNumberToCardinal(number)
+      words = this.bigNumberToCardinal(integerPart)
     }
 
     return words
   }
 }
-
-/**
- * Converts a number to Hungarian cardinal (written) form.
- *
- * @param {number|string|bigint} value The number to convert.
- * @param {Object} [options] Conversion options (see Hungarian class options).
- * @returns {string} The number expressed in Hungarian words.
- * @throws {TypeError} If value is NaN or invalid type.
- * @throws {Error} If value is an invalid number string.
- *
- * @example
- * convertToWords(42); // 'negyvenkettő'
- * convertToWords(21); // 'huszonegy'
- */
-export default function convertToWords (value, options = {}) {
-  return new Hungarian(options).convertToWords(value)
-}

package/lib/languages/id.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Indonesian language converter.
+ *
+ * Supports:
+ * - "Se-" prefix for one (seratus, seribu, sejuta)
+ * - Regular patterns (puluh for tens, ratus for hundreds)
+ * - Space-separated number components
+ */
+export class Indonesian extends AbstractLanguage {
+    /**
+     * Word forms for digits 0-9.
+     * @type {Object.<number, string[]>}
+     */
+    digitWords: {
+        [x: number]: string[];
+    };
+    /**
+     * Scale magnitude words keyed by exponent (10^n).
+     * @type {Object.<number, string>}
+     */
+    scaleWords: {
+        [x: number]: string;
+    };
+    /** Splits number into groups of 3 digits. */
+    splitBy3(number: any): any[][];
+    /** Converts digit blocks to Indonesian words. */
+    spell(blocks: any): any[];
+    /** Converts hundreds digit with "seratus" or "ratus" suffix. */
+    getHundreds(number: any): string[];
+    /** Converts tens and units digits with "puluh" or "belas" suffix. */
+    getTens(number: any): string[];
+    /** Joins word blocks with magnitude scale words. */
+    join(wordBlocks: any): string;
+    /** Converts integer part using Indonesian group-based conversion. */
+    integerToWords(integerPart: any): string;
+}
+import { AbstractLanguage } from '../classes/abstract-language.js';

package/lib/languages/id.js

@@ -1,35 +1,23 @@
-import AbstractLanguage from '../classes/abstract-language.js'
+import { AbstractLanguage } from '../classes/abstract-language.js'
 
 /**
  * Indonesian language converter.
  *
- * Converts numbers to Indonesian words following Indonesian conventions:
- * - Simple base-10 structure
- * - "Se-" prefix for one (e.g., "seratus" = one hundred, "seribu" = one thousand)
+ * Supports:
+ * - "Se-" prefix for one (seratus, seribu, sejuta)
+ * - Regular patterns (puluh for tens, ratus for hundreds)
  * - Space-separated number components
- * - Straightforward grouping by thousands
- *
- * Key Features:
- * - Base number mapping (base) for single digits 0-9
- * - Magnitude scale (thousands) mapping powers of 10 to Indonesian words
- * - Group-based algorithm:
- *   1. Split number into groups of 3 digits
- *   2. For each group, convert ones/tens/hundreds using base and naming rules
- *   3. Apply "se-" prefix for 1 (seratus, seribu, sejuta)
- *   4. Combine with magnitude words
- *   5. Join all parts with spaces
- * - Regular patterns (puluh for tens, ratus for hundreds, ribu for thousands)
- * - Clear grouping: ribu (10³), juta (10⁶), miliar (10⁹), triliun (10¹²)
- *
- * Features:
- * - "Se-" prefix usage for singular units
- * - Support for very large numbers (up to decillions)
  */
 export class Indonesian extends AbstractLanguage {
   negativeWord = 'min'
   decimalSeparatorWord = 'koma'
   zeroWord = 'nol'
-  base = {
+
+  /**
+   * Word forms for digits 0-9.
+   * @type {Object.<number, string[]>}
+   */
+  digitWords = {
     0: [],
     1: ['satu'],
     2: ['dua'],
@@ -42,7 +30,11 @@ export class Indonesian extends AbstractLanguage {
     9: ['sembilan']
   }
 
-  thousands = {
+  /**
+   * Scale magnitude words keyed by exponent (10^n).
+   * @type {Object.<number, string>}
+   */
+  scaleWords = {
     3: 'ribu', // 10^3
     6: 'juta', // 10^6
     9: 'miliar', // 10^9
@@ -56,6 +48,7 @@ export class Indonesian extends AbstractLanguage {
     33: 'desiliun'
   }
 
+  /** Splits number into groups of 3 digits. */
   splitBy3 (number) {
     // Split to groups of 3 numbers: 1234567 -> [['1'], ['234'], ['567']]
     const blocks = []
@@ -81,12 +74,13 @@ export class Indonesian extends AbstractLanguage {
     return blocks
   }
 
+  /** Converts digit blocks to Indonesian words. */
   spell (blocks) {
     let wordBlocks = []
     let spelling
     const firstBlock = blocks[0]
     if (firstBlock[0].length === 1) {
-      spelling = firstBlock[0] === '0' ? ['nol'] : this.base[Math.trunc(firstBlock[0])]
+      spelling = firstBlock[0] === '0' ? ['nol'] : this.digitWords[Math.trunc(firstBlock[0])]
     } else if (firstBlock[0].length === 2) {
       spelling = this.getTens(firstBlock[0])
     } else {
@@ -102,16 +96,18 @@ export class Indonesian extends AbstractLanguage {
     return wordBlocks
   }
 
+  /** Converts hundreds digit with "seratus" or "ratus" suffix. */
   getHundreds (number) {
     if (number === '1') {
       return ['seratus']
     } else if (number === '0') {
       return []
     } else {
-      return [...this.base[Math.trunc(number)], 'ratus']
+      return [...this.digitWords[Math.trunc(number)], 'ratus']
     }
   }
 
+  /** Converts tens and units digits with "puluh" or "belas" suffix. */
   getTens (number) {
     if (number[0] === '1') {
       if (number[1] === '0') {
@@ -119,16 +115,17 @@ export class Indonesian extends AbstractLanguage {
       } else if (number[1] === '1') {
         return ['sebelas']
       }
-      return [...this.base[Math.trunc(number[1])], 'belas']
+      return [...this.digitWords[Math.trunc(number[1])], 'belas']
     }
 
     if (number[0] === '0') {
-      return this.base[Math.trunc(number[1])]
+      return this.digitWords[Math.trunc(number[1])]
     }
 
-    return [...this.base[Math.trunc(number[0])], 'puluh', ...this.base[Math.trunc(number[1])]]
+    return [...this.digitWords[Math.trunc(number[0])], 'puluh', ...this.digitWords[Math.trunc(number[1])]]
   }
 
+  /** Joins word blocks with magnitude scale words. */
   join (wordBlocks) {
     let wordList = []
     const length = wordBlocks.length - 1
@@ -146,29 +143,17 @@ export class Indonesian extends AbstractLanguage {
       if (index === length) {
         break
       }
-      wordList = [...wordList, this.thousands[(length - index) * 3]]
+      wordList = [...wordList, this.scaleWords[(length - index) * 3]]
     }
     return wordList.join(' ')
   }
 
-  convertWholePart (number) {
+  /** Converts integer part using Indonesian group-based conversion. */
+  integerToWords (integerPart) {
     return this.join(
       this.spell(
-        this.splitBy3(number)
+        this.splitBy3(integerPart)
       )
     ).trim()
   }
 }
-
-/**
- * Converts a number to Indonesian cardinal (written) form.
- *
- * @param {number|string|bigint} value The number to convert.
- * @param {Object} [options={}] Configuration options.
- * @returns {string} The number expressed in Indonesian 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 Indonesian(options).convertToWords(value)
-}

package/lib/languages/it.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Italian language converter.
+ *
+ * Supports:
+ * - Phonetic contractions (vowel elision: "ventotto" not "ventiotto")
+ * - Accentuation rules for "tre" in compounds ("ventitré")
+ * - Custom word construction for irregular patterns
+ */
+export class Italian extends AbstractLanguage {
+    onesWords: string[];
+    tensWords: {
+        2: string;
+        3: string;
+        4: string;
+        6: string;
+    };
+    exponentPrefixes: string[];
+    /** Adds accent to final "tre" in compound words (ventitré). */
+    accentuate(string: any): any;
+    /** Omits word if it represents zero. */
+    omitIfZero(numberToString: any): any;
+    /** Removes duplicate vowels for phonetic contractions. */
+    phoneticContraction(string: any): any;
+    /** Converts tens (20-99) with phonetic contractions. */
+    tensToCardinal(number: any): any;
+    /** Converts hundreds (100-999) with "cento" composition. */
+    hundredsToCardinal(number: any): any;
+    /** Converts thousands (1000-999999) with "mille/mila" composition. */
+    thousandsToCardinal(number: any): string;
+    /** Converts exponent length to Italian scale word (milione, miliardo, etc.). */
+    exponentLengthToString(exponentLength: any): string;
+    /** Converts large numbers (millions and above) with exponent-based naming. */
+    bigNumberToCardinal(number: any): string;
+    /** Converts integer part using Italian custom algorithm with accentuation. */
+    integerToWords(integerPart: any): any;
+}
+import { AbstractLanguage } from '../classes/abstract-language.js';

package/lib/languages/it.js

@@ -1,40 +1,29 @@
-import GreedyScaleLanguage from '../classes/greedy-scale-language.js'
+import { AbstractLanguage } from '../classes/abstract-language.js'
 
 /**
  * Italian language converter.
  *
- * Converts numbers to Italian words following Italian conventions:
- * - Phonetic contractions (removes duplicate vowels: "ventotto" not "ventiotto")
- * - Accentuation rules for "tre" in compounds ("ventitré" not "ventitre")
- * - Special handling for "uno" and vowel agreement
- * - Complex composition patterns for large numbers
- *
- * Architecture Note:
- * Unlike other GreedyScaleLanguage subclasses, Italian uses a custom algorithm
- * rather than the standard highest-matching-scale approach. This is necessary
- * because Italian's word formation rules are irregular and context-dependent.
- * See tensToCardinal(), hundredsToCardinal(), and bigNumberToCardinal().
- *
- * Features:
- * - Vowel elision (e.g., "ventotto" not "ventiotto")
- * - Accentuation of final "tre" (ventitré, trentacinque - note: accent on compound tres)
- * - Exponent-based large number naming (milione, miliardo, trilione)
- * - Custom word construction for hundreds and thousands
+ * Supports:
+ * - Phonetic contractions (vowel elision: "ventotto" not "ventiotto")
+ * - Accentuation rules for "tre" in compounds ("ventitré")
+ * - Custom word construction for irregular patterns
  */
-export class Italian extends GreedyScaleLanguage {
+export class Italian extends AbstractLanguage {
   negativeWord = 'meno'
   decimalSeparatorWord = 'virgola'
   zeroWord = 'zero'
-  cardinalWords = [
+
+  onesWords = [
     this.zeroWord, 'uno', 'due', 'tre', 'quattro', 'cinque', 'sei', 'sette', 'otto',
     'nove', 'dieci', 'undici', 'dodici', 'tredici', 'quattordici', 'quindici',
     'sedici', 'diciassette', 'diciotto', 'diciannove'
   ]
 
-  strTens = { 2: 'venti', 3: 'trenta', 4: 'quaranta', 6: 'sessanta' }
+  tensWords = { 2: 'venti', 3: 'trenta', 4: 'quaranta', 6: 'sessanta' }
 
   exponentPrefixes = [this.zeroWord, 'm', 'b', 'tr', 'quadr', 'quint', 'sest', 'sett', 'ott', 'nov', 'dec']
 
+  /** Adds accent to final "tre" in compound words (ventitré). */
   accentuate (string) {
     const splittedString = string.split(' ')
 
@@ -44,44 +33,51 @@ export class Italian extends GreedyScaleLanguage {
     return result.join(' ')
   }
 
+  /** Omits word if it represents zero. */
   omitIfZero (numberToString) {
     return numberToString === this.zeroWord ? '' : numberToString
   }
 
+  /** Removes duplicate vowels for phonetic contractions. */
   phoneticContraction (string) {
     return string.replaceAll('oo', 'o').replaceAll('ao', 'o').replaceAll('io', 'o').replaceAll('au', 'u').replaceAll('iu', 'u')
   }
 
+  /** Converts tens (20-99) with phonetic contractions. */
   tensToCardinal (number) {
     const tens = Math.floor(number / 10)
     const units = number % 10
-    const prefix = Object.prototype.hasOwnProperty.call(this.strTens, tens) ? this.strTens[tens] : this.cardinalWords[tens].slice(0, -1) + 'anta'
-    const postfix = this.omitIfZero(this.cardinalWords[units])
+    const prefix = Object.prototype.hasOwnProperty.call(this.tensWords, tens) ? this.tensWords[tens] : this.onesWords[tens].slice(0, -1) + 'anta'
+    const postfix = this.omitIfZero(this.onesWords[units])
     return this.phoneticContraction(prefix + postfix)
   }
 
+  /** Converts hundreds (100-999) with "cento" composition. */
   hundredsToCardinal (number) {
     const hundreds = Math.floor(number / 100)
     let prefix = 'cento'
     if (hundreds !== 1) {
-      prefix = this.cardinalWords[hundreds] + prefix
+      prefix = this.onesWords[hundreds] + prefix
     }
-    const postfix = this.omitIfZero(this.convertWholePart(number % 100))
+    const postfix = this.omitIfZero(this.integerToWords(number % 100))
     return this.phoneticContraction(prefix + postfix)
   }
 
+  /** Converts thousands (1000-999999) with "mille/mila" composition. */
   thousandsToCardinal (number) {
     const thousands = Math.floor(number / 1000)
-    const prefix = thousands === 1 ? 'mille' : this.convertWholePart(thousands) + 'mila'
-    const postfix = this.omitIfZero(this.convertWholePart(number % 1000))
+    const prefix = thousands === 1 ? 'mille' : this.integerToWords(thousands) + 'mila'
+    const postfix = this.omitIfZero(this.integerToWords(number % 1000))
     return prefix + postfix
   }
 
+  /** Converts exponent length to Italian scale word (milione, miliardo, etc.). */
   exponentLengthToString (exponentLength) {
     const prefix = this.exponentPrefixes[Math.floor(exponentLength / 6)]
     return exponentLength % 6 === 0 ? prefix + 'ilione' : prefix + 'iliardo'
   }
 
+  /** Converts large numbers (millions and above) with exponent-based naming. */
   bigNumberToCardinal (number) {
     const digits = [...number.toString()]
 
@@ -99,7 +95,7 @@ export class Italian extends GreedyScaleLanguage {
     if (multiplier.join('') === '1') {
       prefix = 'un '
     } else {
-      prefix = this.convertWholePart(Math.trunc(Number(multiplier.join(''))))
+      prefix = this.integerToWords(Math.trunc(Number(multiplier.join(''))))
       infix = ' ' + infix.slice(0, -1) + 'i' // without last element
     }
 
@@ -107,7 +103,7 @@ export class Italian extends GreedyScaleLanguage {
     if (isSetsEqual(new Set(exponent), new Set(['0']))) {
       postfix = ''
     } else {
-      postfix = this.convertWholePart(Math.trunc(exponent.join('')))
+      postfix = this.integerToWords(Math.trunc(exponent.join('')))
 
       infix += (postfix.includes(' e ') ? ', ' : ' e ')
     }
@@ -115,34 +111,22 @@ export class Italian extends GreedyScaleLanguage {
     return prefix + infix + postfix
   }
 
-  convertWholePart (number) {
+  /** Converts integer part using Italian custom algorithm with accentuation. */
+  integerToWords (integerPart) {
     let words = ''
 
-    if (number < 20) {
-      words = this.cardinalWords[number]
-    } else if (number < 100) {
-      words = this.tensToCardinal(Number(number))
-    } else if (number < 1000) {
-      words = this.hundredsToCardinal(Number(number))
-    } else if (number < 1_000_000) {
-      words = this.thousandsToCardinal(Number(number))
+    if (integerPart < 20) {
+      words = this.onesWords[integerPart]
+    } else if (integerPart < 100) {
+      words = this.tensToCardinal(Number(integerPart))
+    } else if (integerPart < 1000) {
+      words = this.hundredsToCardinal(Number(integerPart))
+    } else if (integerPart < 1_000_000) {
+      words = this.thousandsToCardinal(Number(integerPart))
     } else {
-      words = this.bigNumberToCardinal(number)
+      words = this.bigNumberToCardinal(integerPart)
     }
 
     return this.accentuate(words)
   }
 }
-
-/**
- * Converts a number to Italian cardinal (written) form.
- *
- * @param {number|string|bigint} value The number to convert.
- * @param {Object} [options={}] Configuration options.
- * @returns {string} The number expressed in Italian 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 Italian(options).convertToWords(value)
-}

package/lib/languages/ja.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Japanese language converter.
+ *
+ * Supports:
+ * - Kanji numerals (一, 二, 三, etc.)
+ * - Grouping by 万 (10,000) instead of 1,000
+ * - Special 一 (one) omission rules (十, 百, 千 but 一万, 一億)
+ */
+export class Japanese extends AbstractLanguage {
+    onesWords: string[];
+    scaleWords: string[];
+    /** Converts a segment of up to 4 digits to Japanese kanji with 一 omission rules. */
+    segmentToWords(num: any): string;
+    /** Converts integer part using Japanese 万-based grouping system. */
+    integerToWords(integerPart: any): string;
+}
+import { AbstractLanguage } from '../classes/abstract-language.js';