n2words 5.0.0 → 5.1.0

package/src/fr-BE.js

@@ -13,7 +13,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 { longScale } from './utils/scale.js'
+import { resolveOptions } from './utils/resolve-options.js'
 
 // ============================================================================
 // Vocabulary
@@ -27,6 +29,15 @@ const TENS = ['', '', 'vingt', 'trente', 'quarante', 'cinquante', 'soixante', 's
 const SCALES = ['million', 'billion', 'trillion', 'quadrillion']
 const SCALES_ARD = ['milliard', 'billiard', 'trilliard', 'quadrilliard']
 
+// Supported magnitude ceiling (checked at the public entry points). Long scale:
+// each SCALES entry has a base and an "-ard" form spanning two segment groups,
+// so with the units group that's 2 * SCALES.length + 2 groups of 3 digits.
+// Cardinals must stay below 10^30; ordinals and currency build on the cardinal,
+// so they share the same ceiling.
+export const cardinalMax = longScale(SCALES.length)
+export const ordinalMax = longScale(SCALES.length)
+export const currencyMax = longScale(SCALES.length)
+
 const THOUSAND = 'mille'
 const HUNDRED = 'cent'
 const ZERO = 'zéro'
@@ -56,7 +67,12 @@ const CENTIMES = 'centimes'
 // Segment Building
 // ============================================================================
 
-function buildSegment (n) {
+/**
+ * Builds the words for a 0-999 segment.
+ * @param {number} n - Segment value (0-999)
+ * @returns {{word: string, endsWithCents: boolean, endsWithVingts: boolean}} Segment words and flags
+ */
+function buildSegment(n) {
   if (n === 0) return { word: '', endsWithCents: false, endsWithVingts: false }
 
   const tensOnes = n % 100
@@ -70,11 +86,13 @@ function buildSegment (n) {
   if (hundreds > 0) {
     if (hundreds === 1) {
       parts.push(HUNDRED)
-    } else {
+    }
+    else {
       if (tensOnes === 0) {
         parts.push(ONES[hundreds] + ' ' + HUNDRED + 's')
         endsWithCents = true
-      } else {
+      }
+      else {
         parts.push(ONES[hundreds] + ' ' + HUNDRED)
       }
     }
@@ -83,49 +101,63 @@ function buildSegment (n) {
   // Tens and ones - Belgian pattern
   if (tensOnes === 0) {
     // Just hundreds
-  } else if (tensOnes < 10) {
+  }
+  else if (tensOnes < 10) {
     parts.push(ONES[tensOnes])
-  } else if (tensOnes < 17) {
+  }
+  else if (tensOnes < 17) {
     parts.push(TEENS[tensOnes - 10])
-  } else if (tensOnes < 20) {
+  }
+  else if (tensOnes < 20) {
     parts.push(TEENS[tensOnes - 10])
-  } else if (tensOnes < 70) {
+  }
+  else if (tensOnes < 70) {
     // 20-69: standard pattern
     const t = Math.trunc(tensOnes / 10)
     const o = tensOnes % 10
     if (o === 0) {
       parts.push(TENS[t])
-    } else if (o === 1) {
+    }
+    else if (o === 1) {
       parts.push(TENS[t] + ' et ' + ONES[1])
-    } else {
+    }
+    else {
       parts.push(TENS[t] + '-' + ONES[o])
     }
-  } else if (tensOnes < 80) {
+  }
+  else if (tensOnes < 80) {
     // 70-79: septante pattern (Belgian)
     const o = tensOnes % 10
     if (o === 0) {
       parts.push('septante')
-    } else if (o === 1) {
+    }
+    else if (o === 1) {
       parts.push('septante et ' + ONES[1])
-    } else {
+    }
+    else {
       parts.push('septante-' + ONES[o])
     }
-  } else if (tensOnes === 80) {
+  }
+  else if (tensOnes === 80) {
     // 80: quatre-vingts (same as standard)
     parts.push('quatre-vingts')
     endsWithVingts = true
-  } else if (tensOnes < 90) {
+  }
+  else if (tensOnes < 90) {
     // 81-89: quatre-vingt-X (same as standard)
     const remainder = tensOnes - 80
     parts.push('quatre-vingt-' + ONES[remainder])
-  } else {
+  }
+  else {
     // 90-99: nonante pattern (Belgian)
     const o = tensOnes % 10
     if (o === 0) {
       parts.push('nonante')
-    } else if (o === 1) {
+    }
+    else if (o === 1) {
       parts.push('nonante et ' + ONES[1])
-    } else {
+    }
+    else {
       parts.push('nonante-' + ONES[o])
     }
   }
@@ -137,7 +169,13 @@ function buildSegment (n) {
 // Helper Functions
 // ============================================================================
 
-function getScaleWord (scaleIndex, segment) {
+/**
+ * Returns the scale word (mille, million, milliard, ...) for a scale index.
+ * @param {number} scaleIndex - Scale group index
+ * @param {bigint} segment - Segment value used to decide pluralization
+ * @returns {string} The scale word
+ */
+function getScaleWord(scaleIndex, segment) {
   if (scaleIndex === 1) return THOUSAND
 
   if (scaleIndex % 2 === 0) {
@@ -145,7 +183,8 @@ function getScaleWord (scaleIndex, segment) {
     const baseWord = SCALES[arrayIndex]
     if (!baseWord) return ''
     return segment > 1n ? baseWord + 's' : baseWord
-  } else {
+  }
+  else {
     const arrayIndex = ((scaleIndex - 1) / 2) - 1
     const ardWord = SCALES_ARD[arrayIndex]
     if (!ardWord) return THOUSAND
@@ -157,7 +196,13 @@ function getScaleWord (scaleIndex, segment) {
 // Conversion Functions
 // ============================================================================
 
-function integerToWords (n, withHyphen = false) {
+/**
+ * Converts a non-negative integer to Belgian French cardinal words.
+ * @param {bigint} n - Non-negative integer
+ * @param {boolean} [withHyphen] - Use hyphens between words
+ * @returns {string} The integer in Belgian French words
+ */
+function integerToWords(n, withHyphen = false) {
   if (n === 0n) return ZERO
 
   if (n < 1000n) {
@@ -172,7 +217,8 @@ function integerToWords (n, withHyphen = false) {
     let result
     if (thousands === 1) {
       result = THOUSAND
-    } else {
+    }
+    else {
       const { word: thousandsWord, endsWithCents, endsWithVingts } = buildSegment(thousands)
       let adjustedWord = thousandsWord
       if (endsWithCents || endsWithVingts) {
@@ -196,7 +242,13 @@ function integerToWords (n, withHyphen = false) {
   return buildLargeNumberWords(n, withHyphen)
 }
 
-function buildLargeNumberWords (n, withHyphen) {
+/**
+ * Builds words for large integers (>= 1,000,000) using scale groups.
+ * @param {bigint} n - Integer value (>= 1,000,000)
+ * @param {boolean} withHyphen - Use hyphens between words
+ * @returns {string} The integer in Belgian French words
+ */
+function buildLargeNumberWords(n, withHyphen) {
   const numStr = n.toString()
   const len = numStr.length
 
@@ -226,10 +278,12 @@ function buildLargeNumberWords (n, withHyphen) {
 
       if (scaleIndex === 0) {
         parts.push(segWords)
-      } else if (scaleIndex === 1) {
+      }
+      else if (scaleIndex === 1) {
         if (segment === 1) {
           parts.push(THOUSAND)
-        } else {
+        }
+        else {
           let adjustedWord = segWords
           if (endsWithCents || endsWithVingts) {
             adjustedWord = segWords.slice(0, -1)
@@ -237,7 +291,8 @@ function buildLargeNumberWords (n, withHyphen) {
           parts.push(adjustedWord)
           parts.push(scaleWord)
         }
-      } else {
+      }
+      else {
         parts.push(segWords)
         parts.push(scaleWord)
       }
@@ -256,7 +311,13 @@ function buildLargeNumberWords (n, withHyphen) {
   return result
 }
 
-function decimalPartToWords (decimalPart, withHyphen) {
+/**
+ * Converts the decimal part digits to words (leading zeros spoken as zéro).
+ * @param {string} decimalPart - Decimal digits as a string
+ * @param {boolean} withHyphen - Use hyphens between words
+ * @returns {string} The decimal part in Belgian French words
+ */
+function decimalPartToWords(decimalPart, withHyphen) {
   let result = ''
   const sep = withHyphen ? '-' : ' '
 
@@ -276,20 +337,28 @@ function decimalPartToWords (decimalPart, withHyphen) {
   return result
 }
 
+/**
+ * @typedef {object} CardinalOptions
+ * @property {boolean} [withHyphenSeparator] - Use hyphens between words
+ */
+
+/** @type {Required<CardinalOptions>} */
+export const cardinalDefaults = { withHyphenSeparator: false }
+
 /**
  * Converts a numeric value to Belgian French words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
- * @param {Object} [options] - Optional configuration
- * @param {boolean} [options.withHyphenSeparator=false] - Use hyphens between words
+ * @param {CardinalOptions} [options] - Optional configuration
  * @returns {string} The number in Belgian French words
  */
-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 { withHyphenSeparator = false } = options
+  const { withHyphenSeparator } = resolveOptions(options, cardinalDefaults)
 
   let result = ''
   const sep = withHyphenSeparator ? '-' : ' '
@@ -318,11 +387,10 @@ function toCardinal (value, options) {
  * - Drop final -e before adding -ième (quatre → quatrième)
  * - cinq → cinquième (add -u- before -ième)
  * - neuf → neuvième (f → v before -ième)
- *
  * @param {string} cardinalWord - Cardinal word to convert
  * @returns {string} Ordinal form
  */
-function cardinalToOrdinal (cardinalWord) {
+function cardinalToOrdinal(cardinalWord) {
   // Handle special endings
   if (cardinalWord.endsWith('cinq')) {
     // cinq → cinquième (add 'u')
@@ -336,16 +404,16 @@ function cardinalToOrdinal (cardinalWord) {
 
   // Drop plural -s from cents/vingts/millions/etc. (quatre-vingts → quatre-vingtième)
   // Note: "trois", "six" also end in s but that's not a plural
-  if (cardinalWord.endsWith('cents') ||
-      cardinalWord.endsWith('vingts') ||
-      cardinalWord.endsWith('millions') ||
-      cardinalWord.endsWith('milliards') ||
-      cardinalWord.endsWith('billions') ||
-      cardinalWord.endsWith('billiards') ||
-      cardinalWord.endsWith('trillions') ||
-      cardinalWord.endsWith('trilliards') ||
-      cardinalWord.endsWith('quadrillions') ||
-      cardinalWord.endsWith('quadrilliards')) {
+  if (cardinalWord.endsWith('cents')
+    || cardinalWord.endsWith('vingts')
+    || cardinalWord.endsWith('millions')
+    || cardinalWord.endsWith('milliards')
+    || cardinalWord.endsWith('billions')
+    || cardinalWord.endsWith('billiards')
+    || cardinalWord.endsWith('trillions')
+    || cardinalWord.endsWith('trilliards')
+    || cardinalWord.endsWith('quadrillions')
+    || cardinalWord.endsWith('quadrilliards')) {
     return cardinalWord.slice(0, -1) + ORDINAL_SUFFIX
   }
 
@@ -360,11 +428,10 @@ function cardinalToOrdinal (cardinalWord) {
 
 /**
  * Converts a positive integer to Belgian French ordinal words.
- *
  * @param {bigint} n - Positive integer
  * @returns {string} Belgian French ordinal words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   // Special case: 1 → premier
   if (n === 1n) {
     return PREMIER
@@ -380,20 +447,19 @@ function integerToOrdinal (n) {
  *
  * Belgian French ordinals: premier (1st), then cardinal + ième.
  * Special rules: quatre→quatrième, cinq→cinquième, neuf→neuvième.
- *
  * @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)    // 'premier'
  * toOrdinal(2)    // 'deuxième'
  * toOrdinal(70)   // 'septantième'
  * toOrdinal(90)   // 'nonantième'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
+  checkMax(integerPart, ordinalMax)
   return integerToOrdinal(integerPart)
 }
 
@@ -401,16 +467,21 @@ function toOrdinal (value) {
 // CURRENCY: toCurrency(value, options?)
 // ============================================================================
 
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [and] - Use "et" between euros and centimes
+ */
+
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults = { and: true }
+
 /**
  * Converts a numeric value to Belgian French currency words (Euro).
- *
  * @param {number | string | bigint} value - The currency amount to convert
- * @param {Object} [options] - Optional configuration
- * @param {boolean} [options.and=true] - Use "et" between euros and centimes
+ * @param {CurrencyOptions} [options] - Optional configuration
  * @returns {string} The amount in Belgian French 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)                 // 'quarante-deux euros et cinquante centimes'
  * toCurrency(1)                     // 'un euro'
@@ -418,10 +489,10 @@ function toOrdinal (value) {
  * toCurrency(0.01)                  // 'un centime'
  * toCurrency(42.50, { and: false }) // 'quarante-deux euros cinquante centimes'
  */
-function toCurrency (value, options) {
-  options = validateOptions(options)
+function toCurrency(value, options) {
   const { isNegative, dollars: euros, cents: centimes } = parseCurrencyValue(value)
-  const { and: useAnd = true } = options
+  checkMax(euros, currencyMax)
+  const { and: useAnd } = resolveOptions(options, currencyDefaults)
 
   // Build result
   let result = ''

package/src/fr-FR.d.ts

@@ -1,35 +1,55 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
+/**
+ * @typedef {object} CardinalOptions
+ * @property {boolean} [withHyphenSeparator] - Use hyphens between all words
+ */
+/** @type {Required<CardinalOptions>} */
+export const cardinalDefaults: Required<CardinalOptions>;
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [and] - Use "et" between euros and centimes
+ */
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults: Required<CurrencyOptions>;
+export type CardinalOptions = {
+    /**
+     * - Use hyphens between all words
+     */
+    withHyphenSeparator?: boolean | undefined;
+};
+export type CurrencyOptions = {
+    /**
+     * - Use "et" between euros and centimes
+     */
+    and?: boolean | undefined;
+};
 /**
  * Converts a numeric value to French 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
- * @param {Object} [options] - Optional configuration
- * @param {boolean} [options.withHyphenSeparator=false] - Use hyphens between all words
+ * @param {CardinalOptions} [options] - Optional configuration
  * @returns {string} The number in French words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCardinal(21)           // 'vingt et un'
  * toCardinal(80)           // 'quatre-vingts'
  * toCardinal(1000000)      // 'un million'
  */
-export function toCardinal(value: number | string | bigint, options?: {
-    withHyphenSeparator?: boolean | undefined;
-}): string;
+export function toCardinal(value: number | string | bigint, options?: CardinalOptions): string;
 /**
  * Converts a numeric value to French ordinal words.
  *
  * French ordinals: premier (1st), then cardinal + ième.
  * Special rules: quatre→quatrième, cinq→cinquième, neuf→neuvième.
- *
  * @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)    // 'premier'
  * toOrdinal(2)    // 'deuxième'
@@ -43,14 +63,11 @@ export function toCardinal(value: number | string | bigint, options?: {
 export function toOrdinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to French currency words (Euro).
- *
  * @param {number | string | bigint} value - The currency amount to convert
- * @param {Object} [options] - Optional configuration
- * @param {boolean} [options.and=true] - Use "et" between euros and centimes
+ * @param {CurrencyOptions} [options] - Optional configuration
  * @returns {string} The amount in French 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)                 // 'quarante-deux euros et cinquante centimes'
  * toCurrency(1)                     // 'un euro'
@@ -58,6 +75,4 @@ export function toOrdinal(value: number | string | bigint): string;
  * toCurrency(0.01)                  // 'un centime'
  * toCurrency(42.50, { and: false }) // 'quarante-deux euros cinquante centimes'
  */
-export function toCurrency(value: number | string | bigint, options?: {
-    and?: boolean | undefined;
-}): string;
+export function toCurrency(value: number | string | bigint, options?: CurrencyOptions): string;