n2words 3.0.0 → 3.1.0

package/lib/languages/en.js

@@ -1,16 +1,14 @@
 /**
- * English language converter - Functional Implementation v2
+ * English 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 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):
+ * Key features:
+ * - Western numbering system (thousand, million, billion)
  * - "and" after hundreds: "one hundred and twenty-three"
  * - Hyphenated tens-ones: "twenty-one", "forty-two"
  * - "and" before final segment when following scale word
+ * - BigInt modulo for efficient segment extraction
  */
 
 import { parseNumericValue } from '../utils/parse-numeric.js'
@@ -31,59 +29,53 @@ const NEGATIVE = 'minus'
 const DECIMAL_SEP = 'point'
 
 // ============================================================================
-// Precomputed Lookup Tables (built once at module load)
+// Segment Building
 // ============================================================================
 
+// Reusable result object to avoid allocation per call
+const segmentResult = { word: '', hasHundred: false }
+
 /**
- * Builds segment word for 0-999.
- * Returns object with word and whether it contains "hundred" (for "and" logic).
+ * Builds words for a 0-999 segment.
+ *
+ * @param {number} n - Number 0-999
+ * @returns {{ word: string, hasHundred: boolean }}
  */
 function buildSegment (n) {
-  if (n === 0) return { word: '', hasHundred: false }
+  if (n === 0) {
+    segmentResult.word = ''
+    segmentResult.hasHundred = false
+    return segmentResult
+  }
 
   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
-  }
+  const tens = Math.trunc(n / 10) % 10
+  const hundreds = Math.trunc(n / 100)
 
-  // Tens and ones
+  // Build tens-ones part first
   let tensOnes = ''
   if (tens === 1) {
     tensOnes = TEENS[ones]
   } else if (tens >= 2) {
-    if (ones > 0) {
-      tensOnes = TENS[tens] + '-' + ONES[ones]
-    } else {
-      tensOnes = TENS[tens]
-    }
+    tensOnes = ones > 0 ? TENS[tens] + '-' + ONES[ones] : TENS[tens]
   } else if (ones > 0) {
     tensOnes = ONES[ones]
   }
 
-  // Combine with "and" after hundreds
-  if (result && tensOnes) {
-    return { word: result + ' and ' + tensOnes, hasHundred: true }
+  // Hundreds place
+  if (hundreds > 0) {
+    if (tensOnes) {
+      segmentResult.word = ONES[hundreds] + ' ' + HUNDRED + ' and ' + tensOnes
+    } else {
+      segmentResult.word = ONES[hundreds] + ' ' + HUNDRED
+    }
+    segmentResult.hasHundred = true
+  } else {
+    segmentResult.word = tensOnes
+    segmentResult.hasHundred = false
   }
 
-  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
+  return segmentResult
 }
 
 // ============================================================================
@@ -99,26 +91,22 @@ for (let i = 0; i < 1000; i++) {
 function integerToWords (n) {
   if (n === 0n) return ZERO
 
-  // Fast path: numbers < 1000 (direct lookup)
+  // Fast path: numbers < 1000
   if (n < 1000n) {
-    return SEGMENTS[Number(n)]
+    return buildSegment(Number(n)).word
   }
 
-  // Fast path: numbers < 1,000,000 (thousands)
+  // Fast path: numbers < 1,000,000
   if (n < 1_000_000n) {
     const thousands = Number(n / 1000n)
     const remainder = Number(n % 1000n)
 
-    let result = SEGMENTS[thousands] + ' ' + SCALES[0]
+    const { word: thousandsWord } = buildSegment(thousands)
+    let result = thousandsWord + ' ' + 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
-      }
+      const { word: remainderWord, hasHundred } = buildSegment(remainder)
+      result += hasHundred ? ' ' + remainderWord : ' and ' + remainderWord
     }
 
     return result
@@ -136,7 +124,7 @@ function integerToWords (n) {
  * @returns {string} English words
  */
 function buildLargeNumberWords (n) {
-  // Extract segments using BigInt division (faster than string slicing)
+  // Extract segments using BigInt division
   // Segments are stored least-significant first (index 0 = ones, 1 = thousands, etc.)
   const segments = []
   let temp = n
@@ -154,8 +142,7 @@ function buildLargeNumberWords (n) {
     }
   }
 
-  // Build result string directly (avoids intermediate object allocations)
-  // Process from most-significant (end) to least-significant (start)
+  // Build result string (process from most-significant to least)
   let result = ''
   let prevWasScale = false
 
@@ -163,8 +150,7 @@ function buildLargeNumberWords (n) {
     const segment = segments[i]
     if (segment === 0) continue
 
-    const segmentWord = SEGMENTS[segment]
-    const hasHundred = SEGMENTS_HAS_HUNDRED[segment]
+    const { word, hasHundred } = buildSegment(segment)
     const isLastSegment = (i === firstNonZeroIdx)
 
     // Add "and" only before FINAL segment if it follows scale and doesn't have hundred
@@ -174,7 +160,7 @@ function buildLargeNumberWords (n) {
 
     // Add segment word
     if (result) result += ' '
-    result += segmentWord
+    result += word
 
     // Add scale word (i=0 is units, i=1 is thousands, etc.)
     if (i > 0) {

package/lib/languages/es.js

@@ -1,13 +1,9 @@
 /**
  * Spanish 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 optimization: Precompute all segment values (0-999) at module load.
- * This eliminates all per-call string manipulation for segment conversion.
- *
- * Spanish-specific rules (handled in precomputation):
+ * Spanish-specific rules:
  * - Gender agreement: uno/una, veintiuno/veintiuna, hundreds
  * - Special twenties: veinte, veintiuno, veintidós, ... veintinueve
  * - "y" conjunction: treinta y uno (only 30-99 with ones)
@@ -49,7 +45,7 @@ const NEGATIVE = 'menos'
 const DECIMAL_SEP = 'punto'
 
 // ============================================================================
-// Precomputed Lookup Tables (built once at module load)
+// Segment Building
 // ============================================================================
 
 /**
@@ -104,18 +100,6 @@ function buildSegment (n, feminine) {
   return parts.join(' ')
 }
 
-// Precompute all 1000 segment words (0-999) for masculine
-const SEGMENTS_MASC = new Array(1000)
-for (let i = 0; i < 1000; i++) {
-  SEGMENTS_MASC[i] = buildSegment(i, false)
-}
-
-// Precompute all 1000 segment words (0-999) for feminine
-const SEGMENTS_FEM = new Array(1000)
-for (let i = 0; i < 1000; i++) {
-  SEGMENTS_FEM[i] = buildSegment(i, true)
-}
-
 // ============================================================================
 // Helper Functions
 // ============================================================================
@@ -160,11 +144,9 @@ function getScaleWord (scaleIndex, segment) {
 function integerToWords (n, feminine) {
   if (n === 0n) return ZERO
 
-  const segments = feminine ? SEGMENTS_FEM : SEGMENTS_MASC
-
-  // Fast path: numbers < 1000 (direct lookup)
+  // Fast path: numbers < 1000
   if (n < 1000n) {
-    return segments[Number(n)]
+    return buildSegment(Number(n), feminine)
   }
 
   // Fast path: numbers < 1,000,000 (thousands)
@@ -178,7 +160,7 @@ function integerToWords (n, feminine) {
       result = THOUSAND
     } else {
       // Use masculine for thousands segment, but check for "uno" → omit before mil
-      const thousandsWord = SEGMENTS_MASC[thousands]
+      const thousandsWord = buildSegment(thousands, false)
       // "uno mil" → "mil" (handled in joinSegments equivalent)
       if (thousandsWord === 'uno' || thousandsWord === 'una') {
         result = THOUSAND
@@ -188,7 +170,7 @@ function integerToWords (n, feminine) {
     }
 
     if (remainder > 0) {
-      result += ' ' + segments[remainder]
+      result += ' ' + buildSegment(remainder, feminine)
     }
 
     return result
@@ -216,8 +198,6 @@ function buildLargeNumberWords (n, feminine) {
     temp = temp / 1000n
   }
 
-  const segments = feminine ? SEGMENTS_FEM : SEGMENTS_MASC
-
   // Build result string directly
   let result = ''
 
@@ -231,13 +211,13 @@ function buildLargeNumberWords (n, feminine) {
 
     if (i === 0) {
       // Units segment
-      result += segments[Number(segment)]
+      result += buildSegment(Number(segment), feminine)
     } else if (i === 1) {
       // Thousands: omit "uno" before mil
       if (segment === 1n) {
         result += THOUSAND
       } else {
-        result += SEGMENTS_MASC[Number(segment)] + ' ' + scaleWord
+        result += buildSegment(Number(segment), false) + ' ' + scaleWord
       }
     } else if (i % 2 === 1) {
       // Odd scale indices (3, 5, 7): "mil millones", "mil billones", etc.
@@ -245,7 +225,7 @@ function buildLargeNumberWords (n, feminine) {
       if (segment === 1n) {
         result += scaleWord
       } else {
-        result += SEGMENTS_MASC[Number(segment)] + ' ' + scaleWord
+        result += buildSegment(Number(segment), false) + ' ' + scaleWord
       }
     } else {
       // Even scale indices (2, 4, 6): millón, billón, trillón
@@ -254,7 +234,7 @@ function buildLargeNumberWords (n, feminine) {
         result += 'un ' + scaleWord
       } else {
         // Use masculine for scale segment
-        result += SEGMENTS_MASC[Number(segment)] + ' ' + scaleWord
+        result += buildSegment(Number(segment), false) + ' ' + scaleWord
       }
     }
   }

package/lib/languages/fi.js

@@ -1,7 +1,7 @@
 /**
  * Finnish 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:
  * - Compound tens+ones without spaces: "kaksikymmentäyksi" (21)
@@ -35,7 +35,7 @@ const DECIMAL_SEP = 'pilkku'
 const SCALES = ['miljoona', 'miljardi', 'biljoona', 'triljoona']
 
 // ============================================================================
-// Precomputed Lookup Tables (built once at module load)
+// Segment Building
 // ============================================================================
 
 /**
@@ -79,13 +79,6 @@ function buildSegment (n) {
   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
 // ============================================================================
@@ -101,7 +94,7 @@ function integerToWords (n) {
 
   // Fast path: numbers < 1000 (direct lookup)
   if (n < 1000n) {
-    return SEGMENTS[Number(n)]
+    return buildSegment(Number(n))
   }
 
   // Fast path: numbers < 1,000,000 (thousands)
@@ -114,11 +107,11 @@ function integerToWords (n) {
     if (thousands === 1) {
       result = THOUSAND
     } else {
-      result = SEGMENTS[thousands] + ' ' + THOUSAND
+      result = buildSegment(thousands) + ' ' + THOUSAND
     }
 
     if (remainder > 0) {
-      result += ' ' + SEGMENTS[remainder]
+      result += ' ' + buildSegment(remainder)
     }
 
     return result
@@ -161,7 +154,7 @@ function buildLargeNumberWords (n) {
     const segment = segments[i]
 
     if (segment !== 0) {
-      const segmentWord = SEGMENTS[segment]
+      const segmentWord = buildSegment(segment)
 
       if (scaleIndex === 0) {
         // Units segment

package/lib/languages/fil.js

@@ -1,7 +1,7 @@
 /**
  * Filipino language converter - Functional Implementation
  *
- * Self-contained converter with precomputed lookup tables.
+ * Self-contained module with its own input validation, ready for subpath exports.
  *
  * Key features:
  * - Linker "ng" after vowels: "isang daang" (100)
@@ -46,7 +46,7 @@ function addLinker (word) {
 }
 
 // ============================================================================
-// Precomputed Lookup Table
+// Segment Building
 // ============================================================================
 
 function buildSegment (n) {
@@ -91,16 +91,11 @@ function buildSegment (n) {
   return parts.join(' ')
 }
 
-const SEGMENTS = new Array(1000)
-for (let i = 0; i < 1000; i++) {
-  SEGMENTS[i] = buildSegment(i)
-}
-
 /**
  * Builds segment with linker added to last word (for use before scale words).
  */
 function buildSegmentWithLinker (n) {
-  const segmentWord = SEGMENTS[n]
+  const segmentWord = buildSegment(n)
   if (!segmentWord) return ''
 
   // Find the last space to get the last word
@@ -124,12 +119,6 @@ function buildSegmentWithLinker (n) {
   return prefix + addLinker(lastWord)
 }
 
-// Precompute segments with linker for scale word usage
-const SEGMENTS_WITH_LINKER = new Array(1000)
-for (let i = 0; i < 1000; i++) {
-  SEGMENTS_WITH_LINKER[i] = buildSegmentWithLinker(i)
-}
-
 // ============================================================================
 // Conversion Functions
 // ============================================================================
@@ -138,7 +127,7 @@ function integerToWords (n) {
   if (n === 0n) return ZERO
 
   if (n < 1000n) {
-    return SEGMENTS[Number(n)]
+    return buildSegment(Number(n))
   }
 
   return buildLargeNumberWords(n)
@@ -170,10 +159,10 @@ function buildLargeNumberWords (n) {
     if (result) result += ' '
 
     if (i === 0) {
-      result += SEGMENTS[segment]
+      result += buildSegment(segment)
     } else {
       // Add linker to segment before scale word
-      const segmentWord = SEGMENTS_WITH_LINKER[segment]
+      const segmentWord = buildSegmentWithLinker(segment)
       result += segmentWord + ' ' + scaleWord
     }
   }

package/lib/languages/fr-BE.js

@@ -1,7 +1,7 @@
 /**
  * French (Belgium) language converter - Functional Implementation
  *
- * Self-contained converter with precomputed lookup tables.
+ * Self-contained module with its own input validation, ready for subpath exports.
  *
  * Belgian French differences from standard French:
  * - septante (70) instead of soixante-dix
@@ -32,7 +32,7 @@ const NEGATIVE = 'moins'
 const DECIMAL_SEP = 'virgule'
 
 // ============================================================================
-// Precomputed Lookup Tables
+// Segment Building
 // ============================================================================
 
 function buildSegment (n) {
@@ -112,18 +112,6 @@ function buildSegment (n) {
   return { word: parts.join(' '), endsWithCents, endsWithVingts }
 }
 
-// Precompute all 1000 segment words
-const SEGMENTS = new Array(1000)
-const SEGMENTS_ENDS_CENTS = new Array(1000)
-const SEGMENTS_ENDS_VINGTS = new Array(1000)
-
-for (let i = 0; i < 1000; i++) {
-  const result = buildSegment(i)
-  SEGMENTS[i] = result.word
-  SEGMENTS_ENDS_CENTS[i] = result.endsWithCents
-  SEGMENTS_ENDS_VINGTS[i] = result.endsWithVingts
-}
-
 // ============================================================================
 // Helper Functions
 // ============================================================================
@@ -152,7 +140,7 @@ function integerToWords (n, withHyphen = false) {
   if (n === 0n) return ZERO
 
   if (n < 1000n) {
-    const word = SEGMENTS[Number(n)]
+    const { word } = buildSegment(Number(n))
     return withHyphen ? word.replace(/ /g, '-') : word
   }
 
@@ -164,15 +152,17 @@ function integerToWords (n, withHyphen = false) {
     if (thousands === 1) {
       result = THOUSAND
     } else {
-      let thousandsWord = SEGMENTS[thousands]
-      if (SEGMENTS_ENDS_CENTS[thousands] || SEGMENTS_ENDS_VINGTS[thousands]) {
-        thousandsWord = thousandsWord.slice(0, -1)
+      const { word: thousandsWord, endsWithCents, endsWithVingts } = buildSegment(thousands)
+      let adjustedWord = thousandsWord
+      if (endsWithCents || endsWithVingts) {
+        adjustedWord = thousandsWord.slice(0, -1)
       }
-      result = thousandsWord + (withHyphen ? '-' : ' ') + THOUSAND
+      result = adjustedWord + (withHyphen ? '-' : ' ') + THOUSAND
     }
 
     if (remainder > 0) {
-      result += (withHyphen ? '-' : ' ') + SEGMENTS[remainder]
+      const { word: remainderWord } = buildSegment(remainder)
+      result += (withHyphen ? '-' : ' ') + remainderWord
     }
 
     if (withHyphen) {
@@ -211,22 +201,23 @@ function buildLargeNumberWords (n, withHyphen) {
 
     if (segment !== 0) {
       const scaleWord = scaleIndex > 0 ? getScaleWord(scaleIndex, BigInt(segment)) : ''
+      const { word: segWords, endsWithCents, endsWithVingts } = buildSegment(segment)
 
       if (scaleIndex === 0) {
-        parts.push(SEGMENTS[segment])
+        parts.push(segWords)
       } else if (scaleIndex === 1) {
         if (segment === 1) {
           parts.push(THOUSAND)
         } else {
-          let segWords = SEGMENTS[segment]
-          if (SEGMENTS_ENDS_CENTS[segment] || SEGMENTS_ENDS_VINGTS[segment]) {
-            segWords = segWords.slice(0, -1)
+          let adjustedWord = segWords
+          if (endsWithCents || endsWithVingts) {
+            adjustedWord = segWords.slice(0, -1)
           }
-          parts.push(segWords)
+          parts.push(adjustedWord)
           parts.push(scaleWord)
         }
       } else {
-        parts.push(SEGMENTS[segment])
+        parts.push(segWords)
         parts.push(scaleWord)
       }
     }

package/lib/languages/fr.js

@@ -1,13 +1,9 @@
 /**
  * French 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 optimization: Precompute all segment values (0-999) at module load.
- * This eliminates all per-call string manipulation for segment conversion.
- *
- * French-specific rules (handled in precomputation):
+ * French-specific rules:
  * - Vigesimal patterns: 70 = soixante-dix, 80 = quatre-vingts, 90 = quatre-vingt-dix
  * - "et" conjunction: vingt et un (21), soixante et onze (71), but NOT quatre-vingt-un
  * - Pluralization: "cents" loses 's' when followed by more digits
@@ -37,7 +33,7 @@ const NEGATIVE = 'moins'
 const DECIMAL_SEP = 'virgule'
 
 // ============================================================================
-// Precomputed Lookup Tables (built once at module load)
+// Segment Building
 // ============================================================================
 
 /**
@@ -128,18 +124,6 @@ function buildSegment (n) {
   return { word: parts.join(' '), endsWithCents, endsWithVingts }
 }
 
-// Precompute all 1000 segment words (0-999)
-const SEGMENTS = new Array(1000)
-const SEGMENTS_ENDS_CENTS = new Array(1000)
-const SEGMENTS_ENDS_VINGTS = new Array(1000)
-
-for (let i = 0; i < 1000; i++) {
-  const result = buildSegment(i)
-  SEGMENTS[i] = result.word
-  SEGMENTS_ENDS_CENTS[i] = result.endsWithCents
-  SEGMENTS_ENDS_VINGTS[i] = result.endsWithVingts
-}
-
 // ============================================================================
 // Helper Functions
 // ============================================================================
@@ -183,9 +167,9 @@ function getScaleWord (scaleIndex, segment) {
 function integerToWords (n, withHyphen = false) {
   if (n === 0n) return ZERO
 
-  // Fast path: numbers < 1000 (direct lookup)
+  // Fast path: numbers < 1000
   if (n < 1000n) {
-    const word = SEGMENTS[Number(n)]
+    const { word } = buildSegment(Number(n))
     return withHyphen ? word.replace(/ /g, '-') : word
   }
 
@@ -200,15 +184,17 @@ function integerToWords (n, withHyphen = false) {
       result = THOUSAND
     } else {
       // Check if segment ends with "cents" or "vingts" - need to strip 's' before mille
-      let thousandsWord = SEGMENTS[thousands]
-      if (SEGMENTS_ENDS_CENTS[thousands] || SEGMENTS_ENDS_VINGTS[thousands]) {
-        thousandsWord = thousandsWord.slice(0, -1) // Remove trailing 's'
+      const { word: thousandsWord, endsWithCents, endsWithVingts } = buildSegment(thousands)
+      let adjustedWord = thousandsWord
+      if (endsWithCents || endsWithVingts) {
+        adjustedWord = thousandsWord.slice(0, -1) // Remove trailing 's'
       }
-      result = thousandsWord + (withHyphen ? '-' : ' ') + THOUSAND
+      result = adjustedWord + (withHyphen ? '-' : ' ') + THOUSAND
     }
 
     if (remainder > 0) {
-      result += (withHyphen ? '-' : ' ') + SEGMENTS[remainder]
+      const { word: remainderWord } = buildSegment(remainder)
+      result += (withHyphen ? '-' : ' ') + remainderWord
     }
 
     if (withHyphen) {
@@ -257,26 +243,27 @@ function buildLargeNumberWords (n, withHyphen) {
 
     if (segment !== 0) {
       const scaleWord = scaleIndex > 0 ? getScaleWord(scaleIndex, BigInt(segment)) : ''
+      const { word: segWords, endsWithCents, endsWithVingts } = buildSegment(segment)
 
       if (scaleIndex === 0) {
         // Units segment
-        parts.push(SEGMENTS[segment])
+        parts.push(segWords)
       } else if (scaleIndex === 1) {
         // Thousands: "mille" not "un mille"
         if (segment === 1) {
           parts.push(THOUSAND)
         } else {
-          let segWords = SEGMENTS[segment]
           // Strip 's' from cents/vingts before mille
-          if (SEGMENTS_ENDS_CENTS[segment] || SEGMENTS_ENDS_VINGTS[segment]) {
-            segWords = segWords.slice(0, -1)
+          let adjustedWord = segWords
+          if (endsWithCents || endsWithVingts) {
+            adjustedWord = segWords.slice(0, -1)
           }
-          parts.push(segWords)
+          parts.push(adjustedWord)
           parts.push(scaleWord)
         }
       } else {
         // Million and above
-        parts.push(SEGMENTS[segment])
+        parts.push(segWords)
         parts.push(scaleWord)
       }
     }