n2words 3.1.0 → 5.0.0

package/{lib/languages/pt.js → src/pt-PT.js}

@@ -1,17 +1,20 @@
 /**
- * Portuguese language converter - Functional Implementation
+ * Portuguese (Portugal) language converter
  *
- * Self-contained module with its own input validation, ready for subpath exports.
+ * CLDR: pt-PT | European Portuguese as used in Portugal
  *
  * Portuguese-specific rules:
  * - "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)
+ * - Long 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'
+import { parseCardinalValue } from './utils/parse-cardinal.js'
+import { parseCurrencyValue } from './utils/parse-currency.js'
+import { parseOrdinalValue } from './utils/parse-ordinal.js'
+import { validateOptions } from './utils/validate-options.js'
 
 // ============================================================================
 // Vocabulary (module-level constants)
@@ -29,6 +32,18 @@ const ZERO = 'zero'
 const NEGATIVE = 'menos'
 const DECIMAL_SEP = 'vírgula'
 
+// Ordinal vocabulary
+const ORDINAL_ONES = ['', 'primeiro', 'segundo', 'terceiro', 'quarto', 'quinto', 'sexto', 'sétimo', 'oitavo', 'nono']
+const ORDINAL_TEENS = ['décimo', 'décimo primeiro', 'décimo segundo', 'décimo terceiro', 'décimo quarto', 'décimo quinto', 'décimo sexto', 'décimo sétimo', 'décimo oitavo', 'décimo nono']
+const ORDINAL_TENS = ['', '', 'vigésimo', 'trigésimo', 'quadragésimo', 'quinquagésimo', 'sexagésimo', 'septuagésimo', 'octogésimo', 'nonagésimo']
+const ORDINAL_HUNDREDS = ['', 'centésimo', 'ducentésimo', 'tricentésimo', 'quadringentésimo', 'quingentésimo', 'sexcentésimo', 'septingentésimo', 'octingentésimo', 'nongentésimo']
+
+// Currency vocabulary (Euro)
+const EURO = 'euro'
+const EUROS = 'euros'
+const CENTIMO = 'cêntimo'
+const CENTIMOS = 'cêntimos'
+
 // ============================================================================
 // Segment Building
 // ============================================================================
@@ -44,8 +59,8 @@ function buildSegment (n) {
   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 tens = Math.trunc(n / 10) % 10
+  const hundreds = Math.trunc(n / 100)
 
   const parts = []
 
@@ -263,12 +278,12 @@ function decimalPartToWords (decimalPart) {
  * @throws {Error} If value is not a valid number format
  *
  * @example
- * toWords(21)           // 'vinte e um'
- * toWords(100)          // 'cem'
- * toWords(1000000)      // 'um milhão'
+ * toCardinal(21)           // 'vinte e um'
+ * toCardinal(100)          // 'cem'
+ * toCardinal(1000000)      // 'um milhão'
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
 
@@ -285,8 +300,215 @@ function toWords (value) {
   return result
 }
 
+// ============================================================================
+// Ordinal Functions
+// ============================================================================
+
+/**
+ * Builds ordinal words for 0-999.
+ *
+ * @param {number} n - Number 0-999
+ * @returns {string} Portuguese ordinal words
+ */
+function buildOrdinalSegment (n) {
+  if (n === 0) return ''
+
+  const ones = n % 10
+  const tens = Math.trunc(n / 10) % 10
+  const hundreds = Math.trunc(n / 100)
+
+  const parts = []
+
+  // Hundreds ordinal
+  if (hundreds > 0) {
+    parts.push(ORDINAL_HUNDREDS[hundreds])
+  }
+
+  // Tens and ones
+  if (tens === 1) {
+    // 10-19: use teens array (décimo, décimo primeiro, etc.)
+    parts.push(ORDINAL_TEENS[ones])
+  } else if (tens >= 2) {
+    parts.push(ORDINAL_TENS[tens])
+    if (ones > 0) {
+      parts.push(ORDINAL_ONES[ones])
+    }
+  } else if (ones > 0) {
+    parts.push(ORDINAL_ONES[ones])
+  }
+
+  return parts.join(' ')
+}
+
+/**
+ * Builds ordinal words for large numbers.
+ *
+ * @param {bigint} n - Non-negative integer
+ * @returns {string} Portuguese ordinal words
+ */
+function buildLargeOrdinal (n) {
+  // Extract segments
+  const segments = []
+  let temp = n
+  while (temp > 0n) {
+    segments.push(Number(temp % 1000n))
+    temp = temp / 1000n
+  }
+
+  // Find the lowest non-zero segment (index 0 = units, lowest scale)
+  let lowestNonZeroIdx = 0
+  for (let i = 0; i < segments.length; i++) {
+    if (segments[i] !== 0) {
+      lowestNonZeroIdx = i
+      break
+    }
+  }
+
+  // Scale ordinal words (singular forms)
+  const SCALE_ORDINAL = ['', 'milésimo', 'milionésimo', 'mil milionésimo', 'bilionésimo', 'mil bilionésimo', 'trilionésimo']
+
+  let result = ''
+
+  for (let i = segments.length - 1; i >= 0; i--) {
+    const segment = segments[i]
+    if (segment === 0) continue
+
+    if (result) result += ' '
+
+    if (i === lowestNonZeroIdx) {
+      // Last non-zero segment gets ordinal form
+      if (i === 0) {
+        // Units: just ordinal
+        result += buildOrdinalSegment(segment)
+      } else if (segment === 1 && i > 0) {
+        // Exact scale: "milésimo", "milionésimo", etc.
+        result += SCALE_ORDINAL[i]
+      } else {
+        // Segment + scale ordinal
+        result += buildOrdinalSegment(segment) + ' ' + SCALE_ORDINAL[i]
+      }
+    } else {
+      // Higher segments use cardinal form
+      if (i === 0) {
+        result += buildSegment(segment).word
+      } else if (i === 1) {
+        if (segment === 1) {
+          result += THOUSAND
+        } else {
+          result += buildSegment(segment).word + ' ' + THOUSAND
+        }
+      } else {
+        const scaleWord = segment === 1 ? SCALE_WORDS_SINGULAR[i] : SCALE_WORDS_PLURAL[i]
+        if (segment === 1) {
+          result += 'um ' + scaleWord
+        } else {
+          result += buildSegment(segment).word + ' ' + scaleWord
+        }
+      }
+    }
+  }
+
+  return result
+}
+
+/**
+ * Converts a number to Portuguese ordinal words.
+ *
+ * @param {number | string | bigint} value - The number to convert
+ * @returns {string} Portuguese ordinal words
+ *
+ * @example
+ * toOrdinal(1)     // 'primeiro'
+ * toOrdinal(21)    // 'vigésimo primeiro'
+ * toOrdinal(100)   // 'centésimo'
+ */
+function toOrdinal (value) {
+  const n = parseOrdinalValue(value)
+
+  // Fast path: 1-9
+  if (n < 10n) {
+    return ORDINAL_ONES[Number(n)]
+  }
+
+  // Fast path: 10-19
+  if (n < 20n) {
+    return ORDINAL_TEENS[Number(n) - 10]
+  }
+
+  // Fast path: 20-99
+  if (n < 100n) {
+    const ones = Number(n % 10n)
+    const tens = Number(n / 10n)
+    if (ones === 0) {
+      return ORDINAL_TENS[tens]
+    }
+    return ORDINAL_TENS[tens] + ' ' + ORDINAL_ONES[ones]
+  }
+
+  // Fast path: 100-999
+  if (n < 1000n) {
+    return buildOrdinalSegment(Number(n))
+  }
+
+  // Large numbers
+  return buildLargeOrdinal(n)
+}
+
+// ============================================================================
+// Currency Functions
+// ============================================================================
+
+/**
+ * Converts a number to Portuguese currency words (Euro).
+ *
+ * @param {number | string | bigint} value - The amount to convert
+ * @param {Object} [options]
+ * @param {boolean} [options.and=true] - Include "e" between euros and cents
+ * @returns {string} Portuguese currency words
+ *
+ * @example
+ * toCurrency(42.50)  // 'quarenta e dois euros e cinquenta cêntimos'
+ * toCurrency(1)      // 'um euro'
+ * toCurrency(0.01)   // 'um cêntimo'
+ */
+function toCurrency (value, options) {
+  options = validateOptions(options)
+  const { isNegative, dollars: euros, cents } = parseCurrencyValue(value)
+  const { and = true } = options
+
+  let result = ''
+
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  const hasEuros = euros > 0n
+  const hasCents = cents > 0n
+
+  if (!hasEuros && !hasCents) {
+    return ZERO + ' ' + EUROS
+  }
+
+  if (hasEuros) {
+    const euroWords = integerToWords(euros)
+    const euroUnit = euros === 1n ? EURO : EUROS
+    result += euroWords + ' ' + euroUnit
+  }
+
+  if (hasCents) {
+    if (hasEuros) {
+      result += and ? ' e ' : ' '
+    }
+    const centWords = integerToWords(cents)
+    const centUnit = cents === 1n ? CENTIMO : CENTIMOS
+    result += centWords + ' ' + centUnit
+  }
+
+  return result
+}
+
 // ============================================================================
 // Public API
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/ro-RO.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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
+ * toCardinal(21)                        // 'douăzeci și unu'
+ * toCardinal(1, { gender: 'feminine' }) // 'una'
+ * toCardinal(1000)                      // 'o mie'
+ */
+export function toCardinal(value: number | string | bigint, options?: {
+    gender?: string | undefined;
+}): string;
+/**
+ * Converts a numeric value to Romanian ordinal words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The ordinal in Romanian words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a positive integer
+ *
+ * @example
+ * toOrdinal(1)   // 'primul'
+ * toOrdinal(21)  // 'douăzeci și primul'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Romanian Leu currency words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The currency in Romanian words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCurrency(1)     // 'un leu'
+ * toCurrency(2.50)  // 'doi lei cincizeci de bani'
+ */
+export function toCurrency(value: number | string | bigint): string;

package/{lib/languages/ro.js → src/ro-RO.js}

@@ -1,7 +1,7 @@
 /**
- * Romanian language converter - Functional Implementation
+ * Romanian (Romania) language converter
  *
- * A performance-optimized number-to-words converter using precomputed lookup tables.
+ * CLDR: ro-RO | Romanian as used in Romania
  *
  * Key features:
  * - Gender agreement (unu/una, doi/două)
@@ -10,8 +10,10 @@
  * - Feminine units for thousands
  */
 
-import { parseNumericValue } from '../utils/parse-numeric.js'
-import { validateOptions } from '../utils/validate-options.js'
+import { parseCardinalValue } from './utils/parse-cardinal.js'
+import { parseCurrencyValue } from './utils/parse-currency.js'
+import { parseOrdinalValue } from './utils/parse-ordinal.js'
+import { validateOptions } from './utils/validate-options.js'
 
 // ============================================================================
 // Vocabulary (module-level constants)
@@ -31,6 +33,20 @@ const ZERO = 'zero'
 const NEGATIVE = 'minus'
 const DECIMAL_SEP = 'virgulă'
 
+// Ordinal vocabulary (masculine forms)
+const ORDINAL_ONES = ['', 'primul', 'al doilea', 'al treilea', 'al patrulea', 'al cincilea', 'al șaselea', 'al șaptelea', 'al optulea', 'al nouălea']
+const ORDINAL_TEENS = ['al zecelea', 'al unsprezecelea', 'al doisprezecelea', 'al treisprezecelea', 'al paisprezecelea', 'al cincisprezecelea', 'al șaisprezecelea', 'al șaptesprezecelea', 'al optsprezecelea', 'al nouăsprezecelea']
+const ORDINAL_TENS = ['', '', 'al douăzecilea', 'al treizecilea', 'al patruzecilea', 'al cincizecilea', 'al șaizecilea', 'al șaptezecilea', 'al optzecilea', 'al nouăzecilea']
+const ORDINAL_HUNDRED = 'al sutălea'
+const ORDINAL_THOUSAND = 'al miilea'
+const ORDINAL_MILLION = 'al milionulea'
+
+// Currency (Romanian Leu)
+const LEU_SINGULAR = 'leu'
+const LEU_PLURAL = 'lei'
+const BAN_SINGULAR = 'ban'
+const BAN_PLURAL = 'bani'
+
 // Scale metadata: [singular, plural, article, feminine, needsDe]
 // - singular: form for 1
 // - plural: form for 2+
@@ -64,7 +80,7 @@ function spellUnder100 (n, feminine = false, masculineTeens = false) {
   if (n < 20) {
     return masculineTeens ? TEENS_MASC[n - 10] : TEENS[n - 10]
   }
-  const t = Math.floor(n / 10)
+  const t = Math.trunc(n / 10)
   const u = n % 10
   if (u === 0) {
     return TWENTIES[t]
@@ -80,7 +96,7 @@ function spellUnder1000 (n, feminine = false, masculineTeens = false) {
   if (n === 0) return ''
   if (n < 100) return spellUnder100(n, feminine, masculineTeens)
 
-  const h = Math.floor(n / 100)
+  const h = Math.trunc(n / 100)
   const r = n % 100
   const hundredWord = HUNDREDS[h]
 
@@ -126,16 +142,16 @@ function buildScalePhrase (segment, scaleIndex) {
  * @param {Object} options - Conversion options
  * @returns {string} Romanian words
  */
-function integerToWords (n, options = {}) {
+function integerToWords (n, gender) {
   if (n === 0n) return ZERO
 
   // Fast path: numbers < 1000
   if (n < 1000n) {
-    const feminine = options.gender === 'feminine'
+    const feminine = gender === 'feminine'
     return spellUnder1000(Number(n), feminine)
   }
 
-  return buildLargeNumberWords(n, options)
+  return buildLargeNumberWords(n, gender)
 }
 
 /**
@@ -146,7 +162,7 @@ function integerToWords (n, options = {}) {
  * @param {Object} options - Conversion options
  * @returns {string} Romanian words
  */
-function buildLargeNumberWords (n, options) {
+function buildLargeNumberWords (n, gender) {
   // Extract segments using BigInt division (faster than string slicing)
   // Segments stored least-significant first (index 0 = ones, 1 = thousands, etc.)
   const segmentValues = []
@@ -166,7 +182,7 @@ function buildLargeNumberWords (n, options) {
     let segmentWords
     if (i === 0) {
       // Units segment - use gender from options
-      const feminine = options.gender === 'feminine'
+      const feminine = gender === 'feminine'
       segmentWords = spellUnder1000(segment, feminine)
     } else {
       // Scale segment
@@ -227,13 +243,16 @@ function decimalPartToWords (decimalPart) {
  * @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'
+ * toCardinal(21)                        // 'douăzeci și unu'
+ * toCardinal(1, { gender: 'feminine' }) // 'una'
+ * toCardinal(1000)                      // 'o mie'
  */
-function toWords (value, options) {
+function toCardinal (value, options) {
   options = validateOptions(options)
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
+
+  // Apply option defaults
+  const { gender = 'masculine' } = options
 
   let result = ''
 
@@ -241,7 +260,7 @@ function toWords (value, options) {
     result = NEGATIVE + ' '
   }
 
-  result += integerToWords(integerPart, options)
+  result += integerToWords(integerPart, gender)
 
   if (decimalPart) {
     result += ' ' + DECIMAL_SEP + ' ' + decimalPartToWords(decimalPart)
@@ -250,8 +269,183 @@ function toWords (value, options) {
   return result
 }
 
+// ============================================================================
+// Ordinal Functions
+// ============================================================================
+
+/**
+ * Builds ordinal for tens and ones (0-99).
+ *
+ * @param {number} n - Number 0-99
+ * @returns {string} Ordinal word
+ */
+function buildOrdinalTensOnes (n) {
+  if (n === 0) return ''
+  if (n < 10) return ORDINAL_ONES[n]
+  if (n < 20) return ORDINAL_TEENS[n - 10]
+
+  const ones = n % 10
+  const tens = Math.trunc(n / 10)
+
+  if (ones === 0) {
+    return ORDINAL_TENS[tens]
+  }
+  // Compound: cardinal tens + ordinal ones (only last is ordinal)
+  return TWENTIES[tens] + ' și ' + ORDINAL_ONES[ones]
+}
+
+/**
+ * Converts a non-negative integer to Romanian ordinal words.
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} Romanian ordinal words
+ */
+function integerToOrdinal (n) {
+  if (n === 0n) return ''
+  if (n === 1n) return ORDINAL_ONES[1]
+
+  // Numbers < 100
+  if (n < 100n) {
+    return buildOrdinalTensOnes(Number(n))
+  }
+
+  // Numbers < 1000
+  if (n < 1000n) {
+    const hundreds = Number(n / 100n)
+    const remainder = Number(n % 100n)
+
+    if (remainder === 0) {
+      return ORDINAL_HUNDRED
+    }
+    return HUNDREDS[hundreds] + ' ' + buildOrdinalTensOnes(remainder)
+  }
+
+  // Numbers < 1,000,000
+  if (n < 1_000_000n) {
+    const thousands = Number(n / 1000n)
+    const remainder = Number(n % 1000n)
+
+    if (remainder === 0) {
+      if (thousands === 1) {
+        return ORDINAL_THOUSAND
+      }
+      return buildScalePhrase(thousands, 1) + ' ' + ORDINAL_THOUSAND
+    }
+
+    // Cardinal thousands + ordinal remainder
+    let result
+    if (thousands === 1) {
+      result = 'o mie'
+    } else {
+      result = buildScalePhrase(thousands, 1)
+    }
+
+    if (remainder < 100) {
+      return result + ' ' + buildOrdinalTensOnes(remainder)
+    }
+
+    const remHundreds = Math.trunc(remainder / 100)
+    const remTensOnes = remainder % 100
+
+    if (remTensOnes === 0) {
+      return result + ' ' + ORDINAL_HUNDRED
+    }
+    return result + ' ' + HUNDREDS[remHundreds] + ' ' + buildOrdinalTensOnes(remTensOnes)
+  }
+
+  // Numbers >= 1,000,000
+  const millions = Number(n / 1_000_000n)
+  const remainder = n % 1_000_000n
+
+  if (remainder === 0n) {
+    if (millions === 1) {
+      return ORDINAL_MILLION
+    }
+    return buildScalePhrase(millions, 2) + ' ' + ORDINAL_MILLION
+  }
+
+  // Cardinal millions + ordinal remainder
+  let result
+  if (millions === 1) {
+    result = 'un milion'
+  } else {
+    result = buildScalePhrase(millions, 2)
+  }
+
+  return result + ' ' + integerToOrdinal(remainder)
+}
+
+/**
+ * Converts a numeric value to Romanian ordinal words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The ordinal in Romanian words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a positive integer
+ *
+ * @example
+ * toOrdinal(1)   // 'primul'
+ * toOrdinal(21)  // 'douăzeci și primul'
+ */
+function toOrdinal (value) {
+  const n = parseOrdinalValue(value)
+  return integerToOrdinal(n)
+}
+
+// ============================================================================
+// Currency Functions
+// ============================================================================
+
+/**
+ * Converts a numeric value to Romanian Leu currency words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The currency in Romanian words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCurrency(1)     // 'un leu'
+ * toCurrency(2.50)  // 'doi lei cincizeci de bani'
+ */
+function toCurrency (value) {
+  const { isNegative, dollars, cents } = parseCurrencyValue(value)
+
+  const parts = []
+
+  if (isNegative) {
+    parts.push(NEGATIVE)
+  }
+
+  // Lei (masculine)
+  if (dollars > 0n || cents === 0n) {
+    if (dollars === 1n) {
+      parts.push('un ' + LEU_SINGULAR)
+    } else {
+      const leuWord = integerToWords(dollars, 'masculine')
+      parts.push(leuWord + ' ' + LEU_PLURAL)
+    }
+  }
+
+  // Bani (masculine)
+  if (cents > 0n) {
+    const centNum = Number(cents)
+    if (centNum === 1) {
+      parts.push('un ' + BAN_SINGULAR)
+    } else if (centNum >= 20) {
+      const banWord = spellUnder100(centNum, false)
+      parts.push(banWord + ' de ' + BAN_PLURAL)
+    } else {
+      const banWord = spellUnder100(centNum, false)
+      parts.push(banWord + ' ' + BAN_PLURAL)
+    }
+  }
+
+  return parts.join(' ')
+}
+
 // ============================================================================
 // Public API
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/ru-RU.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 toCardinal(value: number | string | bigint, options?: {
+    gender?: "masculine" | "feminine" | undefined;
+}): string;
+/**
+ * Converts a numeric value to Russian ordinal words (masculine nominative).
+ *
+ * @param {number | string | bigint} value - The numeric value to convert (must be a positive integer)
+ * @returns {string} The number as ordinal words (e.g., "первый", "сорок второй")
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {RangeError} If value is negative, zero, or has a decimal part
+ *
+ * @example
+ * toOrdinal(1)    // 'первый'
+ * toOrdinal(2)    // 'второй'
+ * toOrdinal(3)    // 'третий'
+ * toOrdinal(21)   // 'двадцать первый'
+ * toOrdinal(42)   // 'сорок второй'
+ * toOrdinal(100)  // 'сотый'
+ * toOrdinal(101)  // 'сто первый'
+ * toOrdinal(1000) // 'тысячный'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Russian currency words (Russian Ruble).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @param {Object} [options] - Optional configuration
+ * @param {boolean} [options.and=true] - Use "и" between rubles and kopecks
+ * @returns {string} The amount in Russian currency words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCurrency(42.50)                    // 'сорок два рубля и пятьдесят копеек'
+ * toCurrency(1)                        // 'один рубль'
+ * toCurrency(0.99)                     // 'девяносто девять копеек'
+ * toCurrency(0.01)                     // 'одна копейка'
+ * toCurrency(42.50, { and: false })    // 'сорок два рубля пятьдесят копеек'
+ */
+export function toCurrency(value: number | string | bigint, options?: {
+    and?: boolean | undefined;
+}): string;