n2words 2.0.0 → 3.0.0

package/lib/languages/fa.js

@@ -1,144 +1,134 @@
-import { AbstractLanguage } from '../classes/abstract-language.js'
-
 /**
- * Persian language converter.
+ * Persian language converter - Functional Implementation
+ *
+ * Self-contained converter using recursive decomposition.
  *
- * Supports:
+ * Key features:
  * - "و" (and) conjunction for compound numbers
- * - Recursive conversion for larger numbers
+ * - Omit "یک" (one) before thousand
+ * - Pre-composed hundreds (دویست, سيصد, etc.)
  */
-export class Persian extends AbstractLanguage {
-  negativeWord = 'منفى'
-  decimalSeparatorWord = 'ممیّز'
-  zeroWord = 'صفر'
-
-  /**
-   * Words for digits 1-9.
-   * @type {Object.<number, string>}
-   */
-  onesWords = {
-    1: 'یک',
-    2: 'دو',
-    3: 'سه',
-    4: 'چهار',
-    5: 'پنج',
-    6: 'شش',
-    7: 'هفت',
-    8: 'هشت',
-    9: 'نه'
+
+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)]
   }
 
-  /**
-   * Words for teen numbers (10-19).
-   * @type {Object.<number, string>}
-   */
-  teensWords = {
-    10: 'ده',
-    11: 'یازده',
-    12: 'دوازده',
-    13: 'سیزده',
-    14: 'چهارده',
-    15: 'پانزده',
-    16: 'شانزده',
-    17: 'هفده',
-    18: 'هجده',
-    19: 'نوزده'
+  // 10-19
+  if (n <= 19n) {
+    return TEENS[Number(n)]
   }
 
-  /**
-   * Words for multiples of ten (20-90).
-   * @type {Object.<number, string>}
-   */
-  tensWords = {
-    20: 'بیست',
-    30: 'سی',
-    40: 'چهل',
-    50: 'پنجاه',
-    60: 'شصت',
-    70: 'هفتاد',
-    80: 'هشتاد',
-    90: 'نود'
+  // 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)]}`
   }
 
-  /**
-   * Words for hundreds (100-900).
-   * @type {Object.<number, string>}
-   */
-  hundredsWords = {
-    100: 'صد',
-    200: 'دویست',
-    300: 'سيصد',
-    400: 'چهار صد',
-    500: 'پانصد',
-    600: 'ششصد',
-    700: 'هفتصد',
-    800: 'هشتصد',
-    900: 'نهصد'
+  // 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)}`
   }
 
-  /**
-   * Scale magnitude words.
-   * @type {Object.<number, string>}
-   */
-  scaleWords = {
-    1000: 'هزار',
-    1_000_000: 'میلیون'
+  // 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}`
   }
 
-  /** Converts integer part using categorized word tables. */
-  integerToWords (integerPart) {
-    // Zero
-    if (integerPart === 0n) {
-      return this.zeroWord
-    }
+  // 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}`
+}
 
-    // 1-9
-    if (integerPart <= 9n) {
-      return this.onesWords[integerPart]
-    }
+function decimalPartToWords (decimalPart) {
+  let result = ''
+  let i = 0
 
-    // 10-19
-    if (integerPart <= 19n) {
-      return this.teensWords[integerPart]
-    }
+  while (i < decimalPart.length && decimalPart[i] === '0') {
+    if (result) result += ' '
+    result += ZERO
+    i++
+  }
 
-    // 20-99
-    if (integerPart < 100n) {
-      const ones = integerPart % 10n
-      const tens = integerPart - ones
-      if (ones === 0n) {
-        return this.tensWords[tens]
-      }
-      return `${this.tensWords[tens]} و ${this.onesWords[ones]}`
-    }
+  const remainder = decimalPart.slice(i)
+  if (remainder) {
+    if (result) result += ' '
+    result += integerToWords(BigInt(remainder))
+  }
 
-    // 100-999
-    if (integerPart < 1000n) {
-      const hundreds = 100n * (integerPart / 100n)
-      const remainder = integerPart - hundreds
-      if (remainder === 0n) {
-        return this.hundredsWords[hundreds]
-      }
-      return `${this.hundredsWords[hundreds]} و ${this.integerToWords(remainder)}`
-    }
+  return result
+}
 
-    // 1000-999999
-    if (integerPart < 1_000_000n) {
-      const thousandMultiplier = integerPart / 1000n
-      // Persian omits "one" before thousand: 1000 is just "هزار", not "یک هزار"
-      const thousandPrefix = thousandMultiplier === 1n
-        ? ''
-        : this.integerToWords(thousandMultiplier) + ' '
-      const remainder = integerPart % 1000n
-      const suffix = remainder === 0n ? '' : ' ' + this.integerToWords(remainder)
-      return `${thousandPrefix}${this.scaleWords[1000]}${suffix}`
-    }
+/**
+ * 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 + ' '
+  }
 
-    // 1000000+
-    const millionMultiplier = integerPart / 1_000_000n
-    const millionPrefix = this.integerToWords(millionMultiplier) + ' ' + this.scaleWords[1_000_000]
-    const remainder = integerPart % 1_000_000n
-    const suffix = remainder === 0n ? '' : ' و ' + this.integerToWords(remainder)
-    return `${millionPrefix}${suffix}`
+  result += integerToWords(integerPart)
+
+  if (decimalPart) {
+    result += ' ' + DECIMAL_SEP + ' ' + decimalPartToWords(decimalPart)
   }
+
+  return result
 }
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export { toWords }

package/lib/languages/fi.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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

@@ -0,0 +1,245 @@
+/**
+ * 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,16 +1,7 @@
 /**
- * Filipino language converter.
+ * Converts a numeric value to Filipino words.
  *
- * Supports:
- * - "ng" connectors between words
- * - Implicit "one" omission
- * - Special linkers for certain tens (e.g., "limampung")
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Filipino words
  */
-export class Filipino extends GreedyScaleLanguage {
-    scaleWords: (string | bigint)[][];
-    /** Converts integer part with explicit zero handling. */
-    integerToWords(integerPart: any): string;
-    /** Combines two word-sets with Filipino connector and linker rules. */
-    combineWordSets(preceding: any, following: any): any;
-}
-import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js';
+export function toWords(value: number | string | bigint): string;