n2words 1.24.0 → 3.0.0

package/lib/languages/he.js

@@ -1,329 +1,276 @@
-import SlavicLanguage from '../classes/slavic-language.js'
-
 /**
- * @typedef {Object} HebrewOptions
- * @property {string} [and='ו'] Conjunction character (typically 'ו' for and).
- * @property {boolean} [biblical=false] Use biblical scale words instead of modern ones.
- * @property {boolean} [feminine=false] Use feminine forms for numbers.
- */
-
-/**
- * Hebrew language converter.
- *
- * Implements Hebrew number words using the Slavic language pattern:
- * - Hebrew alphabet and right-to-left text
- * - Hebrew number words (אחת, שתים, שלוש, ארבע...)
- * - Feminine number forms (default in Hebrew)
- * - Optional "ve" (ו, "and") conjunction between number groups
+ * Modern Hebrew language converter - Functional Implementation
  *
- * Key Features:
- * - Three-form pluralization system shared across Slavic languages
- *   * Form 1 (singular): 1 (e.g., "אלף")
- *   * Form 2 (few): 2-4, 22-24, 32-34... excluding teens (e.g., "אלפים")
- *   * Form 3 (many): all other numbers (e.g., "אלף")
- * - Chunk-based decomposition (splits into groups of 3 digits: ones, thousands, millions, etc.)
- * - Large number handling via thousands[] array with indexed [singular, few, many] forms
+ * Self-contained converter with segment-based decomposition.
  *
- * Features:
- * - Right-to-left text orientation
- * - Feminine grammatical gender for numbers
- * - Three-form pluralization (similar to Slavic pattern)
- * - Conjunction control via "and" option
+ * Key features:
+ * - Feminine grammatical forms (default in Modern Hebrew)
+ * - Dual forms for 2, 200, 2000
+ * - Special 1-9 thousands construct state
+ * - "ו" (ve) conjunction rules vary by position
+ * - Per-digit decimal reading
  *
- * Inherits from SlavicLanguage for complex pluralization algorithms.
+ * Optimization: Precomputed segment lookup tables for 0-999.
  */
-export class Hebrew extends SlavicLanguage {
-  negativeWord = 'מינוס'
-  decimalSeparatorWord = 'נקודה'
-  zeroWord = 'אפס'
-  convertDecimalsPerDigit = true
-
-  // Modern Hebrew (feminine forms)
-  ones = {
-    1: 'אחת',
-    2: 'שתים',
-    3: 'שלש',
-    4: 'ארבע',
-    5: 'חמש',
-    6: 'שש',
-    7: 'שבע',
-    8: 'שמונה',
-    9: 'תשע'
-  }
 
-  tens = {
-    0: 'עשר',
-    1: 'אחת עשרה',
-    2: 'שתים עשרה',
-    3: 'שלש עשרה',
-    4: 'ארבע עשרה',
-    5: 'חמש עשרה',
-    6: 'שש עשרה',
-    7: 'שבע עשרה',
-    8: 'שמונה עשרה',
-    9: 'תשע עשרה'
-  }
+import { parseNumericValue } from '../utils/parse-numeric.js'
+import { validateOptions } from '../utils/validate-options.js'
 
-  twenties = {
-    2: 'עשרים',
-    3: 'שלשים',
-    4: 'ארבעים',
-    5: 'חמישים',
-    6: 'ששים',
-    7: 'שבעים',
-    8: 'שמונים',
-    9: 'תשעים'
-  }
+// ============================================================================
+// Vocabulary (arrays for indexed access - faster than object property lookup)
+// ============================================================================
 
-  hundreds = {
-    1: 'מאה',
-    2: 'מאתיים',
-    3: 'מאות'
-  }
+// Feminine forms (default in Modern Hebrew) - index 0 unused
+const ONES = ['', 'אחת', 'שתים', 'שלש', 'ארבע', 'חמש', 'שש', 'שבע', 'שמונה', 'תשע']
+const TEENS = ['עשר', 'אחת עשרה', 'שתים עשרה', 'שלש עשרה', 'ארבע עשרה', 'חמש עשרה', 'שש עשרה', 'שבע עשרה', 'שמונה עשרה', 'תשע עשרה']
+const TENS = ['', '', 'עשרים', 'שלשים', 'ארבעים', 'חמישים', 'ששים', 'שבעים', 'שמונים', 'תשעים']
+const HUNDREDS = ['', 'מאה', 'מאתיים', 'שלש מאות', 'ארבע מאות', 'חמש מאות', 'שש מאות', 'שבע מאות', 'שמונה מאות', 'תשע מאות']
 
-  thousands = {
-    1: 'אלף',
-    2: 'אלפיים',
-    3: 'שלשת אלפים',
-    4: 'ארבעת אלפים',
-    5: 'חמשת אלפים',
-    6: 'ששת אלפים',
-    7: 'שבעת אלפים',
-    8: 'שמונת אלפים',
-    9: 'תשעת אלפים'
-  }
+// Special forms for 1-9 thousand (index 0 unused)
+const THOUSANDS_SPECIAL = ['', 'אלף', 'אלפיים', 'שלשת אלפים', 'ארבעת אלפים', 'חמשת אלפים', 'ששת אלפים', 'שבעת אלפים', 'שמונת אלפים', 'תשעת אלפים']
 
-  scale = {
-    1: 'אלף', // thousand (singular)
-    2: 'מיליון', // million
-    3: 'מיליארד', // billion
-    4: 'טריליון', // trillion
-    5: 'קוודרליון', // quadrillion
-    6: 'קווינטיליון' // quintillion
-  }
+// Scale words (index 1 = thousands, 2 = millions, etc.)
+const SCALE = ['', 'אלף', 'מיליון', 'מיליארד', 'טריליון', 'קוודרליון', 'קווינטיליון']
+const SCALE_PLURAL = ['', 'אלפים', 'מיליונים', 'מיליארדים', 'טריליונים', 'קוודרליונים', 'קווינטיליונים']
 
-  scalePlural = {
-    1: 'אלפים', // thousands
-    2: 'מיליונים', // millions
-    3: 'מיליארדים', // billions
-    4: 'טריליונים', // trillions
-    5: 'קוודרליונים', // quadrillions
-    6: 'קווינטיליונים' // quintillions
-  }
+const ZERO = 'אפס'
+const NEGATIVE = 'מינוס'
+const DECIMAL_SEP = 'נקודה'
 
-  // Biblical Hebrew (masculine forms)
-  biblicalOnes = {
-    1: 'אחד',
-    2: 'שניים',
-    3: 'שלשה',
-    4: 'ארבעה',
-    5: 'חמשה',
-    6: 'ששה',
-    7: 'שבעה',
-    8: 'שמונה',
-    9: 'תשעה'
-  }
+// ============================================================================
+// Precomputed Lookup Tables (built once at module load)
+// ============================================================================
 
-  biblicalTens = {
-    0: 'עשרה',
-    1: 'אחד עשר',
-    2: 'שנים עשר',
-    3: 'שלשה עשר',
-    4: 'ארבעה עשר',
-    5: 'חמשה עשר',
-    6: 'ששה עשר',
-    7: 'שבעה עשר',
-    8: 'שמונה עשר',
-    9: 'תשעה עשר'
-  }
+/**
+ * Builds segment word for scale segments (thousands, millions, etc.).
+ * "ו" is added before tens and ones when following hundreds.
+ */
+function buildScaleSegment (n, andWord) {
+  if (n === 0) return ''
 
-  biblicalTwenties = {
-    2: 'עשרים',
-    3: 'שלשים',
-    4: 'ארבעים',
-    5: 'חמישים',
-    6: 'ששים',
-    7: 'שבעים',
-    8: 'שמונים',
-    9: 'תשעים'
-  }
+  const ones = n % 10
+  const tens = Math.floor(n / 10) % 10
+  const hundreds = Math.floor(n / 100)
 
-  biblicalHundreds = {
-    1: 'מאה',
-    2: 'מאתיים',
-    3: 'מאות'
-  }
+  let result = ''
 
-  biblicalThousands = {
-    1: 'אלף',
-    2: 'אלפיים',
-    3: 'שלשת אלפים',
-    4: 'ארבעת אלפים',
-    5: 'חמשת אלפים',
-    6: 'ששת אלפים',
-    7: 'שבעת אלפים',
-    8: 'שמונת אלפים',
-    9: 'תשעת אלפים'
+  // Hundreds
+  if (hundreds > 0) {
+    result = HUNDREDS[hundreds]
   }
 
-  biblicalScale = {
-    1: 'אלף',
-    2: 'מיליון',
-    3: 'מיליארד',
-    4: 'טריליון',
-    5: 'קוודרליון',
-    6: 'קווינטיליון'
-  }
+  // Tens and ones
+  if (tens === 1) {
+    // Teens (10-19)
+    const teenWord = TEENS[ones]
+    if (result) {
+      result += ' ' + andWord + teenWord
+    } else {
+      result = teenWord
+    }
+  } else {
+    // Tens (20-90)
+    if (tens >= 2) {
+      if (result) {
+        result += ' ' + andWord + TENS[tens]
+      } else {
+        result = TENS[tens]
+      }
+    }
 
-  biblicalScalePlural = {
-    1: 'אלפים',
-    2: 'מיליונים',
-    3: 'מיליארדים',
-    4: 'טריליונים',
-    5: 'קוודרליונים',
-    6: 'קווינטיליונים'
+    // Ones
+    if (ones > 0) {
+      if (result) {
+        result += ' ' + andWord + ONES[ones]
+      } else {
+        result = ONES[ones]
+      }
+    }
   }
 
-  /**
-   * Initializes the Hebrew converter with language-specific options.
-   *
-   * @param {HebrewOptions} [options={}] Configuration options.
-   */
-  constructor ({ and = 'ו', biblical = false, feminine = false } = {}) {
-    super({ feminine })
-
-    this.and = and
-    this.feminine = feminine
-
-    this.biblical = biblical
-    if (this.biblical) {
-      this.ones = this.biblicalOnes
-      this.tens = this.biblicalTens
-      this.twenties = this.biblicalTwenties
-      this.hundreds = this.biblicalHundreds
-      this.thousands = this.biblicalThousands
-      this.scale = this.biblicalScale
-      this.scalePlural = this.biblicalScalePlural
-    }
+  return result
+}
+
+/**
+ * Builds segment word for units segment (no scale word).
+ * "ו" is only added before the final ones digit.
+ */
+function buildUnitsSegment (n, andWord) {
+  if (n === 0) return ''
+
+  const ones = n % 10
+  const tens = Math.floor(n / 10) % 10
+  const hundreds = Math.floor(n / 100)
+
+  let result = ''
+
+  // Hundreds
+  if (hundreds > 0) {
+    result = HUNDREDS[hundreds]
   }
 
-  convertWholePart (number) {
-    if (number === 0n) {
-      return this.zeroWord
+  // Tens (no conjunction)
+  if (tens === 1) {
+    // Teens (10-19)
+    if (result) {
+      result += ' ' + TEENS[ones]
+    } else {
+      result = TEENS[ones]
     }
-    const words = []
-    const chunks = this.splitByX(number.toString(), 3)
-    let index = chunks.length
-    for (const x of chunks) {
-      index = index - 1
-      if (x === 0n) {
-        continue
+  } else {
+    if (tens >= 2) {
+      if (result) {
+        result += ' ' + TENS[tens]
+      } else {
+        result = TENS[tens]
       }
+    }
 
-      const [n1, n2, n3] = this.getDigits(x)
-
-      if (index > 0) {
-        // For thousands and above, handle the full chunk value
-        const chunkWords = []
-        let hasHundreds = false
-
-        // Process hundreds in this chunk
-        if (n3 > 0n) {
-          hasHundreds = true
-          if (n3 <= 2n) {
-            chunkWords.push(this.hundreds[n3])
-          } else {
-            chunkWords.push(this.ones[n3] + ' ' + this.hundreds[3])
-          }
-        }
+    // Ones - conjunction only here
+    if (ones > 0) {
+      if (result) {
+        result += ' ' + andWord + ONES[ones]
+      } else {
+        result = ONES[ones]
+      }
+    }
+  }
 
-        // Process tens in this chunk
-        if (n2 > 1n) {
-          // Add conjunction if there were hundreds before
-          const tensWord = this.twenties[n2]
-          chunkWords.push(hasHundreds ? this.and + tensWord : tensWord)
-        }
+  return result
+}
 
-        // Process ones in this chunk
-        if (n2 === 1n) {
-          // Add conjunction if there were hundreds before
-          const onesWord = this.tens[n1]
-          chunkWords.push(hasHundreds ? this.and + onesWord : onesWord)
-        } else if (n1 > 0n) {
-          // For "one million", "one billion", etc., don't add the word "one"
-          if (x === 1n && index > 1) {
-            // Skip adding "one" for millions/billions/etc.
-          } else if (x <= 9n && chunkWords.length === 0 && index === 1) {
-            // Use special forms for 1-9 thousand
-            chunkWords.push(this.thousands[n1])
-          } else {
-            const onesWord = this.ones[n1]
-            // Add conjunction if there were hundreds or tens before
-            chunkWords.push((hasHundreds || n2 > 0n) ? this.and + onesWord : onesWord)
-          }
-        }
+// Precompute all 1000 segment words with default conjunction
+const SCALE_SEGMENTS = new Array(1000)
+const UNITS_SEGMENTS = new Array(1000)
+for (let i = 0; i < 1000; i++) {
+  SCALE_SEGMENTS[i] = buildScaleSegment(i, 'ו')
+  UNITS_SEGMENTS[i] = buildUnitsSegment(i, 'ו')
+}
 
-        // Add scale word (thousand, million, billion, etc.)
-        if (x > 9n || index > 1) {
-          // For numbers > 9 or higher scales, use appropriate scale word
-          if (x === 1n) {
-            // Singular form (e.g., "one thousand", "one million")
-            chunkWords.push(this.scale[index])
-          } else if (x === 2n && index === 1) {
-            // Special dual form for "two thousand" (already in thousands[2])
-            return [this.thousands[2], ...words].join(' ')
-          } else if (x === 2n) {
-            // For two million, two billion, etc. - use plural form
-            chunkWords.push(this.scalePlural[index])
-          } else if (index === 1) {
-            // For thousands (10+), always use singular "אלף"
-            chunkWords.push(this.scale[index])
-          } else {
-            // For millions/billions/etc. use plural form
-            chunkWords.push(this.scalePlural[index])
-          }
-        }
+// ============================================================================
+// Conversion Functions
+// ============================================================================
 
-        words.push(chunkWords.join(' '))
-        continue
-      }
+/**
+ * Converts a non-negative integer to Hebrew words.
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @param {Object} options - Conversion options
+ * @returns {string} Hebrew words
+ */
+function integerToWords (n, options) {
+  if (n === 0n) return ZERO
+
+  const andWord = options.andWord ?? 'ו'
+  const usePrecomputed = andWord === 'ו'
 
-      if (n3 > 0n) {
-        if (n3 <= 2n) {
-          words.push(this.hundreds[n3])
+  // Fast path: numbers < 1000 (direct lookup)
+  if (n < 1000n) {
+    return usePrecomputed ? UNITS_SEGMENTS[Number(n)] : buildUnitsSegment(Number(n), andWord)
+  }
+
+  // Extract segments using BigInt modulo
+  const segments = []
+  let temp = n
+  while (temp > 0n) {
+    segments.push(Number(temp % 1000n))
+    temp = temp / 1000n
+  }
+
+  // Build result string directly
+  let result = ''
+
+  for (let i = segments.length - 1; i >= 0; i--) {
+    const segment = segments[i]
+    if (segment === 0) continue
+
+    if (i === 0) {
+      // Units segment (no scale word)
+      const segmentWord = usePrecomputed ? UNITS_SEGMENTS[segment] : buildUnitsSegment(segment, andWord)
+      if (result) {
+        // Add "ו" before single-digit units when following scale words
+        if (segment <= 9) {
+          result += ' ' + andWord + segmentWord
         } else {
-          words.push(this.ones[n3] + ' ' + this.hundreds[3])
+          result += ' ' + segmentWord
         }
+      } else {
+        result = segmentWord
       }
-
-      if (n2 > 1n) {
-        words.push(this.twenties[n2])
+    } else if (i === 1) {
+      // Thousands - special handling for 1-9
+      if (segment <= 9) {
+        if (result) result += ' '
+        result += THOUSANDS_SPECIAL[segment]
+      } else {
+        const segmentWord = usePrecomputed ? SCALE_SEGMENTS[segment] : buildScaleSegment(segment, andWord)
+        if (result) result += ' '
+        result += segmentWord + ' ' + SCALE[1]
       }
-
-      if (n2 === 1n) {
-        words.push(this.tens[n1])
-      } else if (n1 > 0n) {
-        words.push(this.ones[n1])
+    } else {
+      // Millions and above
+      if (segment === 1) {
+        if (result) result += ' '
+        result += SCALE[i]
+      } else {
+        const segmentWord = usePrecomputed ? SCALE_SEGMENTS[segment] : buildScaleSegment(segment, andWord)
+        if (result) result += ' '
+        result += segmentWord + ' ' + SCALE_PLURAL[i]
       }
     }
+  }
 
-    if (words.length > 1) {
-      words[words.length - 1] = this.and + words.at(-1)
-    }
+  return result
+}
 
-    return words.join(' ')
+/**
+ * Converts decimal digits to Hebrew words (digit by digit).
+ *
+ * @param {string} decimalPart - Decimal digits (without the point)
+ * @returns {string} Hebrew words for decimal part
+ */
+function decimalPartToWords (decimalPart) {
+  let result = ''
+
+  for (let i = 0; i < decimalPart.length; i++) {
+    const d = parseInt(decimalPart[i], 10)
+    if (result) result += ' '
+    result += d === 0 ? ZERO : ONES[d]
   }
+
+  return result
 }
 
 /**
- * Converts a number to Hebrew cardinal (written) form.
+ * Converts a numeric value to Modern Hebrew words.
  *
- * @param {number|string|bigint} value The number to convert.
- * @param {HebrewOptions} [options={}] Configuration options.
- * @returns {string} The number expressed in Hebrew words.
- * @throws {TypeError} If value is NaN or invalid type.
- * @throws {Error} If value is an invalid number string.
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @param {Object} [options] - Optional configuration
+ * @param {('masculine'|'feminine')} [options.gender='masculine'] - Grammatical gender
+ * @param {string} [options.andWord] - Custom conjunction word
+ * @returns {string} The number in Modern Hebrew words
  */
-export default function convertToWords (value, options = {}) {
-  return new Hebrew(options).convertToWords(value)
+function toWords (value, options) {
+  options = validateOptions(options)
+  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+
+  let result = ''
+
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  result += integerToWords(integerPart, options)
+
+  if (decimalPart) {
+    result += ' ' + DECIMAL_SEP + ' ' + decimalPartToWords(decimalPart)
+  }
+
+  return result
 }
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export { toWords }

package/lib/languages/hi.d.ts

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