n2words 4.0.0 → 5.1.0

package/src/es-US.js

@@ -20,7 +20,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)
@@ -45,6 +47,14 @@ const HUNDREDS_FEM = ['', 'cienta', 'doscientas', 'trescientas', 'cuatrocientas'
 const SCALES = ['mil', 'millón', 'billón', 'trillón', 'cuatrillón', 'quintillón']
 const SCALES_PLURAL = ['mil', 'millones', 'billones', 'trillones', 'cuatrillones', 'quintillones']
 
+// Supported magnitude ceilings (checked at the public entry points). Short
+// scale: SCALES covers 10^3..10^18, plus the units group, so cardinals span at
+// most SCALES.length + 1 groups of 3 digits (below 10^21). Ordinals are bounded
+// lower: the millions multiplier uses buildOrdinalSegment (0-999), so n < 10^9.
+export const cardinalMax = western(SCALES.length)
+export const ordinalMax = bounded(9)
+export const currencyMax = western(SCALES.length)
+
 const ZERO = 'cero'
 const NEGATIVE = 'menos'
 const DECIMAL_SEP = 'punto'
@@ -78,7 +88,7 @@ const CURRENCY_CONNECTOR = 'con'
  * @param {boolean} feminine - Use feminine forms
  * @returns {string} Spanish word
  */
-function buildSegment (n, feminine) {
+function buildSegment(n, feminine) {
   if (n === 0) return ''
 
   // Special case: exact 100 is "cien" (no gender)
@@ -100,22 +110,27 @@ function buildSegment (n, feminine) {
   // Tens and ones
   if (tensOnes === 0) {
     // Just hundreds
-  } else if (tensOnes < 10) {
+  }
+  else if (tensOnes < 10) {
     // Single digit
     const onesArr = feminine ? ONES_FEM : ONES_MASC
     parts.push(onesArr[tensOnes])
-  } else if (tensOnes < 20) {
+  }
+  else if (tensOnes < 20) {
     // 10-19: teens
     parts.push(TEENS[ones])
-  } else if (tensOnes < 30) {
+  }
+  else if (tensOnes < 30) {
     // 20-29: special twenties
     const twentiesArr = feminine ? TWENTIES_FEM : TWENTIES_MASC
     parts.push(twentiesArr[ones])
-  } else {
+  }
+  else {
     // 30-99: tens y ones
     if (ones === 0) {
       parts.push(TENS[tens])
-    } else {
+    }
+    else {
       const onesArr = feminine ? ONES_FEM : ONES_MASC
       parts.push(TENS[tens] + ' y ' + onesArr[ones])
     }
@@ -130,12 +145,11 @@ function buildSegment (n, feminine) {
 
 /**
  * Converts a non-negative integer to Spanish words (short scale).
- *
  * @param {bigint} n - Non-negative integer to convert
  * @param {boolean} feminine - Use feminine forms
  * @returns {string} Spanish words
  */
-function integerToWords (n, feminine) {
+function integerToWords(n, feminine) {
   if (n === 0n) return ZERO
 
   // Fast path: numbers < 1000
@@ -164,23 +178,25 @@ function integerToWords (n, feminine) {
     if (i === 0) {
       // Units segment - use requested gender
       result += buildSegment(Number(segment), feminine)
-    } else if (i === 1) {
+    }
+    else if (i === 1) {
       // Thousands: "mil" not "uno mil"
       if (segment === 1n) {
         result += SCALES[0]
-      } else {
+      }
+      else {
         result += buildSegment(Number(segment), false) + ' ' + SCALES[0]
       }
-    } else {
+    }
+    else {
       // Millions and above: "un millón", "dos millones", etc.
+      // Callers guard the magnitude (cardinalMax) so scaleIndex stays in range.
       const scaleIndex = i - 1 // SCALES[1] = millón, SCALES[2] = billón, etc.
-      if (scaleIndex >= SCALES.length) {
-        // Beyond our scale vocabulary
-        result += buildSegment(Number(segment), false)
-      } else if (segment === 1n) {
+      if (segment === 1n) {
         // "un millón" not "uno millón"
         result += 'un ' + SCALES[scaleIndex]
-      } else {
+      }
+      else {
         result += buildSegment(Number(segment), false) + ' ' + SCALES_PLURAL[scaleIndex]
       }
     }
@@ -191,12 +207,11 @@ function integerToWords (n, feminine) {
 
 /**
  * Converts decimal digits to Spanish words.
- *
  * @param {string} decimalPart - Decimal digits (without the point)
  * @param {boolean} feminine - Use feminine forms
  * @returns {string} Spanish words for decimal part
  */
-function decimalPartToWords (decimalPart, feminine) {
+function decimalPartToWords(decimalPart, feminine) {
   let result = ''
 
   // Handle leading zeros
@@ -217,27 +232,37 @@ function decimalPartToWords (decimalPart, feminine) {
   return result
 }
 
+/**
+ * @typedef {object} CardinalOptions
+ * @property {('masculine'|'feminine')} [gender] - Grammatical gender
+ */
+
+/** @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 Spanish words (US short scale).
- *
  * @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 Spanish words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCardinal(21)                        // 'veintiuno'
  * toCardinal(21, {gender: 'feminine'})  // 'veintiuna'
  * toCardinal(1000000000)                // 'un billón'
  */
-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)
   const feminine = gender === 'feminine'
 
   let result = ''
@@ -261,12 +286,11 @@ function toCardinal (value, options) {
 
 /**
  * Builds ordinal word for a 0-999 segment.
- *
  * @param {number} n - Segment value 0-999
  * @param {boolean} feminine - Use feminine forms
  * @returns {string} Spanish ordinal word
  */
-function buildOrdinalSegment (n, feminine) {
+function buildOrdinalSegment(n, feminine) {
   if (n === 0) return ''
 
   const ones = n % 10
@@ -283,7 +307,8 @@ function buildOrdinalSegment (n, feminine) {
   if (hundreds > 0) {
     if (hundreds === 1) {
       parts.push(hundredWord)
-    } else {
+    }
+    else {
       const prefixes = ['', '', 'du', 'tri', 'cuadri', 'quin', 'sex', 'septi', 'octi', 'noni']
       parts.push(prefixes[hundreds] + hundredWord)
     }
@@ -304,12 +329,11 @@ function buildOrdinalSegment (n, feminine) {
 
 /**
  * Converts a positive integer to Spanish ordinal words.
- *
  * @param {bigint} n - Positive integer to convert
  * @param {boolean} feminine - Use feminine forms
  * @returns {string} Spanish ordinal words
  */
-function integerToOrdinal (n, feminine) {
+function integerToOrdinal(n, feminine) {
   const thousandWord = feminine ? ORDINAL_THOUSAND_FEM : ORDINAL_THOUSAND_MASC
   const millionWord = feminine ? ORDINAL_MILLION_FEM : ORDINAL_MILLION_MASC
 
@@ -323,11 +347,12 @@ function integerToOrdinal (n, feminine) {
     const thousands = Number(n / 1000n)
     const remainder = Number(n % 1000n)
 
-    let result = ''
+    let result
 
     if (thousands === 1) {
       result = thousandWord
-    } else {
+    }
+    else {
       result = buildOrdinalSegment(thousands, feminine) + ' ' + thousandWord
     }
 
@@ -342,11 +367,12 @@ function integerToOrdinal (n, feminine) {
   const millions = Number(n / 1_000_000n)
   const remainder = n % 1_000_000n
 
-  let result = ''
+  let result
 
   if (millions === 1) {
     result = millionWord
-  } else {
+  }
+  else {
     result = buildOrdinalSegment(millions, feminine) + ' ' + millionWord
   }
 
@@ -357,26 +383,34 @@ function integerToOrdinal (n, feminine) {
   return result
 }
 
+/**
+ * @typedef {object} OrdinalOptions
+ * @property {('masculine'|'feminine')} [gender] - Grammatical gender
+ */
+
+/** @type {Required<OrdinalOptions>} */
+export const ordinalDefaults = { gender: 'masculine' }
+
+/** @type {{ gender: ReadonlyArray<Required<OrdinalOptions>['gender']> }} */
+export const ordinalValues = { gender: ['masculine', 'feminine'] }
+
 /**
  * Converts a numeric value to Spanish ordinal words.
- *
  * @param {number | string | bigint} value - The positive integer to convert
- * @param {Object} [options] - Optional configuration
- * @param {('masculine'|'feminine')} [options.gender='masculine'] - Grammatical gender
+ * @param {OrdinalOptions} [options] - Optional configuration
  * @returns {string} The number in Spanish ordinal words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a positive integer
- *
  * @example
  * toOrdinal(1)                          // 'primero'
  * toOrdinal(1, { gender: 'feminine' })  // 'primera'
  * toOrdinal(21)                         // 'vigésimo primero'
  */
-function toOrdinal (value, options) {
-  options = validateOptions(options)
+function toOrdinal(value, options) {
   const integerPart = parseOrdinalValue(value)
+  checkMax(integerPart, ordinalMax)
 
-  const { gender = 'masculine' } = options
+  const { gender } = resolveOptions(options, ordinalDefaults, ordinalValues)
   const feminine = gender === 'feminine'
 
   return integerToOrdinal(integerPart, feminine)
@@ -386,29 +420,34 @@ function toOrdinal (value, options) {
 // CURRENCY: toCurrency(value, options?)
 // ============================================================================
 
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [and] - Use "con" between dollars and cents
+ */
+
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults = { and: true }
+
 /**
  * Converts a numeric value to US Dollar currency words in Spanish.
  *
  * US Dollar uses masculine gender for dólares (el dólar)
  * and masculine for centavos (el centavo).
- *
  * @param {number | string | bigint} value - The currency amount to convert
- * @param {Object} [options] - Optional configuration
- * @param {boolean} [options.and=true] - Use "con" between dollars and cents
+ * @param {CurrencyOptions} [options] - Optional configuration
  * @returns {string} The amount in Spanish US Dollar 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)                  // 'cuarenta y dos dólares con cincuenta centavos'
  * toCurrency(1)                      // 'un dólar'
  * toCurrency(0.99)                   // 'noventa y nueve centavos'
  * toCurrency(42.50, { and: false })  // 'cuarenta y dos dólares cincuenta centavos'
  */
-function toCurrency (value, options) {
-  options = validateOptions(options)
+function toCurrency(value, options) {
   const { isNegative, dollars, cents: centavos } = parseCurrencyValue(value)
-  const { and: useAnd = true } = options
+  checkMax(dollars, currencyMax)
+  const { and: useAnd } = resolveOptions(options, currencyDefaults)
 
   let result = ''
   if (isNegative) result = NEGATIVE + ' '
@@ -418,7 +457,8 @@ function toCurrency (value, options) {
     // Use masculine for dollars, but "un dólar" not "uno dólar"
     if (dollars === 1n) {
       result += 'un ' + DOLAR
-    } else {
+    }
+    else {
       result += integerToWords(dollars, false) + ' ' + DOLARES
     }
   }
@@ -431,7 +471,8 @@ function toCurrency (value, options) {
     // Use masculine for centavos, but "un centavo" not "uno centavo"
     if (centavos === 1n) {
       result += 'un ' + CENTAVO
-    } else {
+    }
+    else {
       result += integerToWords(centavos, false) + ' ' + CENTAVOS
     }
   }

package/src/fa-IR.d.ts

@@ -1,18 +1,18 @@
+export const cardinalMax: null;
+export const ordinalMax: null;
+export const currencyMax: null;
 /**
  * Converts a numeric value to Persian words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Persian words
  */
 export function toCardinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Persian ordinal words.
- *
  * @param {number | string | bigint} value - The numeric value to convert (positive integer)
  * @returns {string} The number as ordinal words
  * @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)    // 'دوم'
@@ -24,12 +24,10 @@ export function toOrdinal(value: number | string | bigint): string;
  *
  * Iranian Rial has no subunit in modern usage.
  * (Historically dinar was 1/100 rial, but not used today)
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Persian 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)     // 'چهل و دو ریال'
  * toCurrency(1000)   // 'هزار ریال'

package/src/fa-IR.js

@@ -12,14 +12,24 @@
 import { parseCardinalValue } from './utils/parse-cardinal.js'
 import { parseCurrencyValue } from './utils/parse-currency.js'
 import { parseOrdinalValue } from './utils/parse-ordinal.js'
+import { UNBOUNDED } from './utils/scale.js'
+
+// No fixed scale ceiling — the speller composes every magnitude.
+export const cardinalMax = UNBOUNDED
+export const ordinalMax = UNBOUNDED
+export const currencyMax = UNBOUNDED
 
 // ============================================================================
 // Vocabulary
 // ============================================================================
 
+/** @type {Record<number, string>} */
 const ONES = { 1: 'یک', 2: 'دو', 3: 'سه', 4: 'چهار', 5: 'پنج', 6: 'شش', 7: 'هفت', 8: 'هشت', 9: 'نه' }
+/** @type {Record<number, string>} */
 const TEENS = { 10: 'ده', 11: 'یازده', 12: 'دوازده', 13: 'سیزده', 14: 'چهارده', 15: 'پانزده', 16: 'شانزده', 17: 'هفده', 18: 'هجده', 19: 'نوزده' }
+/** @type {Record<number, string>} */
 const TENS = { 20: 'بیست', 30: 'سی', 40: 'چهل', 50: 'پنجاه', 60: 'شصت', 70: 'هفتاد', 80: 'هشتاد', 90: 'نود' }
+/** @type {Record<number, string>} */
 const HUNDREDS = { 100: 'صد', 200: 'دویست', 300: 'سيصد', 400: 'چهار صد', 500: 'پانصد', 600: 'ششصد', 700: 'هفتصد', 800: 'هشتصد', 900: 'نهصد' }
 
 const THOUSAND = 'هزار'
@@ -37,6 +47,7 @@ const DECIMAL_SEP = 'ممیّز'
 // Persian ordinals: add -ُم (-om) suffix to cardinal
 // Special forms for 1st, 2nd, 3rd
 const ORDINAL_SUFFIX = 'م' // ـُم (-om)
+/** @type {Record<number, string>} */
 const ORDINAL_ONES = {
   1: 'اول', // avval (first)
   2: 'دوم', // dovvom (second)
@@ -46,7 +57,7 @@ const ORDINAL_ONES = {
   6: 'ششم',
   7: 'هفتم',
   8: 'هشتم',
-  9: 'نهم'
+  9: 'نهم',
 }
 
 // ============================================================================
@@ -59,7 +70,12 @@ const RIAL = 'ریال'
 // Conversion Functions
 // ============================================================================
 
-function integerToWords (n) {
+/**
+ * Converts a non-negative integer to Persian cardinal words.
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} Persian cardinal words
+ */
+function integerToWords(n) {
   if (n === 0n) return ZERO
 
   // 1-9
@@ -121,7 +137,12 @@ function integerToWords (n) {
   return `${milliardPrefix}${suffix}`
 }
 
-function decimalPartToWords (decimalPart) {
+/**
+ * Converts the fractional digits of a number to Persian words.
+ * @param {string} decimalPart - The fractional digits as a string
+ * @returns {string} Persian words for the decimal portion
+ */
+function decimalPartToWords(decimalPart) {
   let result = ''
   let i = 0
 
@@ -142,11 +163,10 @@ function decimalPartToWords (decimalPart) {
 
 /**
  * Converts a numeric value to Persian words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Persian words
  */
-function toCardinal (value) {
+function toCardinal(value) {
   const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
@@ -172,11 +192,10 @@ function toCardinal (value) {
  * Converts a non-negative integer to Persian ordinal words.
  *
  * Persian ordinals: اول (1st), دوم (2nd), سوم (3rd), then cardinal + م suffix.
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Persian ordinal words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   // Special forms for 1-9
   if (n >= 1n && n <= 9n) {
     return ORDINAL_ONES[Number(n)]
@@ -189,18 +208,16 @@ function integerToOrdinal (n) {
 
 /**
  * Converts a numeric value to Persian ordinal words.
- *
  * @param {number | string | bigint} value - The numeric value to convert (positive integer)
  * @returns {string} The number as ordinal words
  * @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(10)   // 'دهم'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
   return integerToOrdinal(integerPart)
 }
@@ -214,18 +231,16 @@ function toOrdinal (value) {
  *
  * Iranian Rial has no subunit in modern usage.
  * (Historically dinar was 1/100 rial, but not used today)
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Persian 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)     // 'چهل و دو ریال'
  * toCurrency(1000)   // 'هزار ریال'
  * toCurrency(-5)     // 'منفى پنج ریال'
  */
-function toCurrency (value) {
+function toCurrency(value) {
   const { isNegative, dollars: rial } = parseCurrencyValue(value)
 
   let result = ''

package/src/fi-FI.d.ts

@@ -1,11 +1,12 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
 /**
  * Converts a numeric value to Finnish words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Finnish words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCardinal(21)       // 'kaksikymmentäyksi'
  * toCardinal(1000)     // 'tuhat'
@@ -14,12 +15,10 @@
 export function toCardinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Finnish ordinal words.
- *
  * @param {number | string | bigint} value - The numeric value to convert (positive integer)
  * @returns {string} The number as ordinal words
  * @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)    // 'ensimmäinen'
  * toOrdinal(2)    // 'toinen'
@@ -32,12 +31,10 @@ export function toOrdinal(value: number | string | bigint): string;
  *
  * Euro uses sentti as subunit (100 senttiä = 1 euro).
  * Finnish has singular/plural: 1 euro vs 2 euroa, 1 sentti vs 2 senttiä.
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Finnish currency words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCurrency(1)      // 'yksi euro'
  * toCurrency(42)     // 'neljäkymmentäkaksi euroa'