n2words 4.0.0 → 5.1.0

package/src/bn-BD.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 { indian } from './utils/scale.js'
 
 // ============================================================================
 // Vocabulary
@@ -53,20 +55,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 in the range 0-999
+ * @returns {string} Bengali words for the segment
  */
-function buildSegment (n) {
+function buildSegment(n) {
   if (n === 0) return ''
   if (n < 100) return BELOW_HUNDRED[n]
 
@@ -88,11 +99,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} Bengali words
  */
-function integerToWords (n) {
+function integerToWords(n) {
   if (n === 0n) return ZERO
 
   // Fast path: numbers < 1000 (direct lookup)
@@ -124,7 +134,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])
     }
@@ -138,7 +149,12 @@ function integerToWords (n) {
   return words.join(' ')
 }
 
-function decimalPartToWords (decimalPart) {
+/**
+ * Converts the fractional digits string to Bengali words.
+ * @param {string} decimalPart - The fractional digits (e.g. '05')
+ * @returns {string} Bengali words for the decimal part
+ */
+function decimalPartToWords(decimalPart) {
   let result = ''
   let i = 0
 
@@ -159,12 +175,14 @@ function decimalPartToWords (decimalPart) {
 
 /**
  * Converts a numeric value to Bengali words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Bengali 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 = ''
 
@@ -189,11 +207,10 @@ function toCardinal (value) {
  * Converts a positive integer to Bengali ordinal words.
  *
  * Bengali ordinals: First 6 are irregular, then add -তম suffix.
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Bengali ordinal words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   // Special ordinals for 1-6
   if (n >= 1n && n <= 6n) {
     return ORDINAL_SPECIAL[Number(n)]
@@ -206,20 +223,20 @@ function integerToOrdinal (n) {
 
 /**
  * Converts a numeric value to Bengali 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)
 }
 
@@ -229,19 +246,18 @@ function toOrdinal (value) {
 
 /**
  * Converts a numeric value to Bengali currency words (Bangladeshi Taka).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Bengali 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: taka, cents: paisa } = parseCurrencyValue(value)
+  checkMax(taka, currencyMax)
 
   // Build result
   let result = ''

package/src/cs-CZ.d.ts

@@ -1,14 +1,15 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
 /**
  * Converts a numeric value to Czech 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
  * @returns {string} The number in Czech words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCardinal(21)           // 'dvacet jedna'
  * toCardinal(1000)         // 'tisíc'
@@ -18,12 +19,10 @@
 export function toCardinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Czech 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)    // 'první'
  * toOrdinal(2)    // 'druhý'
@@ -34,12 +33,10 @@ export function toCardinal(value: number | string | bigint): string;
 export function toOrdinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Czech currency words (Koruna).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Czech 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)     // 'čtyřicet dva koruny'
  * toCurrency(1)      // 'jedna koruna'

package/src/cs-CZ.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)
@@ -32,6 +34,7 @@ const TENS = ['', '', 'dvacet', 'třicet', 'čtyřicet', 'padesát', 'šedesát'
 const HUNDREDS = ['', 'sto', 'dvě stě', 'tři sta', 'čtyři sta', 'pět set', 'šest set', 'sedm set', 'osm set', 'devět set']
 
 // Scale plural forms [singular, few (2-4), many (5+)]
+/** @type {Record<number, string[]>} */
 const PLURAL_FORMS = {
   1: ['tisíc', 'tisíce', 'tisíc'], // 10^3
   2: ['milion', 'miliony', 'milionů'], // 10^6
@@ -41,9 +44,16 @@ const PLURAL_FORMS = {
   6: ['trilion', 'triliony', 'trilionů'], // 10^18
   7: ['triliarda', 'triliardy', 'triliard'], // 10^21
   8: ['kvadrilion', 'kvadriliony', 'kvadrilionů'], // 10^24
-  9: ['kvadriliarda', 'kvadriliardy', 'kvadriliard'] // 10^27
+  9: ['kvadriliarda', 'kvadriliardy', 'kvadriliard'], // 10^27
 }
 
+// PLURAL_FORMS is keyed by 1000-power; past its largest key the builder drops the
+// scale word (cardinal) or dereferences undefined (ordinal), so cap there.
+const MAX_SCALE_KEY = Math.max(...Object.keys(PLURAL_FORMS).map(Number))
+export const cardinalMax = western(MAX_SCALE_KEY)
+export const ordinalMax = western(MAX_SCALE_KEY)
+export const currencyMax = western(MAX_SCALE_KEY)
+
 const ZERO = 'nula'
 const NEGATIVE = 'mínus'
 
@@ -81,8 +91,10 @@ const HALER_FORMS = ['haléř', 'haléře', 'haléřů']
 
 /**
  * Builds segment word for 0-999 (masculine, default form).
+ * @param {number} n - Number 0-999
+ * @returns {string} Czech words
  */
-function buildSegment (n) {
+function buildSegment(n) {
   if (n === 0) return ''
 
   const ones = n % 10
@@ -100,12 +112,14 @@ function buildSegment (n) {
   if (tens === 1) {
     // Teens
     parts.push(TEENS[ones])
-  } else if (tens >= 2) {
+  }
+  else if (tens >= 2) {
     parts.push(TENS[tens])
     if (ones > 0) {
       parts.push(ONES[ones])
     }
-  } else if (ones > 0) {
+  }
+  else if (ones > 0) {
     parts.push(ONES[ones])
   }
 
@@ -115,8 +129,10 @@ function buildSegment (n) {
 /**
  * Builds segment word for 0-999 with feminine hundreds.
  * Hundreds use irregular forms (dvě stě, tři sta) but ones remain masculine.
+ * @param {number} n - Number 0-999
+ * @returns {string} Czech words
  */
-function buildSegmentWithHundreds (n) {
+function buildSegmentWithHundreds(n) {
   if (n === 0) return ''
 
   const ones = n % 10
@@ -133,12 +149,14 @@ function buildSegmentWithHundreds (n) {
   // Tens and ones use masculine form
   if (tens === 1) {
     parts.push(TEENS[ones])
-  } else if (tens >= 2) {
+  }
+  else if (tens >= 2) {
     parts.push(TENS[tens])
     if (ones > 0) {
       parts.push(ONES[ones]) // masculine
     }
-  } else if (ones > 0) {
+  }
+  else if (ones > 0) {
     parts.push(ONES[ones]) // masculine
   }
 
@@ -152,12 +170,11 @@ function buildSegmentWithHundreds (n) {
 /**
  * Czech pluralization: 1 = singular, 2-4 = few, else = many.
  * Teens (11-19) always use "many" form.
- *
  * @param {bigint} n - The number
  * @param {string[]} forms - [singular, few, many]
  * @returns {string} The appropriate form
  */
-function pluralize (n, forms) {
+function pluralize(n, forms) {
   if (n === 1n) return forms[0]
 
   const lastDigit = n % 10n
@@ -174,13 +191,17 @@ function pluralize (n, forms) {
 /**
  * Gets the decimal separator word based on integer part.
  * celá (0-1), celé (2-4), celých (5+)
+ * @param {bigint} integerPart - The integer part of the value
+ * @returns {string} The decimal separator word
  */
-function getDecimalSeparator (integerPart) {
+function getDecimalSeparator(integerPart) {
   if (integerPart === 0n || integerPart === 1n) {
     return 'celá'
-  } else if (integerPart >= 2n && integerPart <= 4n) {
+  }
+  else if (integerPart >= 2n && integerPart <= 4n) {
     return 'celé'
-  } else {
+  }
+  else {
     return 'celých'
   }
 }
@@ -191,11 +212,10 @@ function getDecimalSeparator (integerPart) {
 
 /**
  * Converts a non-negative integer to Czech words.
- *
  * @param {bigint} n - Non-negative integer to convert
  * @returns {string} Czech words
  */
-function integerToWords (n) {
+function integerToWords(n) {
   if (n === 0n) return ZERO
 
   // Fast path: numbers < 1000
@@ -214,7 +234,8 @@ function integerToWords (n) {
     if (thousands === 1n) {
       // Omit "one" before tisíc
       result = scaleWord
-    } else {
+    }
+    else {
       result = buildSegment(Number(thousands)) + ' ' + scaleWord
     }
 
@@ -233,11 +254,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} Czech words
  */
-function buildLargeNumberWords (n) {
+function buildLargeNumberWords(n) {
   // Extract segments using BigInt division (faster than string slicing)
   // Segments stored least-significant first (index 0 = ones, 1 = thousands, etc.)
   const segmentValues = []
@@ -259,7 +279,8 @@ function buildLargeNumberWords (n) {
     if (i === 0) {
       // Units segment (no scale word) - use form with irregular hundreds
       result += buildSegmentWithHundreds(Number(segment))
-    } else {
+    }
+    else {
       // Scale word needed
       const forms = PLURAL_FORMS[i]
       if (forms) {
@@ -268,11 +289,13 @@ function buildLargeNumberWords (n) {
         if (segment === 1n) {
           // Omit "one" before scale words
           result += scaleWord
-        } else {
+        }
+        else {
           // Use masculine form for multiplier before scale words
           result += buildSegment(Number(segment)) + ' ' + scaleWord
         }
-      } else {
+      }
+      else {
         // Fallback for very large scales without defined forms
         result += buildSegment(Number(segment))
       }
@@ -284,11 +307,10 @@ function buildLargeNumberWords (n) {
 
 /**
  * Converts decimal digits to Czech words.
- *
  * @param {string} decimalPart - Decimal digits (without the point)
  * @returns {string} Czech words for decimal part
  */
-function decimalPartToWords (decimalPart) {
+function decimalPartToWords(decimalPart) {
   let result = ''
 
   // Handle leading zeros
@@ -314,20 +336,21 @@ 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 Czech words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCardinal(21)           // 'dvacet jedna'
  * toCardinal(1000)         // 'tisíc'
  * toCardinal(2000)         // 'dva tisíce'
  * toCardinal(5000)         // 'pět tisíc'
  */
-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 = ''
 
@@ -351,11 +374,10 @@ function toCardinal (value) {
 
 /**
  * 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
@@ -378,11 +400,10 @@ function buildOrdinalTensOnes (n) {
 
 /**
  * Converts a positive integer to Czech ordinal words (masculine nominative).
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Ordinal Czech words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   if (n < 100n) {
     return buildOrdinalTensOnes(Number(n))
   }
@@ -420,11 +441,10 @@ function integerToOrdinal (n) {
 
 /**
  * Builds ordinal words for numbers >= 1,000,000.
- *
  * @param {bigint} n - Number >= 1,000,000
  * @returns {string} Ordinal Czech words
  */
-function buildLargeOrdinal (n) {
+function buildLargeOrdinal(n) {
   const segmentValues = []
   let temp = n
   while (temp > 0n) {
@@ -450,23 +470,28 @@ function buildLargeOrdinal (n) {
     if (i === 0) {
       if (isLastNonZero) {
         parts.push(integerToOrdinal(segment))
-      } else {
+      }
+      else {
         parts.push(buildSegmentWithHundreds(Number(segment)))
       }
-    } else {
+    }
+    else {
       if (isLastNonZero) {
         if (segment === 1n) {
           parts.push(ORDINAL_SCALES[i - 1] || PLURAL_FORMS[i][0])
-        } else {
+        }
+        else {
           parts.push(buildSegment(Number(segment)) + ' ' + (ORDINAL_SCALES[i - 1] || PLURAL_FORMS[i][0]))
         }
-      } else {
+      }
+      else {
         const forms = PLURAL_FORMS[i]
         if (forms) {
           const scaleWord = pluralize(segment, forms)
           if (segment === 1n) {
             parts.push(scaleWord)
-          } else {
+          }
+          else {
             parts.push(buildSegment(Number(segment)) + ' ' + scaleWord)
           }
         }
@@ -479,12 +504,10 @@ function buildLargeOrdinal (n) {
 
 /**
  * Converts a numeric value to Czech 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)    // 'první'
  * toOrdinal(2)    // 'druhý'
@@ -492,8 +515,10 @@ function buildLargeOrdinal (n) {
  * toOrdinal(100)  // 'stý'
  * toOrdinal(1000) // 'tisící'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
+  // Ordinals reuse the cardinal scale table, so they share its ceiling.
+  checkMax(integerPart, ordinalMax)
   return integerToOrdinal(integerPart)
 }
 
@@ -503,20 +528,19 @@ function toOrdinal (value) {
 
 /**
  * Converts a numeric value to Czech currency words (Koruna).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Czech 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)     // 'čtyřicet dva koruny'
  * toCurrency(1)      // 'jedna koruna'
  * toCurrency(1.50)   // 'jedna koruna padesát haléřů'
  * toCurrency(-5)     // 'mínus pět korun'
  */
-function toCurrency (value) {
+function toCurrency(value) {
   const { isNegative, dollars: koruny, cents: halere } = parseCurrencyValue(value)
+  checkMax(koruny, currencyMax)
 
   let result = ''
   if (isNegative) {

package/src/da-DK.d.ts

@@ -1,11 +1,12 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
 /**
  * Converts a numeric value to Danish words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Danish words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCardinal(21)       // 'enogtyve'
  * toCardinal(1000)     // 'ettusind'
@@ -14,12 +15,10 @@
 export function toCardinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Danish 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)    // 'første'
  * toOrdinal(2)    // 'anden'
@@ -30,12 +29,10 @@ export function toOrdinal(value: number | string | bigint): string;
  * Converts a numeric value to Danish currency words (Danish Krone).
  *
  * Uses krone/kroner and øre (100 øre = 1 krone).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Danish 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)      // 'en krone'
  * toCurrency(42)     // 'toogfyrre kroner'