n2words 5.0.0 → 5.1.0

package/src/he-IL.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 { bounded, western } from './utils/scale.js'
+import { resolveOptions } from './utils/resolve-options.js'
 
 // ============================================================================
 // Vocabulary (arrays for indexed access - faster than object property lookup)
@@ -33,6 +35,15 @@ const THOUSANDS_SPECIAL = ['', 'אלף', 'אלפיים', 'שלשת אלפים',
 const SCALE = ['', 'אלף', 'מיליון', 'מיליארד', 'טריליון', 'קוודרליון', 'קווינטיליון']
 const SCALE_PLURAL = ['', 'אלפים', 'מיליונים', 'מיליארדים', 'טריליונים', 'קוודרליונים', 'קווינטיליונים']
 
+// Supported magnitude ceilings (checked at the public entry points). Cardinal
+// SCALE reaches index SCALE.length-1 (10^18), so cardinals/currency must stay
+// below 10^(SCALE.length * 3) = 10^21. Ordinals are bounded lower: past 10^6
+// the millions multiplier is built with buildScaleSegment (0-999), so n must
+// stay below 10^9. Decimals are read digit-by-digit (no ceiling).
+export const cardinalMax = western(SCALE.length - 1)
+export const ordinalMax = bounded(9)
+export const currencyMax = western(SCALE.length - 1)
+
 const ZERO = 'אפס'
 const NEGATIVE = 'מינוס'
 const DECIMAL_SEP = 'נקודה'
@@ -59,8 +70,11 @@ const AGORA_PLURAL = 'אגורות'
 /**
  * Builds segment word for scale segments (thousands, millions, etc.).
  * "ו" is added before tens and ones when following hundreds.
+ * @param {number} n - Segment value (0-999)
+ * @param {string} andWord - Conjunction word
+ * @returns {string} Hebrew words for the segment
  */
-function buildScaleSegment (n, andWord) {
+function buildScaleSegment(n, andWord) {
   if (n === 0) return ''
 
   const ones = n % 10
@@ -80,15 +94,18 @@ function buildScaleSegment (n, andWord) {
     const teenWord = TEENS[ones]
     if (result) {
       result += ' ' + andWord + teenWord
-    } else {
+    }
+    else {
       result = teenWord
     }
-  } else {
+  }
+  else {
     // Tens (20-90)
     if (tens >= 2) {
       if (result) {
         result += ' ' + andWord + TENS[tens]
-      } else {
+      }
+      else {
         result = TENS[tens]
       }
     }
@@ -97,7 +114,8 @@ function buildScaleSegment (n, andWord) {
     if (ones > 0) {
       if (result) {
         result += ' ' + andWord + ONES[ones]
-      } else {
+      }
+      else {
         result = ONES[ones]
       }
     }
@@ -109,8 +127,11 @@ function buildScaleSegment (n, andWord) {
 /**
  * Builds segment word for units segment (no scale word).
  * "ו" is only added before the final ones digit.
+ * @param {number} n - Segment value (0-999)
+ * @param {string} andWord - Conjunction word
+ * @returns {string} Hebrew words for the segment
  */
-function buildUnitsSegment (n, andWord) {
+function buildUnitsSegment(n, andWord) {
   if (n === 0) return ''
 
   const ones = n % 10
@@ -129,14 +150,17 @@ function buildUnitsSegment (n, andWord) {
     // Teens (10-19)
     if (result) {
       result += ' ' + TEENS[ones]
-    } else {
+    }
+    else {
       result = TEENS[ones]
     }
-  } else {
+  }
+  else {
     if (tens >= 2) {
       if (result) {
         result += ' ' + TENS[tens]
-      } else {
+      }
+      else {
         result = TENS[tens]
       }
     }
@@ -145,7 +169,8 @@ function buildUnitsSegment (n, andWord) {
     if (ones > 0) {
       if (result) {
         result += ' ' + andWord + ONES[ones]
-      } else {
+      }
+      else {
         result = ONES[ones]
       }
     }
@@ -160,12 +185,11 @@ function buildUnitsSegment (n, andWord) {
 
 /**
  * Converts a non-negative integer to Hebrew words.
- *
  * @param {bigint} n - Non-negative integer to convert
  * @param {string} andWord - Conjunction word
  * @returns {string} Hebrew words
  */
-function integerToWords (n, andWord) {
+function integerToWords(n, andWord) {
   if (n === 0n) return ZERO
 
   // Fast path: numbers < 1000
@@ -195,28 +219,34 @@ function integerToWords (n, andWord) {
         // Add "ו" before single-digit units when following scale words
         if (segment <= 9) {
           result += ' ' + andWord + segmentWord
-        } else {
+        }
+        else {
           result += ' ' + segmentWord
         }
-      } else {
+      }
+      else {
         result = segmentWord
       }
-    } else if (i === 1) {
+    }
+    else if (i === 1) {
       // Thousands - special handling for 1-9
       if (segment <= 9) {
         if (result) result += ' '
         result += THOUSANDS_SPECIAL[segment]
-      } else {
+      }
+      else {
         const segmentWord = buildScaleSegment(segment, andWord)
         if (result) result += ' '
         result += segmentWord + ' ' + SCALE[1]
       }
-    } else {
+    }
+    else {
       // Millions and above
       if (segment === 1) {
         if (result) result += ' '
         result += SCALE[i]
-      } else {
+      }
+      else {
         const segmentWord = buildScaleSegment(segment, andWord)
         if (result) result += ' '
         result += segmentWord + ' ' + SCALE_PLURAL[i]
@@ -229,11 +259,10 @@ function integerToWords (n, andWord) {
 
 /**
  * Converts decimal digits to Hebrew words (digit by digit).
- *
  * @param {string} decimalPart - Decimal digits (without the point)
  * @returns {string} Hebrew words for decimal part
  */
-function decimalPartToWords (decimalPart) {
+function decimalPartToWords(decimalPart) {
   let result = ''
 
   for (let i = 0; i < decimalPart.length; i++) {
@@ -245,20 +274,26 @@ function decimalPartToWords (decimalPart) {
   return result
 }
 
+/**
+ * @typedef {object} CardinalOptions
+ * @property {string} [andWord] - Custom conjunction word
+ */
+
+/** @type {Required<CardinalOptions>} */
+export const cardinalDefaults = { andWord: 'ו' }
+
 /**
  * Converts a numeric value to Modern Hebrew words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
- * @param {Object} [options] - Optional configuration
- * @param {string} [options.andWord='ו'] - Custom conjunction word
+ * @param {CardinalOptions} [options] - Optional configuration
  * @returns {string} The number in Modern Hebrew words
  */
-function toCardinal (value, options) {
-  options = validateOptions(options)
+function toCardinal(value, options) {
   const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
+  checkMax(integerPart, cardinalMax)
 
   // Apply option defaults
-  const { andWord = 'ו' } = options
+  const { andWord } = resolveOptions(options, cardinalDefaults)
 
   let result = ''
 
@@ -281,11 +316,10 @@ function toCardinal (value, options) {
 
 /**
  * Builds ordinal for tens and ones (0-99).
- *
  * @param {number} n - Number 0-99
  * @returns {string} Ordinal word
  */
-function buildOrdinalTensOnes (n) {
+function buildOrdinalTensOnes(n) {
   if (n === 0) return ''
   if (n < 10) return ORDINAL_ONES[n]
   if (n < 20) return ORDINAL_TEENS[n - 10]
@@ -303,11 +337,10 @@ function buildOrdinalTensOnes (n) {
 
 /**
  * Converts a non-negative integer to Hebrew ordinal words.
- *
  * @param {bigint} n - Non-negative integer to convert
  * @returns {string} Hebrew ordinal words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   if (n === 0n) return ''
   if (n === 1n) return ORDINAL_ONES[1]
 
@@ -327,7 +360,8 @@ function integerToOrdinal (n) {
         return ORDINAL_HUNDRED
       }
       result = HUNDREDS[hundreds]
-    } else {
+    }
+    else {
       if (remainder === 0) {
         return HUNDREDS[hundreds]
       }
@@ -353,7 +387,8 @@ function integerToOrdinal (n) {
     let result
     if (thousands <= 9) {
       result = THOUSANDS_SPECIAL[thousands]
-    } else {
+    }
+    else {
       result = buildScaleSegment(thousands, 'ו') + ' ' + SCALE[1]
     }
 
@@ -385,7 +420,8 @@ function integerToOrdinal (n) {
   let result
   if (millions === 1) {
     result = SCALE[2]
-  } else {
+  }
+  else {
     result = buildScaleSegment(millions, 'ו') + ' ' + SCALE_PLURAL[2]
   }
 
@@ -394,18 +430,17 @@ function integerToOrdinal (n) {
 
 /**
  * Converts a numeric value to Hebrew ordinal words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The ordinal in Hebrew words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a positive integer
- *
  * @example
  * toOrdinal(1)   // 'ראשון'
  * toOrdinal(21)  // 'עשרים וראשון'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const n = parseOrdinalValue(value)
+  checkMax(n, ordinalMax)
   return integerToOrdinal(n)
 }
 
@@ -415,8 +450,10 @@ function toOrdinal (value) {
 
 /**
  * Builds segment word for currency (masculine forms).
+ * @param {number} n - Segment value (0-999)
+ * @returns {string} Hebrew words for the segment (masculine form)
  */
-function buildCurrencySegment (n) {
+function buildCurrencySegment(n) {
   if (n === 0) return ''
 
   const ones = n % 10
@@ -436,15 +473,18 @@ function buildCurrencySegment (n) {
     const teenWord = TEENS[ones]
     if (result) {
       result += ' ' + teenWord
-    } else {
+    }
+    else {
       result = teenWord
     }
-  } else {
+  }
+  else {
     // Tens (20-90)
     if (tens >= 2) {
       if (result) {
         result += ' ' + TENS[tens]
-      } else {
+      }
+      else {
         result = TENS[tens]
       }
     }
@@ -453,7 +493,8 @@ function buildCurrencySegment (n) {
     if (ones > 0) {
       if (result) {
         result += ' ו' + ONES_MASC[ones]
-      } else {
+      }
+      else {
         result = ONES_MASC[ones]
       }
     }
@@ -464,11 +505,10 @@ function buildCurrencySegment (n) {
 
 /**
  * Converts a non-negative integer to Hebrew currency words (masculine).
- *
  * @param {bigint} n - Non-negative integer to convert
  * @returns {string} Hebrew words (masculine form)
  */
-function integerToCurrencyWords (n) {
+function integerToCurrencyWords(n) {
   if (n === 0n) return ZERO
 
   // Fast path: numbers < 1000
@@ -484,18 +524,17 @@ function integerToCurrencyWords (n) {
 
 /**
  * Converts a numeric value to Hebrew New Israeli Shekel currency words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The currency in Hebrew words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCurrency(1)     // 'שקל אחד'
  * toCurrency(2.50)  // 'שניים שקלים חמישים אגורות'
  */
-function toCurrency (value) {
+function toCurrency(value) {
   const { isNegative, dollars, cents } = parseCurrencyValue(value)
+  checkMax(dollars, currencyMax)
 
   const parts = []
 
@@ -507,9 +546,11 @@ function toCurrency (value) {
   if (dollars > 0n || cents === 0n) {
     if (dollars === 1n) {
       parts.push(SHEKEL_SINGULAR + ' ' + ONES_MASC[1])
-    } else if (dollars === 2n) {
+    }
+    else if (dollars === 2n) {
       parts.push(ONES_MASC[2] + ' ' + SHEKEL_PLURAL)
-    } else {
+    }
+    else {
       const shekelWord = integerToCurrencyWords(dollars)
       const shekelForm = SHEKEL_PLURAL
       parts.push(shekelWord + ' ' + shekelForm)
@@ -521,7 +562,8 @@ function toCurrency (value) {
     const centNum = Number(cents)
     if (centNum === 1) {
       parts.push(AGORA_SINGULAR + ' ' + ONES[1])
-    } else {
+    }
+    else {
       const centWord = integerToWords(cents, 'ו')
       parts.push(centWord + ' ' + AGORA_PLURAL)
     }

package/src/hi-IN.d.ts

@@ -1,18 +1,18 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
 /**
  * Converts a numeric value to Hindi words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Hindi words
  */
 export function toCardinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Hindi 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 Hindi currency words (Indian Rupee).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Hindi 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/hi-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,23 +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 - Number 0-999
  * @returns {string} Hindi words for the segment
  */
-function buildSegment (n) {
+function buildSegment(n) {
   if (n === 0) return ''
   if (n < 100) return BELOW_HUNDRED[n]
 
@@ -94,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} Hindi words
  */
-function integerToWords (n) {
+function integerToWords(n) {
   if (n === 0n) return ZERO
 
   // Fast path: numbers < 1000
@@ -130,7 +137,8 @@ function integerToWords (n) {
     if (i === 0) {
       // First segment (units place) can be 0-999
       words.push(buildSegment(segment))
-    } else {
+    }
+    else {
       // Other segments are 0-99
       words.push(BELOW_HUNDRED[segment])
     }
@@ -144,7 +152,12 @@ function integerToWords (n) {
   return words.join(' ')
 }
 
-function decimalPartToWords (decimalPart) {
+/**
+ * Converts the decimal-part digit string to Hindi words.
+ * @param {string} decimalPart - The digits after the decimal separator
+ * @returns {string} Hindi words for the decimal part
+ */
+function decimalPartToWords(decimalPart) {
   let result = ''
   let i = 0
 
@@ -165,12 +178,14 @@ function decimalPartToWords (decimalPart) {
 
 /**
  * Converts a numeric value to Hindi words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Hindi 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 = ''
 
@@ -195,11 +210,10 @@ function toCardinal (value) {
  * Converts a positive integer to Hindi ordinal words.
  *
  * Hindi ordinals: First 6 are irregular, then add -वाँ suffix.
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Hindi ordinal words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   // Special ordinals for 1-6
   if (n >= 1n && n <= 6n) {
     return ORDINAL_SPECIAL[Number(n)]
@@ -212,20 +226,20 @@ function integerToOrdinal (n) {
 
 /**
  * Converts a numeric value to Hindi 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)
 }
 
@@ -235,19 +249,18 @@ function toOrdinal (value) {
 
 /**
  * Converts a numeric value to Hindi currency words (Indian Rupee).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Hindi 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/hr-HR.d.ts

@@ -1,22 +1,35 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
+/**
+ * @typedef {object} CardinalOptions
+ * @property {('masculine'|'feminine')} [gender] - Grammatical gender
+ */
+/** @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 = {
+    /**
+     * - Grammatical gender
+     */
+    gender?: "feminine" | "masculine" | undefined;
+};
 /**
  * Converts a numeric value to Croatian words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
- * @param {Object} [options] - Optional configuration
- * @param {('masculine'|'feminine')} [options.gender='masculine'] - Grammatical gender
+ * @param {CardinalOptions} [options] - Optional configuration
  * @returns {string} The number in Croatian words
  */
-export function toCardinal(value: number | string | bigint, options?: {
-    gender?: "masculine" | "feminine" | undefined;
-}): string;
+export function toCardinal(value: number | string | bigint, options?: CardinalOptions): string;
 /**
  * Converts a numeric value to Croatian 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)    // 'prvi'
  * toOrdinal(2)    // 'drugi'
@@ -27,12 +40,10 @@ export function toCardinal(value: number | string | bigint, options?: {
 export function toOrdinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Croatian currency words (Euro).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Croatian 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)     // 'četrdeset dva eura'
  * toCurrency(1)      // 'jedan euro'