n2words 5.0.0 → 5.1.1

package/src/pt-BR.js

@@ -14,7 +14,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 { western } from './utils/scale.js'
+import { resolveOptions } from './utils/resolve-options.js'
 
 // ============================================================================
 // Vocabulary (module-level constants)
@@ -43,12 +45,13 @@ const ORDINAL_HUNDREDS = ['', 'centésimo', 'ducentésimo', 'tricentésimo', 'qu
 // ============================================================================
 
 // Dicionário focado no uso no Brasil (centavos para dólar e euro em vez de cêntimos)
+/** @type {Record<string, {major: string[], minor: string[]}>} */
 const CURRENCIES = {
   BRL: { major: ['real', 'reais'], minor: ['centavo', 'centavos'] },
   USD: { major: ['dólar', 'dólares'], minor: ['centavo', 'centavos'] },
   EUR: { major: ['euro', 'euros'], minor: ['centavo', 'centavos'] }, // No Brasil é comum falar "centavos de euro"
   GBP: { major: ['libra', 'libras'], minor: ['pêni', 'pence'] },
-  JPY: { major: ['iene', 'ienes'], minor: ['sen', 'sen'] } // Iene não tem subdivisão usada no dia a dia
+  JPY: { major: ['iene', 'ienes'], minor: ['sen', 'sen'] }, // Iene não tem subdivisão usada no dia a dia
 }
 
 // Fallback para caso o usuário passe uma moeda não mapeada (ex: 'CAD')
@@ -61,8 +64,10 @@ const DEFAULT_CURRENCY_WORDS = { major: ['unidade', 'unidades'], minor: ['centav
 /**
  * Builds segment word for 0-999 with Portuguese "e" rules.
  * Returns the word and whether it's an exact hundred (for "cem" handling).
+ * @param {number} n - Number 0-999
+ * @returns {{word: string, isExactHundred: boolean, startsWithHundreds?: boolean}} The segment word and hundred-related flags
  */
-function buildSegment (n) {
+function buildSegment(n) {
   if (n === 0) return { word: '', isExactHundred: false }
 
   // Special case: exact 100 is "cem"
@@ -83,14 +88,17 @@ function buildSegment (n) {
   if (tens === 1) {
     // Teens (10-19)
     parts.push(TEENS[ones])
-  } else if (tens >= 2) {
+  }
+  else if (tens >= 2) {
     if (ones > 0) {
       // Tens + ones with "e": "vinte e um"
       parts.push(TENS[tens] + ' e ' + ONES[ones])
-    } else {
+    }
+    else {
       parts.push(TENS[tens])
     }
-  } else if (ones > 0) {
+  }
+  else if (ones > 0) {
     parts.push(ONES[ones])
   }
 
@@ -115,7 +123,7 @@ const SCALE_WORDS_SINGULAR = [
   'quatrilhão', // 5: 10^15
   'quintilhão', // 6: 10^18
   'sextilhão', // 7: 10^21
-  'setilhão' // 8: 10^24
+  'setilhão', // 8: 10^24
 ]
 
 const SCALE_WORDS_PLURAL = [
@@ -127,20 +135,32 @@ const SCALE_WORDS_PLURAL = [
   'quatrilhões', // 5: 10^15
   'quintilhões', // 6: 10^18
   'sextilhões', // 7: 10^21
-  'setilhões' // 8: 10^24
+  'setilhões', // 8: 10^24
 ]
 
+// Scale ordinal words (short scale for pt-BR). Module-scope so its length can
+// derive the ordinal ceiling and so it isn't rebuilt on every call.
+const SCALE_ORDINAL = ['', 'milésimo', 'milionésimo', 'bilionésimo', 'trilionésimo', 'quatrilionésimo', 'quintilionésimo', 'sextilionésimo']
+
+// Supported magnitude ceilings (checked at the public entry points). Cardinal
+// scale words reach index SCALE_WORDS_SINGULAR.length-1 (setilhão, 10^24), so
+// cardinals/currency must stay below 10^27. The ordinal of a number whose
+// lowest non-zero group is a scale group uses SCALE_ORDINAL, which is shorter,
+// so ordinals must stay below 10^(SCALE_ORDINAL.length * 3).
+export const cardinalMax = western(SCALE_WORDS_SINGULAR.length - 1)
+export const ordinalMax = western(SCALE_ORDINAL.length - 1)
+export const currencyMax = western(SCALE_WORDS_SINGULAR.length - 1)
+
 // ============================================================================
 // Conversion Functions
 // ============================================================================
 
 /**
  * Converts a non-negative integer to Portuguese words.
- *
  * @param {bigint} n - Non-negative integer to convert
  * @returns {string} Portuguese words
  */
-function integerToWords (n) {
+function integerToWords(n) {
   if (n === 0n) return ZERO
 
   // Fast path: numbers < 1000
@@ -157,7 +177,8 @@ function integerToWords (n) {
     if (thousands === 1) {
       // "mil" not "um mil"
       result = THOUSAND
-    } else {
+    }
+    else {
       result = buildSegment(thousands).word + ' ' + THOUSAND
     }
 
@@ -166,7 +187,8 @@ function integerToWords (n) {
       // REGRA DO "E": Menor que 100 OU Centena Exata (ex: 500)
       if (!remainderResult.startsWithHundreds || remainderResult.isExactHundred) {
         result += ' e ' + remainderResult.word
-      } else {
+      }
+      else {
         result += ' ' + remainderResult.word
       }
     }
@@ -181,11 +203,10 @@ function integerToWords (n) {
 /**
  * Builds words for numbers >= 1,000,000.
  * Uses BigInt division for faster segment extraction.
- *
  * @param {bigint} n - Number >= 1,000,000
  * @returns {string} Portuguese words
  */
-function buildLargeNumberWords (n) {
+function buildLargeNumberWords(n) {
   // Extract segments using BigInt division
   const segments = []
   let temp = n
@@ -224,20 +245,24 @@ function buildLargeNumberWords (n) {
       // Units segment
       result += segmentResult.word
       prevWasScale = false
-    } else if (i === 1) {
+    }
+    else if (i === 1) {
       // Thousands
       if (segment === 1) {
         result += THOUSAND
-      } else {
+      }
+      else {
         result += segmentResult.word + ' ' + THOUSAND
       }
       prevWasScale = true
-    } else {
+    }
+    else {
       // Million and above
       const scaleWord = segment === 1 ? SCALE_WORDS_SINGULAR[i] : SCALE_WORDS_PLURAL[i]
       if (segment === 1) {
         result += 'um ' + scaleWord
-      } else {
+      }
+      else {
         result += segmentResult.word + ' ' + scaleWord
       }
       prevWasScale = true
@@ -249,11 +274,10 @@ function buildLargeNumberWords (n) {
 
 /**
  * Converts decimal digits to Portuguese words.
- *
  * @param {string} decimalPart - Decimal digits (without the point)
  * @returns {string} Portuguese words for decimal part
  */
-function decimalPartToWords (decimalPart) {
+function decimalPartToWords(decimalPart) {
   let result = ''
 
   // Handle leading zeros
@@ -276,12 +300,14 @@ function decimalPartToWords (decimalPart) {
 
 /**
  * Converts a numeric value to Portuguese words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Portuguese words
  */
-function toCardinal (value) {
+function toCardinal(value) {
   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)
 
   let result = ''
 
@@ -304,11 +330,10 @@ function toCardinal (value) {
 
 /**
  * Builds ordinal words for 0-999.
- *
  * @param {number} n - Number 0-999
  * @returns {string} Portuguese ordinal words
  */
-function buildOrdinalSegment (n) {
+function buildOrdinalSegment(n) {
   if (n === 0) return ''
 
   const ones = n % 10
@@ -326,12 +351,14 @@ function buildOrdinalSegment (n) {
   if (tens === 1) {
     // 10-19: use teens array (décimo, décimo primeiro, etc.)
     parts.push(ORDINAL_TEENS[ones])
-  } else if (tens >= 2) {
+  }
+  else if (tens >= 2) {
     parts.push(ORDINAL_TENS[tens])
     if (ones > 0) {
       parts.push(ORDINAL_ONES[ones])
     }
-  } else if (ones > 0) {
+  }
+  else if (ones > 0) {
     parts.push(ORDINAL_ONES[ones])
   }
 
@@ -340,11 +367,10 @@ function buildOrdinalSegment (n) {
 
 /**
  * Builds ordinal words for large numbers.
- *
  * @param {bigint} n - Non-negative integer
  * @returns {string} Portuguese ordinal words
  */
-function buildLargeOrdinal (n) {
+function buildLargeOrdinal(n) {
   // Extract segments
   const segments = []
   let temp = n
@@ -362,9 +388,6 @@ function buildLargeOrdinal (n) {
     }
   }
 
-  // Scale ordinal words (singular forms - short scale for pt-BR)
-  const SCALE_ORDINAL = ['', 'milésimo', 'milionésimo', 'bilionésimo', 'trilionésimo', 'quatrilionésimo', 'quintilionésimo', 'sextilionésimo']
-
   let result = ''
 
   for (let i = segments.length - 1; i >= 0; i--) {
@@ -378,28 +401,35 @@ function buildLargeOrdinal (n) {
       if (i === 0) {
         // Units: just ordinal
         result += buildOrdinalSegment(segment)
-      } else if (segment === 1 && i > 0) {
+      }
+      else if (segment === 1 && i > 0) {
         // Exact scale: "milésimo", "milionésimo", etc.
         result += SCALE_ORDINAL[i]
-      } else {
+      }
+      else {
         // Segment + scale ordinal
         result += buildOrdinalSegment(segment) + ' ' + SCALE_ORDINAL[i]
       }
-    } else {
+    }
+    else {
       // Higher segments use cardinal form
       if (i === 0) {
         result += buildSegment(segment).word
-      } else if (i === 1) {
+      }
+      else if (i === 1) {
         if (segment === 1) {
           result += THOUSAND
-        } else {
+        }
+        else {
           result += buildSegment(segment).word + ' ' + THOUSAND
         }
-      } else {
+      }
+      else {
         const scaleWord = segment === 1 ? SCALE_WORDS_SINGULAR[i] : SCALE_WORDS_PLURAL[i]
         if (segment === 1) {
           result += 'um ' + scaleWord
-        } else {
+        }
+        else {
           result += buildSegment(segment).word + ' ' + scaleWord
         }
       }
@@ -411,12 +441,12 @@ function buildLargeOrdinal (n) {
 
 /**
  * Converts a number to Portuguese ordinal words.
- *
  * @param {number | string | bigint} value - The number to convert
  * @returns {string} Portuguese ordinal words
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const n = parseOrdinalValue(value)
+  checkMax(n, ordinalMax)
 
   // Fast path: 1-9
   if (n < 10n) {
@@ -451,31 +481,40 @@ function toOrdinal (value) {
 // Currency Functions
 // ============================================================================
 
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [and] - Include "e" between major and minor units
+ * @property {string} [currency] - Currency code (e.g., 'BRL', 'USD'); empty means auto-detect for pt-BR
+ */
+
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults = { and: true, currency: '' }
+
 /**
  * Converts a number to Brazilian Portuguese currency words.
- *
  * @param {number | string | bigint} value - The amount to convert
- * @param {Object} [options]
- * @param {boolean} [options.and=true] - Include "e" between major and minor units
- * @param {string} [options.currency] - Currency code (e.g., 'BRL', 'USD')
+ * @param {CurrencyOptions} [options] Currency formatting options
  * @returns {string} Brazilian Portuguese currency words
- *
  * @example
  * toCurrency(42.50)                    // 'quarenta e dois reais e cinquenta centavos'
  * toCurrency(42.50, {currency: 'USD'}) // 'quarenta e dois dólares e cinquenta centavos'
  */
-function toCurrency (value, options) {
-  options = validateOptions(options)
+function toCurrency(value, options) {
   const { isNegative, dollars: majorUnits, cents: minorUnits } = parseCurrencyValue(value)
-  const { and = true } = options
+  checkMax(majorUnits, currencyMax)
+  const { and, currency } = resolveOptions(options, currencyDefaults)
 
   // 1. Descobre a moeda informada ou busca automaticamente a padrão do país (pt-BR = BRL)
-  let currencyCode = options.currency
+  let currencyCode = currency
   if (!currencyCode) {
     try {
-      const localeInfo = new Intl.Locale('pt-BR')
+      // Intl Locale Info (getCurrencies) is a newer TC39 API present at
+      // runtime in modern engines but not yet in the TS ES2022 lib types;
+      // augment the type locally rather than widen the project's lib.
+      const localeInfo = /** @type {Intl.Locale & { getCurrencies(): string[] }} */ (new Intl.Locale('pt-BR'))
       currencyCode = localeInfo.getCurrencies?.()[0]
-    } catch (e) {
+    }
+    catch {
       // Ignora erro em ambientes antigos (fallback garantido abaixo)
     }
     currencyCode = currencyCode || 'BRL' // Padrão absoluto para o Brasil
@@ -485,7 +524,7 @@ function toCurrency (value, options) {
   // 2. Busca os nomes no dicionário ou usa o fallback genérico
   const currencyWords = CURRENCIES[currencyCode] || {
     major: [currencyCode, currencyCode],
-    minor: DEFAULT_CURRENCY_WORDS.minor
+    minor: DEFAULT_CURRENCY_WORDS.minor,
   }
 
   let result = ''
@@ -519,7 +558,8 @@ function toCurrency (value, options) {
     // Ignora adicionar unidade de centavos se a moeda não os tiver (ex: JPY onde minor é string vazia)
     if (minorUnit === '') {
       result += minorText
-    } else {
+    }
+    else {
       result += minorText + ' ' + minorUnit
     }
   }

package/src/pt-PT.d.ts

@@ -1,14 +1,27 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [and] - Include "e" between euros and cents
+ */
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults: Required<CurrencyOptions>;
+export type CurrencyOptions = {
+    /**
+     * - Include "e" between euros and cents
+     */
+    and?: boolean | undefined;
+};
 /**
  * Converts a numeric value to Portuguese words.
  *
  * This is the main public API. It accepts any valid numeric input
  * (number, string, or bigint) and handles parsing internally.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Portuguese words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCardinal(21)           // 'vinte e um'
  * toCardinal(100)          // 'cem'
@@ -17,10 +30,8 @@
 export function toCardinal(value: number | string | bigint): string;
 /**
  * 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'
@@ -29,17 +40,12 @@ export function toCardinal(value: number | string | bigint): string;
 export function toOrdinal(value: number | string | bigint): string;
 /**
  * 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
+ * @param {CurrencyOptions} [options] Currency formatting options
  * @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'
  */
-export function toCurrency(value: number | string | bigint, options?: {
-    and?: boolean | undefined;
-}): string;
+export function toCurrency(value: number | string | bigint, options?: CurrencyOptions): string;