n2words 2.0.0 → 3.0.0

package/lib/languages/pl.js

@@ -1,110 +1,330 @@
-import { SlavicLanguage } from '../classes/slavic-language.js'
-
 /**
- * Polish language converter.
+ * Polish 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:
- * - Three-form pluralization (one/few/many)
- * - Polish-specific declension patterns
- * - Distinctive Polish phonology and orthography
+ * Polish-specific rules (handled in precomputation):
+ * - Three-form pluralization: 1 = singular, 2-4 = few, 5+ = many
+ * - Gender agreement (masculine/feminine for numbers < 1000)
+ * - Omit "jeden" before scale words (tysiąc, milion, etc.)
+ * - Irregular hundreds: dwieście, trzysta, czterysta, pięćset...
+ * - Long scale with -ard forms: miliard, biliard, tryliard
  */
-export class Polish extends SlavicLanguage {
-  negativeWord = 'minus'
-  decimalSeparatorWord = 'przecinek'
-  zeroWord = 'zero'
-
-  onesWords = {
-    1: 'jeden',
-    2: 'dwa',
-    3: 'trzy',
-    4: 'cztery',
-    5: 'pięć',
-    6: 'sześć',
-    7: 'siedem',
-    8: 'osiem',
-    9: 'dziewięć'
+
+import { parseNumericValue } from '../utils/parse-numeric.js'
+import { validateOptions } from '../utils/validate-options.js'
+
+// ============================================================================
+// Vocabulary (module-level constants)
+// ============================================================================
+
+const ONES_MASC = ['', 'jeden', 'dwa', 'trzy', 'cztery', 'pięć', 'sześć', 'siedem', 'osiem', 'dziewięć']
+const ONES_FEM = ['', 'jedna', 'dwie', 'trzy', 'cztery', 'pięć', 'sześć', 'siedem', 'osiem', 'dziewięć']
+
+const TEENS = ['dziesięć', 'jedenaście', 'dwanaście', 'trzynaście', 'czternaście', 'piętnaście', 'szesnaście', 'siedemnaście', 'osiemnaście', 'dziewiętnaście']
+
+const TENS = ['', '', 'dwadzieścia', 'trzydzieści', 'czterdzieści', 'pięćdziesiąt', 'sześćdziesiąt', 'siedemdziesiąt', 'osiemdziesiąt', 'dziewięćdziesiąt']
+
+// Irregular hundreds
+const HUNDREDS = ['', 'sto', 'dwieście', 'trzysta', 'czterysta', 'pięćset', 'sześćset', 'siedemset', 'osiemset', 'dziewięćset']
+
+// Scale words: [singular, few (2-4), many (5+)]
+const PLURAL_FORMS = {
+  1: ['tysiąc', 'tysiące', 'tysięcy'],
+  2: ['milion', 'miliony', 'milionów'],
+  3: ['miliard', 'miliardy', 'miliardów'],
+  4: ['bilion', 'biliony', 'bilionów'],
+  5: ['biliard', 'biliardy', 'biliardów'],
+  6: ['trylion', 'tryliony', 'trylionów'],
+  7: ['tryliard', 'tryliardy', 'tryliardów'],
+  8: ['kwadrylion', 'kwadryliony', 'kwadrylionów'],
+  9: ['kwaryliard', 'kwadryliardy', 'kwadryliardów'],
+  10: ['kwintylion', 'kwintyliony', 'kwintylionów']
+}
+
+const ZERO = 'zero'
+const NEGATIVE = 'minus'
+const DECIMAL_SEP = 'przecinek'
+
+// ============================================================================
+// Precomputed Lookup Tables (built once at module load)
+// ============================================================================
+
+/**
+ * Builds segment word for 0-999 (masculine form).
+ * @param {number} n - Segment value
+ * @returns {string} Polish word
+ */
+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
+  if (hundreds > 0) {
+    parts.push(HUNDREDS[hundreds])
   }
 
-  onesFeminineWords = {
-    1: 'jedna',
-    2: 'dwie',
-    3: 'trzy',
-    4: 'cztery',
-    5: 'pięć',
-    6: 'sześć',
-    7: 'siedem',
-    8: 'osiem',
-    9: 'dziewięć'
+  // Tens and ones
+  if (tens === 1) {
+    // Teens (10-19)
+    parts.push(TEENS[ones])
+  } else {
+    if (tens >= 2) {
+      parts.push(TENS[tens])
+    }
+    if (ones > 0) {
+      parts.push(ONES_MASC[ones])
+    }
   }
 
-  teensWords = {
-    0: 'dziesięć',
-    1: 'jedenaście',
-    2: 'dwanaście',
-    3: 'trzynaście',
-    4: 'czternaście',
-    5: 'piętnaście',
-    6: 'szesnaście',
-    7: 'siedemnaście',
-    8: 'osiemnaście',
-    9: 'dziewiętnaście'
+  return parts.join(' ')
+}
+
+/**
+ * Builds segment word for 0-999 (feminine form - only differs in ones).
+ * @param {number} n - Segment value
+ * @returns {string} Polish word
+ */
+function buildSegmentFeminine (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
+  if (hundreds > 0) {
+    parts.push(HUNDREDS[hundreds])
   }
 
-  twentiesWords = {
-    2: 'dwadzieścia',
-    3: 'trzydzieści',
-    4: 'czterdzieści',
-    5: 'pięćdziesiąt',
-    6: 'sześćdziesiąt',
-    7: 'siedemdziesiąt',
-    8: 'osiemdziesiąt',
-    9: 'dziewięćdziesiąt'
+  // Tens and ones - feminine for ones only
+  if (tens === 1) {
+    parts.push(TEENS[ones])
+  } else {
+    if (tens >= 2) {
+      parts.push(TENS[tens])
+    }
+    if (ones > 0) {
+      parts.push(ONES_FEM[ones])
+    }
+  }
+
+  return parts.join(' ')
+}
+
+// Precompute all 1000 segment words (0-999)
+const SEGMENTS_MASC = new Array(1000)
+const SEGMENTS_FEM = new Array(1000)
+for (let i = 0; i < 1000; i++) {
+  SEGMENTS_MASC[i] = buildSegment(i)
+  SEGMENTS_FEM[i] = buildSegmentFeminine(i)
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Polish pluralization: 1 = singular, 2-4 = few, else = many.
+ * Special case: 11-19 always use many form.
+ *
+ * @param {bigint} n - Number to pluralize
+ * @param {string[]} forms - [singular, few, many]
+ * @returns {string} Correct plural form
+ */
+function pluralize (n, forms) {
+  if (n === 1n) {
+    return forms[0]
   }
 
-  hundredsWords = {
-    1: 'sto',
-    2: 'dwieście',
-    3: 'trzysta',
-    4: 'czterysta',
-    5: 'pięćset',
-    6: 'sześćset',
-    7: 'siedemset',
-    8: 'osiemset',
-    9: 'dziewięćset'
+  const lastDigit = n % 10n
+  const lastTwoDigits = n % 100n
+
+  // Teens (11-19) always use many form
+  // 2-4 use few form (but not 12-14)
+  if (lastDigit >= 2n && lastDigit <= 4n && (lastTwoDigits < 10n || lastTwoDigits > 20n)) {
+    return forms[1]
   }
 
-  pluralForms = {
-    1: ['tysiąc', 'tysiące', 'tysięcy'], // 10^ 3
-    2: ['milion', 'miliony', 'milionów'], // 10^ 6
-    3: ['miliard', 'miliardy', 'miliardów'], // 10^ 9
-    4: ['bilion', 'biliony', 'bilionów'], // 10^ 12
-    5: ['biliard', 'biliardy', 'biliardów'], // 10^ 15
-    6: ['trylion', 'tryliony', 'trylionów'], // 10^ 18
-    7: ['tryliard', 'tryliardy', 'tryliardów'], // 10^ 21
-    8: ['kwadrylion', 'kwadryliony', 'kwadrylionów'], // 10^ 24
-    9: ['kwaryliard', 'kwadryliardy', 'kwadryliardów'], // 10^ 27
-    10: ['kwintylion', 'kwintyliony', 'kwintylionów'] // 10^ 30
+  return forms[2]
+}
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Polish words.
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @param {Object} options - Conversion options
+ * @returns {string} Polish words
+ */
+function integerToWords (n, options = {}) {
+  if (n === 0n) return ZERO
+
+  // Fast path: numbers < 1000 (direct lookup)
+  if (n < 1000n) {
+    const segments = options.gender === 'feminine' ? SEGMENTS_FEM : SEGMENTS_MASC
+    return segments[Number(n)]
   }
 
-  /**
-   * Polish omits "one" before scale words.
-   * e.g., 1000 is "tysiąc" not "jeden tysiąc"
-   */
-  omitOneBeforeScale = true
+  // Fast path: numbers < 1,000,000 (thousands)
+  if (n < 1_000_000n) {
+    const thousands = Number(n / 1000n)
+    const remainder = Number(n % 1000n)
+
+    const scaleWord = pluralize(BigInt(thousands), PLURAL_FORMS[1])
+
+    let result
+    if (thousands === 1) {
+      // Omit "jeden" before tysiąc
+      result = scaleWord
+    } else {
+      result = SEGMENTS_MASC[thousands] + ' ' + scaleWord
+    }
 
-  /** Implements Polish-specific three-form pluralization rules. */
-  pluralize (n, forms) {
-    if (n === 1n) {
-      return forms[0]
+    if (remainder > 0) {
+      result += ' ' + SEGMENTS_MASC[remainder]
     }
 
-    const lastDigit = n % 10n
-    const lastTwoDigits = n % 100n
+    return result
+  }
+
+  // For numbers >= 1,000,000, use scale decomposition
+  return buildLargeNumberWords(n, options)
+}
 
-    if (lastDigit < 5n && lastDigit > 1n && (lastTwoDigits < 10n || lastTwoDigits > 20n)) {
-      return forms[1]
+/**
+ * Builds words for numbers >= 1,000,000.
+ * Uses BigInt division for faster segment extraction.
+ *
+ * @param {bigint} n - Number >= 1,000,000
+ * @param {Object} options - Conversion options
+ * @returns {string} Polish words
+ */
+function buildLargeNumberWords (n, options) {
+  // 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(temp % 1000n)
+    temp = temp / 1000n
+  }
+
+  // Build result string directly
+  let result = ''
+
+  for (let i = segmentValues.length - 1; i >= 0; i--) {
+    const segment = segmentValues[i]
+    if (segment === 0n) continue
+
+    const segmentWord = SEGMENTS_MASC[Number(segment)]
+
+    if (result) result += ' '
+
+    if (i === 0) {
+      // Units segment
+      result += segmentWord
+    } else {
+      // Scale word needed
+      const forms = PLURAL_FORMS[i]
+      if (forms) {
+        const scaleWord = pluralize(segment, forms)
+
+        if (segment === 1n) {
+          // Omit "jeden" before scale words
+          result += scaleWord
+        } else {
+          result += segmentWord + ' ' + scaleWord
+        }
+      }
     }
+  }
 
-    return forms[2]
+  return result
+}
+
+/**
+ * Converts decimal digits to Polish words.
+ *
+ * @param {string} decimalPart - Decimal digits (without the point)
+ * @param {Object} options - Conversion options
+ * @returns {string} Polish 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 += ' '
+    result += integerToWords(BigInt(remainder), options)
+  }
+
+  return result
+}
+
+/**
+ * Converts a numeric value to Polish 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] - Conversion options
+ * @param {string} [options.gender='masculine'] - Gender for numbers < 1000
+ * @returns {string} The number in Polish words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toWords(1)                          // 'jeden'
+ * toWords(1, { gender: 'feminine' })  // 'jedna'
+ * toWords(1000)                       // 'tysiąc'
+ * toWords(2000)                       // 'dwa tysiące'
+ */
+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, options)
+  }
+
+  return result
 }
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+export { toWords }

package/lib/languages/pt.d.ts

@@ -1,29 +1,17 @@
 /**
- * (European) Portuguese language converter.
+ * Converts a numeric value to Portuguese words.
  *
- * Supports:
- * - Gender-aware hundreds (duzentos, trezentos)
- * - "e" (and) conjunction for number combinations
- * - Post-processing to normalize word flow
+ * 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 Portuguese words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toWords(21)           // 'vinte e um'
+ * toWords(100)          // 'cem'
+ * toWords(1000000)      // 'um milhão'
  */
-export class Portuguese extends GreedyScaleLanguage {
-    static POSTCLEAN_REGEX: RegExp;
-    scaleWords: (string | bigint)[][];
-    hundredsWords: {
-        1: string;
-        2: string;
-        3: string;
-        4: string;
-        5: string;
-        6: string;
-        7: string;
-        8: string;
-        9: string;
-    };
-    finalizeWords(words: any): any;
-    /** Combines two word-sets according to Portuguese grammar 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;