n2words 3.0.0 → 4.0.0

package/src/utils/parse-ordinal.js

@@ -0,0 +1,103 @@
+/**
+ * Ordinal value parsing utility.
+ * Optimized parser for ordinal conversion - accepts only positive integers.
+ * @module parse-ordinal
+ */
+
+import { expandScientificNotation, hasScientificNotation } from './expand-scientific.js'
+
+/**
+ * Parses a value for ordinal conversion.
+ * Ordinals require positive integers only (no zero, negatives, or decimals).
+ *
+ * @param {number|string|bigint} value - The value to parse
+ * @returns {bigint} The positive integer value
+ * @throws {TypeError} If value is not number, string, or bigint
+ * @throws {RangeError} If value is zero, negative, or has a decimal part
+ */
+export function parseOrdinalValue (value) {
+  const type = typeof value
+
+  // BigInt: simplest case
+  if (type === 'bigint') {
+    if (value <= 0n) {
+      throw new RangeError('Ordinals must be positive integers')
+    }
+    return value
+  }
+
+  // Number: fast path for safe integers
+  if (type === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new RangeError('Ordinals must be finite numbers')
+    }
+    if (!Number.isInteger(value)) {
+      throw new RangeError('Ordinals must be whole numbers')
+    }
+    if (value <= 0) {
+      throw new RangeError('Ordinals must be positive integers')
+    }
+    return BigInt(value)
+  }
+
+  // String input
+  if (type === 'string') {
+    return parseOrdinalString(value)
+  }
+
+  throw new TypeError(
+    `Invalid value type: expected number, string, or bigint, received ${type}`
+  )
+}
+
+/**
+ * Parses a string for ordinal conversion.
+ *
+ * @param {string} value - The string to parse
+ * @returns {bigint} The positive integer value
+ * @throws {RangeError} If string is not a valid positive integer
+ */
+function parseOrdinalString (value) {
+  const trimmed = value.trim()
+
+  if (trimmed.length === 0) {
+    throw new RangeError('Ordinals cannot be empty strings')
+  }
+
+  // Quick rejection for obvious non-ordinals
+  if (trimmed[0] === '-') {
+    throw new RangeError('Ordinals cannot be negative')
+  }
+
+  if (trimmed.includes('.')) {
+    throw new RangeError('Ordinals must be whole numbers')
+  }
+
+  // Handle scientific notation with full precision expansion
+  if (hasScientificNotation(trimmed)) {
+    const expanded = expandScientificNotation(trimmed)
+
+    // Check if expansion resulted in a decimal
+    if (expanded.includes('.')) {
+      throw new RangeError('Ordinals must be whole numbers')
+    }
+
+    const result = BigInt(expanded)
+    if (result <= 0n) {
+      throw new RangeError('Ordinals must be positive integers')
+    }
+    return result
+  }
+
+  // Parse as BigInt directly
+  try {
+    const result = BigInt(trimmed)
+    if (result <= 0n) {
+      throw new RangeError('Ordinals must be positive integers')
+    }
+    return result
+  } catch (e) {
+    if (e instanceof RangeError) throw e
+    throw new RangeError(`Invalid ordinal format: "${value}"`)
+  }
+}

package/src/vi-VN.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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
+ * toCardinal(42)           // 'bốn mươi hai'
+ * toCardinal(101)          // 'một trăm lẻ một'
+ * toCardinal(1000000)      // 'một triệu'
+ */
+export function toCardinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Vietnamese ordinal words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert (positive integer)
+ * @returns {string} The number as ordinal words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {RangeError} If value is negative, zero, or has a decimal part
+ *
+ * @example
+ * toOrdinal(1)    // 'thứ nhất'
+ * toOrdinal(2)    // 'thứ hai'
+ * toOrdinal(10)   // 'thứ mười'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Vietnamese currency words (Dong).
+ *
+ * Vietnamese Dong has no subunit in modern usage (xu are historical).
+ * Amounts are rounded to whole đồng.
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Vietnamese currency words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCurrency(42)     // 'bốn mươi hai đồng'
+ * toCurrency(1000)   // 'một nghìn đồng'
+ * toCurrency(-5)     // 'âm năm đồng'
+ */
+export function toCurrency(value: number | string | bigint): string;

package/{lib/languages/vi.js → src/vi-VN.js}

@@ -1,19 +1,17 @@
 /**
- * Vietnamese language converter - Functional Implementation v2
+ * Vietnamese (Vietnam) language converter
  *
- * A performance-optimized number-to-words converter using precomputed lookup tables.
- * Self-contained module with its own input validation, ready for subpath exports.
+ * CLDR: vi-VN | Vietnamese as used in Vietnam
  *
- * 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):
+ * 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ỷ)
  */
 
-import { parseNumericValue } from '../utils/parse-numeric.js'
+import { parseCardinalValue } from './utils/parse-cardinal.js'
+import { parseCurrencyValue } from './utils/parse-currency.js'
+import { parseOrdinalValue } from './utils/parse-ordinal.js'
 
 // ============================================================================
 // Vocabulary (module-level constants)
@@ -37,17 +35,30 @@ const NEGATIVE = 'âm'
 const DECIMAL_SEP = 'phẩy'
 const LE = 'lẻ' // "odd/extra" marker for gaps
 
+// ============================================================================
+// Ordinal Vocabulary
+// ============================================================================
+
+const ORDINAL_PREFIX = 'thứ'
+// First is special: "thứ nhất" (not "thứ một")
+const ORDINAL_ONE = 'nhất'
+
+// ============================================================================
+// Currency Vocabulary (Vietnamese Dong)
+// ============================================================================
+
+const DONG = 'đồng'
+
 // 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)
+// Segment Building
 // ============================================================================
 
 /**
  * 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]
@@ -63,7 +74,7 @@ function buildBelowHundred (n) {
 
   // 20-99
   const ones = n % 10
-  const tens = Math.floor(n / 10)
+  const tens = Math.trunc(n / 10)
   const tensWord = ONES[tens] + ' mươi'
 
   if (ones === 0) return tensWord
@@ -74,12 +85,11 @@ function buildBelowHundred (n) {
 
 /**
  * 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 hundreds = Math.trunc(n / 100)
   const remainder = n % 100
 
   let result = ''
@@ -101,37 +111,23 @@ function buildSegment (n) {
     } else {
       // 10-99 after hundreds
       if (result) result += ' '
-      result += BELOW_100[remainder]
+      result += buildBelowHundred(remainder)
     }
   }
 
   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]
+/**
+ * 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)
 }
 
 // ============================================================================
@@ -147,14 +143,14 @@ for (let i = 10; i < 100; i++) {
 function integerToWords (n) {
   if (n === 0n) return ZERO
 
-  // Fast path: numbers < 100 (direct lookup)
+  // Fast path: numbers < 100
   if (n < 100n) {
-    return BELOW_100[Number(n)]
+    return buildBelowHundred(Number(n))
   }
 
-  // Fast path: numbers < 1000 (direct lookup)
+  // Fast path: numbers < 1000
   if (n < 1000n) {
-    return SEGMENTS[Number(n)]
+    return buildSegment(Number(n))
   }
 
   // Fast path: numbers < 1,000,000 (thousands)
@@ -162,7 +158,7 @@ function integerToWords (n) {
     const thousands = Number(n / 1000n)
     const remainder = Number(n % 1000n)
 
-    const thousandsWords = SEGMENTS[thousands] + ' ' + SCALES[1]
+    const thousandsWords = buildSegment(thousands) + ' ' + SCALES[1]
 
     if (remainder === 0) {
       return thousandsWords
@@ -170,10 +166,10 @@ function integerToWords (n) {
 
     // Check if remainder needs "lẻ" marker (< 100)
     if (remainder < 100) {
-      return thousandsWords + ' ' + LE_SEGMENTS[remainder]
+      return thousandsWords + ' ' + buildLeSegment(remainder)
     }
 
-    return thousandsWords + ' ' + SEGMENTS[remainder]
+    return thousandsWords + ' ' + buildSegment(remainder)
   }
 
   // For numbers >= 1,000,000, use scale decomposition
@@ -212,7 +208,7 @@ function buildLargeNumberWords (n) {
   for (let i = 0; i < segments.length; i++) {
     const segment = segments[i]
     if (segment !== 0) {
-      const words = SEGMENTS[segment]
+      const words = buildSegment(segment)
       if (words) {
         if (scaleIndex > 0) {
           parts.push(words + ' ' + SCALES[scaleIndex])
@@ -237,7 +233,7 @@ function buildLargeNumberWords (n) {
     for (let i = 1; i < partsLen - 1; i++) {
       result += ' ' + parts[i]
     }
-    return result + ' ' + LE_SEGMENTS[lastSegment]
+    return result + ' ' + buildLeSegment(lastSegment)
   }
 
   // Join with spaces
@@ -287,12 +283,12 @@ function decimalPartToWords (decimalPart) {
  * @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'
+ * toCardinal(42)           // 'bốn mươi hai'
+ * toCardinal(101)          // 'một trăm lẻ một'
+ * toCardinal(1000000)      // 'một triệu'
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
 
@@ -309,8 +305,83 @@ function toWords (value) {
   return result
 }
 
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Vietnamese ordinal words.
+ *
+ * Vietnamese ordinals use "thứ" prefix + cardinal number.
+ * Special case: "thứ nhất" for 1st (not "thứ một").
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Vietnamese ordinal words
+ */
+function integerToOrdinal (n) {
+  // Special case: 1st is "thứ nhất"
+  if (n === 1n) {
+    return ORDINAL_PREFIX + ' ' + ORDINAL_ONE
+  }
+
+  // All others: "thứ" + cardinal
+  return ORDINAL_PREFIX + ' ' + integerToWords(n)
+}
+
+/**
+ * Converts a numeric value to Vietnamese ordinal words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert (positive integer)
+ * @returns {string} The number as ordinal words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {RangeError} If value is negative, zero, or has a decimal part
+ *
+ * @example
+ * toOrdinal(1)    // 'thứ nhất'
+ * toOrdinal(2)    // 'thứ hai'
+ * toOrdinal(10)   // 'thứ mười'
+ */
+function toOrdinal (value) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value)
+// ============================================================================
+
+/**
+ * Converts a numeric value to Vietnamese currency words (Dong).
+ *
+ * Vietnamese Dong has no subunit in modern usage (xu are historical).
+ * Amounts are rounded to whole đồng.
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Vietnamese currency words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCurrency(42)     // 'bốn mươi hai đồng'
+ * toCurrency(1000)   // 'một nghìn đồng'
+ * toCurrency(-5)     // 'âm năm đồng'
+ */
+function toCurrency (value) {
+  const { isNegative, dollars: dong } = parseCurrencyValue(value)
+
+  let result = ''
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  result += integerToWords(dong)
+  result += ' ' + DONG
+
+  return result
+}
+
 // ============================================================================
 // Public API
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/yo-NG.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 toCardinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Yoruba ordinal words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert (positive integer)
+ * @returns {string} The number as ordinal words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {RangeError} If value is negative, zero, or has a decimal part
+ *
+ * @example
+ * toOrdinal(1)    // 'àkọ́kọ́'
+ * toOrdinal(2)    // 'ìkejì'
+ * toOrdinal(3)    // 'ìkẹẹ̀ta'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Yoruba currency words (Nigerian Naira).
+ *
+ * Uses náírà (naira) and kọ́bọ̀ (kobo).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Yoruba currency words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCurrency(42)     // 'èjì lé lógójì náírà'
+ * toCurrency(1.50)   // 'ọ̀kan náírà àti àádọ́ta kọ́bọ̀'
+ * toCurrency(-5)     // 'àìní àrùn náírà'
+ */
+export function toCurrency(value: number | string | bigint): string;