n2words 2.0.0 → 3.1.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,296 @@
-import { AbstractLanguage } from '../classes/abstract-language.js'
-
 /**
- * Vietnamese language converter.
+ * Vietnamese language converter - Functional Implementation
+ *
+ * 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
+ * Vietnamese-specific rules:
+ * - 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'
-  }
-
-  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'
-  }
-
-  /** 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
+
+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.)
+
+// ============================================================================
+// Segment Building
+// ============================================================================
+
+/**
+ * Builds word for 0-99 with special forms (mốt, lăm).
+ */
+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 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')
+  // 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.
+ */
+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
+  }
+
+  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 += buildBelowHundred(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
+}
+
+/**
+ * Builds "lẻ" prefixed word for small remainders (1-99) after scale words.
+ */
+function buildLeSegment (n) {
+  if (n === 0) return ''
+  if (n < 10) {
+    // Use "năm" not "lăm" after lẻ
+    return LE + ' ' + (n === 5 ? 'năm' : ONES[n])
+  }
+  return LE + ' ' + buildBelowHundred(n)
+}
+
+// ============================================================================
+// 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
+  if (n < 100n) {
+    return buildBelowHundred(Number(n))
+  }
+
+  // Fast path: numbers < 1000
+  if (n < 1000n) {
+    return buildSegment(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 = buildSegment(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 + ' ' + buildLeSegment(remainder)
     }
-    return words.join(' ')
+
+    return thousandsWords + ' ' + buildSegment(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 = buildSegment(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 + ' ' + buildLeSegment(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/yo.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Converts a numeric value to Yoruba words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Yoruba words
+ */
+export function toWords(value: number | string | bigint): string;