n2words 3.0.0 → 4.0.0

package/lib/languages/en.js

@@ -1,256 +0,0 @@
-/**
- * English 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.
- *
- * Key optimization: Precompute all segment values (0-999) at module load.
- * This eliminates all per-call string manipulation for segment conversion.
- *
- * English-specific rules (handled in precomputation):
- * - "and" after hundreds: "one hundred and twenty-three"
- * - Hyphenated tens-ones: "twenty-one", "forty-two"
- * - "and" before final segment when following scale word
- */
-
-import { parseNumericValue } from '../utils/parse-numeric.js'
-
-// ============================================================================
-// Vocabulary (module-level constants)
-// ============================================================================
-
-const ONES = ['', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine']
-const TEENS = ['ten', 'eleven', 'twelve', 'thirteen', 'fourteen', 'fifteen', 'sixteen', 'seventeen', 'eighteen', 'nineteen']
-const TENS = ['', '', 'twenty', 'thirty', 'forty', 'fifty', 'sixty', 'seventy', 'eighty', 'ninety']
-
-const SCALES = ['thousand', 'million', 'billion', 'trillion', 'quadrillion', 'quintillion', 'sextillion', 'septillion', 'octillion']
-
-const HUNDRED = 'hundred'
-const ZERO = 'zero'
-const NEGATIVE = 'minus'
-const DECIMAL_SEP = 'point'
-
-// ============================================================================
-// Precomputed Lookup Tables (built once at module load)
-// ============================================================================
-
-/**
- * Builds segment word for 0-999.
- * Returns object with word and whether it contains "hundred" (for "and" logic).
- */
-function buildSegment (n) {
-  if (n === 0) return { word: '', hasHundred: false }
-
-  const ones = n % 10
-  const tens = Math.floor(n / 10) % 10
-  const hundreds = Math.floor(n / 100)
-
-  let result = ''
-  let hasHundred = false
-
-  // Hundreds
-  if (hundreds > 0) {
-    result = ONES[hundreds] + ' ' + HUNDRED
-    hasHundred = true
-  }
-
-  // Tens and ones
-  let tensOnes = ''
-  if (tens === 1) {
-    tensOnes = TEENS[ones]
-  } else if (tens >= 2) {
-    if (ones > 0) {
-      tensOnes = TENS[tens] + '-' + ONES[ones]
-    } else {
-      tensOnes = TENS[tens]
-    }
-  } else if (ones > 0) {
-    tensOnes = ONES[ones]
-  }
-
-  // Combine with "and" after hundreds
-  if (result && tensOnes) {
-    return { word: result + ' and ' + tensOnes, hasHundred: true }
-  }
-
-  return { word: result || tensOnes, hasHundred }
-}
-
-// Precompute all 1000 segment words (0-999)
-const SEGMENTS = new Array(1000)
-const SEGMENTS_HAS_HUNDRED = new Array(1000)
-
-for (let i = 0; i < 1000; i++) {
-  const result = buildSegment(i)
-  SEGMENTS[i] = result.word
-  SEGMENTS_HAS_HUNDRED[i] = result.hasHundred
-}
-
-// ============================================================================
-// Conversion Functions
-// ============================================================================
-
-/**
- * Converts a non-negative integer to English words.
- *
- * @param {bigint} n - Non-negative integer to convert
- * @returns {string} English words
- */
-function integerToWords (n) {
-  if (n === 0n) return ZERO
-
-  // 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)
-
-    let result = SEGMENTS[thousands] + ' ' + SCALES[0]
-
-    if (remainder > 0) {
-      const remainderWord = SEGMENTS[remainder]
-      // Insert "and" if remainder doesn't have hundred
-      if (!SEGMENTS_HAS_HUNDRED[remainder]) {
-        result += ' and ' + remainderWord
-      } else {
-        result += ' ' + remainderWord
-      }
-    }
-
-    return result
-  }
-
-  // For numbers >= 1,000,000, use scale decomposition
-  return buildLargeNumberWords(n)
-}
-
-/**
- * Builds words for numbers >= 1,000,000.
- * Uses BigInt division for faster segment extraction.
- *
- * @param {bigint} n - Number >= 1,000,000
- * @returns {string} English words
- */
-function buildLargeNumberWords (n) {
-  // Extract segments using BigInt division (faster than string slicing)
-  // Segments are stored least-significant first (index 0 = ones, 1 = thousands, etc.)
-  const segments = []
-  let temp = n
-  while (temp > 0n) {
-    segments.push(Number(temp % 1000n))
-    temp = temp / 1000n
-  }
-
-  // Find the first (smallest index) non-zero segment - this is processed last
-  let firstNonZeroIdx = -1
-  for (let i = 0; i < segments.length; i++) {
-    if (segments[i] !== 0) {
-      firstNonZeroIdx = i
-      break
-    }
-  }
-
-  // Build result string directly (avoids intermediate object allocations)
-  // Process from most-significant (end) to least-significant (start)
-  let result = ''
-  let prevWasScale = false
-
-  for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i]
-    if (segment === 0) continue
-
-    const segmentWord = SEGMENTS[segment]
-    const hasHundred = SEGMENTS_HAS_HUNDRED[segment]
-    const isLastSegment = (i === firstNonZeroIdx)
-
-    // Add "and" only before FINAL segment if it follows scale and doesn't have hundred
-    if (result && isLastSegment && prevWasScale && !hasHundred) {
-      result += ' and'
-    }
-
-    // Add segment word
-    if (result) result += ' '
-    result += segmentWord
-
-    // Add scale word (i=0 is units, i=1 is thousands, etc.)
-    if (i > 0) {
-      result += ' ' + SCALES[i - 1]
-      prevWasScale = true
-    } else {
-      prevWasScale = false
-    }
-  }
-
-  return result
-}
-
-/**
- * Converts decimal digits to English words.
- *
- * @param {string} decimalPart - Decimal digits (without the point)
- * @returns {string} English 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 English 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 English words
- * @throws {TypeError} If value is not a valid numeric type
- * @throws {Error} If value is not a valid number format
- *
- * @example
- * toWords(42)           // 'forty-two'
- * toWords(-3.14)        // 'minus three point one four'
- * toWords('1000000')    // 'one million'
- */
-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/es.d.ts

@@ -1,21 +0,0 @@
-/**
- * Converts a numeric value to Spanish 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
- * @param {Object} [options] - Optional configuration
- * @param {('masculine'|'feminine')} [options.gender='masculine'] - Grammatical gender
- * @returns {string} The number in Spanish words
- * @throws {TypeError} If value is not a valid numeric type
- * @throws {Error} If value is not a valid number format
- *
- * @example
- * toWords(21)                        // 'veintiuno'
- * toWords(21, {gender: 'feminine'})  // 'veintiuna'
- * toWords(1000000)                   // 'un millón'
- */
-export function toWords(value: number | string | bigint, options?: {
-    gender?: "masculine" | "feminine" | undefined;
-}): string;

package/lib/languages/fa.d.ts

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

package/lib/languages/fa.js

@@ -1,134 +0,0 @@
-/**
- * Persian language converter - Functional Implementation
- *
- * Self-contained converter using recursive decomposition.
- *
- * Key features:
- * - "و" (and) conjunction for compound numbers
- * - Omit "یک" (one) before thousand
- * - Pre-composed hundreds (دویست, سيصد, etc.)
- */
-
-import { parseNumericValue } from '../utils/parse-numeric.js'
-
-// ============================================================================
-// Vocabulary
-// ============================================================================
-
-const ONES = { 1: 'یک', 2: 'دو', 3: 'سه', 4: 'چهار', 5: 'پنج', 6: 'شش', 7: 'هفت', 8: 'هشت', 9: 'نه' }
-const TEENS = { 10: 'ده', 11: 'یازده', 12: 'دوازده', 13: 'سیزده', 14: 'چهارده', 15: 'پانزده', 16: 'شانزده', 17: 'هفده', 18: 'هجده', 19: 'نوزده' }
-const TENS = { 20: 'بیست', 30: 'سی', 40: 'چهل', 50: 'پنجاه', 60: 'شصت', 70: 'هفتاد', 80: 'هشتاد', 90: 'نود' }
-const HUNDREDS = { 100: 'صد', 200: 'دویست', 300: 'سيصد', 400: 'چهار صد', 500: 'پانصد', 600: 'ششصد', 700: 'هفتصد', 800: 'هشتصد', 900: 'نهصد' }
-
-const THOUSAND = 'هزار'
-const MILLION = 'میلیون'
-
-const ZERO = 'صفر'
-const NEGATIVE = 'منفى'
-const DECIMAL_SEP = 'ممیّز'
-
-// ============================================================================
-// Conversion Functions
-// ============================================================================
-
-function integerToWords (n) {
-  if (n === 0n) return ZERO
-
-  // 1-9
-  if (n <= 9n) {
-    return ONES[Number(n)]
-  }
-
-  // 10-19
-  if (n <= 19n) {
-    return TEENS[Number(n)]
-  }
-
-  // 20-99
-  if (n < 100n) {
-    const ones = n % 10n
-    const tens = n - ones
-    if (ones === 0n) {
-      return TENS[Number(tens)]
-    }
-    return `${TENS[Number(tens)]} و ${ONES[Number(ones)]}`
-  }
-
-  // 100-999
-  if (n < 1000n) {
-    const hundreds = 100n * (n / 100n)
-    const remainder = n - hundreds
-    if (remainder === 0n) {
-      return HUNDREDS[Number(hundreds)]
-    }
-    return `${HUNDREDS[Number(hundreds)]} و ${integerToWords(remainder)}`
-  }
-
-  // 1000-999999
-  if (n < 1_000_000n) {
-    const thousandMultiplier = n / 1000n
-    // Persian omits "one" before thousand: 1000 is just "هزار", not "یک هزار"
-    const thousandPrefix = thousandMultiplier === 1n
-      ? ''
-      : integerToWords(thousandMultiplier) + ' '
-    const remainder = n % 1000n
-    const suffix = remainder === 0n ? '' : ' ' + integerToWords(remainder)
-    return `${thousandPrefix}${THOUSAND}${suffix}`
-  }
-
-  // 1000000+
-  const millionMultiplier = n / 1_000_000n
-  const millionPrefix = integerToWords(millionMultiplier) + ' ' + MILLION
-  const remainder = n % 1_000_000n
-  const suffix = remainder === 0n ? '' : ' و ' + integerToWords(remainder)
-  return `${millionPrefix}${suffix}`
-}
-
-function decimalPartToWords (decimalPart) {
-  let result = ''
-  let i = 0
-
-  while (i < decimalPart.length && decimalPart[i] === '0') {
-    if (result) result += ' '
-    result += ZERO
-    i++
-  }
-
-  const remainder = decimalPart.slice(i)
-  if (remainder) {
-    if (result) result += ' '
-    result += integerToWords(BigInt(remainder))
-  }
-
-  return result
-}
-
-/**
- * Converts a numeric value to Persian words.
- *
- * @param {number | string | bigint} value - The numeric value to convert
- * @returns {string} The number in Persian words
- */
-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
-}
-
-// ============================================================================
-// Exports
-// ============================================================================
-
-export { toWords }

package/lib/languages/fi.d.ts

@@ -1,14 +0,0 @@
-/**
- * Converts a numeric value to Finnish words.
- *
- * @param {number | string | bigint} value - The numeric value to convert
- * @returns {string} The number in Finnish words
- * @throws {TypeError} If value is not a valid numeric type
- * @throws {Error} If value is not a valid number format
- *
- * @example
- * toWords(21)       // 'kaksikymmentäyksi'
- * toWords(1000)     // 'tuhat'
- * toWords('3.14')   // 'kolme pilkku yksi neljä'
- */
-export function toWords(value: number | string | bigint): string;

package/lib/languages/fi.js

@@ -1,245 +0,0 @@
-/**
- * Finnish language converter - Functional Implementation
- *
- * A performance-optimized number-to-words converter using precomputed lookup tables.
- *
- * Key features:
- * - Compound tens+ones without spaces: "kaksikymmentäyksi" (21)
- * - Teens with "-toista" suffix
- * - Omit "yksi" before sata/tuhat but keep before miljoona+
- * - Long scale: miljoona, miljardi, biljoona
- * - Per-digit decimal reading
- */
-
-import { parseNumericValue } from '../utils/parse-numeric.js'
-
-// ============================================================================
-// Vocabulary (module-level constants)
-// ============================================================================
-
-const ONES = ['', 'yksi', 'kaksi', 'kolme', 'neljä', 'viisi', 'kuusi', 'seitsemän', 'kahdeksan', 'yhdeksän']
-
-const TEENS = ['kymmenen', 'yksitoista', 'kaksitoista', 'kolmetoista', 'neljätoista', 'viisitoista', 'kuusitoista', 'seitsemäntoista', 'kahdeksantoista', 'yhdeksäntoista']
-
-// Tens use "kymmentä" suffix
-const TENS = ['', '', 'kaksikymmentä', 'kolmekymmentä', 'neljäkymmentä', 'viisikymmentä', 'kuusikymmentä', 'seitsemänkymmentä', 'kahdeksankymmentä', 'yhdeksänkymmentä']
-
-const HUNDRED = 'sata'
-const THOUSAND = 'tuhat'
-
-const ZERO = 'nolla'
-const NEGATIVE = 'miinus'
-const DECIMAL_SEP = 'pilkku'
-
-// Long scale
-const SCALES = ['miljoona', 'miljardi', 'biljoona', 'triljoona']
-
-// ============================================================================
-// Precomputed Lookup Tables (built once at module load)
-// ============================================================================
-
-/**
- * Builds segment word for 0-999.
- * Omits "yksi" before "sata" (hundred).
- */
-function buildSegment (n) {
-  if (n === 0) return ''
-
-  const ones = n % 10
-  const tens = Math.floor(n / 10) % 10
-  const hundreds = Math.floor(n / 100)
-
-  const parts = []
-
-  // Hundreds - omit "yksi" before sata
-  if (hundreds > 0) {
-    if (hundreds === 1) {
-      parts.push(HUNDRED)
-    } else {
-      parts.push(ONES[hundreds] + ' ' + HUNDRED)
-    }
-  }
-
-  // Tens and ones
-  const tensOnes = n % 100
-
-  if (tensOnes === 0) {
-    // Just hundreds
-  } else if (tensOnes < 10) {
-    parts.push(ONES[ones])
-  } else if (tensOnes < 20) {
-    parts.push(TEENS[ones])
-  } else if (ones === 0) {
-    parts.push(TENS[tens])
-  } else {
-    // Compound: "kaksikymmentäyksi" (no space)
-    parts.push(TENS[tens] + ONES[ones])
-  }
-
-  return parts.join(' ')
-}
-
-// Precompute all 1000 segment words (0-999)
-const SEGMENTS = new Array(1000)
-
-for (let i = 0; i < 1000; i++) {
-  SEGMENTS[i] = buildSegment(i)
-}
-
-// ============================================================================
-// Conversion Functions
-// ============================================================================
-
-/**
- * Converts a non-negative integer to Finnish words.
- *
- * @param {bigint} n - Non-negative integer to convert
- * @returns {string} Finnish words
- */
-function integerToWords (n) {
-  if (n === 0n) return ZERO
-
-  // 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)
-
-    // Omit "yksi" before tuhat
-    let result
-    if (thousands === 1) {
-      result = THOUSAND
-    } else {
-      result = SEGMENTS[thousands] + ' ' + THOUSAND
-    }
-
-    if (remainder > 0) {
-      result += ' ' + SEGMENTS[remainder]
-    }
-
-    return result
-  }
-
-  // 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} Finnish 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 segmentWord = SEGMENTS[segment]
-
-      if (scaleIndex === 0) {
-        // Units segment
-        parts.push(segmentWord)
-      } else if (scaleIndex === 1) {
-        // Thousands - omit "yksi" before tuhat
-        if (segment === 1) {
-          parts.push(THOUSAND)
-        } else {
-          parts.push(segmentWord + ' ' + THOUSAND)
-        }
-      } else {
-        // Millions+ - keep "yksi" before scale words
-        const scaleWord = SCALES[scaleIndex - 2]
-        parts.push(segmentWord + ' ' + scaleWord)
-      }
-    }
-
-    scaleIndex--
-  }
-
-  return parts.join(' ')
-}
-
-/**
- * Converts decimal digits to Finnish words (per-digit).
- *
- * @param {string} decimalPart - Decimal digits (without the point)
- * @returns {string} Finnish words for decimal part
- */
-function decimalPartToWords (decimalPart) {
-  const parts = []
-
-  for (const digit of decimalPart) {
-    const d = parseInt(digit, 10)
-    if (d === 0) {
-      parts.push(ZERO)
-    } else {
-      parts.push(ONES[d])
-    }
-  }
-
-  return parts.join(' ')
-}
-
-/**
- * Converts a numeric value to Finnish words.
- *
- * @param {number | string | bigint} value - The numeric value to convert
- * @returns {string} The number in Finnish words
- * @throws {TypeError} If value is not a valid numeric type
- * @throws {Error} If value is not a valid number format
- *
- * @example
- * toWords(21)       // 'kaksikymmentäyksi'
- * toWords(1000)     // 'tuhat'
- * toWords('3.14')   // 'kolme pilkku yksi neljä'
- */
-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/fil.d.ts

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

package/lib/languages/fr-BE.d.ts

@@ -1,11 +0,0 @@
-/**
- * Converts a numeric value to Belgian French words.
- *
- * @param {number | string | bigint} value - The numeric value to convert
- * @param {Object} [options] - Optional configuration
- * @param {boolean} [options.withHyphenSeparator=false] - Use hyphens between words
- * @returns {string} The number in Belgian French words
- */
-export function toWords(value: number | string | bigint, options?: {
-    withHyphenSeparator?: boolean | undefined;
-}): string;