n2words 2.0.0 → 3.0.0

package/lib/languages/nl.js

@@ -1,155 +1,339 @@
-import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js'
-
 /**
- * Dutch language converter.
+ * Dutch 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.
  *
- * Supports:
- * - Optional "en" (and) separator for tens
- * - Optional comma before hundreds
- * - Compound word formation without hyphenation
+ * Dutch-specific rules (handled in precomputation):
+ * - Inverted tens-ones: eenentwintig (one-and-twenty)
+ * - "ën" connector when ones ends in 'e' (twee, drie)
+ * - Compound words without spaces
+ * - Hundred pairing for 1100-9999 (elfhonderd style)
+ * - "één" vs "een" (accentOne option)
+ * - Optional "en" separator (includeOptionalAnd option)
+ * - Long scale with -ard forms
  */
-export class Dutch extends GreedyScaleLanguage {
-  negativeWord = 'min'
-  decimalSeparatorWord = 'komma'
-  zeroWord = 'nul'
-
-  scaleWords = [
-    [1_000_000_000_000_000_000_000_000_000n, 'quadriljard'],
-    [1_000_000_000_000_000_000_000_000n, 'quadriljoen'],
-    [1_000_000_000_000_000_000_000n, 'triljard'],
-    [1_000_000_000_000_000_000n, 'triljoen'],
-    [1_000_000_000_000_000n, 'biljard'],
-    [1_000_000_000_000n, 'biljoen'],
-    [1_000_000_000n, 'miljard'],
-    [1_000_000n, 'miljoen'],
-    [1000n, 'duizend'],
-    [100n, 'honderd'],
-    [90n, 'negentig'],
-    [80n, 'tachtig'],
-    [70n, 'zeventig'],
-    [60n, 'zestig'],
-    [50n, 'vijftig'],
-    [40n, 'veertig'],
-    [30n, 'dertig'],
-    [20n, 'twintig'],
-    [19n, 'negentien'],
-    [18n, 'achttien'],
-    [17n, 'zeventien'],
-    [16n, 'zestien'],
-    [15n, 'vijftien'],
-    [14n, 'veertien'],
-    [13n, 'dertien'],
-    [12n, 'twaalf'],
-    [11n, 'elf'],
-    [10n, 'tien'],
-    [9n, 'negen'],
-    [8n, 'acht'],
-    [7n, 'zeven'],
-    [6n, 'zes'],
-    [5n, 'vijf'],
-    [4n, 'vier'],
-    [3n, 'drie'],
-    [2n, 'twee'],
-    [1n, 'één'],
-    [0n, 'nul']
-  ]
-
-  constructor (options = {}) {
-    super()
-
-    this.setOptions({
-      includeOptionalAnd: false,
-      noHundredPairing: false,
-      accentOne: true
-    }, options)
-
-    if (!this.options.accentOne) {
-      this.scaleWords[this.scaleWords.length - 2][1] = 'een'
+
+import { parseNumericValue } from '../utils/parse-numeric.js'
+import { validateOptions } from '../utils/validate-options.js'
+
+// ============================================================================
+// Vocabulary (module-level constants)
+// ============================================================================
+
+const ONES = ['', 'een', 'twee', 'drie', 'vier', 'vijf', 'zes', 'zeven', 'acht', 'negen']
+const TEENS = ['tien', 'elf', 'twaalf', 'dertien', 'veertien', 'vijftien', 'zestien', 'zeventien', 'achttien', 'negentien']
+const TENS = ['', '', 'twintig', 'dertig', 'veertig', 'vijftig', 'zestig', 'zeventig', 'tachtig', 'negentig']
+
+const HUNDRED = 'honderd'
+
+// Scale words (long scale with -ard forms)
+const SCALES = ['duizend', 'miljoen', 'miljard', 'biljoen', 'biljard', 'triljoen', 'triljard', 'quadriljoen', 'quadriljard']
+
+const ZERO = 'nul'
+const NEGATIVE = 'min'
+const DECIMAL_SEP = 'komma'
+
+// ============================================================================
+// Precomputed Lookup Tables (built once at module load)
+// ============================================================================
+
+/**
+ * Builds segment word for 0-999.
+ * @param {number} n - Segment value
+ * @param {boolean} withAnd - Include "en" for values < 13 after hundreds
+ * @returns {string} Dutch word (compound, no spaces)
+ */
+function buildSegment (n, withAnd) {
+  if (n === 0) return ''
+
+  const ones = n % 10
+  const tens = Math.floor(n / 10) % 10
+  const hundreds = Math.floor(n / 100)
+  const tensOnes = n % 100
+
+  let result = ''
+
+  // Hundreds
+  if (hundreds > 0) {
+    if (hundreds === 1) {
+      result = HUNDRED
+    } else {
+      result = ONES[hundreds] + HUNDRED
     }
   }
 
-  /** Combines two word-sets according to Dutch grammar rules. */
-  combineWordSets (preceding, following) {
-    let precedingWord = Object.keys(preceding)[0]
-    let followingWord = Object.keys(following)[0]
-    const precedingValue = Object.values(preceding)[0] // BigInt
-    const followingValue = Object.values(following)[0] // BigInt
-
-    // Implicit "een": omit before large multipliers ("miljoen" not "een miljoen")
-    if (precedingValue === 1n) {
-      if (followingValue < 1_000_000n) {
-        return following
-      }
-      precedingWord = this.options.accentOne ? 'één' : 'een'
+  // Tens and ones
+  if (tensOnes === 0) {
+    // Just hundreds
+  } else if (tensOnes < 10) {
+    // Single digit - add "en" if withAnd and after hundreds
+    if (hundreds > 0 && withAnd) {
+      result += 'en' + ONES[tensOnes]
+    } else {
+      result += ONES[tensOnes]
+    }
+  } else if (tensOnes < 20) {
+    // Teens - add "en" if withAnd and after hundreds and < 13
+    if (hundreds > 0 && withAnd && tensOnes < 13) {
+      result += 'en' + TEENS[ones]
+    } else {
+      result += TEENS[ones]
+    }
+  } else {
+    // 20-99: Dutch inverts with connector
+    if (ones === 0) {
+      result += TENS[tens]
+    } else {
+      // "ën" if ones ends in 'e' (twee, drie)
+      const onesWord = ONES[ones]
+      const connector = onesWord.endsWith('e') ? 'ën' : 'en'
+      result += onesWord + connector + TENS[tens]
     }
+  }
 
-    // Handle multiplication and spacing
-    if (followingValue > precedingValue) {
-      let hadSpace = false
-      // Large scale words (millions+): add space before multiplier
-      if (followingValue >= 1_000_000n) {
-        precedingWord += ' '
-        hadSpace = true
-      } else if (followingValue > 100n) {
-        // Hundreds and above: add space after multiplier
-        followingWord += ' '
-        hadSpace = true
-      }
-      // Convert 'één' to 'een' in compounds (when no space or accentOne disabled)
-      if (!hadSpace || !this.options.accentOne) {
-        precedingWord = precedingWord.replace(/één/g, 'een')
-        followingWord = followingWord.replace(/één/g, 'een')
+  return result
+}
+
+// Precompute all 1000 segment words (0-999) - standard form
+const SEGMENTS = new Array(1000)
+for (let i = 0; i < 1000; i++) {
+  SEGMENTS[i] = buildSegment(i, false)
+}
+
+// Precompute all 1000 segment words (0-999) - with optional "en"
+const SEGMENTS_WITH_AND = new Array(1000)
+for (let i = 0; i < 1000; i++) {
+  SEGMENTS_WITH_AND[i] = buildSegment(i, true)
+}
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Dutch words.
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @param {Object} options - Conversion options
+ * @returns {string} Dutch words
+ */
+function integerToWords (n, options) {
+  if (n === 0n) return ZERO
+
+  const { accentOne, includeOptionalAnd, noHundredPairing } = options
+  const segments = includeOptionalAnd ? SEGMENTS_WITH_AND : SEGMENTS
+
+  // Apply één/een replacement
+  const applyAccent = (word) => {
+    if (accentOne) {
+      return word.replace(/\been\b/g, 'één')
+    }
+    return word
+  }
+
+  // Fast path: numbers < 1000 (direct lookup)
+  if (n < 1000n) {
+    return applyAccent(segments[Number(n)])
+  }
+
+  // Hundred pairing for 1100-9999
+  if (!noHundredPairing && n >= 1100n && n < 10000n) {
+    const high = Number(n / 100n)
+    const low = Number(n % 100n)
+
+    // Only use pairing when high is not a multiple of 10
+    if (high % 10 !== 0) {
+      let result = segments[high] + HUNDRED
+      if (low > 0) {
+        const lowWord = segments[low]
+        if (includeOptionalAnd && low < 13) {
+          result += ' en ' + lowWord
+        } else {
+          result += ' ' + lowWord
+        }
       }
-      return { [`${precedingWord}${followingWord}`]: precedingValue * followingValue }
+      return applyAccent(result)
     }
+  }
+
+  // Fast path: numbers < 1,000,000 (thousands)
+  if (n < 1_000_000n) {
+    const thousands = Number(n / 1000n)
+    const remainder = Number(n % 1000n)
 
-    // Track if we're adding a space (which keeps words separate)
-    let hasSpace = false
-
-    if (followingValue < 10n && precedingValue > 10n && precedingValue < 100n) {
-      const temporary = followingWord
-      followingWord = precedingWord
-      const andTxt = temporary.endsWith('e') ? 'ën' : 'en'
-      precedingWord = `${temporary}${andTxt}`
-    } else if (followingValue < 13n && precedingValue < 1000n && this.options.includeOptionalAnd) {
-      precedingWord = `${precedingWord}en`
-    } else if (followingValue < 13n && precedingValue >= 1000n && this.options.includeOptionalAnd) {
-      followingWord = ` en ${followingWord}`
-      hasSpace = true
-    } else if (precedingValue >= 1_000_000n) {
-      precedingWord += ' '
-      hasSpace = true
-    } else if (precedingValue === 1000n) {
-      precedingWord += ' '
-      hasSpace = true
+    let result
+    if (thousands === 1) {
+      // "duizend" not "eenduizend"
+      result = SCALES[0]
+    } else {
+      // Compound: "vijfduizend"
+      result = segments[thousands] + SCALES[0]
     }
 
-    // Convert 'één' to 'een' in direct compounds (no space)
-    // Keep 'één' only if there's a space AND accentOne=true
-    if (!hasSpace) {
-      precedingWord = precedingWord.replace(/één/g, 'een')
-      followingWord = followingWord.replace(/één/g, 'een')
-    } else if (!this.options.accentOne) {
-      precedingWord = precedingWord.replace(/één/g, 'een')
-      followingWord = followingWord.replace(/één/g, 'een')
+    if (remainder > 0) {
+      const remainderWord = segments[remainder]
+      if (includeOptionalAnd && remainder < 13) {
+        result += ' en ' + remainderWord
+      } else {
+        result += ' ' + remainderWord
+      }
     }
 
-    return { [`${precedingWord}${followingWord}`]: precedingValue + followingValue }
+    return applyAccent(result)
   }
 
-  integerToWords (integerPart) {
-    if (integerPart >= 1100n && integerPart < 10_000n && !this.options.noHundredPairing) {
-      const high = integerPart / 100n
-      const low = integerPart % 100n
-      if (high % 10n !== 0n) {
-        let result = super.integerToWords(high) + 'honderd'
-        if (low) {
-          result +=
-            (this.options.includeOptionalAnd ? ' en ' : ' ') + super.integerToWords(low)
+  // For numbers >= 1,000,000, use scale decomposition
+  return applyAccent(buildLargeNumberWords(n, options))
+}
+
+/**
+ * Builds words for numbers >= 1,000,000.
+ * Uses BigInt division for faster segment extraction (4x faster than string slicing).
+ *
+ * @param {bigint} n - Number >= 1,000,000
+ * @param {Object} options - Conversion options
+ * @returns {string} Dutch words
+ */
+function buildLargeNumberWords (n, options) {
+  const { includeOptionalAnd } = options
+  const segmentLookup = includeOptionalAnd ? SEGMENTS_WITH_AND : SEGMENTS
+
+  // Extract segments using BigInt division (faster than string slicing)
+  // Segments stored least-significant first (index 0 = ones, 1 = thousands, etc.)
+  const segmentValues = []
+  let temp = n
+  while (temp > 0n) {
+    segmentValues.push(Number(temp % 1000n))
+    temp = temp / 1000n
+  }
+
+  // Build result string directly (avoids object allocation and join)
+  let result = ''
+  let prevWasScale = false
+
+  for (let i = segmentValues.length - 1; i >= 0; i--) {
+    const segment = segmentValues[i]
+    if (segment === 0) continue
+
+    if (i === 0) {
+      // Units segment
+      const word = segmentLookup[segment]
+      if (result) {
+        if (prevWasScale && includeOptionalAnd && segment < 13) {
+          result += ' en ' + word
+        } else {
+          result += ' ' + word
         }
-        return result
+      } else {
+        result = word
       }
+      prevWasScale = false
+    } else if (i === 1) {
+      // Thousands - compound
+      if (result) result += ' '
+      if (segment === 1) {
+        result += SCALES[0]
+      } else {
+        result += segmentLookup[segment] + SCALES[0]
+      }
+      prevWasScale = true
+    } else {
+      // Million and above - space around scale
+      const scaleWord = SCALES[i - 1]
+      if (result) result += ' '
+      if (segment === 1) {
+        result += 'een ' + scaleWord
+      } else {
+        result += segmentLookup[segment] + ' ' + scaleWord
+      }
+      prevWasScale = true
     }
-    return super.integerToWords(integerPart)
   }
+
+  return result
+}
+
+/**
+ * Converts decimal digits to Dutch words.
+ *
+ * @param {string} decimalPart - Decimal digits (without the point)
+ * @param {Object} options - Conversion options
+ * @returns {string} Dutch words for decimal part
+ */
+function decimalPartToWords (decimalPart, options) {
+  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 += ' '
+    const word = integerToWords(BigInt(remainder), { ...options, noHundredPairing: true })
+    result += word
+  }
+
+  return result
 }
+
+/**
+ * Converts a numeric value to Dutch 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
+ * @param {Object} [options] - Optional configuration
+ * @param {boolean} [options.accentOne=true] - Use "één" instead of "een"
+ * @param {boolean} [options.includeOptionalAnd=false] - Include "en" before small numbers
+ * @param {boolean} [options.noHundredPairing=false] - Disable hundred pairing (1104→duizend honderdvier)
+ * @returns {string} The number in Dutch words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toWords(21)                        // 'eenentwintig'
+ * toWords(1)                         // 'één'
+ * toWords(1, {accentOne: false})     // 'een'
+ * toWords(1104)                      // 'elfhonderd vier'
+ */
+function toWords (value, options) {
+  options = validateOptions(options)
+  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+
+  const opts = {
+    accentOne: options.accentOne !== false, // default true
+    includeOptionalAnd: options.includeOptionalAnd || false,
+    noHundredPairing: options.noHundredPairing || false
+  }
+
+  let result = ''
+
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  result += integerToWords(integerPart, opts)
+
+  if (decimalPart) {
+    result += ' ' + DECIMAL_SEP + ' ' + decimalPartToWords(decimalPart, opts)
+  }
+
+  return result
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+export { toWords }

package/lib/languages/pa.d.ts

@@ -1,11 +1,7 @@
 /**
- * Punjabi language converter.
+ * Converts a numeric value to Punjabi words.
  *
- * Supports:
- * - Indian numbering system (ਹਜ਼ਾਰ, ਲੱਖ, ਕਰੋੜ)
- * - Gurmukhi script
- * - Complete word forms for 0-99
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Punjabi words
  */
-export class Punjabi extends SouthAsianLanguage {
-}
-import { SouthAsianLanguage } from '../classes/south-asian-language.js';
+export function toWords(value: number | string | bigint): string;