n2words 1.24.0 → 2.0.0

package/lib/languages/vi.js

@@ -1,37 +1,19 @@
-import AbstractLanguage from '../classes/abstract-language.js'
+import { AbstractLanguage } from '../classes/abstract-language.js'
 
 /**
  * Vietnamese language converter.
  *
- * Converts numbers to Vietnamese words following Vietnamese number naming:
- * - Base-10 grouping system (trăm = hundred, nghìn = thousand, triệu = million, tỷ = billion)
- * - Special pronunciation rules for 5 and 15 (lăm instead of năm)
- * - Special pronunciation for final 1 in compound numbers (mốt instead of một)
- * - "Lẻ" (odd/extra) used when tens place is zero but units exist
- *
- * Key Features:
- * - Base number mapping for 0-19 (with special forms)
- * - Tens mapping (hai mươi, ba mươi, etc.)
- * - Group-based algorithm:
- *   1. Split number into groups of 3 digits
- *   2. For each group, build words using special pronunciation rules:
- *      - "Mốt" instead of "một" for final 1 (e.g., 21 → hai mươi mốt)
- *      - "Lăm" instead of "năm" for 15 and mid-group 5 (e.g., 15, 105)
- *      - "Lẻ" prefix when tens=0 but units>0 (e.g., 101 → một trăm lẻ một)
- *   3. Append magnitude word (nghìn/triệu/tỷ)
- *   4. Join all groups with spaces
- * - Support for large numbers up to vigintillions
- *
- * Features:
- * - Natural Vietnamese number flow
- * - Proper handling of special cases (mốt, lăm)
- * - Contextual pronunciation adjustments
+ * Supports:
+ * - Special pronunciation rules (lăm for 5, mốt for final 1)
+ * - "Lẻ" (odd/extra) when tens place is zero
+ * - Vietnamese diacritical marks
  */
 export class Vietnamese extends AbstractLanguage {
   negativeWord = 'âm'
   decimalSeparatorWord = 'phẩy'
   zeroWord = 'không'
-  base = {
+
+  belowTwentyWords = {
     0: 'không',
     1: 'một',
     2: 'hai',
@@ -54,7 +36,7 @@ export class Vietnamese extends AbstractLanguage {
     19: 'mười chín'
   }
 
-  tens = {
+  twentiesWords = {
     20: 'hai mươi',
     30: 'ba mươi',
     40: 'bốn mươi',
@@ -65,7 +47,7 @@ export class Vietnamese extends AbstractLanguage {
     90: 'chín mươi'
   }
 
-  thousands = {
+  scaleWords = {
     1: 'nghìn', // 10^1
     2: 'triệu', // 10^2
     3: 'tỷ', // 10^3
@@ -88,20 +70,15 @@ export class Vietnamese extends AbstractLanguage {
     20: 'Vigintillion'
   }
 
-  /**
-   * Convert numbers less than 100 to Vietnamese words.
-   *
-   * @param {number} number The number to convert (0-99).
-   * @returns {string} The Vietnamese representation.
-   */
+  /** Convert numbers less than 100 to Vietnamese words. */
   convertLess100 (number) {
     const unitsPart = number % 10
     const tensPart = number - unitsPart
-    const tensPartText = this.tens[tensPart]
+    const tensPartText = this.twentiesWords[tensPart]
     if (unitsPart === 0) {
       return tensPartText
     }
-    const unitsPartText = this.base[unitsPart]
+    const unitsPartText = this.belowTwentyWords[unitsPart]
     let suffix = unitsPartText
     if (unitsPart === 1) {
       suffix = 'mốt'
@@ -112,18 +89,13 @@ export class Vietnamese extends AbstractLanguage {
     return tensPartText + ' ' + suffix
   }
 
-  /**
-   * Convert numbers less than 1000 to Vietnamese words.
-   *
-   * @param {number} number The number to convert (0-999).
-   * @returns {string} The Vietnamese representation.
-   */
+  /** Convert numbers less than 1000 to Vietnamese words. */
   convertLess1000 (number) {
     const words = []
     const tensUnitsPart = number % 100
     const hundredsPart = number - tensUnitsPart
     if (hundredsPart > 0) {
-      words.push(this.base[hundredsPart / 100], 'trăm')
+      words.push(this.belowTwentyWords[hundredsPart / 100], 'trăm')
     }
     if (tensUnitsPart > 0 && tensUnitsPart < 10) {
       if (words.length > 0) {
@@ -132,21 +104,16 @@ export class Vietnamese extends AbstractLanguage {
       if (tensUnitsPart === 5) {
         words.push('năm')
       } else {
-        words.push(this.base[tensUnitsPart])
+        words.push(this.belowTwentyWords[tensUnitsPart])
       }
     }
     if (tensUnitsPart >= 10) {
-      words.push(this.convertWholePart(tensUnitsPart))
+      words.push(this.integerToWords(tensUnitsPart))
     }
     return words.join(' ')
   }
 
-  /**
-   * Convert numbers greater than 1000 to Vietnamese words.
-   *
-   * @param {bigint} number The number to convert (>= 1000).
-   * @returns {string} The Vietnamese representation.
-   */
+  /** Convert numbers greater than 1000 to Vietnamese words. */
   convertMore1000 (number) {
     const words = []
     let division = number / 1000n
@@ -156,38 +123,25 @@ export class Vietnamese extends AbstractLanguage {
       power = power + 1
     }
     const r = number - (division * BigInt(Math.pow(1000, power)))
-    words.push(this.convertWholePart(division), this.thousands[power])
+    words.push(this.integerToWords(division), this.scaleWords[power])
     if (r > 0n) {
       if (r <= 99n) {
         words.push('lẻ')
       }
-      words.push(this.convertWholePart(r))
+      words.push(this.integerToWords(r))
     }
     return words.join(' ')
   }
 
-  convertWholePart (number) {
-    if (number < 20n) {
-      return this.base[Number(number)]
+  integerToWords (integerPart) {
+    if (integerPart < 20n) {
+      return this.belowTwentyWords[Number(integerPart)]
     } else {
-      if (number < 100n) {
-        return this.convertLess100(Number(number))
+      if (integerPart < 100n) {
+        return this.convertLess100(Number(integerPart))
       } else {
-        return (number < 1000n ? this.convertLess1000(Number(number)) : this.convertMore1000(number))
+        return (integerPart < 1000n ? this.convertLess1000(Number(integerPart)) : this.convertMore1000(integerPart))
       }
     }
   }
 }
-
-/**
- * Converts a number to Vietnamese cardinal (written) form.
- *
- * @param {number|string|bigint} value The number to convert.
- * @param {Object} [options={}] Configuration options.
- * @returns {string} The number expressed in Vietnamese 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 Vietnamese(options).convertToWords(value)
-}

package/lib/languages/zh-Hans.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Simplified Chinese language converter.
+ *
+ * Supports:
+ * - Simplified Chinese characters (简体中文)
+ * - No word separators (concatenated format)
+ * - Optional formal (financial) vs common numerals
+ */
+export class SimplifiedChinese extends GreedyScaleLanguage {
+    constructor(options?: {});
+    scaleWords: (string | bigint)[][];
+    /** Combines two word-sets according to Chinese grammar rules. */
+    combineWordSets(preceding: any, following: any): any;
+    /** Returns the number of digits in a number. */
+    digit(number_: any): any;
+    /** Counts the number of zero digits in a number. */
+    zeroDigit(number_: any): number;
+    /** Converts decimal digits to words by reading each digit individually. */
+    decimalDigitsToWords(decimalString: any): string[];
+}
+import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js';

package/lib/languages/zh-Hans.js

@@ -1,37 +1,28 @@
-import GreedyScaleLanguage from '../classes/greedy-scale-language.js'
+import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js'
 
 /**
- * @typedef {Object} ChineseOptions
- * @property {boolean} [formal=true] Use formal/financial numerals (壹贰叁) vs. common numerals (一二三).
- */
-
-/**
- * Chinese language converter.
+ * Simplified Chinese language converter.
  *
- * Features:
- * - Concatenated number-word format (no spaces)
- * - Implicit zero insertion for positional values
- * - Decimal digits pronounced individually
- * - Supports both formal (financial) and common (everyday) styles
+ * Supports:
+ * - Simplified Chinese characters (简体中文)
+ * - No word separators (concatenated format)
+ * - Optional formal (financial) vs common numerals
  */
-export class Chinese extends GreedyScaleLanguage {
+export class SimplifiedChinese extends GreedyScaleLanguage {
   negativeWord = '负'
   decimalSeparatorWord = '点'
   zeroWord = '零'
   wordSeparator = ''
 
-  /**
-   * Initializes the Chinese converter.
-   *
-   * @param {ChineseOptions} [options={}] Configuration options.
-   */
-  constructor ({ formal = true } = {}) {
+  constructor (options = {}) {
     super()
 
-    this.formal = formal
+    this.setOptions({
+      formal: true
+    }, options)
 
-    if (this.formal) {
-      this.scaleWordPairs = [
+    if (this.options.formal) {
+      this.scaleWords = [
         [1_000_000_000_000n, '万'],
         [100_000_000n, '亿'],
         [10_000n, '万'],
@@ -50,7 +41,7 @@ export class Chinese extends GreedyScaleLanguage {
         [0n, '零']
       ]
     } else {
-      this.scaleWordPairs = [
+      this.scaleWords = [
         [1_000_000_000_000n, '万'],
         [100_000_000n, '亿'],
         [10_000n, '万'],
@@ -71,95 +62,50 @@ export class Chinese extends GreedyScaleLanguage {
     }
   }
 
-  /**
-   * Merges two adjacent word-number pairs according to Chinese grammar rules.
-   *
-   * Chinese-specific rules:
-   * - Omits '一' (or '壹' in formal style) before single digits (< 10)
-   * - Concatenates without space
-   * - Inserts '零' (zero) when positional values skip magnitude levels
-   * - Multiplies when right > left, adds otherwise
-   *
-   * @param {Object} leftPair The left operand as `{ word: number }`.
-   * @param {Object} rightPair The right operand as `{ word: number }`.
-   * @returns {Object} Merged pair with combined word and resulting number.
-   */
-  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 according to Chinese grammar 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 1 before single digits (< 10)
-    if (leftNumber === 1n && rightNumber < 10n) {
-      return rightPair
+    if (precedingValue === 1n && followingValue < 10n) {
+      return following
     }
 
-    // Multiply when right > left (scale words like 千, 万, 亿)
-    if (rightNumber > leftNumber) {
-      return { [`${leftWord}${rightWord}`]: leftNumber * rightNumber }
+    // Multiply when following > preceding (scale words like 仁, 万, 亿)
+    if (followingValue > precedingValue) {
+      return { [`${precedingWord}${followingWord}`]: precedingValue * followingValue }
     }
 
     // Insert "零" (zero) when position skip levels (e.g., 1003 = 千零三)
-    // zeroDigit() checks if gap exists between left and right magnitude
-    if (this.zeroDigit(leftNumber) > this.digit(rightNumber)) {
-      return { [`${leftWord}${this.zeroWord}${rightWord}`]: leftNumber + rightNumber }
+    // zeroDigit() checks if gap exists between preceding and following magnitude
+    if (this.zeroDigit(precedingValue) > this.digit(followingValue)) {
+      return { [`${precedingWord}${this.zeroWord}${followingWord}`]: precedingValue + followingValue }
     }
 
     // Default: concatenate without zero insertion
-    return { [`${leftWord}${rightWord}`]: leftNumber + rightNumber }
+    return { [`${precedingWord}${followingWord}`]: precedingValue + followingValue }
   }
 
-  /**
-   * Get the number of digits in a number.
-   *
-   * @param {bigint|number} number_ The number to count digits for.
-   * @returns {number} The count of digits.
-   */
+  /** Returns the number of digits in a number. */
   digit (number_) {
     return number_.toString().length
   }
 
-  /**
-   * Count the number of zeros in a number.
-   *
-   * @param {bigint|number} number_ The number to count zeros in.
-   * @returns {number} The count of zero digits.
-   */
+  /** Counts the number of zero digits in a number. */
   zeroDigit (number_) {
     return [...number_.toString()].filter(c => c === '0').length
   }
 
-  /**
-   * Convert decimal digits to words by reading each digit individually.
-   * Overrides the default grouped behavior from AbstractLanguage.
-   *
-   * @param {string} decimalString The decimal digits as a string.
-   * @returns {Array<string>} Array of individual digit words.
-   */
+  /** Converts decimal digits to words by reading each digit individually. */
   decimalDigitsToWords (decimalString) {
     const words = []
     for (let i = 0; i < decimalString.length; i++) {
       const digitValue = BigInt(decimalString[i])
-      words.push(this.convertWholePart(digitValue))
+      words.push(this.integerToWords(digitValue))
     }
     return words
   }
 }
-
-/**
- * Converts a number to Chinese cardinal (written) form.
- *
- * @param {number|string|bigint} value The number to convert.
- * @param {ChineseOptions} [options] Conversion options.
- * @returns {string} The number expressed in Chinese words.
- * @throws {TypeError} If value is NaN or invalid type.
- * @throws {Error} If value is an invalid number string.
- *
- * @example
- * convertToWords(42); // '肆拾贰' (formal style)
- * convertToWords(42, { formal: false }); // '四十二' (common style)
- */
-export default function convertToWords (value, options = {}) {
-  return new Chinese(options).convertToWords(value)
-}

package/lib/languages/zh-Hant.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Traditional Chinese language converter.
+ *
+ * Supports:
+ * - Traditional Chinese characters (繁體中文)
+ * - No word separators (concatenated format)
+ * - Optional formal (financial) vs common numerals
+ */
+export class TraditionalChinese extends GreedyScaleLanguage {
+    constructor(options?: {});
+    scaleWords: (string | bigint)[][];
+    /** Combines two word-sets with Traditional Chinese grammar rules and zero insertion. */
+    combineWordSets(preceding: any, following: any): any;
+    /** Returns the number of digits in a number. */
+    digit(number_: any): any;
+    /** Counts the number of zero digits in a number. */
+    zeroDigit(number_: any): number;
+    /** Converts decimal digits to words by reading each digit individually. */
+    decimalDigitsToWords(decimalString: any): string[];
+}
+import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js';

package/lib/languages/zh-Hant.js

@@ -0,0 +1,111 @@
+import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js'
+
+/**
+ * Traditional Chinese language converter.
+ *
+ * Supports:
+ * - Traditional Chinese characters (繁體中文)
+ * - No word separators (concatenated format)
+ * - Optional formal (financial) vs common numerals
+ */
+export class TraditionalChinese extends GreedyScaleLanguage {
+  negativeWord = '負'
+  decimalSeparatorWord = '點'
+  zeroWord = '零'
+  wordSeparator = ''
+
+  constructor (options = {}) {
+    super()
+
+    this.setOptions({
+      formal: true
+    }, options)
+
+    if (this.options.formal) {
+      this.scaleWords = [
+        [1_000_000_000_000n, '萬'],
+        [100_000_000n, '億'],
+        [10_000n, '萬'],
+        [1000n, '仟'],
+        [100n, '佰'],
+        [10n, '拾'],
+        [9n, '玖'],
+        [8n, '捌'],
+        [7n, '柒'],
+        [6n, '陸'],
+        [5n, '伍'],
+        [4n, '肆'],
+        [3n, '參'],
+        [2n, '貳'],
+        [1n, '壹'],
+        [0n, '零']
+      ]
+    } else {
+      this.scaleWords = [
+        [1_000_000_000_000n, '萬'],
+        [100_000_000n, '億'],
+        [10_000n, '萬'],
+        [1000n, '千'],
+        [100n, '百'],
+        [10n, '十'],
+        [9n, '九'],
+        [8n, '八'],
+        [7n, '七'],
+        [6n, '六'],
+        [5n, '五'],
+        [4n, '四'],
+        [3n, '三'],
+        [2n, '二'],
+        [1n, '一'],
+        [0n, '零']
+      ]
+    }
+  }
+
+  /** Combines two word-sets with Traditional Chinese grammar rules and zero insertion. */
+  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 1 before single digits (< 10)
+    if (precedingValue === 1n && followingValue < 10n) {
+      return following
+    }
+
+    // Multiply when following > preceding (scale words like 千, 萬, 億)
+    if (followingValue > precedingValue) {
+      return { [`${precedingWord}${followingWord}`]: precedingValue * followingValue }
+    }
+
+    // Insert "零" (zero) when position skip levels (e.g., 1003 = 千零三)
+    // zeroDigit() checks if gap exists between preceding and following magnitude
+    if (this.zeroDigit(precedingValue) > this.digit(followingValue)) {
+      return { [`${precedingWord}${this.zeroWord}${followingWord}`]: precedingValue + followingValue }
+    }
+
+    // Default: concatenate without zero insertion
+    return { [`${precedingWord}${followingWord}`]: precedingValue + followingValue }
+  }
+
+  /** Returns the number of digits in a number. */
+  digit (number_) {
+    return number_.toString().length
+  }
+
+  /** Counts the number of zero digits in a number. */
+  zeroDigit (number_) {
+    return [...number_.toString()].filter(c => c === '0').length
+  }
+
+  /** Converts decimal digits to words by reading each digit individually. */
+  decimalDigitsToWords (decimalString) {
+    const words = []
+    for (let i = 0; i < decimalString.length; i++) {
+      const digitValue = BigInt(decimalString[i])
+      words.push(this.integerToWords(digitValue))
+    }
+    return words
+  }
+}