n2words 4.0.0 → 5.1.0

package/src/lv-LV.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)
@@ -72,9 +74,18 @@ const SCALE_FORMS = [
   ['kvintiljons', 'kvintiljoni', 'kvintiljonu'],
   ['sikstiljons', 'sikstiljoni', 'sikstiljonu'],
   ['septiljons', 'septiljoni', 'septiljonu'],
-  ['oktiljons', 'oktiljoni', 'oktiljonu']
+  ['oktiljons', 'oktiljoni', 'oktiljonu'],
 ]
 
+// Supported magnitude ceilings (checked at the public entry points). Both
+// tables are indexed [scaleIndex - 1] (units separate), so the cardinal/
+// currency ceiling is 10^((SCALE_FORMS.length + 1) * 3) = 10^30, and the
+// shorter ORDINAL_SCALES bounds ordinals at 10^((ORDINAL_SCALES.length + 1) *
+// 3) = 10^15.
+export const cardinalMax = western(SCALE_FORMS.length)
+export const ordinalMax = western(ORDINAL_SCALES.length)
+export const currencyMax = western(SCALE_FORMS.length)
+
 // ============================================================================
 // Segment Building
 // ============================================================================
@@ -83,8 +94,10 @@ const SCALE_FORMS = [
  * Builds segment word for 0-999 (masculine form).
  * Does NOT include special handling for segment=1 (omitOneBeforeScale).
  * That's handled at join time.
+ * @param {number} n - Segment value 0-999
+ * @returns {string} The segment in Latvian words
  */
-function buildSegment (n) {
+function buildSegment(n) {
   if (n === 0) return ''
 
   const ones = n % 10
@@ -98,11 +111,13 @@ function buildSegment (n) {
     if (hundreds === 1 && tens === 0 && ones > 0) {
       // 101-109: use genitive form "simtu"
       parts.push(HUNDRED_GENITIVE)
-    } else if (hundreds > 1) {
+    }
+    else if (hundreds > 1) {
       // 200-999: use plural "simti"
       parts.push(ONES_MASC[hundreds])
       parts.push(HUNDRED_PLURAL)
-    } else {
+    }
+    else {
       // 100, 110-199: use singular "simts"
       parts.push(HUNDRED_SINGULAR)
     }
@@ -116,7 +131,8 @@ function buildSegment (n) {
   // Teens or ones
   if (tens === 1) {
     parts.push(TEENS[ones])
-  } else if (ones > 0) {
+  }
+  else if (ones > 0) {
     parts.push(ONES_MASC[ones])
   }
 
@@ -125,8 +141,10 @@ function buildSegment (n) {
 
 /**
  * Builds segment word for 0-999 (feminine form - only differs in ones).
+ * @param {number} n - Segment value 0-999
+ * @returns {string} The segment in Latvian words
  */
-function buildSegmentFeminine (n) {
+function buildSegmentFeminine(n) {
   if (n === 0) return ''
 
   const ones = n % 10
@@ -139,10 +157,12 @@ function buildSegmentFeminine (n) {
   if (hundreds > 0) {
     if (hundreds === 1 && tens === 0 && ones > 0) {
       parts.push(HUNDRED_GENITIVE)
-    } else if (hundreds > 1) {
+    }
+    else if (hundreds > 1) {
       parts.push(ONES_MASC[hundreds])
       parts.push(HUNDRED_PLURAL)
-    } else {
+    }
+    else {
       parts.push(HUNDRED_SINGULAR)
     }
   }
@@ -155,7 +175,8 @@ function buildSegmentFeminine (n) {
   // Teens or ones - feminine for ones only
   if (tens === 1) {
     parts.push(TEENS[ones])
-  } else if (ones > 0) {
+  }
+  else if (ones > 0) {
     parts.push(ONES_FEM[ones])
   }
 
@@ -170,12 +191,11 @@ function buildSegmentFeminine (n) {
  * Latvian pluralization - simpler than Slavic.
  * Singular: ends in 1 (except 11)
  * Plural: everything else
- *
  * @param {number} n - The segment value
  * @param {string[]} forms - [singular, plural, genitive]
  * @returns {string} The appropriate form
  */
-function pluralize (n, forms) {
+function pluralize(n, forms) {
   if (n === 0) return forms[2]
 
   const lastDigit = n % 10
@@ -191,12 +211,11 @@ function pluralize (n, forms) {
 /**
  * Latvian currency pluralization.
  * Uses genitive for 0, 10-19, and multiples of 10.
- *
  * @param {number} n - The segment value
  * @param {string[]} forms - [singular, plural, genitive]
  * @returns {string} The appropriate form
  */
-function pluralizeCurrency (n, forms) {
+function pluralizeCurrency(n, forms) {
   if (n === 0) return forms[2]
 
   const lastDigit = n % 10
@@ -227,12 +246,11 @@ function pluralizeCurrency (n, forms) {
 
 /**
  * Converts a non-negative integer to Latvian words.
- *
  * @param {bigint} n - Non-negative integer to convert
- * @param {Object} options - Conversion options
+ * @param {string} gender - Gender for numbers < 1000
  * @returns {string} Latvian words
  */
-function integerToWords (n, gender) {
+function integerToWords(n, gender) {
   if (n === 0n) return ZERO
 
   // Fast path: numbers < 1000
@@ -243,17 +261,15 @@ function integerToWords (n, gender) {
 
   // For numbers >= 1000, feminine only applies to final segment if < 1000
   // But we use masculine for all segments when n >= 1000
-  return buildLargeNumberWords(n, gender)
+  return buildLargeNumberWords(n)
 }
 
 /**
  * Builds words for numbers >= 1000.
- *
  * @param {bigint} n - Number >= 1000
- * @param {Object} options - Conversion options
  * @returns {string} Latvian words
  */
-function buildLargeNumberWords (n, gender) {
+function buildLargeNumberWords(n) {
   const numStr = n.toString()
   const len = numStr.length
 
@@ -285,7 +301,8 @@ function buildLargeNumberWords (n, gender) {
       if (scaleIndex === 0) {
         // Units segment - use masculine (feminine doesn't apply when n >= 1000)
         parts.push(segmentWord)
-      } else {
+      }
+      else {
         // Segment with scale word
         const scaleForms = SCALE_FORMS[scaleIndex - 1]
         const scaleWord = pluralize(segment, scaleForms)
@@ -293,7 +310,8 @@ function buildLargeNumberWords (n, gender) {
         // Latvian omits "one" before scale words
         if (segment === 1) {
           parts.push(scaleWord)
-        } else {
+        }
+        else {
           parts.push(segmentWord + ' ' + scaleWord)
         }
       }
@@ -307,12 +325,11 @@ function buildLargeNumberWords (n, gender) {
 
 /**
  * Converts decimal digits to Latvian words.
- *
  * @param {string} decimalPart - Decimal digits (without the point)
- * @param {Object} options - Conversion options
+ * @param {string} gender - Gender for numbers < 1000
  * @returns {string} Latvian words for decimal part
  */
-function decimalPartToWords (decimalPart, gender) {
+function decimalPartToWords(decimalPart, gender) {
   let result = ''
 
   // Handle leading zeros
@@ -333,27 +350,37 @@ function decimalPartToWords (decimalPart, gender) {
   return result
 }
 
+/**
+ * @typedef {object} CardinalOptions
+ * @property {('masculine'|'feminine')} [gender] - Gender for numbers < 1000
+ */
+
+/** @type {Required<CardinalOptions>} */
+export const cardinalDefaults = { gender: 'masculine' }
+
+/** @type {{ gender: ReadonlyArray<Required<CardinalOptions>['gender']> }} */
+export const cardinalValues = { gender: ['masculine', 'feminine'] }
+
 /**
  * Converts a numeric value to Latvian words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
- * @param {Object} [options] - Conversion options
- * @param {string} [options.gender='masculine'] - Gender for numbers < 1000
+ * @param {CardinalOptions} [options] - Conversion options
  * @returns {string} The number in Latvian words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCardinal(42)                          // 'četrdesmit divi'
  * toCardinal(1, { gender: 'feminine' })   // 'viena'
  * toCardinal(1000)                        // 'tūkstotis'
  */
-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 { gender = 'masculine' } = options
+  const { gender } = resolveOptions(options, cardinalDefaults, cardinalValues)
 
   let result = ''
 
@@ -376,11 +403,10 @@ function toCardinal (value, options) {
 
 /**
  * Builds ordinal for a 0-99 segment when it's the final (ordinal) part.
- *
  * @param {number} n - Number 0-99
  * @returns {string} Ordinal words
  */
-function buildOrdinalTensOnes (n) {
+function buildOrdinalTensOnes(n) {
   if (n === 0) return ''
 
   const onesDigit = n % 10
@@ -403,11 +429,10 @@ function buildOrdinalTensOnes (n) {
 
 /**
  * Converts a positive integer to Latvian ordinal words (masculine nominative).
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Ordinal Latvian words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   if (n < 100n) {
     return buildOrdinalTensOnes(Number(n))
   }
@@ -425,7 +450,8 @@ function integerToOrdinal (n) {
     let hundredWord
     if (hundredsDigit === 1) {
       hundredWord = HUNDRED_SINGULAR
-    } else {
+    }
+    else {
       hundredWord = ONES_MASC[hundredsDigit] + ' ' + HUNDRED_PLURAL
     }
     return hundredWord + ' ' + buildOrdinalTensOnes(remainder)
@@ -454,11 +480,10 @@ function integerToOrdinal (n) {
 
 /**
  * Builds ordinal words for numbers >= 1,000,000.
- *
  * @param {bigint} n - Number >= 1,000,000
  * @returns {string} Ordinal Latvian words
  */
-function buildLargeOrdinal (n) {
+function buildLargeOrdinal(n) {
   const numStr = n.toString()
   const len = numStr.length
 
@@ -493,25 +518,30 @@ function buildLargeOrdinal (n) {
       if (scaleIndex === 0) {
         if (isLastNonZero) {
           parts.push(integerToOrdinal(BigInt(segment)))
-        } else {
+        }
+        else {
           parts.push(buildSegment(segment))
         }
-      } else {
+      }
+      else {
         if (isLastNonZero) {
           if (segment === 1) {
             parts.push(ORDINAL_SCALES[scaleIndex - 1])
-          } else {
+          }
+          else {
             // For 2+, include cardinal scale word before ordinal
             const scaleForms = SCALE_FORMS[scaleIndex - 1]
             const cardinalScaleWord = pluralize(segment, scaleForms)
             parts.push(buildSegment(segment) + ' ' + cardinalScaleWord + ' ' + ORDINAL_SCALES[scaleIndex - 1])
           }
-        } else {
+        }
+        else {
           const scaleForms = SCALE_FORMS[scaleIndex - 1]
           const scaleWord = pluralize(segment, scaleForms)
           if (segment === 1) {
             parts.push(scaleWord)
-          } else {
+          }
+          else {
             parts.push(buildSegment(segment) + ' ' + scaleWord)
           }
         }
@@ -526,12 +556,10 @@ function buildLargeOrdinal (n) {
 
 /**
  * Converts a numeric value to Latvian ordinal words (masculine nominative).
- *
  * @param {number | string | bigint} value - The numeric value to convert (must be a 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)    // 'pirmais'
  * toOrdinal(2)    // 'otrais'
@@ -539,8 +567,9 @@ function buildLargeOrdinal (n) {
  * toOrdinal(100)  // 'simtais'
  * toOrdinal(1000) // 'tūkstošais'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
+  checkMax(integerPart, ordinalMax)
   return integerToOrdinal(integerPart)
 }
 
@@ -550,20 +579,19 @@ function toOrdinal (value) {
 
 /**
  * Converts a numeric value to Latvian currency words (Euro).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Latvian 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)     // 'četrdesmit divi eiro'
  * toCurrency(1)      // 'viens eiro'
  * toCurrency(1.50)   // 'viens eiro piecdesmit centu'
  * toCurrency(-5)     // 'mīnus pieci eiro'
  */
-function toCurrency (value) {
+function toCurrency(value) {
   const { isNegative, dollars: euros, cents } = parseCurrencyValue(value)
+  checkMax(euros, currencyMax)
 
   let result = ''
   if (isNegative) {

package/src/mr-IN.d.ts

@@ -1,18 +1,18 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
 /**
  * Converts a numeric value to Marathi words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Marathi words
  */
 export function toCardinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Marathi 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)    // 'पहिला'
  * toOrdinal(2)    // 'दुसरा'
@@ -22,12 +22,10 @@ export function toCardinal(value: number | string | bigint): string;
 export function toOrdinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Marathi currency words (Indian Rupee).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Marathi 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)  // 'बेचाळीस रुपये पन्नास पैसे'
  * toCurrency(1)      // 'एक रुपया'

package/src/mr-IN.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 { indian } from './utils/scale.js'
 
 // ============================================================================
 // Vocabulary
@@ -56,20 +58,29 @@ const BELOW_HUNDRED = [
   'साठ', 'एकसष्ठ', 'बासष्ठ', 'त्रेसष्ठ', 'चौसष्ठ', 'पासष्ठ', 'सहासष्ठ', 'सदुसष्ठ', 'अडुसष्ठ', 'एकोणसत्तर',
   'सत्तर', 'एकाहत्तर', 'बाहत्तर', 'त्र्याहत्तर', 'चौऱ्याहत्तर', 'पंच्याहत्तर', 'शहात्तर', 'सत्याहत्तर', 'अठ्ठ्याहत्तर', 'एकोणऐंशी',
   'ऐंशी', 'एक्याऐंशी', 'ब्याऐंशी', 'त्र्याऐंशी', 'चौऱ्याऐंशी', 'पंच्याऐंशी', 'शहाऐंशी', 'सत्याऐंशी', 'अठ्ठ्याऐंशी', 'एकोणनव्वद',
-  'नव्वद', 'एक्याण्णव', 'ब्याण्णव', 'त्र्याण्णव', 'चौऱ्याण्णव', 'पंच्याण्णव', 'शहाण्णव', 'सत्याण्णव', 'अठ्ठ्याण्णव', 'नव्याण्णव'
+  'नव्वद', 'एक्याण्णव', 'ब्याण्णव', 'त्र्याण्णव', 'चौऱ्याण्णव', 'पंच्याण्णव', 'शहाण्णव', 'सत्याण्णव', 'अठ्ठ्याण्णव', 'नव्याण्णव',
 ]
 
 // Scale words: index 0 = units (empty), 1 = thousand, 2 = lakh, 3 = crore, etc.
 const SCALE_WORDS = ['', 'हजार', 'लाख', 'कोटी', 'अब्ज', 'खर्व', 'निखर्व', 'महापद्म', 'शंकू']
 
+// 3-2-2 Indian grouping: a 3-digit base segment, then 2 digits per scale word
+// (SCALE_WORDS[0] = '' is the units slot). Past the table the scale word is
+// dropped, which collapses the magnitude — so cap there.
+export const cardinalMax = indian(SCALE_WORDS.length)
+export const ordinalMax = indian(SCALE_WORDS.length)
+export const currencyMax = indian(SCALE_WORDS.length)
+
 // ============================================================================
 // Segment Building
 // ============================================================================
 
 /**
  * Builds words for a 0-999 segment.
+ * @param {number} n - Segment value (0-999)
+ * @returns {string} Marathi words for the segment
  */
-function buildSegment (n) {
+function buildSegment(n) {
   if (n === 0) return ''
   if (n < 100) return BELOW_HUNDRED[n]
 
@@ -91,11 +102,10 @@ function buildSegment (n) {
  *
  * Uses BigInt modulo for segment extraction (faster than string slicing).
  * South Asian 3-2-2 grouping: first 3 digits, then groups of 2.
- *
  * @param {bigint} n - Non-negative integer to convert
  * @returns {string} Marathi words
  */
-function integerToWords (n) {
+function integerToWords(n) {
   if (n === 0n) return ZERO
 
   // Fast path: numbers < 1000 (direct lookup)
@@ -121,7 +131,8 @@ function integerToWords (n) {
 
     if (i === 0) {
       words.push(buildSegment(segment))
-    } else {
+    }
+    else {
       words.push(BELOW_HUNDRED[segment])
     }
 
@@ -133,7 +144,12 @@ function integerToWords (n) {
   return words.join(' ')
 }
 
-function decimalPartToWords (decimalPart) {
+/**
+ * Reads the fractional digits per-digit in Marathi.
+ * @param {string} decimalPart - Decimal digit string
+ * @returns {string} Marathi words for each digit
+ */
+function decimalPartToWords(decimalPart) {
   // Per-digit decimal reading
   const digits = []
   for (const char of decimalPart) {
@@ -145,12 +161,13 @@ function decimalPartToWords (decimalPart) {
 
 /**
  * Converts a numeric value to Marathi words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Marathi words
  */
-function toCardinal (value) {
+function toCardinal(value) {
   const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
+  // The fraction is spelled digit by digit, so only the integer part has a ceiling.
+  checkMax(integerPart, cardinalMax)
 
   let result = ''
 
@@ -175,11 +192,10 @@ function toCardinal (value) {
  * Converts a positive integer to Marathi ordinal words.
  *
  * Marathi ordinals: First 6 are irregular, then add -वा suffix.
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Marathi ordinal words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   // Special ordinals for 1-6
   if (n >= 1n && n <= 6n) {
     return ORDINAL_SPECIAL[Number(n)]
@@ -192,20 +208,20 @@ function integerToOrdinal (n) {
 
 /**
  * Converts a numeric value to Marathi 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)    // 'पहिला'
  * toOrdinal(2)    // 'दुसरा'
  * toOrdinal(3)    // 'तिसरा'
  * toOrdinal(10)   // 'दहावा'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
+  // Ordinals build on the cardinal speller, so they share its ceiling.
+  checkMax(integerPart, ordinalMax)
   return integerToOrdinal(integerPart)
 }
 
@@ -215,19 +231,18 @@ function toOrdinal (value) {
 
 /**
  * Converts a numeric value to Marathi currency words (Indian Rupee).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Marathi 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)  // 'बेचाळीस रुपये पन्नास पैसे'
  * toCurrency(1)      // 'एक रुपया'
  * toCurrency(0.01)   // 'एक पैसा'
  */
-function toCurrency (value) {
+function toCurrency(value) {
   const { isNegative, dollars: rupees, cents: paise } = parseCurrencyValue(value)
+  checkMax(rupees, currencyMax)
 
   // Build result
   let result = ''

package/src/ms-MY.d.ts

@@ -1,18 +1,18 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
 /**
  * Converts a numeric value to Malay words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Malay words
  */
 export function toCardinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Malay 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)    // 'pertama'
  * toOrdinal(2)    // 'kedua'
@@ -23,12 +23,10 @@ export function toOrdinal(value: number | string | bigint): string;
  * Converts a numeric value to Malay currency words (Ringgit).
  *
  * Malaysian Ringgit uses sen as subunit (100 sen = 1 ringgit).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Malay 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)     // 'empat puluh dua ringgit'
  * toCurrency(1.50)   // 'satu ringgit lima puluh sen'