n2words 1.24.0 → 3.0.0

package/lib/languages/zh-Hans.js

@@ -1,165 +1,182 @@
-import GreedyScaleLanguage from '../classes/greedy-scale-language.js'
-
 /**
- * @typedef {Object} ChineseOptions
- * @property {boolean} [formal=true] Use formal/financial numerals (壹贰叁) vs. common numerals (一二三).
+ * Simplified Chinese language converter - Functional Implementation
+ *
+ * Self-contained converter for Simplified Chinese.
+ *
+ * Key features:
+ * - Myriad-based (万, 亿) grouping - 4 digits
+ * - Formal (financial) vs common numerals
+ * - Zero insertion for skipped positions
+ * - No word separators (concatenated format)
  */
 
+import { parseNumericValue } from '../utils/parse-numeric.js'
+import { validateOptions } from '../utils/validate-options.js'
+
+// ============================================================================
+// Vocabulary
+// ============================================================================
+
+// Common (everyday) numerals
+const ONES_COMMON = ['零', '一', '二', '三', '四', '五', '六', '七', '八', '九']
+const TEN_COMMON = '十'
+const HUNDRED_COMMON = '百'
+const THOUSAND_COMMON = '千'
+
+// Formal (financial) numerals - harder to alter/forge
+const ONES_FORMAL = ['零', '壹', '贰', '叁', '肆', '伍', '陆', '柒', '捌', '玖']
+const TEN_FORMAL = '拾'
+const HUNDRED_FORMAL = '佰'
+const THOUSAND_FORMAL = '仟'
+
+// Scale words
+const WAN_WORD = '万' // 10,000
+const YI_WORD = '亿' // 100,000,000
+
+const ZERO = '零'
+const NEGATIVE = '负'
+const DECIMAL_SEP = '点'
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
 /**
- * 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
+ * Convert number below 万 (10,000) to words using direct string concatenation.
  */
-export class Chinese extends GreedyScaleLanguage {
-  negativeWord = '负'
-  decimalSeparatorWord = '点'
-  zeroWord = '零'
-  wordSeparator = ''
-
-  /**
-   * Initializes the Chinese converter.
-   *
-   * @param {ChineseOptions} [options={}] Configuration options.
-   */
-  constructor ({ formal = true } = {}) {
-    super()
-
-    this.formal = formal
-
-    if (this.formal) {
-      this.scaleWordPairs = [
-        [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.scaleWordPairs = [
-        [1_000_000_000_000n, '万'],
-        [100_000_000n, '亿'],
-        [10_000n, '万'],
-        [1000n, '千'],
-        [100n, '百'],
-        [10n, '十'],
-        [9n, '九'],
-        [8n, '八'],
-        [7n, '七'],
-        [6n, '六'],
-        [5n, '五'],
-        [4n, '四'],
-        [3n, '三'],
-        [2n, '二'],
-        [1n, '一'],
-        [0n, '零']
-      ]
-    }
-  }
+function convertBelowWan (value, ones, ten, hundred, thousand) {
+  if (value === 0n) return ''
 
-  /**
-   * 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]
-
-    // Implicit one: omit 1 before single digits (< 10)
-    if (leftNumber === 1n && rightNumber < 10n) {
-      return rightPair
-    }
+  let result = ''
+  let needsZero = false
 
-    // Multiply when right > left (scale words like 千, 万, 亿)
-    if (rightNumber > leftNumber) {
-      return { [`${leftWord}${rightWord}`]: leftNumber * rightNumber }
-    }
+  // Thousands (千)
+  const thousandsVal = value / 1000n
+  const thousandsRemainder = value % 1000n
+  if (thousandsVal > 0n) {
+    result = ones[Number(thousandsVal)] + thousand
+    needsZero = thousandsRemainder > 0n && thousandsRemainder < 100n
+  }
 
-    // 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 }
-    }
+  // Hundreds (百)
+  const hundredsVal = thousandsRemainder / 100n
+  const hundredsRemainder = thousandsRemainder % 100n
+  if (hundredsVal > 0n) {
+    if (needsZero) result += ZERO
+    result += ones[Number(hundredsVal)] + hundred
+    needsZero = hundredsRemainder > 0n && hundredsRemainder < 10n
+  } else if (thousandsVal > 0n && hundredsRemainder > 0n) {
+    needsZero = true
+  }
 
-    // Default: concatenate without zero insertion
-    return { [`${leftWord}${rightWord}`]: leftNumber + rightNumber }
+  // Tens (十)
+  const tensVal = hundredsRemainder / 10n
+  const onesVal = hundredsRemainder % 10n
+  if (tensVal > 0n) {
+    if (needsZero) result += ZERO
+    result += ones[Number(tensVal)] + ten
+    needsZero = false
+  } else if ((hundredsVal > 0n || thousandsVal > 0n) && onesVal > 0n) {
+    needsZero = true
   }
 
-  /**
-   * Get the number of digits in a number.
-   *
-   * @param {bigint|number} number_ The number to count digits for.
-   * @returns {number} The count of digits.
-   */
-  digit (number_) {
-    return number_.toString().length
+  // Ones
+  if (onesVal > 0n) {
+    if (needsZero) result += ZERO
+    result += ones[Number(onesVal)]
   }
 
-  /**
-   * 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.
-   */
-  zeroDigit (number_) {
-    return [...number_.toString()].filter(c => c === '0').length
+  return result
+}
+
+/**
+ * Convert number below 亿 (100 million) to words.
+ */
+function convertBelowYi (value, ones, ten, hundred, thousand) {
+  if (value === 0n) return ''
+
+  if (value >= 10_000n) {
+    const wanValue = value / 10_000n
+    const wanRemainder = value % 10_000n
+
+    let result = convertBelowWan(wanValue, ones, ten, hundred, thousand) + WAN_WORD
+
+    if (wanRemainder > 0n) {
+      const needsZero = (wanValue % 10n === 0n) || (wanRemainder < 1000n)
+      if (needsZero) result += ZERO
+      result += convertBelowWan(wanRemainder, ones, ten, hundred, thousand)
+    }
+
+    return result
   }
 
-  /**
-   * 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.
-   */
-  decimalDigitsToWords (decimalString) {
-    const words = []
-    for (let i = 0; i < decimalString.length; i++) {
-      const digitValue = BigInt(decimalString[i])
-      words.push(this.convertWholePart(digitValue))
+  return convertBelowWan(value, ones, ten, hundred, thousand)
+}
+
+function integerToWords (n, formal = true) {
+  if (n === 0n) return ZERO
+
+  const ones = formal ? ONES_FORMAL : ONES_COMMON
+  const ten = formal ? TEN_FORMAL : TEN_COMMON
+  const hundred = formal ? HUNDRED_FORMAL : HUNDRED_COMMON
+  const thousand = formal ? THOUSAND_FORMAL : THOUSAND_COMMON
+
+  // Handle numbers >= 亿 (100 million)
+  if (n >= 100_000_000n) {
+    const yiValue = n / 100_000_000n
+    const yiRemainder = n % 100_000_000n
+
+    let result = convertBelowYi(yiValue, ones, ten, hundred, thousand) + YI_WORD
+
+    if (yiRemainder > 0n) {
+      if (yiRemainder < 10_000_000n) result += ZERO
+      result += convertBelowYi(yiRemainder, ones, ten, hundred, thousand)
     }
-    return words
+
+    return result
   }
+
+  return convertBelowYi(n, ones, ten, hundred, thousand)
 }
 
 /**
- * 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.
+ * Convert decimal digits to words using direct concatenation.
+ */
+function decimalDigitsToWords (decimalString, ones) {
+  let result = ''
+  for (let i = 0; i < decimalString.length; i++) {
+    result += ones[Number(decimalString[i])]
+  }
+  return result
+}
+
+/**
+ * Converts a numeric value to Simplified Chinese words.
  *
- * @example
- * convertToWords(42); // '肆拾贰' (formal style)
- * convertToWords(42, { formal: false }); // '四十二' (common style)
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @param {Object} [options] - Optional configuration
+ * @param {boolean} [options.formal=true] - Use formal/financial numerals
+ * @returns {string} The number in Simplified Chinese words
  */
-export default function convertToWords (value, options = {}) {
-  return new Chinese(options).convertToWords(value)
+function toWords (value, options) {
+  options = validateOptions(options)
+  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+  const formal = options.formal !== false // Default to true
+
+  let result = isNegative ? NEGATIVE : ''
+
+  result += integerToWords(integerPart, formal)
+
+  if (decimalPart) {
+    const ones = formal ? ONES_FORMAL : ONES_COMMON
+    result += DECIMAL_SEP + decimalDigitsToWords(decimalPart, ones)
+  }
+
+  return result
 }
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export { toWords }

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

@@ -0,0 +1,11 @@
+/**
+ * Converts a numeric value to Traditional Chinese words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @param {Object} [options] - Optional configuration
+ * @param {boolean} [options.formal=true] - Use formal/financial numerals
+ * @returns {string} The number in Traditional Chinese words
+ */
+export function toWords(value: number | string | bigint, options?: {
+    formal?: boolean | undefined;
+}): string;

package/lib/languages/zh-Hant.js

@@ -0,0 +1,202 @@
+/**
+ * Traditional Chinese language converter - Functional Implementation
+ *
+ * Self-contained converter for Traditional Chinese.
+ *
+ * Key features:
+ * - Myriad-based (萬, 億) grouping - 4 digits
+ * - Formal (financial) vs common numerals
+ * - Zero insertion for skipped positions
+ * - No word separators (concatenated format)
+ *
+ * Differences from Simplified:
+ * - Different character forms (e.g., 負/负, 點/点, 億/亿, 萬/万)
+ * - Some formal numerals differ (參/叁, 貳/贰, 陸/陆)
+ */
+
+import { parseNumericValue } from '../utils/parse-numeric.js'
+import { validateOptions } from '../utils/validate-options.js'
+
+// ============================================================================
+// Vocabulary
+// ============================================================================
+
+// Common (everyday) numerals - Traditional forms
+const ONES_COMMON = ['零', '一', '二', '三', '四', '五', '六', '七', '八', '九']
+const TEN_COMMON = '十'
+const HUNDRED_COMMON = '百'
+const THOUSAND_COMMON = '千'
+
+// Formal (financial) numerals - Traditional forms
+const ONES_FORMAL = ['零', '壹', '貳', '參', '肆', '伍', '陸', '柒', '捌', '玖']
+const TEN_FORMAL = '拾'
+const HUNDRED_FORMAL = '佰'
+const THOUSAND_FORMAL = '仟'
+
+// Scale words - Traditional forms
+const WAN_WORD = '萬' // 10,000
+const YI_WORD = '億' // 100,000,000
+
+const ZERO = '零'
+const NEGATIVE = '負'
+const DECIMAL_SEP = '點'
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+function integerToWords (n, formal = true) {
+  if (n === 0n) return ZERO
+
+  const ones = formal ? ONES_FORMAL : ONES_COMMON
+  const ten = formal ? TEN_FORMAL : TEN_COMMON
+  const hundred = formal ? HUNDRED_FORMAL : HUNDRED_COMMON
+  const thousand = formal ? THOUSAND_FORMAL : THOUSAND_COMMON
+
+  // Convert number below 萬 (10,000)
+  function convertBelowWan (value) {
+    if (value === 0n) return ''
+
+    const parts = []
+    let needsZero = false
+
+    // Thousands (千)
+    const thousandsVal = value / 1000n
+    const thousandsRemainder = value % 1000n
+    if (thousandsVal > 0n) {
+      parts.push(ones[Number(thousandsVal)] + thousand)
+      needsZero = thousandsRemainder > 0n && thousandsRemainder < 100n
+    }
+
+    // Hundreds (百)
+    const hundredsVal = thousandsRemainder / 100n
+    const hundredsRemainder = thousandsRemainder % 100n
+    if (hundredsVal > 0n) {
+      if (needsZero) {
+        parts.push(ZERO)
+        needsZero = false
+      }
+      parts.push(ones[Number(hundredsVal)] + hundred)
+      needsZero = hundredsRemainder > 0n && hundredsRemainder < 10n
+    } else if (thousandsVal > 0n && hundredsRemainder > 0n) {
+      needsZero = true
+    }
+
+    // Tens (十)
+    const tensVal = hundredsRemainder / 10n
+    const onesVal = hundredsRemainder % 10n
+    if (tensVal > 0n) {
+      if (needsZero) {
+        parts.push(ZERO)
+        needsZero = false
+      }
+      parts.push(ones[Number(tensVal)] + ten)
+    } else if ((hundredsVal > 0n || thousandsVal > 0n) && onesVal > 0n) {
+      needsZero = true
+    }
+
+    // Ones
+    if (onesVal > 0n) {
+      if (needsZero) {
+        parts.push(ZERO)
+      }
+      parts.push(ones[Number(onesVal)])
+    }
+
+    return parts.join('')
+  }
+
+  // Convert number below 億 (100 million)
+  function convertBelowYi (value) {
+    if (value === 0n) return ''
+
+    const parts = []
+
+    if (value >= 10_000n) {
+      const wanValue = value / 10_000n
+      const wanRemainder = value % 10_000n
+
+      parts.push(convertBelowWan(wanValue) + WAN_WORD)
+
+      if (wanRemainder > 0n) {
+        const wanEndsWithZero = wanValue % 10n === 0n
+        const remainderMissesThousands = wanRemainder < 1000n
+        const needsZero = wanEndsWithZero || remainderMissesThousands
+        if (needsZero) {
+          parts.push(ZERO)
+        }
+        parts.push(convertBelowWan(wanRemainder))
+      }
+    } else {
+      parts.push(convertBelowWan(value))
+    }
+
+    return parts.join('')
+  }
+
+  // Main conversion
+  const parts = []
+
+  if (n >= 100_000_000n) {
+    const yiValue = n / 100_000_000n
+    const yiRemainder = n % 100_000_000n
+
+    const yiWords = convertBelowYi(yiValue)
+    parts.push(yiWords + YI_WORD)
+
+    if (yiRemainder > 0n) {
+      const needsZero = yiRemainder < 10_000_000n
+      if (needsZero) {
+        parts.push(ZERO)
+      }
+      parts.push(convertBelowYi(yiRemainder))
+    }
+  } else {
+    parts.push(convertBelowYi(n))
+  }
+
+  return parts.join('')
+}
+
+function decimalDigitsToWords (decimalString, formal = true) {
+  const ones = formal ? ONES_FORMAL : ONES_COMMON
+  const words = []
+  for (const char of decimalString) {
+    words.push(ones[Number(char)])
+  }
+  return words
+}
+
+/**
+ * Converts a numeric value to Traditional Chinese words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @param {Object} [options] - Optional configuration
+ * @param {boolean} [options.formal=true] - Use formal/financial numerals
+ * @returns {string} The number in Traditional Chinese words
+ */
+function toWords (value, options) {
+  options = validateOptions(options)
+  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+  const formal = options.formal !== false // Default to true
+
+  let result = ''
+
+  if (isNegative) {
+    result = NEGATIVE
+  }
+
+  result += integerToWords(integerPart, formal)
+
+  if (decimalPart) {
+    result += DECIMAL_SEP + decimalDigitsToWords(decimalPart, formal).join('')
+  }
+
+  return result
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export { toWords }

package/lib/n2words.d.ts

@@ -0,0 +1,53 @@
+import { toWords as am } from './languages/am.js';
+import { toWords as amLatn } from './languages/am-Latn.js';
+import { toWords as ar } from './languages/ar.js';
+import { toWords as az } from './languages/az.js';
+import { toWords as bn } from './languages/bn.js';
+import { toWords as cs } from './languages/cs.js';
+import { toWords as da } from './languages/da.js';
+import { toWords as de } from './languages/de.js';
+import { toWords as el } from './languages/el.js';
+import { toWords as en } from './languages/en.js';
+import { toWords as es } from './languages/es.js';
+import { toWords as fa } from './languages/fa.js';
+import { toWords as fi } from './languages/fi.js';
+import { toWords as fil } from './languages/fil.js';
+import { toWords as fr } from './languages/fr.js';
+import { toWords as frBE } from './languages/fr-BE.js';
+import { toWords as gu } from './languages/gu.js';
+import { toWords as ha } from './languages/ha.js';
+import { toWords as hbo } from './languages/hbo.js';
+import { toWords as he } from './languages/he.js';
+import { toWords as hi } from './languages/hi.js';
+import { toWords as hr } from './languages/hr.js';
+import { toWords as hu } from './languages/hu.js';
+import { toWords as id } from './languages/id.js';
+import { toWords as it } from './languages/it.js';
+import { toWords as ja } from './languages/ja.js';
+import { toWords as kn } from './languages/kn.js';
+import { toWords as ko } from './languages/ko.js';
+import { toWords as lt } from './languages/lt.js';
+import { toWords as lv } from './languages/lv.js';
+import { toWords as mr } from './languages/mr.js';
+import { toWords as ms } from './languages/ms.js';
+import { toWords as nb } from './languages/nb.js';
+import { toWords as nl } from './languages/nl.js';
+import { toWords as pa } from './languages/pa.js';
+import { toWords as pl } from './languages/pl.js';
+import { toWords as pt } from './languages/pt.js';
+import { toWords as ro } from './languages/ro.js';
+import { toWords as ru } from './languages/ru.js';
+import { toWords as srCyrl } from './languages/sr-Cyrl.js';
+import { toWords as srLatn } from './languages/sr-Latn.js';
+import { toWords as sv } from './languages/sv.js';
+import { toWords as sw } from './languages/sw.js';
+import { toWords as ta } from './languages/ta.js';
+import { toWords as te } from './languages/te.js';
+import { toWords as th } from './languages/th.js';
+import { toWords as tr } from './languages/tr.js';
+import { toWords as uk } from './languages/uk.js';
+import { toWords as ur } from './languages/ur.js';
+import { toWords as vi } from './languages/vi.js';
+import { toWords as zhHans } from './languages/zh-Hans.js';
+import { toWords as zhHant } from './languages/zh-Hant.js';
+export { am, amLatn, ar, az, bn, cs, da, de, el, en, es, fa, fi, fil, fr, frBE, gu, ha, hbo, he, hi, hr, hu, id, it, ja, kn, ko, lt, lv, mr, ms, nb, nl, pa, pl, pt, ro, ru, srCyrl, srLatn, sv, sw, ta, te, th, tr, uk, ur, vi, zhHans, zhHant };