n2words 2.0.0 → 3.0.0

package/lib/languages/vi.d.ts

@@ -1,72 +1,17 @@
 /**
- * Vietnamese language converter.
+ * Converts a numeric value to Vietnamese words.
  *
- * Supports:
- * - Special pronunciation rules (lăm for 5, mốt for final 1)
- * - "Lẻ" (odd/extra) when tens place is zero
- * - Vietnamese diacritical marks
+ * 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 class Vietnamese extends AbstractLanguage {
-    belowTwentyWords: {
-        0: string;
-        1: string;
-        2: string;
-        3: string;
-        4: string;
-        5: string;
-        6: string;
-        7: string;
-        8: string;
-        9: string;
-        10: string;
-        11: string;
-        12: string;
-        13: string;
-        14: string;
-        15: string;
-        16: string;
-        17: string;
-        18: string;
-        19: string;
-    };
-    twentiesWords: {
-        20: string;
-        30: string;
-        40: string;
-        50: string;
-        60: string;
-        70: string;
-        80: string;
-        90: string;
-    };
-    scaleWords: {
-        1: string;
-        2: string;
-        3: string;
-        4: string;
-        5: string;
-        6: string;
-        7: string;
-        8: string;
-        9: string;
-        10: string;
-        11: string;
-        12: string;
-        13: string;
-        14: string;
-        15: string;
-        16: string;
-        17: string;
-        18: string;
-        19: string;
-        20: string;
-    };
-    /** Convert numbers less than 100 to Vietnamese words. */
-    convertLess100(number: any): any;
-    /** Convert numbers less than 1000 to Vietnamese words. */
-    convertLess1000(number: any): any;
-    /** Convert numbers greater than 1000 to Vietnamese words. */
-    convertMore1000(number: any): any;
-    integerToWords(integerPart: any): any;
-}
-import { AbstractLanguage } from '../classes/abstract-language.js';
+export function toWords(value: number | string | bigint): string;

package/lib/languages/vi.js

@@ -1,147 +1,316 @@
-import { AbstractLanguage } from '../classes/abstract-language.js'
-
 /**
- * Vietnamese language converter.
+ * Vietnamese language converter - Functional Implementation v2
+ *
+ * A performance-optimized number-to-words converter using precomputed lookup tables.
+ * Self-contained module with its own input validation, ready for subpath exports.
  *
- * Supports:
- * - Special pronunciation rules (lăm for 5, mốt for final 1)
- * - "Lẻ" (odd/extra) when tens place is zero
- * - Vietnamese diacritical marks
+ * Key optimization: Precompute all segment values (0-999) at module load.
+ * This eliminates all per-call string manipulation for segment conversion.
+ *
+ * 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'
-
-  belowTwentyWords = {
-    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'
-  }
 
-  twentiesWords = {
-    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']
 
-  scaleWords = {
-    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'
+// 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]
+
+  // 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. */
-  convertLess100 (number) {
-    const unitsPart = number % 10
-    const tensPart = number - unitsPart
-    const tensPartText = this.twentiesWords[tensPart]
-    if (unitsPart === 0) {
-      return tensPartText
-    }
-    const unitsPartText = this.belowTwentyWords[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. */
-  convertLess1000 (number) {
-    const words = []
-    const tensUnitsPart = number % 100
-    const hundredsPart = number - tensUnitsPart
-    if (hundredsPart > 0) {
-      words.push(this.belowTwentyWords[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.belowTwentyWords[tensUnitsPart])
+        result = ONES[remainder]
       }
+    } else {
+      // 10-99 after hundreds
+      if (result) result += ' '
+      result += BELOW_100[remainder]
     }
-    if (tensUnitsPart >= 10) {
-      words.push(this.integerToWords(tensUnitsPart))
-    }
-    return words.join(' ')
   }
 
-  /** Convert numbers greater than 1000 to Vietnamese words. */
-  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.integerToWords(division), this.scaleWords[power])
-    if (r > 0n) {
-      if (r <= 99n) {
-        words.push('lẻ')
-      }
-      words.push(this.integerToWords(r))
+
+    // Check if remainder needs "lẻ" marker (< 100)
+    if (remainder < 100) {
+      return thousandsWords + ' ' + LE_SEGMENTS[remainder]
     }
-    return words.join(' ')
+
+    return thousandsWords + ' ' + SEGMENTS[remainder]
   }
 
-  integerToWords (integerPart) {
-    if (integerPart < 20n) {
-      return this.belowTwentyWords[Number(integerPart)]
-    } else {
-      if (integerPart < 100n) {
-        return this.convertLess100(Number(integerPart))
-      } else {
-        return (integerPart < 1000n ? this.convertLess1000(Number(integerPart)) : this.convertMore1000(integerPart))
+  // 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 numeric value to Vietnamese words.
+ *
+ * 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'
+ */
+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

@@ -1,21 +1,11 @@
 /**
- * Simplified Chinese language converter.
+ * Converts a numeric value to Simplified Chinese words.
  *
- * Supports:
- * - Simplified Chinese characters (简体中文)
- * - No word separators (concatenated format)
- * - Optional formal (financial) vs common numerals
+ * @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 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';
+export function toWords(value: number | string | bigint, options?: {
+    formal?: boolean | undefined;
+}): string;