n2words 2.0.0 → 3.0.0

package/lib/languages/el.js

@@ -1,90 +1,243 @@
-import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js'
-
 /**
- * Greek language converter.
+ * Greek language converter - Functional Implementation
+ *
+ * A performance-optimized number-to-words converter using precomputed lookup tables.
  *
- * Supports:
+ * Key features:
  * - Space-separated number composition
  * - Implicit "one" (ένα) omission before scale words
- * - Digit-by-digit decimal reading
+ * - Irregular hundreds (διακόσια, τριακόσια, etc.)
+ * - Per-digit decimal reading
+ */
+
+import { parseNumericValue } from '../utils/parse-numeric.js'
+
+// ============================================================================
+// Vocabulary (module-level constants)
+// ============================================================================
+
+const ONES = ['', 'ένα', 'δύο', 'τρία', 'τέσσερα', 'πέντε', 'έξι', 'επτά', 'οκτώ', 'εννέα']
+
+const TEENS = ['δέκα', 'έντεκα', 'δώδεκα', 'δεκατρία', 'δεκατέσσερα', 'δεκαπέντε', 'δεκαέξι', 'δεκαεπτά', 'δεκαοκτώ', 'δεκαεννέα']
+
+const TENS = ['', '', 'είκοσι', 'τριάντα', 'σαράντα', 'πενήντα', 'εξήντα', 'εβδομήντα', 'ογδόντα', 'ενενήντα']
+
+// Greek has irregular hundreds
+const HUNDREDS = ['', 'εκατό', 'διακόσια', 'τριακόσια', 'τετρακόσια', 'πεντακόσια', 'εξακόσια', 'επτακόσια', 'οκτακόσια', 'εννιακόσια']
+
+const THOUSAND = 'χίλια'
+
+const ZERO = 'μηδέν'
+const NEGATIVE = 'μείον'
+const DECIMAL_SEP = 'κόμμα'
+
+// Short scale
+const SCALES = ['εκατομμύριο', 'δισεκατομμύριο', 'τρισεκατομμύριο']
+
+// ============================================================================
+// Precomputed Lookup Tables (built once at module load)
+// ============================================================================
+
+/**
+ * Builds segment word for 0-999.
  */
-export class Greek extends GreedyScaleLanguage {
-  negativeWord = 'μείον'
-  decimalSeparatorWord = 'κόμμα'
-  zeroWord = 'μηδέν'
-  usePerDigitDecimals = true
-
-  scaleWords = [
-    // Large numbers (limited set for now)
-    [1_000_000_000n, 'δισεκατομμύριο'],
-    [1_000_000n, 'εκατομμύριο'],
-    [1000n, 'χίλια'],
-
-    // Hundreds
-    [900n, 'εννιακόσια'],
-    [800n, 'οκτακόσια'],
-    [700n, 'επτακόσια'],
-    [600n, 'εξακόσια'],
-    [500n, 'πεντακόσια'],
-    [400n, 'τετρακόσια'],
-    [300n, 'τριακόσια'],
-    [200n, 'διακόσια'],
-    [100n, 'εκατό'],
-
-    // Tens
-    [90n, 'ενενήντα'],
-    [80n, 'ογδόντα'],
-    [70n, 'εβδομήντα'],
-    [60n, 'εξήντα'],
-    [50n, 'πενήντα'],
-    [40n, 'σαράντα'],
-    [30n, 'τριάντα'],
-    [20n, 'είκοσι'],
-    [19n, 'δεκαεννέα'],
-    [18n, 'δεκαοκτώ'],
-    [17n, 'δεκαεπτά'],
-    [16n, 'δεκαέξι'],
-    [15n, 'δεκαπέντε'],
-    [14n, 'δεκατέσσερα'],
-    [13n, 'δεκατρία'],
-    [12n, 'δώδεκα'],
-    [11n, 'έντεκα'],
-    [10n, 'δέκα'],
-
-    // Singles
-    [9n, 'εννέα'],
-    [8n, 'οκτώ'],
-    [7n, 'επτά'],
-    [6n, 'έξι'],
-    [5n, 'πέντε'],
-    [4n, 'τέσσερα'],
-    [3n, 'τρία'],
-    [2n, 'δύο'],
-    [1n, 'ένα'],
-    [0n, 'μηδέν']
-  ]
-
-  /** Combines two word-sets with Greek space-separation rules. */
-  combineWordSets (preceding, following) {
-    const precedingWord = Object.keys(preceding)[0]
-    const precedingValue = Object.values(preceding)[0]
-    const followingWord = Object.keys(following)[0]
-    const followingValue = Object.values(following)[0]
-
-    // Implicit one: omit "ένα" before any following value (> 0)
-    if (precedingValue === 1n) {
-      return following
+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 (irregular forms)
+  if (hundreds > 0) {
+    parts.push(HUNDREDS[hundreds])
+  }
+
+  // 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 {
+    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 Greek words.
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} Greek 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 "ένα" before χίλια
+    let result
+    if (thousands === 1) {
+      result = THOUSAND
+    } else {
+      result = SEGMENTS[thousands] + ' ' + THOUSAND
+    }
+
+    if (remainder > 0) {
+      result += ' ' + SEGMENTS[remainder]
     }
 
-    // No special handling needed for trailing 'ένα';
-    // nested merge will first collapse {1, 'ένα'} -> 'ένα'.
+    return result
+  }
 
-    // Multiplication: larger following scale multiplied by preceding number
-    if (followingValue > precedingValue) {
-      return { [`${precedingWord} ${followingWord}`]: precedingValue * followingValue }
+  // 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} Greek 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 "ένα" before χίλια
+        if (segment === 1) {
+          parts.push(THOUSAND)
+        } else {
+          parts.push(segmentWord + ' ' + THOUSAND)
+        }
+      } else {
+        // Millions+ - omit "ένα" before scale words
+        const scaleWord = SCALES[scaleIndex - 2]
+        if (segment === 1) {
+          parts.push(scaleWord)
+        } else {
+          parts.push(segmentWord + ' ' + scaleWord)
+        }
+      }
+    }
+
+    scaleIndex--
+  }
+
+  return parts.join(' ')
+}
+
+/**
+ * Converts decimal digits to Greek words (per-digit).
+ *
+ * @param {string} decimalPart - Decimal digits (without the point)
+ * @returns {string} Greek 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])
     }
+  }
 
-    // Addition: smaller numbers added together
-    return { [`${precedingWord} ${followingWord}`]: precedingValue + followingValue }
+  return parts.join(' ')
+}
+
+/**
+ * Converts a numeric value to Greek words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Greek 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(1000)     // 'χίλια'
+ * toWords('3.14')   // 'τρία κόμμα ένα τέσσερα'
+ */
+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/en.d.ts

@@ -1,16 +1,17 @@
 /**
- * English language converter.
+ * Converts a numeric value to English words.
  *
- * Supports:
- * - Hyphenated compounds (e.g., "twenty-three")
- * - "and" after hundreds (e.g., "one hundred and one")
- * - Numbers up to octillions
+ * 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'
  */
-export class English extends GreedyScaleLanguage {
-    scaleWords: (string | bigint)[][];
-    /** Combines two word-sets with English hyphenation and "and" rules. */
-    combineWordSets(preceding: any, following: any): {
-        [x: string]: any;
-    };
-}
-import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js';
+export function toWords(value: number | string | bigint): string;

package/lib/languages/en.js

@@ -1,86 +1,256 @@
-import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js'
+/**
+ * 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)
+// ============================================================================
 
 /**
- * English language converter.
+ * 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.
  *
- * Supports:
- * - Hyphenated compounds (e.g., "twenty-three")
- * - "and" after hundreds (e.g., "one hundred and one")
- * - Numbers up to octillions
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} English words
  */
-export class English extends GreedyScaleLanguage {
-  negativeWord = 'minus'
-  decimalSeparatorWord = 'point'
-  zeroWord = 'zero'
-
-  scaleWords = [
-    [1_000_000_000_000_000_000_000_000_000n, 'octillion'],
-    [1_000_000_000_000_000_000_000_000n, 'septillion'],
-    [1_000_000_000_000_000_000_000n, 'sextillion'],
-    [1_000_000_000_000_000_000n, 'quintillion'],
-    [1_000_000_000_000_000n, 'quadrillion'],
-    [1_000_000_000_000n, 'trillion'],
-    [1_000_000_000n, 'billion'],
-    [1_000_000n, 'million'],
-    [1000n, 'thousand'],
-    [100n, 'hundred'],
-    [90n, 'ninety'],
-    [80n, 'eighty'],
-    [70n, 'seventy'],
-    [60n, 'sixty'],
-    [50n, 'fifty'],
-    [40n, 'forty'],
-    [30n, 'thirty'],
-    [20n, 'twenty'],
-    [19n, 'nineteen'],
-    [18n, 'eighteen'],
-    [17n, 'seventeen'],
-    [16n, 'sixteen'],
-    [15n, 'fifteen'],
-    [14n, 'fourteen'],
-    [13n, 'thirteen'],
-    [12n, 'twelve'],
-    [11n, 'eleven'],
-    [10n, 'ten'],
-    [9n, 'nine'],
-    [8n, 'eight'],
-    [7n, 'seven'],
-    [6n, 'six'],
-    [5n, 'five'],
-    [4n, 'four'],
-    [3n, 'three'],
-    [2n, 'two'],
-    [1n, 'one'],
-    [0n, 'zero']
-  ]
-
-  /** Combines two word-sets with English hyphenation and "and" rules. */
-  combineWordSets (preceding, following) {
-    const precedingWord = Object.keys(preceding)[0]
-    const precedingValue = Object.values(preceding)[0]
-    const followingWord = Object.keys(following)[0]
-    const followingValue = Object.values(following)[0]
-
-    // Rule 1: Implicit "one" - omit when multiplying ("one hundred" → "hundred")
-    if (precedingValue === 1n && followingValue < 100n) {
-      return { [followingWord]: followingValue }
+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
+      }
     }
 
-    // Rule 2: Hyphenate compounds under 100 ("twenty-three")
-    if (precedingValue < 100n && precedingValue > followingValue) {
-      return { [`${precedingWord}-${followingWord}`]: precedingValue + followingValue }
+    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)
 
-    // Rule 3: Add "and" before units after hundreds ("one hundred and one")
-    if (precedingValue >= 100n && followingValue < 100n) {
-      return { [`${precedingWord} and ${followingWord}`]: precedingValue + followingValue }
+    // Add "and" only before FINAL segment if it follows scale and doesn't have hundred
+    if (result && isLastSegment && prevWasScale && !hasHundred) {
+      result += ' and'
     }
 
-    // Rule 4: Multiply when following > preceding ("one thousand")
-    if (followingValue > precedingValue) {
-      return { [`${precedingWord} ${followingWord}`]: precedingValue * followingValue }
+    // 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 { [`${precedingWord} ${followingWord}`]: precedingValue + followingValue }
+  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 }