n2words 3.0.0 → 4.0.0

package/{lib/languages/es.js → src/es-MX.js}

@@ -1,24 +1,26 @@
 /**
- * Spanish language converter - Functional Implementation
+ * Spanish (Mexico) language converter
  *
- * A performance-optimized number-to-words converter using precomputed lookup tables.
- * Self-contained module with its own input validation, ready for subpath exports.
+ * CLDR: es-MX | Spanish as used in Mexico
  *
- * Key optimization: Precompute all segment values (0-999) at module load.
- * This eliminates all per-call string manipulation for segment conversion.
+ * Uses the European long scale numbering system (per RAE and Academia Mexicana):
+ * - 10⁶ = millón
+ * - 10⁹ = mil millones (thousand millions)
+ * - 10¹² = billón
  *
- * Spanish-specific rules (handled in precomputation):
+ * Spanish-specific rules:
  * - Gender agreement: uno/una, veintiuno/veintiuna, hundreds
  * - Special twenties: veinte, veintiuno, veintidós, ... veintinueve
  * - "y" conjunction: treinta y uno (only 30-99 with ones)
  * - "cien" for exact 100, "ciento/cienta" otherwise
  * - Irregular hundreds: quinientos, setecientos, novecientos
- * - Compound long scale: millón, mil millones, billón, mil billones
  * - "un" before millón (not "uno"), omit before mil
  */
 
-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)
@@ -44,12 +46,32 @@ const SCALES = ['millón', 'billón', 'trillón', 'cuatrillón']
 const SCALES_PLURAL = ['millones', 'billones', 'trillones', 'cuatrillones']
 
 const THOUSAND = 'mil'
+
 const ZERO = 'cero'
 const NEGATIVE = 'menos'
 const DECIMAL_SEP = 'punto'
 
+// Ordinal vocabulary (identical to es-ES - ordinals don't vary by region)
+const ORDINAL_ONES_MASC = ['', 'primero', 'segundo', 'tercero', 'cuarto', 'quinto', 'sexto', 'séptimo', 'octavo', 'noveno']
+const ORDINAL_ONES_FEM = ['', 'primera', 'segunda', 'tercera', 'cuarta', 'quinta', 'sexta', 'séptima', 'octava', 'novena']
+const ORDINAL_TENS_MASC = ['', 'décimo', 'vigésimo', 'trigésimo', 'cuadragésimo', 'quincuagésimo', 'sexagésimo', 'septuagésimo', 'octogésimo', 'nonagésimo']
+const ORDINAL_TENS_FEM = ['', 'décima', 'vigésima', 'trigésima', 'cuadragésima', 'quincuagésima', 'sexagésima', 'septuagésima', 'octogésima', 'nonagésima']
+const ORDINAL_HUNDRED_MASC = 'centésimo'
+const ORDINAL_HUNDRED_FEM = 'centésima'
+const ORDINAL_THOUSAND_MASC = 'milésimo'
+const ORDINAL_THOUSAND_FEM = 'milésima'
+const ORDINAL_MILLION_MASC = 'millonésimo'
+const ORDINAL_MILLION_FEM = 'millonésima'
+
+// Currency vocabulary (Mexican Peso - MXN)
+const PESO = 'peso'
+const PESOS = 'pesos'
+const CENTAVO = 'centavo'
+const CENTAVOS = 'centavos'
+const CURRENCY_CONNECTOR = 'con'
+
 // ============================================================================
-// Precomputed Lookup Tables (built once at module load)
+// Segment Building
 // ============================================================================
 
 /**
@@ -65,8 +87,8 @@ function buildSegment (n, feminine) {
   if (n === 100) return 'cien'
 
   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 tensOnes = n % 100
 
   const parts = []
@@ -104,18 +126,6 @@ function buildSegment (n, feminine) {
   return parts.join(' ')
 }
 
-// Precompute all 1000 segment words (0-999) for masculine
-const SEGMENTS_MASC = new Array(1000)
-for (let i = 0; i < 1000; i++) {
-  SEGMENTS_MASC[i] = buildSegment(i, false)
-}
-
-// Precompute all 1000 segment words (0-999) for feminine
-const SEGMENTS_FEM = new Array(1000)
-for (let i = 0; i < 1000; i++) {
-  SEGMENTS_FEM[i] = buildSegment(i, true)
-}
-
 // ============================================================================
 // Helper Functions
 // ============================================================================
@@ -160,11 +170,9 @@ function getScaleWord (scaleIndex, segment) {
 function integerToWords (n, feminine) {
   if (n === 0n) return ZERO
 
-  const segments = feminine ? SEGMENTS_FEM : SEGMENTS_MASC
-
-  // Fast path: numbers < 1000 (direct lookup)
+  // Fast path: numbers < 1000
   if (n < 1000n) {
-    return segments[Number(n)]
+    return buildSegment(Number(n), feminine)
   }
 
   // Fast path: numbers < 1,000,000 (thousands)
@@ -178,7 +186,7 @@ function integerToWords (n, feminine) {
       result = THOUSAND
     } else {
       // Use masculine for thousands segment, but check for "uno" → omit before mil
-      const thousandsWord = SEGMENTS_MASC[thousands]
+      const thousandsWord = buildSegment(thousands, false)
       // "uno mil" → "mil" (handled in joinSegments equivalent)
       if (thousandsWord === 'uno' || thousandsWord === 'una') {
         result = THOUSAND
@@ -188,7 +196,7 @@ function integerToWords (n, feminine) {
     }
 
     if (remainder > 0) {
-      result += ' ' + segments[remainder]
+      result += ' ' + buildSegment(remainder, feminine)
     }
 
     return result
@@ -216,8 +224,6 @@ function buildLargeNumberWords (n, feminine) {
     temp = temp / 1000n
   }
 
-  const segments = feminine ? SEGMENTS_FEM : SEGMENTS_MASC
-
   // Build result string directly
   let result = ''
 
@@ -231,13 +237,13 @@ function buildLargeNumberWords (n, feminine) {
 
     if (i === 0) {
       // Units segment
-      result += segments[Number(segment)]
+      result += buildSegment(Number(segment), feminine)
     } else if (i === 1) {
       // Thousands: omit "uno" before mil
       if (segment === 1n) {
         result += THOUSAND
       } else {
-        result += SEGMENTS_MASC[Number(segment)] + ' ' + scaleWord
+        result += buildSegment(Number(segment), false) + ' ' + scaleWord
       }
     } else if (i % 2 === 1) {
       // Odd scale indices (3, 5, 7): "mil millones", "mil billones", etc.
@@ -245,7 +251,7 @@ function buildLargeNumberWords (n, feminine) {
       if (segment === 1n) {
         result += scaleWord
       } else {
-        result += SEGMENTS_MASC[Number(segment)] + ' ' + scaleWord
+        result += buildSegment(Number(segment), false) + ' ' + scaleWord
       }
     } else {
       // Even scale indices (2, 4, 6): millón, billón, trillón
@@ -254,7 +260,7 @@ function buildLargeNumberWords (n, feminine) {
         result += 'un ' + scaleWord
       } else {
         // Use masculine for scale segment
-        result += SEGMENTS_MASC[Number(segment)] + ' ' + scaleWord
+        result += buildSegment(Number(segment), false) + ' ' + scaleWord
       }
     }
   }
@@ -291,10 +297,7 @@ function decimalPartToWords (decimalPart, feminine) {
 }
 
 /**
- * Converts a numeric value to Spanish words.
- *
- * This is the main public API. It accepts any valid numeric input
- * (number, string, or bigint) and handles parsing internally.
+ * Converts a numeric value to Spanish words (long scale).
  *
  * @param {number | string | bigint} value - The numeric value to convert
  * @param {Object} [options] - Optional configuration
@@ -304,14 +307,17 @@ function decimalPartToWords (decimalPart, feminine) {
  * @throws {Error} If value is not a valid number format
  *
  * @example
- * toWords(21)                        // 'veintiuno'
- * toWords(21, {gender: 'feminine'})  // 'veintiuna'
- * toWords(1000000)                   // 'un millón'
+ * toCardinal(21)                        // 'veintiuno'
+ * toCardinal(21, {gender: 'feminine'})  // 'veintiuna'
+ * toCardinal(1000000000)                // 'mil millones'
  */
-function toWords (value, options) {
+function toCardinal (value, options) {
   options = validateOptions(options)
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
-  const feminine = options.gender === 'feminine'
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
+
+  // Apply option defaults
+  const { gender = 'masculine' } = options
+  const feminine = gender === 'feminine'
 
   let result = ''
 
@@ -328,8 +334,192 @@ function toWords (value, options) {
   return result
 }
 
+// ============================================================================
+// ORDINAL: toOrdinal(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) {
+  if (n === 0) return ''
+
+  const ones = n % 10
+  const tens = Math.trunc(n / 10) % 10
+  const hundreds = Math.trunc(n / 100)
+
+  const onesArr = feminine ? ORDINAL_ONES_FEM : ORDINAL_ONES_MASC
+  const tensArr = feminine ? ORDINAL_TENS_FEM : ORDINAL_TENS_MASC
+  const hundredWord = feminine ? ORDINAL_HUNDRED_FEM : ORDINAL_HUNDRED_MASC
+
+  const parts = []
+
+  // Hundreds
+  if (hundreds > 0) {
+    if (hundreds === 1) {
+      parts.push(hundredWord)
+    } else {
+      const prefixes = ['', '', 'du', 'tri', 'cuadri', 'quin', 'sex', 'septi', 'octi', 'noni']
+      parts.push(prefixes[hundreds] + hundredWord)
+    }
+  }
+
+  // Tens
+  if (tens > 0) {
+    parts.push(tensArr[tens])
+  }
+
+  // Ones
+  if (ones > 0) {
+    parts.push(onesArr[ones])
+  }
+
+  return parts.join(' ')
+}
+
+/**
+ * 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) {
+  const thousandWord = feminine ? ORDINAL_THOUSAND_FEM : ORDINAL_THOUSAND_MASC
+  const millionWord = feminine ? ORDINAL_MILLION_FEM : ORDINAL_MILLION_MASC
+
+  // Fast path: numbers < 1000
+  if (n < 1000n) {
+    return buildOrdinalSegment(Number(n), feminine)
+  }
+
+  // Numbers 1000-999999
+  if (n < 1_000_000n) {
+    const thousands = Number(n / 1000n)
+    const remainder = Number(n % 1000n)
+
+    let result = ''
+
+    if (thousands === 1) {
+      result = thousandWord
+    } else {
+      result = buildOrdinalSegment(thousands, feminine) + ' ' + thousandWord
+    }
+
+    if (remainder > 0) {
+      result += ' ' + buildOrdinalSegment(remainder, feminine)
+    }
+
+    return result
+  }
+
+  // Numbers >= 1,000,000
+  const millions = Number(n / 1_000_000n)
+  const remainder = n % 1_000_000n
+
+  let result = ''
+
+  if (millions === 1) {
+    result = millionWord
+  } else {
+    result = buildOrdinalSegment(millions, feminine) + ' ' + millionWord
+  }
+
+  if (remainder > 0n) {
+    result += ' ' + integerToOrdinal(remainder, feminine)
+  }
+
+  return result
+}
+
+/**
+ * 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
+ * @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)
+  const integerPart = parseOrdinalValue(value)
+
+  const { gender = 'masculine' } = options
+  const feminine = gender === 'feminine'
+
+  return integerToOrdinal(integerPart, feminine)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value, options?)
+// ============================================================================
+
+/**
+ * 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
+ * @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)
+  const { isNegative, dollars: pesos, cents: centavos } = parseCurrencyValue(value)
+  const { and: useAnd = true } = options
+
+  let result = ''
+  if (isNegative) result = NEGATIVE + ' '
+
+  // Pesos part (show if non-zero, or if no centavos)
+  if (pesos > 0n || centavos === 0n) {
+    // Use masculine for pesos, but "un peso" not "uno peso"
+    if (pesos === 1n) {
+      result += 'un ' + PESO
+    } else {
+      result += integerToWords(pesos, false) + ' ' + PESOS
+    }
+  }
+
+  // Centavos part
+  if (centavos > 0n) {
+    if (pesos > 0n) {
+      result += useAnd ? ' ' + CURRENCY_CONNECTOR + ' ' : ' '
+    }
+    // Use masculine for centavos, but "un centavo" not "uno centavo"
+    if (centavos === 1n) {
+      result += 'un ' + CENTAVO
+    } else {
+      result += integerToWords(centavos, false) + ' ' + CENTAVOS
+    }
+  }
+
+  return result
+}
+
 // ============================================================================
 // Public API
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/es-US.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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
+ * @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;
+/**
+ * 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
+ * @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;
+/**
+ * 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
+ * @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;