n2words 3.1.0 → 4.0.0

package/src/utils/expand-scientific.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Scientific notation expansion utility.
+ * Converts scientific notation strings to full decimal form.
+ * @module expand-scientific
+ */
+/**
+ * Expands scientific notation to full decimal form.
+ * Handles arbitrarily large exponents without precision loss.
+ *
+ * @param {string} str - String in scientific notation (e.g., "1e21", "1.5e-3")
+ * @returns {string} Full decimal representation (e.g., "1000000000000000000000", "0.0015")
+ *
+ * @example
+ * expandScientificNotation("1e21")    // "1000000000000000000000"
+ * expandScientificNotation("1.5e3")   // "1500"
+ * expandScientificNotation("1e-3")    // "0.001"
+ */
+export function expandScientificNotation(str: string): string;
+/**
+ * Converts a number to decimal string, expanding scientific notation if needed.
+ *
+ * @param {number} value - The number to convert
+ * @returns {string} Decimal string representation
+ */
+export function numberToString(value: number): string;
+/**
+ * Checks if a string contains scientific notation.
+ *
+ * @param {string} str - String to check
+ * @returns {boolean} True if string contains 'e' or 'E'
+ */
+export function hasScientificNotation(str: string): boolean;

package/src/utils/expand-scientific.js

@@ -0,0 +1,65 @@
+/**
+ * Scientific notation expansion utility.
+ * Converts scientific notation strings to full decimal form.
+ * @module expand-scientific
+ */
+
+/**
+ * Expands scientific notation to full decimal form.
+ * Handles arbitrarily large exponents without precision loss.
+ *
+ * @param {string} str - String in scientific notation (e.g., "1e21", "1.5e-3")
+ * @returns {string} Full decimal representation (e.g., "1000000000000000000000", "0.0015")
+ *
+ * @example
+ * expandScientificNotation("1e21")    // "1000000000000000000000"
+ * expandScientificNotation("1.5e3")   // "1500"
+ * expandScientificNotation("1e-3")    // "0.001"
+ */
+export function expandScientificNotation (str) {
+  let [mantissa, expStr] = str.toLowerCase().split('e')
+  const exp = parseInt(expStr, 10)
+
+  // Strip sign before processing digits
+  let sign = ''
+  if (mantissa[0] === '-') {
+    sign = '-'
+    mantissa = mantissa.slice(1)
+  }
+
+  const dotIndex = mantissa.indexOf('.')
+  const digits = dotIndex === -1
+    ? mantissa
+    : mantissa.slice(0, dotIndex) + mantissa.slice(dotIndex + 1)
+  const integerLength = dotIndex === -1 ? mantissa.length : dotIndex
+  const newDotPosition = integerLength + exp
+
+  if (newDotPosition >= digits.length) {
+    return sign + digits + '0'.repeat(newDotPosition - digits.length)
+  } else if (newDotPosition <= 0) {
+    return sign + '0.' + '0'.repeat(-newDotPosition) + digits
+  } else {
+    return sign + digits.slice(0, newDotPosition) + '.' + digits.slice(newDotPosition)
+  }
+}
+
+/**
+ * Converts a number to decimal string, expanding scientific notation if needed.
+ *
+ * @param {number} value - The number to convert
+ * @returns {string} Decimal string representation
+ */
+export function numberToString (value) {
+  const str = value.toString()
+  return hasScientificNotation(str) ? expandScientificNotation(str) : str
+}
+
+/**
+ * Checks if a string contains scientific notation.
+ *
+ * @param {string} str - String to check
+ * @returns {boolean} True if string contains 'e' or 'E'
+ */
+export function hasScientificNotation (str) {
+  return str.includes('e') || str.includes('E')
+}

package/src/utils/parse-cardinal.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Parses a value for cardinal conversion.
+ * Cardinals accept any numeric value: integers, decimals, negatives.
+ *
+ * @param {number|string|bigint} value - The value to parse
+ * @returns {{isNegative: boolean, integerPart: bigint, decimalPart?: string}}
+ * @throws {TypeError} If value is not number, string, or bigint
+ * @throws {RangeError} If value is not finite
+ */
+export function parseCardinalValue(value: number | string | bigint): {
+    isNegative: boolean;
+    integerPart: bigint;
+    decimalPart?: string;
+};

package/{lib/utils/parse-numeric.js → src/utils/parse-cardinal.js}

@@ -1,17 +1,22 @@
 /**
- * Numeric value parsing utility.
+ * Cardinal value parsing utility.
  * Transforms user input (number, string, or bigint) into normalized components.
- * @module parse-numeric
+ * Handles negatives, decimals, and scientific notation.
+ * @module parse-cardinal
  */
 
+import { expandScientificNotation, hasScientificNotation, numberToString } from './expand-scientific.js'
+
 /**
- * Parses a numeric value into its components.
- * @param {number|string|bigint} value
+ * Parses a value for cardinal conversion.
+ * Cardinals accept any numeric value: integers, decimals, negatives.
+ *
+ * @param {number|string|bigint} value - The value to parse
  * @returns {{isNegative: boolean, integerPart: bigint, decimalPart?: string}}
  * @throws {TypeError} If value is not number, string, or bigint
- * @throws {Error} If value is not a valid number format
+ * @throws {RangeError} If value is not finite
  */
-export function parseNumericValue (value) {
+export function parseCardinalValue (value) {
   const type = typeof value
 
   // BigInt: simplest case
@@ -24,7 +29,7 @@ export function parseNumericValue (value) {
   // Number: fast path for safe integers
   if (type === 'number') {
     if (!Number.isFinite(value)) {
-      throw new Error('Number must be finite (NaN and Infinity are not supported)')
+      throw new RangeError('Number must be finite (NaN and Infinity are not supported)')
     }
     if (Number.isSafeInteger(value)) {
       return value < 0
@@ -44,27 +49,15 @@ export function parseNumericValue (value) {
   )
 }
 
-/**
- * Converts a number to decimal string, expanding scientific notation if needed.
- */
-function numberToString (value) {
-  const str = value.toString()
-  return (str.includes('e') || str.includes('E'))
-    ? expandScientificNotation(str)
-    : str
-}
-
 /**
  * Validates and normalizes a string numeric input.
  */
 function normalizeString (value) {
   const trimmed = value.trim()
   if (trimmed.length === 0 || Number.isNaN(Number(trimmed))) {
-    throw new Error(`Invalid number format: "${value}"`)
+    throw new RangeError(`Invalid number format: "${value}"`)
   }
-  return (trimmed.includes('e') || trimmed.includes('E'))
-    ? expandScientificNotation(trimmed)
-    : trimmed
+  return hasScientificNotation(trimmed) ? expandScientificNotation(trimmed) : trimmed
 }
 
 /**
@@ -83,26 +76,3 @@ function parseNumericString (str) {
   const decimalPart = str.slice(dotIndex + 1)
   return { isNegative, integerPart: BigInt(integerStr), decimalPart }
 }
-
-/**
- * Expands scientific notation to decimal form (e.g., "1e21" → "1000...").
- */
-function expandScientificNotation (str) {
-  const [mantissa, expStr] = str.toLowerCase().split('e')
-  const exp = parseInt(expStr, 10)
-
-  const dotIndex = mantissa.indexOf('.')
-  const digits = dotIndex === -1
-    ? mantissa
-    : mantissa.slice(0, dotIndex) + mantissa.slice(dotIndex + 1)
-  const integerLength = dotIndex === -1 ? mantissa.length : dotIndex
-  const newDotPosition = integerLength + exp
-
-  if (newDotPosition >= digits.length) {
-    return digits + '0'.repeat(newDotPosition - digits.length)
-  }
-  if (newDotPosition <= 0) {
-    return '0.' + '0'.repeat(-newDotPosition) + digits
-  }
-  return digits.slice(0, newDotPosition) + '.' + digits.slice(newDotPosition)
-}

package/src/utils/parse-currency.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Parses a value for currency conversion.
+ * Returns dollars and cents as separate bigints, plus negative flag.
+ *
+ * @param {number|string|bigint} value - The value to parse
+ * @returns {{isNegative: boolean, dollars: bigint, cents: bigint}}
+ * @throws {TypeError} If value is not number, string, or bigint
+ * @throws {RangeError} If value is not finite
+ */
+export function parseCurrencyValue(value: number | string | bigint): {
+    isNegative: boolean;
+    dollars: bigint;
+    cents: bigint;
+};

package/src/utils/parse-currency.js

@@ -0,0 +1,91 @@
+/**
+ * Currency value parsing utility.
+ * Optimized parser for currency conversion - extracts dollars and cents.
+ * @module parse-currency
+ */
+
+import { expandScientificNotation, hasScientificNotation, numberToString } from './expand-scientific.js'
+
+/**
+ * Parses a value for currency conversion.
+ * Returns dollars and cents as separate bigints, plus negative flag.
+ *
+ * @param {number|string|bigint} value - The value to parse
+ * @returns {{isNegative: boolean, dollars: bigint, cents: bigint}}
+ * @throws {TypeError} If value is not number, string, or bigint
+ * @throws {RangeError} If value is not finite
+ */
+export function parseCurrencyValue (value) {
+  const type = typeof value
+
+  // BigInt: whole dollars only
+  if (type === 'bigint') {
+    return value < 0n
+      ? { isNegative: true, dollars: -value, cents: 0n }
+      : { isNegative: false, dollars: value, cents: 0n }
+  }
+
+  // Number: fast path for safe integers
+  if (type === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new RangeError('Currency must be a finite number')
+    }
+    if (Number.isSafeInteger(value)) {
+      return value < 0
+        ? { isNegative: true, dollars: BigInt(-value), cents: 0n }
+        : { isNegative: false, dollars: BigInt(value), cents: 0n }
+    }
+    // Non-integer or unsafe: convert to string
+    return parseCurrencyString(numberToString(value))
+  }
+
+  // String input
+  if (type === 'string') {
+    return parseCurrencyString(value)
+  }
+
+  throw new TypeError(
+    `Invalid value type: expected number, string, or bigint, received ${type}`
+  )
+}
+
+/**
+ * Parses a string for currency conversion.
+ *
+ * @param {string} value - The string to parse
+ * @returns {{isNegative: boolean, dollars: bigint, cents: bigint}}
+ */
+function parseCurrencyString (value) {
+  let str = value.trim()
+
+  if (str.length === 0 || Number.isNaN(Number(str))) {
+    throw new RangeError(`Invalid currency format: "${value}"`)
+  }
+
+  // Expand scientific notation
+  if (hasScientificNotation(str)) {
+    str = expandScientificNotation(str)
+  }
+
+  // Handle negative
+  const isNegative = str[0] === '-'
+  if (isNegative) str = str.slice(1)
+
+  // Split on decimal
+  const dotIndex = str.indexOf('.')
+  if (dotIndex === -1) {
+    return { isNegative, dollars: BigInt(str), cents: 0n }
+  }
+
+  const dollarStr = str.slice(0, dotIndex) || '0'
+  const decimalPart = str.slice(dotIndex + 1)
+
+  // Truncate to 2 decimal places and pad if needed
+  const centStr = (decimalPart + '00').slice(0, 2)
+
+  return {
+    isNegative,
+    dollars: BigInt(dollarStr),
+    cents: BigInt(centStr)
+  }
+}

package/src/utils/parse-ordinal.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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: number | string | bigint): bigint;

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,7 +1,7 @@
 /**
- * Vietnamese language converter - Functional Implementation
+ * Vietnamese (Vietnam) language converter
  *
- * Self-contained module with its own input validation, ready for subpath exports.
+ * CLDR: vi-VN | Vietnamese as used in Vietnam
  *
  * Vietnamese-specific rules:
  * - Special pronunciation: "lăm" for 5 in tens position, "mốt" for final 1
@@ -9,7 +9,9 @@
  * - 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)
@@ -33,6 +35,20 @@ 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.)
@@ -58,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
@@ -73,7 +89,7 @@ function buildBelowHundred (n) {
 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 = ''
@@ -267,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 = ''
 
@@ -289,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;