n2words 4.0.0 → 5.1.0

package/src/pt-PT.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)
@@ -51,8 +53,10 @@ const CENTIMOS = 'cêntimos'
 /**
  * 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 "e"/"cem" handling flags
  */
-function buildSegment (n) {
+function buildSegment(n) {
   if (n === 0) return { word: '', isExactHundred: false }
 
   // Special case: exact 100 is "cem"
@@ -73,14 +77,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])
   }
 
@@ -105,7 +112,7 @@ const SCALE_WORDS_SINGULAR = [
   'mil biliões', // 5: 10^15 (compound)
   'trilião', // 6: 10^18
   'mil triliões', // 7: 10^21 (compound)
-  'quatrilião' // 8: 10^24
+  'quatrilião', // 8: 10^24
 ]
 
 const SCALE_WORDS_PLURAL = [
@@ -117,20 +124,32 @@ const SCALE_WORDS_PLURAL = [
   'mil biliões', // 5: 10^15 (compound, same)
   'triliões', // 6: 10^18
   'mil triliões', // 7: 10^21 (compound, same)
-  'quatriliões' // 8: 10^24
+  'quatriliões', // 8: 10^24
 ]
 
+// Scale ordinal words (long scale for pt-PT). 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', 'mil milionésimo', 'bilionésimo', 'mil bilionésimo', 'trilionésimo']
+
+// Supported magnitude ceilings (checked at the public entry points). Cardinal
+// scale words reach index SCALE_WORDS_SINGULAR.length-1 (quatriliã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
@@ -147,7 +166,8 @@ function integerToWords (n) {
     if (thousands === 1) {
       // "mil" not "um mil"
       result = THOUSAND
-    } else {
+    }
+    else {
       result = buildSegment(thousands).word + ' ' + THOUSAND
     }
 
@@ -156,7 +176,8 @@ function integerToWords (n) {
       // Insert "e" before remainder if it doesn't start with hundreds (< 100)
       if (!remainderResult.startsWithHundreds) {
         result += ' e ' + remainderResult.word
-      } else {
+      }
+      else {
         result += ' ' + remainderResult.word
       }
     }
@@ -171,11 +192,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
   // Segments stored least-significant first (index 0 = ones, 1 = thousands, etc.)
   const segments = []
@@ -216,20 +236,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 - use scale arrays
       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
@@ -241,11 +265,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
@@ -271,19 +294,20 @@ function decimalPartToWords (decimalPart) {
  *
  * 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'
  * toCardinal(1000000)      // 'um milhão'
  */
-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 = ''
 
@@ -306,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
@@ -328,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])
   }
 
@@ -342,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
@@ -364,9 +388,6 @@ function buildLargeOrdinal (n) {
     }
   }
 
-  // Scale ordinal words (singular forms)
-  const SCALE_ORDINAL = ['', 'milésimo', 'milionésimo', 'mil milionésimo', 'bilionésimo', 'mil bilionésimo', 'trilionésimo']
-
   let result = ''
 
   for (let i = segments.length - 1; i >= 0; i--) {
@@ -380,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
         }
       }
@@ -413,17 +441,16 @@ function buildLargeOrdinal (n) {
 
 /**
  * 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'
  * toOrdinal(100)   // 'centésimo'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const n = parseOrdinalValue(value)
+  checkMax(n, ordinalMax)
 
   // Fast path: 1-9
   if (n < 10n) {
@@ -458,23 +485,28 @@ function toOrdinal (value) {
 // Currency Functions
 // ============================================================================
 
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [and] - Include "e" between euros and cents
+ */
+
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults = { and: true }
+
 /**
  * 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'
  */
-function toCurrency (value, options) {
-  options = validateOptions(options)
+function toCurrency(value, options) {
   const { isNegative, dollars: euros, cents } = parseCurrencyValue(value)
-  const { and = true } = options
+  checkMax(euros, currencyMax)
+  const { and } = resolveOptions(options, currencyDefaults)
 
   let result = ''
 

package/src/ro-RO.d.ts

@@ -1,29 +1,41 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
+/**
+ * @typedef {object} CardinalOptions
+ * @property {('masculine'|'feminine')} [gender] - Gender for numbers
+ */
+/** @type {Required<CardinalOptions>} */
+export const cardinalDefaults: Required<CardinalOptions>;
+/** @type {{ gender: ReadonlyArray<Required<CardinalOptions>['gender']> }} */
+export const cardinalValues: {
+    gender: ReadonlyArray<Required<CardinalOptions>["gender"]>;
+};
+export type CardinalOptions = {
+    /**
+     * - Gender for numbers
+     */
+    gender?: "feminine" | "masculine" | undefined;
+};
 /**
  * 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'
  */
-export function toCardinal(value: number | string | bigint, options?: {
-    gender?: string | undefined;
-}): string;
+export function toCardinal(value: number | string | bigint, options?: CardinalOptions): string;
 /**
  * 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'
@@ -31,12 +43,10 @@ export function toCardinal(value: number | string | bigint, options?: {
 export function toOrdinal(value: number | string | bigint): string;
 /**
  * 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'