n2words 4.0.0 → 5.1.0

package/src/es-MX.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, longScale } from './utils/scale.js'
+import { resolveOptions } from './utils/resolve-options.js'
 
 // ============================================================================
 // Vocabulary (module-level constants)
@@ -45,6 +47,15 @@ const HUNDREDS_FEM = ['', 'cienta', 'doscientas', 'trescientas', 'cuatrocientas'
 const SCALES = ['millón', 'billón', 'trillón', 'cuatrillón']
 const SCALES_PLURAL = ['millones', 'billones', 'trillones', 'cuatrillones']
 
+// Supported magnitude ceilings (checked at the public entry points). Each
+// SCALES entry spans two segment groups (X and "mil X"); with the units group
+// that's 2 * SCALES.length + 2 groups of 3 digits, so cardinals must stay below
+// 10^30. Ordinals are bounded lower: the millions multiplier uses
+// buildOrdinalSegment (0-999), so n must stay below 10^9.
+export const cardinalMax = longScale(SCALES.length)
+export const ordinalMax = bounded(9)
+export const currencyMax = longScale(SCALES.length)
+
 const THOUSAND = 'mil'
 
 const ZERO = 'cero'
@@ -80,7 +91,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)
@@ -102,22 +113,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])
     }
@@ -132,12 +148,11 @@ function buildSegment (n, feminine) {
 
 /**
  * Gets scale word for Spanish compound long scale.
- *
  * @param {number} scaleIndex - Scale level (1 = thousand, 2 = million, etc.)
  * @param {bigint} segment - Segment value for pluralization
  * @returns {string} Scale word
  */
-function getScaleWord (scaleIndex, segment) {
+function getScaleWord(scaleIndex, segment) {
   if (scaleIndex === 1) return THOUSAND
 
   // Even indices (2, 4, 6, 8): millón, billón, trillón, cuatrillón
@@ -147,7 +162,8 @@ function getScaleWord (scaleIndex, segment) {
     const baseWord = SCALES[arrayIndex]
     if (!baseWord) return ''
     return segment > 1n ? SCALES_PLURAL[arrayIndex] : baseWord
-  } else {
+  }
+  else {
     // Compound: "mil millones" pattern
     const arrayIndex = ((scaleIndex - 1) / 2) - 1
     const pluralWord = SCALES_PLURAL[arrayIndex]
@@ -162,12 +178,11 @@ function getScaleWord (scaleIndex, segment) {
 
 /**
  * Converts a non-negative integer to Spanish words.
- *
  * @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
@@ -184,13 +199,15 @@ function integerToWords (n, feminine) {
     if (thousands === 1) {
       // "mil" not "uno mil"
       result = THOUSAND
-    } else {
+    }
+    else {
       // Use masculine for thousands segment, but check for "uno" → omit before mil
       const thousandsWord = buildSegment(thousands, false)
       // "uno mil" → "mil" (handled in joinSegments equivalent)
       if (thousandsWord === 'uno' || thousandsWord === 'una') {
         result = THOUSAND
-      } else {
+      }
+      else {
         result = thousandsWord + ' ' + THOUSAND
       }
     }
@@ -209,14 +226,14 @@ function integerToWords (n, feminine) {
 /**
  * Builds words for numbers >= 1,000,000.
  * Uses BigInt division for faster segment extraction.
- *
  * @param {bigint} n - Number >= 1,000,000
  * @param {boolean} feminine - Use feminine forms
  * @returns {string} Spanish words
  */
-function buildLargeNumberWords (n, feminine) {
+function buildLargeNumberWords(n, feminine) {
   // Extract segments using BigInt division (faster than string slicing)
   // Segments stored least-significant first (index 0 = ones, 1 = thousands, etc.)
+  // Callers guard the magnitude (cardinalMax) before reaching here.
   const segmentValues = []
   let temp = n
   while (temp > 0n) {
@@ -238,27 +255,33 @@ function buildLargeNumberWords (n, feminine) {
     if (i === 0) {
       // Units segment
       result += buildSegment(Number(segment), feminine)
-    } else if (i === 1) {
+    }
+    else if (i === 1) {
       // Thousands: omit "uno" before mil
       if (segment === 1n) {
         result += THOUSAND
-      } else {
+      }
+      else {
         result += buildSegment(Number(segment), false) + ' ' + scaleWord
       }
-    } else if (i % 2 === 1) {
+    }
+    else if (i % 2 === 1) {
       // Odd scale indices (3, 5, 7): "mil millones", "mil billones", etc.
       // Omit "uno" before these compound scales
       if (segment === 1n) {
         result += scaleWord
-      } else {
+      }
+      else {
         result += buildSegment(Number(segment), false) + ' ' + scaleWord
       }
-    } else {
+    }
+    else {
       // Even scale indices (2, 4, 6): millón, billón, trillón
       if (segment === 1n) {
         // "un millón" not "uno millón"
         result += 'un ' + scaleWord
-      } else {
+      }
+      else {
         // Use masculine for scale segment
         result += buildSegment(Number(segment), false) + ' ' + scaleWord
       }
@@ -270,12 +293,11 @@ function buildLargeNumberWords (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
@@ -296,27 +318,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 (long 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)                // 'mil millones'
  */
-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 = ''
@@ -340,12 +372,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
@@ -362,7 +393,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)
     }
@@ -383,12 +415,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
 
@@ -402,11 +433,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
     }
 
@@ -421,11 +453,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
   }
 
@@ -436,26 +469,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)
@@ -465,29 +506,34 @@ function toOrdinal (value, options) {
 // CURRENCY: toCurrency(value, options?)
 // ============================================================================
 
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [and] - Use "con" between pesos and centavos
+ */
+
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults = { and: true }
+
 /**
  * Converts a numeric value to Mexican Peso currency words.
  *
  * Mexican currency uses masculine gender for pesos (el peso)
  * 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 pesos and centavos
+ * @param {CurrencyOptions} [options] - Optional configuration
  * @returns {string} The amount in Mexican 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 pesos con cincuenta centavos'
  * toCurrency(1)                      // 'un peso'
  * toCurrency(0.99)                   // 'noventa y nueve centavos'
  * toCurrency(42.50, { and: false })  // 'cuarenta y dos pesos cincuenta centavos'
  */
-function toCurrency (value, options) {
-  options = validateOptions(options)
+function toCurrency(value, options) {
   const { isNegative, dollars: pesos, cents: centavos } = parseCurrencyValue(value)
-  const { and: useAnd = true } = options
+  checkMax(pesos, currencyMax)
+  const { and: useAnd } = resolveOptions(options, currencyDefaults)
 
   let result = ''
   if (isNegative) result = NEGATIVE + ' '
@@ -497,7 +543,8 @@ function toCurrency (value, options) {
     // Use masculine for pesos, but "un peso" not "uno peso"
     if (pesos === 1n) {
       result += 'un ' + PESO
-    } else {
+    }
+    else {
       result += integerToWords(pesos, false) + ' ' + PESOS
     }
   }
@@ -510,7 +557,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/es-US.d.ts

@@ -1,58 +1,90 @@
+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} OrdinalOptions
+ * @property {('masculine'|'feminine')} [gender] - Grammatical gender
+ */
+/** @type {Required<OrdinalOptions>} */
+export const ordinalDefaults: Required<OrdinalOptions>;
+/** @type {{ gender: ReadonlyArray<Required<OrdinalOptions>['gender']> }} */
+export const ordinalValues: {
+    gender: ReadonlyArray<Required<OrdinalOptions>["gender"]>;
+};
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [and] - Use "con" between dollars and cents
+ */
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults: Required<CurrencyOptions>;
+export type CardinalOptions = {
+    /**
+     * - Grammatical gender
+     */
+    gender?: "feminine" | "masculine" | undefined;
+};
+export type OrdinalOptions = {
+    /**
+     * - Grammatical gender
+     */
+    gender?: "feminine" | "masculine" | undefined;
+};
+export type CurrencyOptions = {
+    /**
+     * - Use "con" between dollars and cents
+     */
+    and?: boolean | undefined;
+};
 /**
  * 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'
  */
-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 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'
  */
-export function toOrdinal(value: number | string | bigint, options?: {
-    gender?: "masculine" | "feminine" | undefined;
-}): string;
+export function toOrdinal(value: number | string | bigint, options?: OrdinalOptions): string;
 /**
  * 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'
  */
-export function toCurrency(value: number | string | bigint, options?: {
-    and?: boolean | undefined;
-}): string;
+export function toCurrency(value: number | string | bigint, options?: CurrencyOptions): string;