n2words 5.0.0 → 5.1.0

package/src/hr-HR.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 { western } from './utils/scale.js'
+import { resolveOptions } from './utils/resolve-options.js'
 
 // ============================================================================
 // Vocabulary
@@ -71,14 +73,20 @@ const SCALE_FORMS = [
   ['trilijun', 'trilijuna', 'trilijuna'],
   ['trilijarda', 'trilijarde', 'trilijarda'],
   ['kvadrilijun', 'kvadrilijuna', 'kvadrilijuna'],
-  ['kvadrilijarda', 'kvadrilijarde', 'kvadrilijarda']
+  ['kvadrilijarda', 'kvadrilijarde', 'kvadrilijarda'],
 ]
 
 // ============================================================================
 // Segment Building
 // ============================================================================
 
-function pluralize (n, forms) {
+/**
+ * Selects the correct plural form for a count.
+ * @param {number | bigint} n - The count
+ * @param {string[]} forms - The [one, few, many] plural forms
+ * @returns {string} The selected plural form
+ */
+function pluralize(n, forms) {
   const num = typeof n === 'bigint' ? Number(n) : n
   const lastDigit = num % 10
   const lastTwoDigits = num % 100
@@ -92,7 +100,12 @@ function pluralize (n, forms) {
   return forms[2]
 }
 
-function buildSegmentMasc (n) {
+/**
+ * Builds the masculine words for a 0-999 segment.
+ * @param {number} n - Number 0-999
+ * @returns {string} The segment words
+ */
+function buildSegmentMasc(n) {
   if (n === 0) return ''
 
   const onesDigit = n % 10
@@ -111,14 +124,20 @@ function buildSegmentMasc (n) {
 
   if (tensDigit === 1) {
     parts.push(TEENS[onesDigit])
-  } else if (onesDigit > 0) {
+  }
+  else if (onesDigit > 0) {
     parts.push(ONES_MASC[onesDigit])
   }
 
   return parts.join(' ')
 }
 
-function buildSegmentFem (n) {
+/**
+ * Builds the feminine words for a 0-999 segment.
+ * @param {number} n - Number 0-999
+ * @returns {string} The segment words
+ */
+function buildSegmentFem(n) {
   if (n === 0) return ''
 
   const onesDigit = n % 10
@@ -137,7 +156,8 @@ function buildSegmentFem (n) {
 
   if (tensDigit === 1) {
     parts.push(TEENS[onesDigit])
-  } else if (onesDigit > 0) {
+  }
+  else if (onesDigit > 0) {
     parts.push(ONES_FEM[onesDigit])
   }
 
@@ -148,7 +168,13 @@ function buildSegmentFem (n) {
 // Conversion Functions
 // ============================================================================
 
-function integerToWords (n, gender) {
+/**
+ * Converts a non-negative integer to Croatian words.
+ * @param {bigint} n - Non-negative integer to convert
+ * @param {('masculine'|'feminine')} gender - Grammatical gender
+ * @returns {string} The number in Croatian words
+ */
+function integerToWords(n, gender) {
   if (n === 0n) return ZERO
 
   if (n < 1000n) {
@@ -158,7 +184,13 @@ function integerToWords (n, gender) {
   return buildLargeNumberWords(n, gender)
 }
 
-function buildLargeNumberWords (n, gender) {
+/**
+ * Builds words for numbers >= 1000.
+ * @param {bigint} n - Number >= 1000
+ * @param {('masculine'|'feminine')} gender - Grammatical gender
+ * @returns {string} The number in Croatian words
+ */
+function buildLargeNumberWords(n, gender) {
   const numStr = n.toString()
   const len = numStr.length
 
@@ -185,7 +217,8 @@ function buildLargeNumberWords (n, gender) {
     if (segment !== 0) {
       if (scaleIndex === 0) {
         parts.push(gender === 'feminine' ? buildSegmentFem(segment) : buildSegmentMasc(segment))
-      } else {
+      }
+      else {
         const scaleForms = SCALE_FORMS[scaleIndex - 1]
         const scaleWord = pluralize(segment, scaleForms)
         // Thousands (scaleIndex=1) are feminine, others masculine
@@ -201,7 +234,13 @@ function buildLargeNumberWords (n, gender) {
   return parts.join(' ')
 }
 
-function decimalPartToWords (decimalPart, gender) {
+/**
+ * Converts the decimal-part digit string to Croatian words.
+ * @param {string} decimalPart - The decimal digits as a string
+ * @param {('masculine'|'feminine')} gender - Grammatical gender
+ * @returns {string} The decimal part in Croatian words
+ */
+function decimalPartToWords(decimalPart, gender) {
   let result = ''
   let i = 0
 
@@ -220,20 +259,38 @@ function decimalPartToWords (decimalPart, gender) {
   return result
 }
 
+// Supported magnitude ceilings (checked at the public entry points). Both
+// tables are indexed [scaleIndex - 1] (units separate), so the ceiling is
+// 10^((length + 1) * 3): cardinal/currency 10^30, ordinal 10^15.
+export const cardinalMax = western(SCALE_FORMS.length)
+export const ordinalMax = western(ORDINAL_SCALES.length)
+export const currencyMax = western(SCALE_FORMS.length)
+
+/**
+ * @typedef {object} CardinalOptions
+ * @property {('masculine'|'feminine')} [gender] - Grammatical gender
+ */
+
+/** @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 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
  */
-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 = ''
 
@@ -256,11 +313,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
@@ -283,11 +339,10 @@ function buildOrdinalTensOnes (n) {
 
 /**
  * Converts a positive integer to Croatian ordinal words (masculine nominative).
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Ordinal Croatian words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   if (n < 100n) {
     return buildOrdinalTensOnes(Number(n))
   }
@@ -325,11 +380,10 @@ function integerToOrdinal (n) {
 
 /**
  * Builds ordinal words for numbers >= 1,000,000.
- *
  * @param {bigint} n - Number >= 1,000,000
  * @returns {string} Ordinal Croatian words
  */
-function buildLargeOrdinal (n) {
+function buildLargeOrdinal(n) {
   const numStr = n.toString()
   const len = numStr.length
 
@@ -364,19 +418,23 @@ function buildLargeOrdinal (n) {
       if (scaleIndex === 0) {
         if (isLastNonZero) {
           parts.push(integerToOrdinal(BigInt(segment)))
-        } else {
+        }
+        else {
           parts.push(buildSegmentMasc(segment))
         }
-      } else {
+      }
+      else {
         if (isLastNonZero) {
           if (segment === 1) {
             parts.push(ORDINAL_SCALES[scaleIndex - 1])
-          } else {
+          }
+          else {
             const isFeminine = scaleIndex === 1
             const segmentWord = isFeminine ? buildSegmentFem(segment) : buildSegmentMasc(segment)
             parts.push(segmentWord + ' ' + ORDINAL_SCALES[scaleIndex - 1])
           }
-        } else {
+        }
+        else {
           const scaleForms = SCALE_FORMS[scaleIndex - 1]
           const scaleWord = pluralize(segment, scaleForms)
           const isFeminine = scaleIndex === 1
@@ -394,12 +452,10 @@ function buildLargeOrdinal (n) {
 
 /**
  * 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'
@@ -407,8 +463,9 @@ function buildLargeOrdinal (n) {
  * toOrdinal(100)  // 'stoti'
  * toOrdinal(1000) // 'tisućiti'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
+  checkMax(integerPart, ordinalMax)
   return integerToOrdinal(integerPart)
 }
 
@@ -418,20 +475,19 @@ function toOrdinal (value) {
 
 /**
  * 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'
  * toCurrency(1.50)   // 'jedan euro pedeset centi'
  * toCurrency(-5)     // 'minus pet eura'
  */
-function toCurrency (value) {
+function toCurrency(value) {
   const { isNegative, dollars: euros, cents } = parseCurrencyValue(value)
+  checkMax(euros, currencyMax)
 
   let result = ''
   if (isNegative) {

package/src/hu-HU.d.ts

@@ -1,18 +1,18 @@
+export const cardinalMax: null;
+export const ordinalMax: null;
+export const currencyMax: null;
 /**
  * Converts a numeric value to Hungarian words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Hungarian words
  */
 export function toCardinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Hungarian 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)    // 'első'
  * toOrdinal(2)    // 'második'
@@ -24,12 +24,10 @@ export function toOrdinal(value: number | string | bigint): string;
  *
  * Uses forint (no plural form needed in Hungarian).
  * Fillér (1/100) is rarely used but included for completeness.
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Hungarian 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)     // 'negyvenkettő forint'
  * toCurrency(1.50)   // 'egy forint ötven fillér'

package/src/hu-HU.js

@@ -13,6 +13,12 @@
 import { parseCardinalValue } from './utils/parse-cardinal.js'
 import { parseCurrencyValue } from './utils/parse-currency.js'
 import { parseOrdinalValue } from './utils/parse-ordinal.js'
+import { UNBOUNDED } from './utils/scale.js'
+
+// No fixed scale ceiling — the speller composes every magnitude.
+export const cardinalMax = UNBOUNDED
+export const ordinalMax = UNBOUNDED
+export const currencyMax = UNBOUNDED
 
 // ============================================================================
 // Vocabulary
@@ -66,7 +72,7 @@ const WORDS = new Map([
   [3n, 'három'],
   [2n, 'kettő'],
   [1n, 'egy'],
-  [0n, 'nulla']
+  [0n, 'nulla'],
 ])
 
 const ZERO = 'nulla'
@@ -79,6 +85,7 @@ const DECIMAL_SEP = 'egész'
 
 // Hungarian ordinals: special forms 1-10, then cardinal + -dik/-ik suffix
 // Vowel harmony determines -dik vs -ik
+/** @type {Record<number, string>} */
 const ORDINAL_SPECIAL = {
   1: 'első',
   2: 'második',
@@ -99,7 +106,7 @@ const ORDINAL_SPECIAL = {
   80: 'nyolcvanadik',
   90: 'kilencvenedik',
   100: 'századik',
-  1000: 'ezredik'
+  1000: 'ezredik',
 }
 
 // ============================================================================
@@ -113,20 +120,32 @@ const FILLER = 'fillér' // subunit (rarely used, same singular and plural)
 // Conversion Functions
 // ============================================================================
 
-function wordForScale (value) {
+/**
+ * @param {bigint} value The scale or vocabulary key to look up
+ * @returns {string | undefined} The Hungarian word for the key, or undefined if absent
+ */
+function wordForScale(value) {
   return WORDS.get(value)
 }
 
-function tensToCardinal (n) {
+/**
+ * @param {bigint} n The integer (under 100) to convert
+ * @returns {string} The number in Hungarian words
+ */
+function tensToCardinal(n) {
   if (WORDS.has(n)) {
-    return WORDS.get(n)
+    return /** @type {string} */ (WORDS.get(n))
   }
   const tens = n / 10n
   const units = n % 10n
   return wordForScale(tens * 10n) + integerToWordsInner(units)
 }
 
-function hundredsToCardinal (n) {
+/**
+ * @param {bigint} n The integer (under 1000) to convert
+ * @returns {string} The number in Hungarian words
+ */
+function hundredsToCardinal(n) {
   const hundreds = n / 100n
   let prefix = 'száz'
   if (hundreds !== 1n) {
@@ -136,7 +155,11 @@ function hundredsToCardinal (n) {
   return prefix + postfix
 }
 
-function thousandsToCardinal (n) {
+/**
+ * @param {bigint} n The integer (under one million) to convert
+ * @returns {string} The number in Hungarian words
+ */
+function thousandsToCardinal(n) {
   const thousands = n / 1000n
   let prefix = 'ezer'
   if (thousands !== 1n) {
@@ -156,10 +179,14 @@ const SCALES = [
   1_000_000_000_000_000n,
   1_000_000_000_000n,
   1_000_000_000n,
-  1_000_000n
+  1_000_000n,
 ]
 
-function bigNumberToCardinal (n) {
+/**
+ * @param {bigint} n The integer (one million or greater) to convert
+ * @returns {string} The number in Hungarian words
+ */
+function bigNumberToCardinal(n) {
   // Find appropriate scale using BigInt comparison (avoids toString)
   let exp = 1_000_000n
   for (const scale of SCALES) {
@@ -175,7 +202,12 @@ function bigNumberToCardinal (n) {
   return prefix + wordForScale(exp) + postfix
 }
 
-function integerToWordsInner (n, zeroWord = ZERO) {
+/**
+ * @param {bigint} n The integer to convert
+ * @param {string} [zeroWord] The word to use for zero (empty string in compound contexts)
+ * @returns {string} The number in Hungarian words
+ */
+function integerToWordsInner(n, zeroWord = ZERO) {
   // Normalize to BigInt for consistent comparisons
   if (typeof n !== 'bigint') n = BigInt(n)
 
@@ -186,7 +218,7 @@ function integerToWordsInner (n, zeroWord = ZERO) {
     return 'két'
   }
   if (n < 30n) {
-    return wordForScale(n)
+    return /** @type {string} */ (wordForScale(n))
   }
   if (n < 100n) {
     return tensToCardinal(n)
@@ -200,11 +232,19 @@ function integerToWordsInner (n, zeroWord = ZERO) {
   return bigNumberToCardinal(n)
 }
 
-function integerToWords (n) {
+/**
+ * @param {bigint} n The integer to convert
+ * @returns {string} The number in Hungarian words
+ */
+function integerToWords(n) {
   return integerToWordsInner(n, ZERO)
 }
 
-function decimalPartToWords (decimalPart) {
+/**
+ * @param {string} decimalPart The decimal digits (after the separator) to convert
+ * @returns {string} The decimal digits in Hungarian words
+ */
+function decimalPartToWords(decimalPart) {
   let result = ''
   let i = 0
 
@@ -225,11 +265,10 @@ function decimalPartToWords (decimalPart) {
 
 /**
  * Converts a numeric value to Hungarian words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Hungarian words
  */
-function toCardinal (value) {
+function toCardinal(value) {
   const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
@@ -256,11 +295,10 @@ function toCardinal (value) {
  *
  * Hungarian ordinals: első (1st), második (2nd), harmadik (3rd), etc.
  * 1-10 have special forms, others use cardinal + -dik/-edik/-adik/-ödik suffix.
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Hungarian ordinal words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   const num = Number(n)
 
   // Exact special forms
@@ -307,18 +345,16 @@ function integerToOrdinal (n) {
 
 /**
  * Converts a numeric value to Hungarian 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)    // 'első'
  * toOrdinal(2)    // 'második'
  * toOrdinal(21)   // 'huszonegyedik'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
   return integerToOrdinal(integerPart)
 }
@@ -332,18 +368,16 @@ function toOrdinal (value) {
  *
  * Uses forint (no plural form needed in Hungarian).
  * Fillér (1/100) is rarely used but included for completeness.
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Hungarian 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)     // 'negyvenkettő forint'
  * toCurrency(1.50)   // 'egy forint ötven fillér'
  * toCurrency(-5)     // 'mínusz öt forint'
  */
-function toCurrency (value) {
+function toCurrency(value) {
   const { isNegative, dollars: forint, cents: filler } = parseCurrencyValue(value)
 
   let result = ''

package/src/id-ID.d.ts

@@ -1,18 +1,18 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
 /**
  * Converts a numeric value to Indonesian words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Indonesian words
  */
 export function toCardinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Indonesian 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'
@@ -24,12 +24,10 @@ export function toOrdinal(value: number | string | bigint): string;
  *
  * Indonesian Rupiah has no subunit in modern usage (sen are historical).
  * Amounts are rounded to whole rupiah.
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Indonesian 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 rupiah'
  * toCurrency(1000)   // 'seribu rupiah'