n2words 3.0.0 → 3.1.0

package/lib/languages/ka.js

@@ -0,0 +1,291 @@
+/**
+ * Georgian language converter - Functional Implementation
+ *
+ * Self-contained module with its own input validation, ready for subpath exports.
+ *
+ * Georgian-specific rules:
+ * - Vigesimal (base-20) system for 20-99
+ * - 40 = ორმოცი (2×20), 60 = სამოცი (3×20), 80 = ოთხმოცი (4×20)
+ * - 30/50/70/90 use "და" + "ათი": ოცდაათი (20+10), ორმოცდაათი (40+10)
+ * - Compound numbers use "და" (da = "and") connector
+ * - Hundreds: unit prefix + ას (ორასი = 200)
+ * - Short scale for large numbers (მილიონი, მილიარდი, ტრილიონი)
+ */
+
+import { parseNumericValue } from '../utils/parse-numeric.js'
+
+// ============================================================================
+// Vocabulary (module-level constants)
+// ============================================================================
+
+// Numbers 0-9 (primitives)
+const ONES = ['ნული', 'ერთი', 'ორი', 'სამი', 'ოთხი', 'ხუთი', 'ექვსი', 'შვიდი', 'რვა', 'ცხრა']
+
+// Numbers 10-19
+const TEENS = ['ათი', 'თერთმეტი', 'თორმეტი', 'ცამეტი', 'თოთხმეტი', 'თხუთმეტი', 'თექვსმეტი', 'ჩვიდმეტი', 'თვრამეტი', 'ცხრამეტი']
+
+// Vigesimal bases: 20, 40, 60, 80 (with და connector forms)
+const VIGESIMAL = ['', 'ოცი', 'ორმოცი', 'სამოცი', 'ოთხმოცი']
+const VIGESIMAL_DA = ['', 'ოცდა', 'ორმოცდა', 'სამოცდა', 'ოთხმოცდა']
+
+// Prefixes for hundreds (unit forms without final vowel)
+const HUNDRED_PREFIXES = ['', '', 'ორ', 'სამ', 'ოთხ', 'ხუთ', 'ექვს', 'შვიდ', 'რვა', 'ცხრა']
+
+const HUNDRED = 'ასი'
+const HUNDRED_STEM = 'ას' // Without final vowel
+const THOUSAND = 'ათასი'
+const THOUSAND_STEM = 'ათას' // Without final vowel
+
+// Scale words (short scale) - indexed by segment position
+const SCALES = ['', '', 'მილიონი', 'მილიარდი', 'ტრილიონი', 'კვადრილიონი', 'კვინტილიონი', 'სექსტილიონი']
+
+const ZERO = 'ნული'
+const NEGATIVE = 'მინუს'
+const DECIMAL_SEP = 'მთელი'
+
+// ============================================================================
+// Segment Building
+// ============================================================================
+
+/**
+ * Builds segment word for 0-99 using vigesimal system.
+ * @param {number} n - Number 0-99
+ * @returns {string} Georgian word
+ */
+function buildTens (n) {
+  if (n < 10) return ONES[n]
+  if (n < 20) return TEENS[n - 10]
+
+  const vigesimalGroup = Math.floor(n / 20)
+  const remainder = n % 20
+
+  if (remainder === 0) {
+    return VIGESIMAL[vigesimalGroup]
+  }
+
+  // Use და connector: ოცდა + remainder
+  const base = VIGESIMAL_DA[vigesimalGroup]
+  if (remainder < 10) {
+    return base + ONES[remainder]
+  }
+  return base + TEENS[remainder - 10]
+}
+
+/**
+ * Builds segment word for 0-999.
+ * Returns object with full form and stem form (without final vowel).
+ * @param {number} n - Number 0-999
+ * @returns {{full: string, stem: string}} Georgian words
+ */
+function buildSegment (n) {
+  if (n === 0) return { full: '', stem: '' }
+  if (n < 100) {
+    const word = buildTens(n)
+    // Remove final vowel for stem
+    const lastChar = word.slice(-1)
+    const stem = (lastChar === 'ი' || lastChar === 'ა') ? word.slice(0, -1) : word
+    return { full: word, stem }
+  }
+
+  const hundreds = Math.floor(n / 100)
+  const remainder = n % 100
+
+  // Build hundreds: ასი (100), ორასი (200), etc.
+  let hundredWord
+  if (hundreds === 1) {
+    hundredWord = remainder > 0 ? HUNDRED_STEM : HUNDRED
+  } else {
+    hundredWord = HUNDRED_PREFIXES[hundreds] + (remainder > 0 ? HUNDRED_STEM : HUNDRED)
+  }
+
+  if (remainder > 0) {
+    const remainderWord = buildTens(remainder)
+    const full = hundredWord + ' ' + remainderWord
+    // Stem removes final vowel from remainder
+    const lastChar = remainderWord.slice(-1)
+    const remainderStem = (lastChar === 'ი' || lastChar === 'ა') ? remainderWord.slice(0, -1) : remainderWord
+    return { full, stem: hundredWord + ' ' + remainderStem }
+  }
+
+  // Hundreds only - stem removes final ი
+  return { full: hundredWord, stem: hundredWord.slice(0, -1) }
+}
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Georgian words.
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} Georgian words
+ */
+function integerToWords (n) {
+  if (n === 0n) return ZERO
+
+  // Fast path: numbers < 1000
+  if (n < 1000n) {
+    const { full } = buildSegment(Number(n))
+    return full
+  }
+
+  // Fast path: numbers < 1,000,000 (thousands)
+  if (n < 1_000_000n) {
+    const thousands = Number(n / 1000n)
+    const remainder = Number(n % 1000n)
+
+    let result
+    if (thousands === 1) {
+      // "ათასი" not "ერთი ათასი"
+      result = remainder > 0 ? THOUSAND_STEM : THOUSAND
+    } else {
+      // Use stem form before ათასი
+      const { stem: thousandsPart } = buildSegment(thousands)
+      result = thousandsPart + ' ' + (remainder > 0 ? THOUSAND_STEM : THOUSAND)
+    }
+
+    if (remainder > 0) {
+      const { full: remainderWord } = buildSegment(remainder)
+      result += ' ' + remainderWord
+    }
+
+    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} Georgian words
+ */
+function buildLargeNumberWords (n) {
+  const numStr = n.toString()
+  const len = numStr.length
+
+  // Build segments of 3 digits from left to right
+  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) {
+      if (scaleIndex === 0) {
+        // Units (no scale)
+        const { full } = buildSegment(segment)
+        parts.push(full)
+      } else if (scaleIndex === 1) {
+        // Thousands - check if there's a remainder
+        const hasRemainder = segments.slice(i + 1).some(s => s !== 0)
+        const thousandWord = hasRemainder ? THOUSAND_STEM : THOUSAND
+
+        if (segment === 1) {
+          parts.push(thousandWord)
+        } else {
+          const { stem } = buildSegment(segment)
+          parts.push(stem + ' ' + thousandWord)
+        }
+      } else {
+        // Million and above
+        const scaleWord = SCALES[scaleIndex] || SCALES[SCALES.length - 1]
+        if (segment === 1) {
+          parts.push('ერთი ' + scaleWord)
+        } else {
+          const { full } = buildSegment(segment)
+          parts.push(full + ' ' + scaleWord)
+        }
+      }
+    }
+
+    scaleIndex--
+  }
+
+  return parts.join(' ')
+}
+
+/**
+ * Converts decimal digits to Georgian words.
+ *
+ * @param {string} decimalPart - Decimal digits (without the point)
+ * @returns {string} Georgian 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 Georgian 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 Georgian words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toWords(21)           // 'ოცდაერთი'
+ * toWords(100)          // 'ასი'
+ * toWords(1000)         // 'ათასი'
+ */
+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/kn.js

@@ -1,7 +1,7 @@
 /**
  * Kannada language converter - Functional Implementation
  *
- * Self-contained converter for South Asian numbering.
+ * Self-contained module with its own input validation, ready for subpath exports.
  *
  * Key features:
  * - Indian numbering system (ಸಾವಿರ, ಲಕ್ಷ, ಕೋಟಿ)
@@ -39,26 +39,13 @@ const BELOW_HUNDRED = [
 const SCALE_WORDS = ['', 'ಸಾವಿರ', 'ಲಕ್ಷ', 'ಕೋಟಿ', 'ಅಬ್ಜ', 'ಖರ್ವ', 'ನೀಲ', 'ಪದ್ಮ', 'ಶಂಖ']
 
 // ============================================================================
-// Segment Splitting (inlined for performance)
+// Segment Building
 // ============================================================================
 
-function groupByThreeThenTwos (n) {
-  const numStr = n.toString()
-  if (numStr.length <= 3) return [Number(numStr)]
-
-  const segments = []
-  segments.unshift(Number(numStr.slice(-3)))
-
-  let remaining = numStr.slice(0, -3)
-  while (remaining.length > 0) {
-    segments.unshift(Number(remaining.slice(-2)))
-    remaining = remaining.slice(0, -2)
-  }
-
-  return segments
-}
-
-function segmentToWords (n) {
+/**
+ * Builds words for a 0-999 segment.
+ */
+function buildSegment (n) {
   if (n === 0) return ''
   if (n < 100) return BELOW_HUNDRED[n]
 
@@ -75,25 +62,51 @@ function segmentToWords (n) {
 // Conversion Functions
 // ============================================================================
 
+/**
+ * Converts a non-negative integer to Kannada words.
+ *
+ * Uses BigInt modulo for segment extraction (faster than string slicing).
+ * South Asian 3-2-2 grouping: first 3 digits, then groups of 2.
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} Kannada words
+ */
 function integerToWords (n) {
   if (n === 0n) return ZERO
 
-  const segments = groupByThreeThenTwos(n)
-  const segmentCount = segments.length
-  const words = []
+  // Fast path: numbers < 1000 (direct lookup)
+  if (n < 1000n) {
+    return buildSegment(Number(n))
+  }
+
+  // Extract segments using BigInt modulo
+  const segments = []
+  segments.push(Number(n % 1000n))
+  let temp = n / 1000n
+
+  while (temp > 0n) {
+    segments.push(Number(temp % 100n))
+    temp = temp / 100n
+  }
 
-  for (let i = 0; i < segmentCount; i++) {
-    const segmentValue = segments[i]
-    if (segmentValue === 0) continue
+  // Build result string (process from most-significant to least)
+  const words = []
+  for (let i = segments.length - 1; i >= 0; i--) {
+    const segment = segments[i]
+    if (segment === 0) continue
+
+    if (i === 0) {
+      words.push(buildSegment(segment))
+    } else {
+      words.push(BELOW_HUNDRED[segment])
+    }
 
-    const scaleIndex = segmentCount - i - 1
-    words.push(segmentToWords(segmentValue))
-    if (scaleIndex > 0 && SCALE_WORDS[scaleIndex]) {
-      words.push(SCALE_WORDS[scaleIndex])
+    if (i > 0 && SCALE_WORDS[i]) {
+      words.push(SCALE_WORDS[i])
     }
   }
 
-  return words.join(' ').trim()
+  return words.join(' ')
 }
 
 function decimalPartToWords (decimalPart) {

package/lib/languages/ko.js

@@ -1,7 +1,7 @@
 /**
  * Korean language converter - Functional Implementation
  *
- * A performance-optimized number-to-words converter using precomputed lookup tables.
+ * Self-contained module with its own input validation, ready for subpath exports.
  *
  * Key features:
  * - Myriad-based (만) grouping - 4 digits
@@ -31,7 +31,7 @@ const DECIMAL_SEP = '점'
 const SCALES = ['만', '억', '조', '경', '해', '자', '양']
 
 // ============================================================================
-// Precomputed Lookup Tables (built once at module load)
+// Segment Building
 // ============================================================================
 
 /**
@@ -83,13 +83,6 @@ function buildSegment (n) {
   return result
 }
 
-// Precompute all 10000 segment words (0-9999) for myriad grouping
-const SEGMENTS = new Array(10000)
-
-for (let i = 0; i < 10000; i++) {
-  SEGMENTS[i] = buildSegment(i)
-}
-
 // ============================================================================
 // Conversion Functions
 // ============================================================================
@@ -103,9 +96,9 @@ for (let i = 0; i < 10000; i++) {
 function integerToWords (n) {
   if (n === 0n) return ZERO
 
-  // Fast path: numbers < 10000 (direct lookup)
+  // Fast path: numbers < 10000
   if (n < 10000n) {
-    return SEGMENTS[Number(n)]
+    return buildSegment(Number(n))
   }
 
   // For numbers >= 10000, use myriad decomposition
@@ -148,7 +141,7 @@ function buildLargeNumberWords (n) {
     if (segment !== 0) {
       if (scaleIndex === 0) {
         // Units segment (no scale word)
-        parts.push({ word: SEGMENTS[segment], isScale: false })
+        parts.push({ word: buildSegment(segment), isScale: false })
       } else {
         // Segment with scale word
         const scaleWord = SCALES[scaleIndex - 1]
@@ -157,7 +150,7 @@ function buildLargeNumberWords (n) {
         if (segment === 1) {
           parts.push({ word: scaleWord, isScale: true })
         } else {
-          parts.push({ word: SEGMENTS[segment], isScale: false })
+          parts.push({ word: buildSegment(segment), isScale: false })
           parts.push({ word: scaleWord, isScale: true })
         }
       }

package/lib/languages/lt.js

@@ -1,7 +1,7 @@
 /**
  * Lithuanian language converter - Functional Implementation
  *
- * A performance-optimized number-to-words converter using precomputed lookup tables.
+ * Self-contained module with its own input validation, ready for subpath exports.
  *
  * Key features:
  * - Three-form pluralization (singular/plural/genitive)
@@ -45,7 +45,7 @@ const SCALE_FORMS = [
 ]
 
 // ============================================================================
-// Precomputed Lookup Tables (built once at module load)
+// Segment Building
 // ============================================================================
 
 /**
@@ -114,15 +114,6 @@ function buildSegmentFeminine (n) {
   return parts.join(' ')
 }
 
-// Precompute all 1000 segment words (0-999)
-const SEGMENTS_MASC = new Array(1000)
-const SEGMENTS_FEM = new Array(1000)
-
-for (let i = 0; i < 1000; i++) {
-  SEGMENTS_MASC[i] = buildSegment(i)
-  SEGMENTS_FEM[i] = buildSegmentFeminine(i)
-}
-
 // ============================================================================
 // Pluralization
 // ============================================================================
@@ -176,10 +167,10 @@ function pluralize (n, forms) {
 function integerToWords (n, options = {}) {
   if (n === 0n) return ZERO
 
-  // Fast path: numbers < 1000 (direct lookup)
+  // Fast path: numbers < 1000
   if (n < 1000n) {
-    const segments = options.gender === 'feminine' ? SEGMENTS_FEM : SEGMENTS_MASC
-    return segments[Number(n)]
+    const num = Number(n)
+    return options.gender === 'feminine' ? buildSegmentFeminine(num) : buildSegment(num)
   }
 
   // For numbers >= 1000, feminine only applies to final segment if < 1000
@@ -222,7 +213,7 @@ function buildLargeNumberWords (n, options) {
     const segment = segments[i]
 
     if (segment !== 0) {
-      const segmentWord = SEGMENTS_MASC[segment]
+      const segmentWord = buildSegment(segment)
 
       if (scaleIndex === 0) {
         // Units segment - use masculine (feminine doesn't apply when n >= 1000)

package/lib/languages/lv.js

@@ -1,7 +1,7 @@
 /**
  * Latvian language converter - Functional Implementation
  *
- * A performance-optimized number-to-words converter using precomputed lookup tables.
+ * Self-contained module with its own input validation, ready for subpath exports.
  *
  * Key features:
  * - Two-form pluralization (singular for 1 except 11, plural otherwise)
@@ -47,7 +47,7 @@ const SCALE_FORMS = [
 ]
 
 // ============================================================================
-// Precomputed Lookup Tables (built once at module load)
+// Segment Building
 // ============================================================================
 
 /**
@@ -133,15 +133,6 @@ function buildSegmentFeminine (n) {
   return parts.join(' ')
 }
 
-// Precompute all 1000 segment words (0-999)
-const SEGMENTS_MASC = new Array(1000)
-const SEGMENTS_FEM = new Array(1000)
-
-for (let i = 0; i < 1000; i++) {
-  SEGMENTS_MASC[i] = buildSegment(i)
-  SEGMENTS_FEM[i] = buildSegmentFeminine(i)
-}
-
 // ============================================================================
 // Pluralization
 // ============================================================================
@@ -182,10 +173,10 @@ function pluralize (n, forms) {
 function integerToWords (n, options = {}) {
   if (n === 0n) return ZERO
 
-  // Fast path: numbers < 1000 (direct lookup)
+  // Fast path: numbers < 1000
   if (n < 1000n) {
-    const segments = options.gender === 'feminine' ? SEGMENTS_FEM : SEGMENTS_MASC
-    return segments[Number(n)]
+    const num = Number(n)
+    return options.gender === 'feminine' ? buildSegmentFeminine(num) : buildSegment(num)
   }
 
   // For numbers >= 1000, feminine only applies to final segment if < 1000
@@ -227,7 +218,7 @@ function buildLargeNumberWords (n, options) {
     const segment = segments[i]
 
     if (segment !== 0) {
-      const segmentWord = SEGMENTS_MASC[segment]
+      const segmentWord = buildSegment(segment)
 
       if (scaleIndex === 0) {
         // Units segment - use masculine (feminine doesn't apply when n >= 1000)

package/lib/languages/mr.js

@@ -1,7 +1,7 @@
 /**
  * Marathi language converter - Functional Implementation
  *
- * Self-contained converter for South Asian numbering.
+ * Self-contained module with its own input validation, ready for subpath exports.
  *
  * Key features:
  * - Indian numbering system (हजार, लाख, कोटी)
@@ -39,26 +39,13 @@ const BELOW_HUNDRED = [
 const SCALE_WORDS = ['', 'हजार', 'लाख', 'कोटी', 'अब्ज', 'खर्व', 'निखर्व', 'महापद्म', 'शंकू']
 
 // ============================================================================
-// Segment Splitting (inlined for performance)
+// Segment Building
 // ============================================================================
 
-function groupByThreeThenTwos (n) {
-  const numStr = n.toString()
-  if (numStr.length <= 3) return [Number(numStr)]
-
-  const segments = []
-  segments.unshift(Number(numStr.slice(-3)))
-
-  let remaining = numStr.slice(0, -3)
-  while (remaining.length > 0) {
-    segments.unshift(Number(remaining.slice(-2)))
-    remaining = remaining.slice(0, -2)
-  }
-
-  return segments
-}
-
-function segmentToWords (n) {
+/**
+ * Builds words for a 0-999 segment.
+ */
+function buildSegment (n) {
   if (n === 0) return ''
   if (n < 100) return BELOW_HUNDRED[n]
 
@@ -75,25 +62,51 @@ function segmentToWords (n) {
 // Conversion Functions
 // ============================================================================
 
+/**
+ * Converts a non-negative integer to Marathi words.
+ *
+ * Uses BigInt modulo for segment extraction (faster than string slicing).
+ * South Asian 3-2-2 grouping: first 3 digits, then groups of 2.
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} Marathi words
+ */
 function integerToWords (n) {
   if (n === 0n) return ZERO
 
-  const segments = groupByThreeThenTwos(n)
-  const segmentCount = segments.length
-  const words = []
+  // Fast path: numbers < 1000 (direct lookup)
+  if (n < 1000n) {
+    return buildSegment(Number(n))
+  }
+
+  // Extract segments using BigInt modulo
+  const segments = []
+  segments.push(Number(n % 1000n))
+  let temp = n / 1000n
+
+  while (temp > 0n) {
+    segments.push(Number(temp % 100n))
+    temp = temp / 100n
+  }
 
-  for (let i = 0; i < segmentCount; i++) {
-    const segmentValue = segments[i]
-    if (segmentValue === 0) continue
+  // Build result string (process from most-significant to least)
+  const words = []
+  for (let i = segments.length - 1; i >= 0; i--) {
+    const segment = segments[i]
+    if (segment === 0) continue
+
+    if (i === 0) {
+      words.push(buildSegment(segment))
+    } else {
+      words.push(BELOW_HUNDRED[segment])
+    }
 
-    const scaleIndex = segmentCount - i - 1
-    words.push(segmentToWords(segmentValue))
-    if (scaleIndex > 0 && SCALE_WORDS[scaleIndex]) {
-      words.push(SCALE_WORDS[scaleIndex])
+    if (i > 0 && SCALE_WORDS[i]) {
+      words.push(SCALE_WORDS[i])
     }
   }
 
-  return words.join(' ').trim()
+  return words.join(' ')
 }
 
 function decimalPartToWords (decimalPart) {