n2words 4.0.0 → 5.1.0

package/src/fi-FI.js

@@ -14,6 +14,8 @@
 import { parseCardinalValue } from './utils/parse-cardinal.js'
 import { parseCurrencyValue } from './utils/parse-currency.js'
 import { parseOrdinalValue } from './utils/parse-ordinal.js'
+import { checkMax } from './utils/check-max.js'
+import { western } from './utils/scale.js'
 
 // ============================================================================
 // Vocabulary (module-level constants)
@@ -36,6 +38,15 @@ const DECIMAL_SEP = 'pilkku'
 // Long scale
 const SCALES = ['miljoona', 'miljardi', 'biljoona', 'triljoona']
 
+// Supported magnitude ceiling (checked at the public entry points). SCALES is
+// indexed [scaleIndex - 2] (units and thousands separate), so the ceiling is
+// 10^((SCALES.length + 2) * 3) = 10^18. Ordinal (cardinal + suffix) and currency
+// build on the cardinal, so they share it. Decimals are read digit-by-digit
+// (no ceiling).
+export const cardinalMax = western(SCALES.length + 1)
+export const ordinalMax = western(SCALES.length + 1)
+export const currencyMax = western(SCALES.length + 1)
+
 // ============================================================================
 // Ordinal Vocabulary
 // ============================================================================
@@ -66,8 +77,10 @@ const CENT_SINGULAR = 'sentti'
 /**
  * Builds segment word for 0-999.
  * Omits "yksi" before "sata" (hundred).
+ * @param {number} n - Integer 0-999 to convert
+ * @returns {string} Finnish words for the segment
  */
-function buildSegment (n) {
+function buildSegment(n) {
   if (n === 0) return ''
 
   const ones = n % 10
@@ -80,7 +93,8 @@ function buildSegment (n) {
   if (hundreds > 0) {
     if (hundreds === 1) {
       parts.push(HUNDRED)
-    } else {
+    }
+    else {
       parts.push(ONES[hundreds] + ' ' + HUNDRED)
     }
   }
@@ -90,13 +104,17 @@ function buildSegment (n) {
 
   if (tensOnes === 0) {
     // Just hundreds
-  } else if (tensOnes < 10) {
+  }
+  else if (tensOnes < 10) {
     parts.push(ONES[ones])
-  } else if (tensOnes < 20) {
+  }
+  else if (tensOnes < 20) {
     parts.push(TEENS[ones])
-  } else if (ones === 0) {
+  }
+  else if (ones === 0) {
     parts.push(TENS[tens])
-  } else {
+  }
+  else {
     // Compound: "kaksikymmentäyksi" (no space)
     parts.push(TENS[tens] + ONES[ones])
   }
@@ -110,11 +128,10 @@ function buildSegment (n) {
 
 /**
  * Converts a non-negative integer to Finnish words.
- *
  * @param {bigint} n - Non-negative integer to convert
  * @returns {string} Finnish words
  */
-function integerToWords (n) {
+function integerToWords(n) {
   if (n === 0n) return ZERO
 
   // Fast path: numbers < 1000 (direct lookup)
@@ -131,7 +148,8 @@ function integerToWords (n) {
     let result
     if (thousands === 1) {
       result = THOUSAND
-    } else {
+    }
+    else {
       result = buildSegment(thousands) + ' ' + THOUSAND
     }
 
@@ -148,11 +166,10 @@ function integerToWords (n) {
 
 /**
  * Builds words for numbers >= 1,000,000.
- *
  * @param {bigint} n - Number >= 1,000,000
  * @returns {string} Finnish words
  */
-function buildLargeNumberWords (n) {
+function buildLargeNumberWords(n) {
   const numStr = n.toString()
   const len = numStr.length
 
@@ -184,14 +201,17 @@ function buildLargeNumberWords (n) {
       if (scaleIndex === 0) {
         // Units segment
         parts.push(segmentWord)
-      } else if (scaleIndex === 1) {
+      }
+      else if (scaleIndex === 1) {
         // Thousands - omit "yksi" before tuhat
         if (segment === 1) {
           parts.push(THOUSAND)
-        } else {
+        }
+        else {
           parts.push(segmentWord + ' ' + THOUSAND)
         }
-      } else {
+      }
+      else {
         // Millions+ - keep "yksi" before scale words
         const scaleWord = SCALES[scaleIndex - 2]
         parts.push(segmentWord + ' ' + scaleWord)
@@ -206,18 +226,18 @@ function buildLargeNumberWords (n) {
 
 /**
  * Converts decimal digits to Finnish words (per-digit).
- *
  * @param {string} decimalPart - Decimal digits (without the point)
  * @returns {string} Finnish words for decimal part
  */
-function decimalPartToWords (decimalPart) {
+function decimalPartToWords(decimalPart) {
   const parts = []
 
   for (const digit of decimalPart) {
     const d = parseInt(digit, 10)
     if (d === 0) {
       parts.push(ZERO)
-    } else {
+    }
+    else {
       parts.push(ONES[d])
     }
   }
@@ -227,19 +247,18 @@ function decimalPartToWords (decimalPart) {
 
 /**
  * Converts a numeric value to Finnish words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Finnish words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCardinal(21)       // 'kaksikymmentäyksi'
  * toCardinal(1000)     // 'tuhat'
  * toCardinal('3.14')   // 'kolme pilkku yksi neljä'
  */
-function toCardinal (value) {
+function toCardinal(value) {
   const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
+  checkMax(integerPart, cardinalMax)
 
   let result = ''
 
@@ -263,8 +282,10 @@ function toCardinal (value) {
 /**
  * Builds ordinal segment for 0-99.
  * Finnish ordinals have special forms.
+ * @param {number} n - Integer 0-99 to convert
+ * @returns {string} Finnish ordinal words for the segment
  */
-function buildOrdinalSegment (n) {
+function buildOrdinalSegment(n) {
   if (n === 0) return ''
   if (n < 10) return ORDINAL_ONES[n]
   if (n < 20) return ORDINAL_TEENS[n - 10]
@@ -286,11 +307,10 @@ function buildOrdinalSegment (n) {
  *
  * Finnish ordinals: ensimmäinen (1st), toinen (2nd), kolmas (3rd), etc.
  * For larger numbers, use cardinal + ordinal ending.
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Finnish ordinal words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   // Special cases
   if (n === 1n) return ORDINAL_FIRST
   if (n === 2n) return ORDINAL_SECOND
@@ -309,20 +329,19 @@ function integerToOrdinal (n) {
 
 /**
  * Converts a numeric value to Finnish ordinal words.
- *
  * @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)    // 'ensimmäinen'
  * toOrdinal(2)    // 'toinen'
  * toOrdinal(3)    // 'kolmas'
  * toOrdinal(10)   // 'kymmenes'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
+  checkMax(integerPart, ordinalMax)
   return integerToOrdinal(integerPart)
 }
 
@@ -335,19 +354,18 @@ function toOrdinal (value) {
  *
  * Euro uses sentti as subunit (100 senttiä = 1 euro).
  * Finnish has singular/plural: 1 euro vs 2 euroa, 1 sentti vs 2 senttiä.
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Finnish currency words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCurrency(1)      // 'yksi euro'
  * toCurrency(42)     // 'neljäkymmentäkaksi euroa'
  * toCurrency(1.50)   // 'yksi euro viisikymmentä senttiä'
  */
-function toCurrency (value) {
+function toCurrency(value) {
   const { isNegative, dollars: euros, cents } = parseCurrencyValue(value)
+  checkMax(euros, currencyMax)
 
   let result = ''
   if (isNegative) {

package/src/fil-PH.d.ts

@@ -1,18 +1,18 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
 /**
  * Converts a numeric value to Filipino words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Filipino words
  */
 export function toCardinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Filipino ordinal words.
- *
  * @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)    // 'una'
  * toOrdinal(2)    // 'ikalawa'
@@ -23,12 +23,10 @@ export function toOrdinal(value: number | string | bigint): string;
  * Converts a numeric value to Filipino currency words (Philippine Peso).
  *
  * Uses piso (peso) and sentimo (centavo).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Filipino 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)     // 'apatnapu dalawang piso'
  * toCurrency(1.50)   // 'isang piso at limampung sentimo'

package/src/fil-PH.js

@@ -13,6 +13,8 @@
 import { parseCardinalValue } from './utils/parse-cardinal.js'
 import { parseCurrencyValue } from './utils/parse-currency.js'
 import { parseOrdinalValue } from './utils/parse-ordinal.js'
+import { checkMax } from './utils/check-max.js'
+import { western } from './utils/scale.js'
 
 // ============================================================================
 // Vocabulary
@@ -33,6 +35,11 @@ const DECIMAL_SEP = 'punto'
 // Short scale with linker
 const SCALE_WORDS = ['', THOUSAND, 'milyong', 'bilyong', 'trilyong']
 
+// Supported magnitude ceiling (checked at the public entry points), derived from the scale table.
+export const cardinalMax = western(SCALE_WORDS.length - 1)
+export const ordinalMax = western(SCALE_WORDS.length - 1)
+export const currencyMax = western(SCALE_WORDS.length - 1)
+
 // ============================================================================
 // Ordinal Vocabulary
 // ============================================================================
@@ -42,7 +49,7 @@ const SCALE_WORDS = ['', THOUSAND, 'milyong', 'bilyong', 'trilyong']
 const ORDINAL_PREFIX = 'ika'
 const ORDINAL_SPECIAL = {
   1: 'una', // first
-  2: 'ikalawa' // second (contracted form)
+  2: 'ikalawa', // second (contracted form)
 }
 
 // ============================================================================
@@ -58,7 +65,11 @@ const SENTIMO = 'sentimo'
 
 const VOWELS = ['a', 'e', 'i', 'o', 'u']
 
-function addLinker (word) {
+/**
+ * @param {string} word - Word to append a linker to
+ * @returns {string} Word with "ng" or " na" linker appended
+ */
+function addLinker(word) {
   const lastChar = word[word.length - 1]
   if (VOWELS.includes(lastChar)) {
     return word + 'ng'
@@ -70,7 +81,11 @@ function addLinker (word) {
 // Segment Building
 // ============================================================================
 
-function buildSegment (n) {
+/**
+ * @param {number} n - Value 0-999 to convert to words
+ * @returns {string} Filipino words for the segment
+ */
+function buildSegment(n) {
   if (n === 0) return ''
 
   const ones = n % 10
@@ -90,21 +105,26 @@ function buildSegment (n) {
 
   if (tensOnes === 0) {
     // Just hundreds
-  } else if (tensOnes < 10) {
+  }
+  else if (tensOnes < 10) {
     // Single digit
     parts.push(ONES[ones])
-  } else if (tensOnes < 20) {
+  }
+  else if (tensOnes < 20) {
     // Teens (10-19)
     parts.push(TEENS[ones])
-  } else if (ones === 0) {
+  }
+  else if (ones === 0) {
     // Even tens (20, 30, 40, etc.)
     parts.push(TENS[tensDigit])
-  } else {
+  }
+  else {
     // Tens + ones
     // limampu (50) gets special linker: "limampung anim" (56)
     if (tensDigit === 5) {
       parts.push(TENS[tensDigit] + 'ng ' + ONES[ones])
-    } else {
+    }
+    else {
       parts.push(TENS[tensDigit] + ' ' + ONES[ones])
     }
   }
@@ -114,8 +134,10 @@ function buildSegment (n) {
 
 /**
  * Builds segment with linker added to last word (for use before scale words).
+ * @param {number} n - Value 0-999 to convert to words
+ * @returns {string} Filipino words with a trailing linker
  */
-function buildSegmentWithLinker (n) {
+function buildSegmentWithLinker(n) {
   const segmentWord = buildSegment(n)
   if (!segmentWord) return ''
 
@@ -144,7 +166,11 @@ function buildSegmentWithLinker (n) {
 // Conversion Functions
 // ============================================================================
 
-function integerToWords (n) {
+/**
+ * @param {bigint} n - Non-negative integer to convert to words
+ * @returns {string} Filipino words for the integer
+ */
+function integerToWords(n) {
   if (n === 0n) return ZERO
 
   if (n < 1000n) {
@@ -159,7 +185,7 @@ function integerToWords (n) {
  * @param {bigint} n - Number >= 1000
  * @returns {string} Filipino words
  */
-function buildLargeNumberWords (n) {
+function buildLargeNumberWords(n) {
   // Extract segments using BigInt division (faster than string slicing)
   const segmentValues = []
   let temp = n
@@ -181,7 +207,8 @@ function buildLargeNumberWords (n) {
 
     if (i === 0) {
       result += buildSegment(segment)
-    } else {
+    }
+    else {
       // Add linker to segment before scale word
       const segmentWord = buildSegmentWithLinker(segment)
       result += segmentWord + ' ' + scaleWord
@@ -191,7 +218,11 @@ function buildLargeNumberWords (n) {
   return result
 }
 
-function decimalPartToWords (decimalPart) {
+/**
+ * @param {string} decimalPart - Digits after the decimal separator
+ * @returns {string} Per-digit Filipino reading of the decimal part
+ */
+function decimalPartToWords(decimalPart) {
   // Per-digit decimal reading
   const digits = []
   for (const char of decimalPart) {
@@ -203,12 +234,12 @@ function decimalPartToWords (decimalPart) {
 
 /**
  * Converts a numeric value to Filipino words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Filipino words
  */
-function toCardinal (value) {
+function toCardinal(value) {
   const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
+  checkMax(integerPart, cardinalMax)
 
   let result = ''
 
@@ -233,11 +264,10 @@ function toCardinal (value) {
  * Converts a non-negative integer to Filipino ordinal words.
  *
  * Filipino ordinals: una (1st), ikalawa (2nd), then ika- + cardinal.
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Filipino ordinal words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   // Special forms for 1st and 2nd
   if (n === 1n) return ORDINAL_SPECIAL[1]
   if (n === 2n) return ORDINAL_SPECIAL[2]
@@ -248,19 +278,18 @@ function integerToOrdinal (n) {
 
 /**
  * Converts a numeric value to Filipino ordinal words.
- *
  * @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)    // 'una'
  * toOrdinal(2)    // 'ikalawa'
  * toOrdinal(3)    // 'ika-tatlo'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
+  checkMax(integerPart, ordinalMax)
   return integerToOrdinal(integerPart)
 }
 
@@ -272,19 +301,18 @@ function toOrdinal (value) {
  * Converts a numeric value to Filipino currency words (Philippine Peso).
  *
  * Uses piso (peso) and sentimo (centavo).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Filipino 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)     // 'apatnapu dalawang piso'
  * toCurrency(1.50)   // 'isang piso at limampung sentimo'
  * toCurrency(-5)     // 'negatibo limang piso'
  */
-function toCurrency (value) {
+function toCurrency(value) {
   const { isNegative, dollars: pesos, cents: sentimos } = parseCurrencyValue(value)
+  checkMax(pesos, currencyMax)
 
   let result = ''
   if (isNegative) {
@@ -297,18 +325,21 @@ function toCurrency (value) {
     const pesoWords = integerToWords(pesos)
     if (pesos === 0n) {
       result += pesoWords + ' ' + PESO
-    } else {
+    }
+    else {
       // Need to add linker to the last word before "piso"
       const lastSpaceIdx = pesoWords.lastIndexOf(' ')
       if (lastSpaceIdx === -1) {
         // Single word
         result += addLinker(pesoWords) + ' ' + PESO
-      } else {
+      }
+      else {
         const prefix = pesoWords.slice(0, lastSpaceIdx + 1)
         const lastWord = pesoWords.slice(lastSpaceIdx + 1)
         if (lastWord.endsWith('ng')) {
           result += pesoWords + ' ' + PESO
-        } else {
+        }
+        else {
           result += prefix + addLinker(lastWord) + ' ' + PESO
         }
       }
@@ -326,12 +357,14 @@ function toCurrency (value) {
     if (lastSpaceIdx === -1) {
       // Single word
       result += addLinker(sentimoWords) + ' ' + SENTIMO
-    } else {
+    }
+    else {
       const prefix = sentimoWords.slice(0, lastSpaceIdx + 1)
       const lastWord = sentimoWords.slice(lastSpaceIdx + 1)
       if (lastWord.endsWith('ng')) {
         result += sentimoWords + ' ' + SENTIMO
-      } else {
+      }
+      else {
         result += prefix + addLinker(lastWord) + ' ' + SENTIMO
       }
     }

package/src/fr-BE.d.ts

@@ -1,25 +1,46 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
+/**
+ * @typedef {object} CardinalOptions
+ * @property {boolean} [withHyphenSeparator] - Use hyphens between 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 words
+     */
+    withHyphenSeparator?: boolean | undefined;
+};
+export type CurrencyOptions = {
+    /**
+     * - Use "et" between euros and centimes
+     */
+    and?: boolean | undefined;
+};
 /**
  * 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
  */
-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 Belgian French ordinal words.
  *
  * 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'
@@ -29,14 +50,11 @@ export function toCardinal(value: number | string | bigint, options?: {
 export function toOrdinal(value: number | string | bigint): string;
 /**
  * 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'
@@ -44,6 +62,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;