n2words 3.0.0 → 4.0.0

package/lib/languages/pl.js

@@ -1,330 +0,0 @@
-/**
- * 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.
- *
- * 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
- */
-
-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])
-  }
-
-  // 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])
-    }
-  }
-
-  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])
-  }
-
-  // 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]
-  }
-
-  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]
-  }
-
-  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)]
-  }
-
-  // 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
-    }
-
-    if (remainder > 0) {
-      result += ' ' + SEGMENTS_MASC[remainder]
-    }
-
-    return result
-  }
-
-  // For numbers >= 1,000,000, use scale decomposition
-  return buildLargeNumberWords(n, options)
-}
-
-/**
- * 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 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,17 +0,0 @@
-/**
- * Converts a numeric value to Portuguese 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
- * @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 function toWords(value: number | string | bigint): string;

package/lib/languages/pt.js

@@ -1,306 +0,0 @@
-/**
- * Portuguese 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.
- *
- * Portuguese-specific rules (handled in precomputation):
- * - "e" conjunction everywhere: vinte e um, cento e um, mil e um
- * - "cem" for exact 100, "cento" for 100+ remainder
- * - Irregular hundreds: duzentos, trezentos, quatrocentos, etc.
- * - Compound scale: milhão (10^6), mil milhões (10^9), bilião (10^12)
- * - Omit "um" before "mil"
- */
-
-import { parseNumericValue } from '../utils/parse-numeric.js'
-
-// ============================================================================
-// Vocabulary (module-level constants)
-// ============================================================================
-
-const ONES = ['', 'um', 'dois', 'três', 'quatro', 'cinco', 'seis', 'sete', 'oito', 'nove']
-const TEENS = ['dez', 'onze', 'doze', 'treze', 'catorze', 'quinze', 'dezasseis', 'dezassete', 'dezoito', 'dezanove']
-const TENS = ['', '', 'vinte', 'trinta', 'quarenta', 'cinquenta', 'sessenta', 'setenta', 'oitenta', 'noventa']
-
-// Irregular hundreds
-const HUNDREDS = ['', 'cento', 'duzentos', 'trezentos', 'quatrocentos', 'quinhentos', 'seiscentos', 'setecentos', 'oitocentos', 'novecentos']
-
-const THOUSAND = 'mil'
-const ZERO = 'zero'
-const NEGATIVE = 'menos'
-const DECIMAL_SEP = 'vírgula'
-
-// ============================================================================
-// Precomputed Lookup Tables (built once at module load)
-// ============================================================================
-
-/**
- * Builds segment word for 0-999 with Portuguese "e" rules.
- * Returns the word and whether it's an exact hundred (for "cem" handling).
- */
-function buildSegment (n) {
-  if (n === 0) return { word: '', isExactHundred: false }
-
-  // Special case: exact 100 is "cem"
-  if (n === 100) return { word: 'cem', isExactHundred: true }
-
-  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])
-  }
-
-  // Tens and ones
-  if (tens === 1) {
-    // Teens (10-19)
-    parts.push(TEENS[ones])
-  } else if (tens >= 2) {
-    if (ones > 0) {
-      // Tens + ones with "e": "vinte e um"
-      parts.push(TENS[tens] + ' e ' + ONES[ones])
-    } else {
-      parts.push(TENS[tens])
-    }
-  } else if (ones > 0) {
-    parts.push(ONES[ones])
-  }
-
-  // Join hundreds with "e": "cento e um", "duzentos e trinta e um"
-  const word = parts.join(' e ')
-
-  return { word, isExactHundred: hundreds > 0 && tens === 0 && ones === 0 }
-}
-
-// Precompute all 1000 segment words (0-999)
-const SEGMENTS = new Array(1000)
-const SEGMENTS_STARTS_WITH_HUNDREDS = new Array(1000)
-
-for (let i = 0; i < 1000; i++) {
-  const result = buildSegment(i)
-  SEGMENTS[i] = result.word
-  // Precompute whether segment starts with hundreds (100-999)
-  SEGMENTS_STARTS_WITH_HUNDREDS[i] = i >= 100
-}
-
-// ============================================================================
-// Scale Word Lookup (precomputed for common scales)
-// ============================================================================
-
-// Precompute scale words for singular and plural forms
-// Index 1 = thousands, 2 = millions, 3 = billions (mil milhões), etc.
-const SCALE_WORDS_SINGULAR = [
-  '', // 0 unused
-  THOUSAND, // 1: mil
-  'milhão', // 2: 10^6
-  'mil milhões', // 3: 10^9 (compound)
-  'bilião', // 4: 10^12
-  'mil biliões', // 5: 10^15 (compound)
-  'trilião', // 6: 10^18
-  'mil triliões', // 7: 10^21 (compound)
-  'quatrilião' // 8: 10^24
-]
-
-const SCALE_WORDS_PLURAL = [
-  '', // 0 unused
-  THOUSAND, // 1: mil (same)
-  'milhões', // 2: 10^6
-  'mil milhões', // 3: 10^9 (compound, same)
-  'biliões', // 4: 10^12
-  'mil biliões', // 5: 10^15 (compound, same)
-  'triliões', // 6: 10^18
-  'mil triliões', // 7: 10^21 (compound, same)
-  'quatriliões' // 8: 10^24
-]
-
-// ============================================================================
-// Conversion Functions
-// ============================================================================
-
-/**
- * Converts a non-negative integer to Portuguese words.
- *
- * @param {bigint} n - Non-negative integer to convert
- * @returns {string} Portuguese 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)
-
-    let result
-    if (thousands === 1) {
-      // "mil" not "um mil"
-      result = THOUSAND
-    } else {
-      result = SEGMENTS[thousands] + ' ' + THOUSAND
-    }
-
-    if (remainder > 0) {
-      // Insert "e" before remainder if it doesn't start with hundreds (< 100)
-      if (!SEGMENTS_STARTS_WITH_HUNDREDS[remainder]) {
-        result += ' e ' + SEGMENTS[remainder]
-      } else {
-        result += ' ' + SEGMENTS[remainder]
-      }
-    }
-
-    return result
-  }
-
-  // For numbers >= 1,000,000, use scale decomposition
-  return buildLargeNumberWords(n)
-}
-
-/**
- * Builds words for numbers >= 1,000,000.
- * Uses BigInt division for faster segment extraction.
- *
- * @param {bigint} n - Number >= 1,000,000
- * @returns {string} Portuguese words
- */
-function buildLargeNumberWords (n) {
-  // Extract segments using BigInt division
-  // Segments stored least-significant first (index 0 = ones, 1 = thousands, etc.)
-  const segments = []
-  let temp = n
-  while (temp > 0n) {
-    segments.push(Number(temp % 1000n))
-    temp = temp / 1000n
-  }
-
-  // Find the first non-zero segment index (lowest scale with value)
-  let firstNonZeroIdx = 0
-  for (let i = 0; i < segments.length; i++) {
-    if (segments[i] !== 0) {
-      firstNonZeroIdx = i
-      break
-    }
-  }
-
-  // Build result string directly
-  let result = ''
-  let prevWasScale = false
-
-  for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i]
-    if (segment === 0) continue
-
-    const segmentWord = SEGMENTS[segment]
-    const isLastSegment = (i === firstNonZeroIdx)
-
-    // Add "e" before final segment if previous was scale and this doesn't start with hundreds
-    if (result && isLastSegment && prevWasScale && !SEGMENTS_STARTS_WITH_HUNDREDS[segment]) {
-      result += ' e'
-    }
-
-    if (result) result += ' '
-
-    if (i === 0) {
-      // Units segment
-      result += segmentWord
-      prevWasScale = false
-    } else if (i === 1) {
-      // Thousands
-      if (segment === 1) {
-        result += THOUSAND
-      } else {
-        result += segmentWord + ' ' + THOUSAND
-      }
-      prevWasScale = true
-    } else {
-      // Million and above - use precomputed scale arrays
-      const scaleWord = segment === 1 ? SCALE_WORDS_SINGULAR[i] : SCALE_WORDS_PLURAL[i]
-      if (segment === 1) {
-        result += 'um ' + scaleWord
-      } else {
-        result += segmentWord + ' ' + scaleWord
-      }
-      prevWasScale = true
-    }
-  }
-
-  return result
-}
-
-/**
- * Converts decimal digits to Portuguese words.
- *
- * @param {string} decimalPart - Decimal digits (without the point)
- * @returns {string} Portuguese words for decimal part
- */
-function decimalPartToWords (decimalPart) {
-  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))
-  }
-
-  return result
-}
-
-/**
- * Converts a numeric value to Portuguese 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
- * @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'
- */
-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/ro.d.ts

@@ -1,18 +0,0 @@
-/**
- * Converts a numeric value to Romanian words.
- *
- * @param {number | string | bigint} value - The numeric value to convert
- * @param {Object} [options] - Conversion options
- * @param {string} [options.gender='masculine'] - Gender for numbers
- * @returns {string} The number in Romanian words
- * @throws {TypeError} If value is not a valid numeric type
- * @throws {Error} If value is not a valid number format
- *
- * @example
- * toWords(21)                        // 'douăzeci și unu'
- * toWords(1, { gender: 'feminine' }) // 'una'
- * toWords(1000)                      // 'o mie'
- */
-export function toWords(value: number | string | bigint, options?: {
-    gender?: string | undefined;
-}): string;

package/lib/languages/ru.d.ts

@@ -1,11 +0,0 @@
-/**
- * Converts a numeric value to Russian words.
- *
- * @param {number | string | bigint} value - The numeric value to convert
- * @param {Object} [options] - Optional configuration
- * @param {('masculine'|'feminine')} [options.gender='masculine'] - Grammatical gender
- * @returns {string} The number in Russian words
- */
-export function toWords(value: number | string | bigint, options?: {
-    gender?: "masculine" | "feminine" | undefined;
-}): string;