n2words 4.0.0 → 5.1.0

package/src/ro-RO.js

@@ -13,7 +13,9 @@
 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'
+import { checkMax } from './utils/check-max.js'
+import { bounded, western } from './utils/scale.js'
+import { resolveOptions } from './utils/resolve-options.js'
 
 // ============================================================================
 // Vocabulary (module-level constants)
@@ -62,17 +64,28 @@ const SCALE_META = [
   { singular: 'cvintilion', plural: 'cvintilioane', article: 'un', feminine: false, needsDe: true },
   { singular: 'sextilion', plural: 'sextilioane', article: 'un', feminine: false, needsDe: true },
   { singular: 'septilion', plural: 'septilioane', article: 'un', feminine: false, needsDe: true },
-  { singular: 'octilion', plural: 'octilioane', article: 'un', feminine: false, needsDe: true }
+  { singular: 'octilion', plural: 'octilioane', article: 'un', feminine: false, needsDe: true },
 ]
 
+// Cardinal scale words run thousand..octilion; past SCALE_META the builder drops
+// the scale word. The ordinal spells its millions multiplier via spellUnder1000
+// (0-999), so it overflows once that multiplier reaches 1000 — n must stay below 10^9.
+export const cardinalMax = western(SCALE_META.length)
+export const ordinalMax = bounded(9)
+export const currencyMax = western(SCALE_META.length)
+
 // ============================================================================
 // Helper Functions
 // ============================================================================
 
 /**
  * Spells number under 100.
+ * @param {number} n - Number 0-99
+ * @param {boolean} [feminine] - Use feminine forms
+ * @param {boolean} [masculineTeens] - Use masculine teen forms
+ * @returns {string} The number 0-99 in words
  */
-function spellUnder100 (n, feminine = false, masculineTeens = false) {
+function spellUnder100(n, feminine = false, masculineTeens = false) {
   if (n === 0) return ''
   if (n < 10) {
     return feminine ? ONES_FEM[n] : ONES_MASC[n]
@@ -91,8 +104,12 @@ function spellUnder100 (n, feminine = false, masculineTeens = false) {
 
 /**
  * Spells number under 1000.
+ * @param {number} n - Number 0-999
+ * @param {boolean} [feminine] - Use feminine forms
+ * @param {boolean} [masculineTeens] - Use masculine teen forms
+ * @returns {string} The number 0-999 in words
  */
-function spellUnder1000 (n, feminine = false, masculineTeens = false) {
+function spellUnder1000(n, feminine = false, masculineTeens = false) {
   if (n === 0) return ''
   if (n < 100) return spellUnder100(n, feminine, masculineTeens)
 
@@ -107,8 +124,11 @@ function spellUnder1000 (n, feminine = false, masculineTeens = false) {
 /**
  * Builds scale word with proper pluralization and "de" insertion.
  * Romanian always uses feminine forms (două, not doi) when counting scale words.
+ * @param {number} segment - Three-digit segment value (1-999)
+ * @param {number} scaleIndex - Scale position (1 = thousands, 2 = millions, ...)
+ * @returns {string} The scale phrase in words
  */
-function buildScalePhrase (segment, scaleIndex) {
+function buildScalePhrase(segment, scaleIndex) {
   const meta = SCALE_META[scaleIndex - 1]
   if (!meta) return spellUnder1000(segment, true)
 
@@ -137,12 +157,11 @@ function buildScalePhrase (segment, scaleIndex) {
 
 /**
  * Converts a non-negative integer to Romanian words.
- *
  * @param {bigint} n - Non-negative integer to convert
- * @param {Object} options - Conversion options
+ * @param {string | {gender?: string}} gender - Gender for numbers ('feminine'/'masculine')
  * @returns {string} Romanian words
  */
-function integerToWords (n, gender) {
+function integerToWords(n, gender) {
   if (n === 0n) return ZERO
 
   // Fast path: numbers < 1000
@@ -157,12 +176,11 @@ function integerToWords (n, gender) {
 /**
  * Builds words for numbers >= 1000.
  * Uses BigInt division for faster segment extraction.
- *
  * @param {bigint} n - Number >= 1000
- * @param {Object} options - Conversion options
+ * @param {string | {gender?: string}} gender - Gender for numbers ('feminine'/'masculine')
  * @returns {string} Romanian words
  */
-function buildLargeNumberWords (n, gender) {
+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 = []
@@ -184,14 +202,16 @@ function buildLargeNumberWords (n, gender) {
       // Units segment - use gender from options
       const feminine = gender === 'feminine'
       segmentWords = spellUnder1000(segment, feminine)
-    } else {
+    }
+    else {
       // Scale segment
       segmentWords = buildScalePhrase(segment, i)
     }
 
     if (result && segmentWords) {
       result += ' ' + segmentWords
-    } else if (segmentWords) {
+    }
+    else if (segmentWords) {
       result = segmentWords
     }
   }
@@ -202,11 +222,10 @@ function buildLargeNumberWords (n, gender) {
 /**
  * Converts decimal digits to Romanian words.
  * Decimals always use masculine forms.
- *
  * @param {string} decimalPart - Decimal digits (without the point)
  * @returns {string} Romanian words for decimal part
  */
-function decimalPartToWords (decimalPart) {
+function decimalPartToWords(decimalPart) {
   let result = ''
   let i = 0
 
@@ -224,7 +243,8 @@ function decimalPartToWords (decimalPart) {
     const n = BigInt(remainder)
     if (n < 1000n) {
       result += spellUnder1000(Number(n), false, true)
-    } else {
+    }
+    else {
       result += integerToWords(n, { gender: 'masculine' })
     }
   }
@@ -232,27 +252,37 @@ function decimalPartToWords (decimalPart) {
   return result
 }
 
+/**
+ * @typedef {object} CardinalOptions
+ * @property {('masculine'|'feminine')} [gender] - Gender for numbers
+ */
+
+/** @type {Required<CardinalOptions>} */
+export const cardinalDefaults = { gender: 'masculine' }
+
+/** @type {{ gender: ReadonlyArray<Required<CardinalOptions>['gender']> }} */
+export const cardinalValues = { gender: ['masculine', 'feminine'] }
+
 /**
  * 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
+ * @param {CardinalOptions} [options] - Conversion options
  * @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'
  */
-function toCardinal (value, options) {
-  options = validateOptions(options)
+function toCardinal(value, options) {
   const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
+  // Both the integer part and the decimal's significant digits are spelled via
+  // the scale builder, so both must clear the ceiling.
+  checkMax(integerPart, cardinalMax, decimalPart)
 
   // Apply option defaults
-  const { gender = 'masculine' } = options
+  const { gender } = resolveOptions(options, cardinalDefaults, cardinalValues)
 
   let result = ''
 
@@ -275,11 +305,10 @@ function toCardinal (value, options) {
 
 /**
  * Builds ordinal for tens and ones (0-99).
- *
  * @param {number} n - Number 0-99
  * @returns {string} Ordinal word
  */
-function buildOrdinalTensOnes (n) {
+function buildOrdinalTensOnes(n) {
   if (n === 0) return ''
   if (n < 10) return ORDINAL_ONES[n]
   if (n < 20) return ORDINAL_TEENS[n - 10]
@@ -296,11 +325,10 @@ function buildOrdinalTensOnes (n) {
 
 /**
  * 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) {
+function integerToOrdinal(n) {
   if (n === 0n) return ''
   if (n === 1n) return ORDINAL_ONES[1]
 
@@ -336,7 +364,8 @@ function integerToOrdinal (n) {
     let result
     if (thousands === 1) {
       result = 'o mie'
-    } else {
+    }
+    else {
       result = buildScalePhrase(thousands, 1)
     }
 
@@ -368,7 +397,8 @@ function integerToOrdinal (n) {
   let result
   if (millions === 1) {
     result = 'un milion'
-  } else {
+  }
+  else {
     result = buildScalePhrase(millions, 2)
   }
 
@@ -377,18 +407,17 @@ function integerToOrdinal (n) {
 
 /**
  * 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) {
+function toOrdinal(value) {
   const n = parseOrdinalValue(value)
+  checkMax(n, ordinalMax)
   return integerToOrdinal(n)
 }
 
@@ -398,18 +427,17 @@ function toOrdinal (value) {
 
 /**
  * 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) {
+function toCurrency(value) {
   const { isNegative, dollars, cents } = parseCurrencyValue(value)
+  checkMax(dollars, currencyMax)
 
   const parts = []
 
@@ -421,9 +449,17 @@ function toCurrency (value) {
   if (dollars > 0n || cents === 0n) {
     if (dollars === 1n) {
       parts.push('un ' + LEU_SINGULAR)
-    } else {
+    }
+    else {
       const leuWord = integerToWords(dollars, 'masculine')
-      parts.push(leuWord + ' ' + LEU_PLURAL)
+      // Romanian inserts "de" before the noun for the CLDR `other` category:
+      // count >= 20 whose last two digits are 00 or 20-99 — "douăzeci de lei",
+      // "o sută de lei", but "o sută unu lei" (101) and no "de" below 20. The
+      // bani path below applies the same rule; buildScalePhrase uses a related
+      // per-segment predicate for scale words.
+      const m = dollars % 100n
+      const needsDe = dollars >= 20n && (m === 0n || m >= 20n)
+      parts.push(leuWord + (needsDe ? ' de ' : ' ') + LEU_PLURAL)
     }
   }
 
@@ -432,10 +468,12 @@ function toCurrency (value) {
     const centNum = Number(cents)
     if (centNum === 1) {
       parts.push('un ' + BAN_SINGULAR)
-    } else if (centNum >= 20) {
+    }
+    else if (centNum >= 20) {
       const banWord = spellUnder100(centNum, false)
       parts.push(banWord + ' de ' + BAN_PLURAL)
-    } else {
+    }
+    else {
       const banWord = spellUnder100(centNum, false)
       parts.push(banWord + ' ' + BAN_PLURAL)
     }

package/src/ru-RU.d.ts

@@ -1,22 +1,47 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
+/**
+ * @typedef {object} CardinalOptions
+ * @property {('masculine'|'feminine')} [gender] - Grammatical gender
+ */
+/** @type {Required<CardinalOptions>} */
+export const cardinalDefaults: Required<CardinalOptions>;
+/** @type {{ gender: ReadonlyArray<Required<CardinalOptions>['gender']> }} */
+export const cardinalValues: {
+    gender: ReadonlyArray<Required<CardinalOptions>["gender"]>;
+};
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [and] - Use "и" between rubles and kopecks
+ */
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults: Required<CurrencyOptions>;
+export type CardinalOptions = {
+    /**
+     * - Grammatical gender
+     */
+    gender?: "feminine" | "masculine" | undefined;
+};
+export type CurrencyOptions = {
+    /**
+     * - Use "и" between rubles and kopecks
+     */
+    and?: boolean | undefined;
+};
 /**
  * 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
+ * @param {CardinalOptions} [options] - Optional configuration
  * @returns {string} The number in Russian words
  */
-export function toCardinal(value: number | string | bigint, options?: {
-    gender?: "masculine" | "feminine" | undefined;
-}): string;
+export function toCardinal(value: number | string | bigint, options?: CardinalOptions): 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)    // 'второй'
@@ -30,14 +55,11 @@ export function toCardinal(value: number | string | bigint, options?: {
 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
+ * @param {CurrencyOptions} [options] - Optional configuration
  * @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)                        // 'один рубль'
@@ -45,6 +67,4 @@ export function toOrdinal(value: number | string | bigint): string;
  * toCurrency(0.01)                     // 'одна копейка'
  * toCurrency(42.50, { and: false })    // 'сорок два рубля пятьдесят копеек'
  */
-export function toCurrency(value: number | string | bigint, options?: {
-    and?: boolean | undefined;
-}): string;
+export function toCurrency(value: number | string | bigint, options?: CurrencyOptions): string;