n2words 1.24.0 → 3.0.0

package/lib/languages/vi.js

@@ -1,193 +1,316 @@
-import AbstractLanguage from '../classes/abstract-language.js'
-
 /**
- * Vietnamese language converter.
+ * Vietnamese language converter - Functional Implementation v2
  *
- * 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
+ * A performance-optimized number-to-words converter using precomputed lookup tables.
+ * Self-contained module with its own input validation, ready for subpath exports.
  *
- * 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
+ * Key optimization: Precompute all segment values (0-999) at module load.
+ * This eliminates all per-call string manipulation for segment conversion.
  *
- * Features:
- * - Natural Vietnamese number flow
- * - Proper handling of special cases (mốt, lăm)
- * - Contextual pronunciation adjustments
+ * Vietnamese-specific rules (handled in precomputation):
+ * - Special pronunciation: "lăm" for 5 in tens position, "mốt" for final 1
+ * - "Lẻ" (odd/extra) marker when tens place is zero after hundreds/scales
+ * - Short scale system with Vietnamese words (nghìn, triệu, tỷ)
  */
-export class Vietnamese extends AbstractLanguage {
-  negativeWord = 'âm'
-  decimalSeparatorWord = 'phẩy'
-  zeroWord = 'không'
-  base = {
-    0: 'không',
-    1: 'một',
-    2: 'hai',
-    3: 'ba',
-    4: 'bốn',
-    5: 'năm',
-    6: 'sáu',
-    7: 'bảy',
-    8: 'tám',
-    9: 'chín',
-    10: 'mười',
-    11: 'mười một',
-    12: 'mười hai',
-    13: 'mười ba',
-    14: 'mười bốn',
-    15: 'mười lăm',
-    16: 'mười sáu',
-    17: 'mười bảy',
-    18: 'mười tám',
-    19: 'mười chín'
-  }
 
-  tens = {
-    20: 'hai mươi',
-    30: 'ba mươi',
-    40: 'bốn mươi',
-    50: 'năm mươi',
-    60: 'sáu mươi',
-    70: 'bảy mươi',
-    80: 'tám mươi',
-    90: 'chín mươi'
-  }
+import { parseNumericValue } from '../utils/parse-numeric.js'
+
+// ============================================================================
+// Vocabulary (module-level constants)
+// ============================================================================
+
+// Base vocabulary for building lookup tables
+const ONES = ['không', 'một', 'hai', 'ba', 'bốn', 'năm', 'sáu', 'bảy', 'tám', 'chín']
+
+// Scale words indexed by scale level (0 = units, 1 = thousands, etc.)
+const SCALES = [
+  '', 'nghìn', 'triệu', 'tỷ', 'nghìn tỷ', 'trăm nghìn tỷ',
+  'Quintillion', 'Sextillion', 'Septillion', 'Octillion',
+  'Nonillion', 'Decillion', 'Undecillion', 'Duodecillion',
+  'Tredecillion', 'Quattuordecillion', 'Sexdecillion',
+  'Septendecillion', 'Octodecillion', 'Novemdecillion', 'Vigintillion'
+]
+
+const HUNDRED = 'trăm'
+const ZERO = 'không'
+const NEGATIVE = 'âm'
+const DECIMAL_SEP = 'phẩy'
+const LE = 'lẻ' // "odd/extra" marker for gaps
+
+// Special forms
+const MOT_FINAL = 'mốt' // 1 in tens position (21, 31, etc.)
+const LAM = 'lăm' // 5 in tens position (25, 35, etc.)
+
+// ============================================================================
+// Precomputed Lookup Tables (built once at module load)
+// ============================================================================
+
+/**
+ * Builds word for 0-99 with special forms (mốt, lăm).
+ * Only used during table construction.
+ */
+function buildBelowHundred (n) {
+  if (n === 0) return ONES[0]
+  if (n < 10) return ONES[n]
 
-  thousands = {
-    1: 'nghìn', // 10^1
-    2: 'triệu', // 10^2
-    3: 'tỷ', // 10^3
-    4: 'nghìn tỷ',
-    5: 'trăm nghìn tỷ',
-    6: 'Quintillion',
-    7: 'Sextillion',
-    8: 'Septillion',
-    9: 'Octillion',
-    10: 'Nonillion',
-    11: 'Decillion',
-    12: 'Undecillion',
-    13: 'Duodecillion',
-    14: 'Tredecillion',
-    15: 'Quattuordecillion',
-    16: 'Sexdecillion',
-    17: 'Septendecillion',
-    18: 'Octodecillion',
-    19: 'Novemdecillion',
-    20: 'Vigintillion'
+  // Teens: 10-19
+  if (n < 20) {
+    const ones = n - 10
+    if (ones === 0) return 'mười'
+    if (ones === 5) return 'mười lăm'
+    return 'mười ' + ONES[ones]
   }
 
-  /**
-   * Convert numbers less than 100 to Vietnamese words.
-   *
-   * @param {number} number The number to convert (0-99).
-   * @returns {string} The Vietnamese representation.
-   */
-  convertLess100 (number) {
-    const unitsPart = number % 10
-    const tensPart = number - unitsPart
-    const tensPartText = this.tens[tensPart]
-    if (unitsPart === 0) {
-      return tensPartText
-    }
-    const unitsPartText = this.base[unitsPart]
-    let suffix = unitsPartText
-    if (unitsPart === 1) {
-      suffix = 'mốt'
-    }
-    if (unitsPart === 5) {
-      suffix = 'lăm'
-    }
-    return tensPartText + ' ' + suffix
+  // 20-99
+  const ones = n % 10
+  const tens = Math.floor(n / 10)
+  const tensWord = ONES[tens] + ' mươi'
+
+  if (ones === 0) return tensWord
+  if (ones === 1) return tensWord + ' ' + MOT_FINAL
+  if (ones === 5) return tensWord + ' ' + LAM
+  return tensWord + ' ' + ONES[ones]
+}
+
+/**
+ * Builds segment word for 0-999.
+ * Only used during table construction.
+ */
+function buildSegment (n) {
+  if (n === 0) return ''
+
+  const hundreds = Math.floor(n / 100)
+  const remainder = n % 100
+
+  let result = ''
+
+  if (hundreds > 0) {
+    result = ONES[hundreds] + ' ' + HUNDRED
   }
 
-  /**
-   * Convert numbers less than 1000 to Vietnamese words.
-   *
-   * @param {number} number The number to convert (0-999).
-   * @returns {string} The Vietnamese representation.
-   */
-  convertLess1000 (number) {
-    const words = []
-    const tensUnitsPart = number % 100
-    const hundredsPart = number - tensUnitsPart
-    if (hundredsPart > 0) {
-      words.push(this.base[hundredsPart / 100], 'trăm')
-    }
-    if (tensUnitsPart > 0 && tensUnitsPart < 10) {
-      if (words.length > 0) {
-        words.push('lẻ')
-      }
-      if (tensUnitsPart === 5) {
-        words.push('năm')
+  if (remainder > 0) {
+    if (remainder < 10) {
+      // Single digit after hundreds needs "lẻ"
+      if (result) {
+        result += ' ' + LE + ' '
+        // Use "năm" not "lăm" after lẻ
+        result += remainder === 5 ? 'năm' : ONES[remainder]
       } else {
-        words.push(this.base[tensUnitsPart])
+        result = ONES[remainder]
       }
+    } else {
+      // 10-99 after hundreds
+      if (result) result += ' '
+      result += BELOW_100[remainder]
     }
-    if (tensUnitsPart >= 10) {
-      words.push(this.convertWholePart(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.
-   */
-  convertMore1000 (number) {
-    const words = []
-    let division = number / 1000n
-    let power = 1
-    while (division >= 1000n) {
-      division = division / 1000n
-      power = power + 1
+  return result
+}
+
+// Precompute all 100 below-hundred words (0-99)
+// BELOW_100[n] gives the Vietnamese word for n
+const BELOW_100 = new Array(100)
+for (let i = 0; i < 100; i++) {
+  BELOW_100[i] = buildBelowHundred(i)
+}
+
+// Precompute all 1000 segment words (0-999)
+// SEGMENTS[n] gives the Vietnamese word for n within a segment
+const SEGMENTS = new Array(1000)
+for (let i = 0; i < 1000; i++) {
+  SEGMENTS[i] = buildSegment(i)
+}
+
+// Precompute "lẻ" prefixed versions for small remainders after scale words
+// LE_SEGMENTS[n] gives "lẻ X" for n in range 1-99
+const LE_SEGMENTS = new Array(100)
+LE_SEGMENTS[0] = ''
+for (let i = 1; i < 10; i++) {
+  // Use "năm" not "lăm" after lẻ
+  LE_SEGMENTS[i] = LE + ' ' + (i === 5 ? 'năm' : ONES[i])
+}
+for (let i = 10; i < 100; i++) {
+  LE_SEGMENTS[i] = LE + ' ' + BELOW_100[i]
+}
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Vietnamese words.
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} Vietnamese words
+ */
+function integerToWords (n) {
+  if (n === 0n) return ZERO
+
+  // Fast path: numbers < 100 (direct lookup)
+  if (n < 100n) {
+    return BELOW_100[Number(n)]
+  }
+
+  // Fast path: numbers < 1000 (direct lookup)
+  if (n < 1000n) {
+    return SEGMENTS[Number(n)]
+  }
+
+  // Fast path: numbers < 1,000,000 (thousands)
+  if (n < 1_000_000n) {
+    const thousands = Number(n / 1000n)
+    const remainder = Number(n % 1000n)
+
+    const thousandsWords = SEGMENTS[thousands] + ' ' + SCALES[1]
+
+    if (remainder === 0) {
+      return thousandsWords
     }
-    const r = number - (division * BigInt(Math.pow(1000, power)))
-    words.push(this.convertWholePart(division), this.thousands[power])
-    if (r > 0n) {
-      if (r <= 99n) {
-        words.push('lẻ')
-      }
-      words.push(this.convertWholePart(r))
+
+    // Check if remainder needs "lẻ" marker (< 100)
+    if (remainder < 100) {
+      return thousandsWords + ' ' + LE_SEGMENTS[remainder]
     }
-    return words.join(' ')
+
+    return thousandsWords + ' ' + SEGMENTS[remainder]
   }
 
-  convertWholePart (number) {
-    if (number < 20n) {
-      return this.base[Number(number)]
-    } else {
-      if (number < 100n) {
-        return this.convertLess100(Number(number))
-      } else {
-        return (number < 1000n ? this.convertLess1000(Number(number)) : this.convertMore1000(number))
+  // For numbers >= 1,000,000, use scale decomposition
+  return buildLargeNumberWords(n)
+}
+
+/**
+ * Builds words for numbers >= 1,000,000.
+ *
+ * @param {bigint} n - Number >= 1,000,000
+ * @returns {string} Vietnamese words
+ */
+function buildLargeNumberWords (n) {
+  const numStr = n.toString()
+  const len = numStr.length
+
+  // Build segments of 3 digits from right to left
+  const segments = []
+  const segmentSize = 3
+
+  const remainderLen = len % segmentSize
+  let pos = 0
+  if (remainderLen > 0) {
+    segments.push(Number(numStr.slice(0, remainderLen)))
+    pos = remainderLen
+  }
+  while (pos < len) {
+    segments.push(Number(numStr.slice(pos, pos + segmentSize)))
+    pos += segmentSize
+  }
+
+  // Convert segments to words
+  const parts = []
+  let scaleIndex = segments.length - 1
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i]
+    if (segment !== 0) {
+      const words = SEGMENTS[segment]
+      if (words) {
+        if (scaleIndex > 0) {
+          parts.push(words + ' ' + SCALES[scaleIndex])
+        } else {
+          parts.push(words)
+        }
       }
     }
+    scaleIndex--
   }
+
+  // Join with "lẻ" logic for small remainders
+  const partsLen = parts.length
+  if (partsLen === 0) return ZERO
+  if (partsLen === 1) return parts[0]
+
+  // Check if final segment needs "lẻ" marker (remainder <= 99 after scale word)
+  const lastSegment = segments[segments.length - 1]
+  if (lastSegment > 0 && lastSegment <= 99) {
+    // Last segment is small (no hundreds), needs "lẻ" after scale word
+    let result = parts[0]
+    for (let i = 1; i < partsLen - 1; i++) {
+      result += ' ' + parts[i]
+    }
+    return result + ' ' + LE_SEGMENTS[lastSegment]
+  }
+
+  // Join with spaces
+  let result = parts[0]
+  for (let i = 1; i < partsLen; i++) {
+    result += ' ' + parts[i]
+  }
+  return result
+}
+
+/**
+ * Converts decimal digits to Vietnamese words.
+ *
+ * @param {string} decimalPart - Decimal digits (without the point)
+ * @returns {string} Vietnamese words for decimal part
+ */
+function decimalPartToWords (decimalPart) {
+  let result = ''
+
+  // Handle leading zeros
+  let i = 0
+  while (i < decimalPart.length && decimalPart[i] === '0') {
+    if (result) result += ' '
+    result += ZERO
+    i++
+  }
+
+  // Convert remainder as a single number
+  const remainder = decimalPart.slice(i)
+  if (remainder) {
+    if (result) result += ' '
+    result += integerToWords(BigInt(remainder))
+  }
+
+  return result
 }
 
 /**
- * Converts a number to Vietnamese cardinal (written) form.
+ * Converts a numeric value to Vietnamese words.
  *
- * @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.
+ * This is the main public API. It accepts any valid numeric input
+ * (number, string, or bigint) and handles parsing internally.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Vietnamese words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toWords(42)           // 'bốn mươi hai'
+ * toWords(101)          // 'một trăm lẻ một'
+ * toWords(1000000)      // 'một triệu'
  */
-export default function convertToWords (value, options = {}) {
-  return new Vietnamese(options).convertToWords(value)
+function toWords (value) {
+  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+
+  let result = ''
+
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  result += integerToWords(integerPart)
+
+  if (decimalPart) {
+    result += ' ' + DECIMAL_SEP + ' ' + decimalPartToWords(decimalPart)
+  }
+
+  return result
 }
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+export { toWords }

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

@@ -0,0 +1,11 @@
+/**
+ * Converts a numeric value to Simplified 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 Simplified Chinese words
+ */
+export function toWords(value: number | string | bigint, options?: {
+    formal?: boolean | undefined;
+}): string;