n2words 1.24.0 → 3.0.0

package/lib/languages/nl.js

@@ -1,206 +1,339 @@
-import GreedyScaleLanguage from '../classes/greedy-scale-language.js'
+/**
+ * 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.
+ *
+ * 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
+ */
+
+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)
+// ============================================================================
 
 /**
- * @typedef {Object} DutchOptions
- * @property {boolean} [includeOptionalAnd=false] Include optional "en" separator.
- * @property {boolean} [noHundredPairs=false] Disable comma before hundreds.
- * @property {boolean} [accentOne=true] Use accented "één" for one.
+ * 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
+    }
+  }
+
+  // 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]
+    }
+  }
+
+  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
+// ============================================================================
 
 /**
- * Dutch language converter.
+ * Converts a non-negative integer to Dutch words.
  *
- * Features:
- * - Optional "en" (and) separator for tens (includeOptionalAnd)
- * - Optional comma before hundreds (noHundredPairs)
- * - Compound word formation without hyphenation
+ * @param {bigint} n - Non-negative integer to convert
+ * @param {Object} options - Conversion options
+ * @returns {string} Dutch words
  */
-export class Dutch extends GreedyScaleLanguage {
-  negativeWord = 'min'
-  decimalSeparatorWord = 'komma'
-  zeroWord = 'nul'
-  scaleWordPairs = [
-    [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']
-  ]
-
-  /**
-   * Initializes the Dutch converter with language-specific options.
-   *
-   * @param {DutchOptions} [options={}] Configuration options.
-   */
-  constructor ({ includeOptionalAnd = false, noHundredPairs = false, accentOne = true } = {}) {
-    super()
-
-    this.includeOptionalAnd = includeOptionalAnd
-
-    this.noHundredPairs = noHundredPairs
-
-    this.accentOne = accentOne
-    if (!this.accentOne) {
-      this.scaleWordPairs[this.scaleWordPairs.length - 2][1] = 'een'
+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
   }
 
-  /**
-   * Merges two adjacent word-number pairs according to Dutch grammar rules.
-   *
-   * Dutch-specific rules:
-   * - Implicit "één": `mergeScales({ 'één': 1n }, { 'duizend': 1000n })` → `{ 'duizend': 1000n }`
-   * - Reversed digit order for tens + units: `mergeScales({ 'twintig': 20n }, { 'één': 1n })` → `{ 'ééntwintig': 21n }`
-   * - Optional "en" separator based on includeOptionalAnd option
-   * - Compound words without separators for most combinations
-   * - Converts 'één' to 'een' in compound words (no accent in compounds)
-   * - Space separators for large numbers (millions+)
-   *
-   * @param {Object} current The left operand as `{ word: BigInt }`.
-   * @param {Object} next The right operand as `{ word: BigInt }`.
-   * @returns {Object} Merged pair with combined word and resulting numeric value.
-   *
-   * @example
-   * mergeScales({ 'één': 1n }, { 'duizend': 1000n }); // { 'duizend': 1000n }
-   * mergeScales({ 'twintig': 20n }, { 'drie': 3n }); // { 'drieentwintig': 23n }
-   */
-  mergeScales (current, next) {
-    let cText = Object.keys(current)[0]
-    let nText = Object.keys(next)[0]
-    const cNumber = Object.values(current)[0] // BigInt
-    const nNumber = Object.values(next)[0] // BigInt
-
-    // Implicit "een": omit before large multipliers ("miljoen" not "een miljoen")
-    if (cNumber === 1n) {
-      if (nNumber < 1_000_000n) {
-        return next
-      }
-      cText = this.accentOne ? 'één' : 'een'
-    }
+  // Fast path: numbers < 1000 (direct lookup)
+  if (n < 1000n) {
+    return applyAccent(segments[Number(n)])
+  }
 
-    // Handle multiplication and spacing
-    if (nNumber > cNumber) {
-      let hadSpace = false
-      // Large scale words (millions+): add space before multiplier
-      if (nNumber >= 1_000_000n) {
-        cText += ' '
-        hadSpace = true
-      } else if (nNumber > 100n) {
-        // Hundreds and above: add space after multiplier
-        nText += ' '
-        hadSpace = true
-      }
-      // Convert 'één' to 'een' in compounds (when no space or accentOne disabled)
-      if (!hadSpace || !this.accentOne) {
-        cText = cText.replace(/één/g, 'een')
-        nText = nText.replace(/één/g, 'een')
+  // 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 { [`${cText}${nText}`]: cNumber * nNumber }
+      return applyAccent(result)
     }
+  }
 
-    // Track if we're adding a space (which keeps words separate)
-    let hasSpace = false
-
-    if (nNumber < 10n && cNumber > 10n && cNumber < 100n) {
-      const temporary = nText
-      nText = cText
-      const andTxt = temporary.endsWith('e') ? 'ën' : 'en'
-      cText = `${temporary}${andTxt}`
-    } else if (nNumber < 13n && cNumber < 1000n && this.includeOptionalAnd) {
-      cText = `${cText}en`
-    } else if (nNumber < 13n && cNumber >= 1000n && this.includeOptionalAnd) {
-      nText = ` en ${nText}`
-      hasSpace = true
-    } else if (cNumber >= 1_000_000n) {
-      cText += ' '
-      hasSpace = true
-    } else if (cNumber === 1000n) {
-      cText += ' '
-      hasSpace = true
+  // Fast path: numbers < 1,000,000 (thousands)
+  if (n < 1_000_000n) {
+    const thousands = Number(n / 1000n)
+    const remainder = Number(n % 1000n)
+
+    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) {
-      cText = cText.replace(/één/g, 'een')
-      nText = nText.replace(/één/g, 'een')
-    } else if (!this.accentOne) {
-      cText = cText.replace(/één/g, 'een')
-      nText = nText.replace(/één/g, 'een')
+    if (remainder > 0) {
+      const remainderWord = segments[remainder]
+      if (includeOptionalAnd && remainder < 13) {
+        result += ' en ' + remainderWord
+      } else {
+        result += ' ' + remainderWord
+      }
     }
 
-    return { [`${cText}${nText}`]: cNumber + nNumber }
+    return applyAccent(result)
+  }
+
+  // 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
   }
 
-  convertWholePart (value) {
-    if (value >= 1100n && value < 10_000n && !this.noHundredPairs) {
-      const high = value / 100n
-      const low = value % 100n
-      if (high % 10n !== 0n) {
-        let result = super.convertWholePart(high) + 'honderd'
-        if (low) {
-          result +=
-            (this.includeOptionalAnd ? ' en ' : ' ') + super.convertWholePart(low)
+  // 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.convertWholePart(value)
   }
+
+  return result
 }
 
 /**
- * Converts a number to Dutch cardinal (written) form.
+ * Converts decimal digits to Dutch words.
  *
- * @param {number|string|bigint} value The number to convert.
- * @param {Object} [options] Conversion options (see Dutch class options).
- * @param {boolean} [options.includeOptionalAnd=false] Include optional 'en' (and) separator.
- * @param {boolean} [options.noHundredPairs=false] Don't combine hundreds with tens/units.
- * @param {boolean} [options.accentOne=true] Use accented 'één' for standalone 1.
- * @returns {string} The number expressed in Dutch words.
- * @throws {TypeError} If value is NaN or invalid type.
- * @throws {Error} If value is an invalid number string.
+ * @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
- * convertToWords(1); // 'één' (default accent)
- * convertToWords(1, { accentOne: false }); // 'een'
- * convertToWords(21); // 'eenentwintig' (no accent in compounds)
- * convertToWords(42); // 'tweeenveertig'
- * convertToWords('1.5'); // 'één komma vijf'
+ * toWords(21)                        // 'eenentwintig'
+ * toWords(1)                         // 'één'
+ * toWords(1, {accentOne: false})     // 'een'
+ * toWords(1104)                      // 'elfhonderd vier'
  */
-export default function convertToWords (value, options = {}) {
-  return new Dutch(options).convertToWords(value)
+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

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