n2words 5.0.0 → 5.1.1

package/src/nl-NL.js

@@ -16,7 +16,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)
@@ -31,6 +33,19 @@ const HUNDRED = 'honderd'
 // Scale words (long scale with -ard forms)
 const SCALES = ['duizend', 'miljoen', 'miljard', 'biljoen', 'biljard', 'triljoen', 'triljard', 'quadriljoen', 'quadriljard']
 
+// Scale ordinal words. Module-scope so its length can derive the ordinal
+// ceiling and so it isn't rebuilt on every call.
+const SCALE_ORDINAL = ['', 'duizendste', 'miljoenste', 'miljardste', 'biljoenste', 'biljardste', 'triljoenste']
+
+// Supported magnitude ceilings (checked at the public entry points). SCALES is
+// indexed [scaleIndex - 1] from 'duizend' (10^3), so cardinals/currency reach
+// 10^((SCALES.length + 1) * 3) = 10^30. The ordinal of a number whose lowest
+// non-zero group is a scale group uses the shorter SCALE_ORDINAL, so ordinals
+// are bounded at 10^(SCALE_ORDINAL.length * 3) = 10^21.
+export const cardinalMax = western(SCALES.length)
+export const ordinalMax = western(SCALE_ORDINAL.length - 1)
+export const currencyMax = western(SCALES.length)
+
 const ZERO = 'nul'
 const NEGATIVE = 'min'
 const DECIMAL_SEP = 'komma'
@@ -51,7 +66,7 @@ const CENTEN = 'cent' // Cent doesn't pluralize in written currency
  * @param {boolean} withAnd - Include "en" for values < 13 after hundreds
  * @returns {string} Dutch word (compound, no spaces)
  */
-function buildSegment (n, withAnd) {
+function buildSegment(n, withAnd) {
   if (n === 0) return ''
 
   const ones = n % 10
@@ -65,7 +80,8 @@ function buildSegment (n, withAnd) {
   if (hundreds > 0) {
     if (hundreds === 1) {
       result = HUNDRED
-    } else {
+    }
+    else {
       result = ONES[hundreds] + HUNDRED
     }
   }
@@ -73,25 +89,31 @@ function buildSegment (n, withAnd) {
   // Tens and ones
   if (tensOnes === 0) {
     // Just hundreds
-  } else if (tensOnes < 10) {
+  }
+  else if (tensOnes < 10) {
     // Single digit - add "en" if withAnd and after hundreds
     if (hundreds > 0 && withAnd) {
       result += 'en' + ONES[tensOnes]
-    } else {
+    }
+    else {
       result += ONES[tensOnes]
     }
-  } else if (tensOnes < 20) {
+  }
+  else if (tensOnes < 20) {
     // Teens - add "en" if withAnd and after hundreds and < 13
     if (hundreds > 0 && withAnd && tensOnes < 13) {
       result += 'en' + TEENS[ones]
-    } else {
+    }
+    else {
       result += TEENS[ones]
     }
-  } else {
+  }
+  else {
     // 20-99: Dutch inverts with connector
     if (ones === 0) {
       result += TENS[tens]
-    } else {
+    }
+    else {
       // "ën" if ones ends in 'e' (twee, drie)
       const onesWord = ONES[ones]
       const connector = onesWord.endsWith('e') ? 'ën' : 'en'
@@ -108,17 +130,20 @@ function buildSegment (n, withAnd) {
 
 /**
  * Converts a non-negative integer to Dutch words.
- *
  * @param {bigint} n - Non-negative integer to convert
- * @param {Object} options - Conversion options
+ * @param {{accentOne: boolean, includeOptionalAnd: boolean, noHundredPairing: boolean}} options - Conversion options
  * @returns {string} Dutch words
  */
-function integerToWords (n, options) {
+function integerToWords(n, options) {
   if (n === 0n) return ZERO
 
   const { accentOne, includeOptionalAnd, noHundredPairing } = options
 
   // Apply één/een replacement
+  /**
+   * @param {string} word The word to apply accent replacement to
+   * @returns {string} The word with "een" replaced by "één" when accentOne is set
+   */
   const applyAccent = (word) => {
     if (accentOne) {
       return word.replace(/\been\b/g, 'één')
@@ -143,7 +168,8 @@ function integerToWords (n, options) {
         const lowWord = buildSegment(low, includeOptionalAnd)
         if (includeOptionalAnd && low < 13) {
           result += ' en ' + lowWord
-        } else {
+        }
+        else {
           result += ' ' + lowWord
         }
       }
@@ -160,7 +186,8 @@ function integerToWords (n, options) {
     if (thousands === 1) {
       // "duizend" not "eenduizend"
       result = SCALES[0]
-    } else {
+    }
+    else {
       // Compound: "vijfduizend"
       result = buildSegment(thousands, includeOptionalAnd) + SCALES[0]
     }
@@ -169,7 +196,8 @@ function integerToWords (n, options) {
       const remainderWord = buildSegment(remainder, includeOptionalAnd)
       if (includeOptionalAnd && remainder < 13) {
         result += ' en ' + remainderWord
-      } else {
+      }
+      else {
         result += ' ' + remainderWord
       }
     }
@@ -184,12 +212,11 @@ function integerToWords (n, options) {
 /**
  * Builds words for numbers >= 1,000,000.
  * Uses BigInt division for faster segment extraction (4x faster than string slicing).
- *
  * @param {bigint} n - Number >= 1,000,000
- * @param {Object} options - Conversion options
+ * @param {{accentOne: boolean, includeOptionalAnd: boolean, noHundredPairing: boolean}} options - Conversion options
  * @returns {string} Dutch words
  */
-function buildLargeNumberWords (n, options) {
+function buildLargeNumberWords(n, options) {
   const { includeOptionalAnd } = options
 
   // Extract segments using BigInt division (faster than string slicing)
@@ -215,29 +242,35 @@ function buildLargeNumberWords (n, options) {
       if (result) {
         if (prevWasScale && includeOptionalAnd && segment < 13) {
           result += ' en ' + word
-        } else {
+        }
+        else {
           result += ' ' + word
         }
-      } else {
+      }
+      else {
         result = word
       }
       prevWasScale = false
-    } else if (i === 1) {
+    }
+    else if (i === 1) {
       // Thousands - compound
       if (result) result += ' '
       if (segment === 1) {
         result += SCALES[0]
-      } else {
+      }
+      else {
         result += buildSegment(segment, includeOptionalAnd) + SCALES[0]
       }
       prevWasScale = true
-    } else {
+    }
+    else {
       // Million and above - space around scale
       const scaleWord = SCALES[i - 1]
       if (result) result += ' '
       if (segment === 1) {
         result += 'een ' + scaleWord
-      } else {
+      }
+      else {
         result += buildSegment(segment, includeOptionalAnd) + ' ' + scaleWord
       }
       prevWasScale = true
@@ -249,12 +282,11 @@ function buildLargeNumberWords (n, options) {
 
 /**
  * Converts decimal digits to Dutch words.
- *
  * @param {string} decimalPart - Decimal digits (without the point)
- * @param {Object} options - Conversion options
+ * @param {{accentOne: boolean, includeOptionalAnd: boolean, noHundredPairing: boolean}} options - Conversion options
  * @returns {string} Dutch words for decimal part
  */
-function decimalPartToWords (decimalPart, options) {
+function decimalPartToWords(decimalPart, options) {
   let result = ''
 
   // Handle leading zeros
@@ -276,37 +308,40 @@ function decimalPartToWords (decimalPart, options) {
   return result
 }
 
+/**
+ * @typedef {object} CardinalOptions
+ * @property {boolean} [accentOne] - Use "één" instead of "een"
+ * @property {boolean} [includeOptionalAnd] - Include "en" before small numbers
+ * @property {boolean} [noHundredPairing] - Disable hundred pairing (1104→duizend honderdvier)
+ */
+
+/** @type {Required<CardinalOptions>} */
+export const cardinalDefaults = { accentOne: true, includeOptionalAnd: false, noHundredPairing: false }
+
 /**
  * Converts a numeric value to Dutch 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
- * @param {Object} [options] - Optional configuration
- * @param {boolean} [options.accentOne=true] - Use "één" instead of "een"
- * @param {boolean} [options.includeOptionalAnd=false] - Include "en" before small numbers
- * @param {boolean} [options.noHundredPairing=false] - Disable hundred pairing (1104→duizend honderdvier)
+ * @param {CardinalOptions} [options] - Optional configuration
  * @returns {string} The number in Dutch words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCardinal(21)                        // 'eenentwintig'
  * toCardinal(1)                         // 'één'
  * toCardinal(1, {accentOne: false})     // 'een'
  * toCardinal(1104)                      // 'elfhonderd vier'
  */
-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 {
-    accentOne = true,
-    includeOptionalAnd = false,
-    noHundredPairing = false
-  } = options
+  const { accentOne, includeOptionalAnd, noHundredPairing } = resolveOptions(options, cardinalDefaults)
 
   const opts = { accentOne, includeOptionalAnd, noHundredPairing }
 
@@ -335,12 +370,11 @@ const ORDINAL_ONES = ['', 'eerste', 'tweede', 'derde', 'vierde', 'vijfde', 'zesd
 /**
  * Converts a small cardinal to ordinal.
  * Rules: 1-19 add -de (except eerste, derde, achtste), 20+ add -ste
- *
  * @param {string} cardinalWord - Cardinal word
  * @param {number} n - The number value (0-99)
  * @returns {string} Ordinal word
  */
-function smallCardinalToOrdinal (cardinalWord, n) {
+function smallCardinalToOrdinal(cardinalWord, n) {
   // Special cases for 1-9
   if (n >= 1 && n <= 9) return ORDINAL_ONES[n]
 
@@ -358,11 +392,10 @@ function smallCardinalToOrdinal (cardinalWord, n) {
 
 /**
  * Builds ordinal words for 0-999.
- *
  * @param {number} n - Number 0-999
  * @returns {string} Dutch ordinal words
  */
-function buildOrdinalSegment (n) {
+function buildOrdinalSegment(n) {
   if (n === 0) return ''
 
   const hundreds = Math.trunc(n / 100)
@@ -375,10 +408,11 @@ function buildOrdinalSegment (n) {
   }
 
   // Hundreds: need to build prefix + ordinal suffix
-  let prefix = ''
+  let prefix
   if (hundreds === 1) {
     prefix = HUNDRED
-  } else {
+  }
+  else {
     prefix = ONES[hundreds] + HUNDRED
   }
 
@@ -395,17 +429,16 @@ function buildOrdinalSegment (n) {
 
 /**
  * Converts a number to Dutch ordinal words.
- *
  * @param {number | string | bigint} value - The number to convert
  * @returns {string} Dutch ordinal words
- *
  * @example
  * toOrdinal(1)     // 'eerste'
  * toOrdinal(21)    // 'eenentwintigste'
  * toOrdinal(100)   // 'honderdste'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const n = parseOrdinalValue(value)
+  checkMax(n, ordinalMax)
 
   // Fast path: 1-9
   if (n < 10n) return ORDINAL_ONES[Number(n)]
@@ -427,11 +460,10 @@ function toOrdinal (value) {
 
 /**
  * Builds ordinal words for large numbers.
- *
  * @param {bigint} n - Non-negative integer >= 1000
  * @returns {string} Dutch ordinal words
  */
-function buildLargeOrdinal (n) {
+function buildLargeOrdinal(n) {
   // Extract segments
   const segments = []
   let temp = n
@@ -449,9 +481,6 @@ function buildLargeOrdinal (n) {
     }
   }
 
-  // Scale ordinal words
-  const SCALE_ORDINAL = ['', 'duizendste', 'miljoenste', 'miljardste', 'biljoenste', 'biljardste', 'triljoenste']
-
   let result = ''
 
   for (let i = segments.length - 1; i >= 0; i--) {
@@ -465,34 +494,42 @@ function buildLargeOrdinal (n) {
       if (i === 0) {
         // Units segment: use ordinal segment builder
         result += buildOrdinalSegment(segment)
-      } else if (segment === 1 && i > 0) {
+      }
+      else if (segment === 1 && i > 0) {
         // Exact scale: duizendste, miljoenste, etc.
         if (i === 1) {
           result += SCALE_ORDINAL[i]
-        } else {
+        }
+        else {
           result += 'een ' + SCALE_ORDINAL[i]
         }
-      } else {
+      }
+      else {
         // Segment + scale ordinal
         if (i === 1) {
           result += buildSegment(segment, false) + SCALE_ORDINAL[i]
-        } else {
+        }
+        else {
           result += buildSegment(segment, false) + ' ' + SCALE_ORDINAL[i]
         }
       }
-    } else {
+    }
+    else {
       // Higher segments use cardinal form
       if (i === 1) {
         if (segment === 1) {
           result += SCALES[0]
-        } else {
+        }
+        else {
           result += buildSegment(segment, false) + SCALES[0]
         }
-      } else {
+      }
+      else {
         const scaleWord = SCALES[i - 1]
         if (segment === 1) {
           result += 'een ' + scaleWord
-        } else {
+        }
+        else {
           result += buildSegment(segment, false) + ' ' + scaleWord
         }
       }
@@ -506,23 +543,28 @@ function buildLargeOrdinal (n) {
 // Currency Functions
 // ============================================================================
 
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [and] - Include "en" between euros and cents
+ */
+
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults = { and: true }
+
 /**
  * Converts a number to Dutch currency words (Euro).
- *
  * @param {number | string | bigint} value - The amount to convert
- * @param {Object} [options]
- * @param {boolean} [options.and=true] - Include "en" between euros and cents
+ * @param {CurrencyOptions} [options] Optional configuration
  * @returns {string} Dutch currency words
- *
  * @example
  * toCurrency(42.50)  // 'tweeënveertig euro en vijftig cent'
  * toCurrency(1)      // 'één euro'
  * toCurrency(0.01)   // 'één cent'
  */
-function toCurrency (value, options) {
-  options = validateOptions(options)
+function toCurrency(value, options) {
   const { isNegative, dollars: euros, cents } = parseCurrencyValue(value)
-  const { and = true } = options
+  checkMax(euros, currencyMax)
+  const { and } = resolveOptions(options, currencyDefaults)
 
   let result = ''
 

package/src/pa-IN.d.ts

@@ -1,18 +1,18 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
 /**
  * Converts a numeric value to Punjabi words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Punjabi words
  */
 export function toCardinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Punjabi 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 Punjabi currency words (Indian Rupee).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Punjabi 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/pa-IN.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
@@ -55,20 +57,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} Punjabi words for the segment
  */
-function buildSegment (n) {
+function buildSegment(n) {
   if (n === 0) return ''
   if (n < 100) return BELOW_HUNDRED[n]
 
@@ -90,11 +101,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} Punjabi words
  */
-function integerToWords (n) {
+function integerToWords(n) {
   if (n === 0n) return ZERO
 
   // Fast path: numbers < 1000 (direct lookup)
@@ -120,7 +130,8 @@ function integerToWords (n) {
 
     if (i === 0) {
       words.push(buildSegment(segment))
-    } else {
+    }
+    else {
       words.push(BELOW_HUNDRED[segment])
     }
 
@@ -132,7 +143,12 @@ function integerToWords (n) {
   return words.join(' ')
 }
 
-function decimalPartToWords (decimalPart) {
+/**
+ * Converts the fractional digit string to Punjabi words.
+ * @param {string} decimalPart - Digits after the decimal point
+ * @returns {string} Punjabi words for the decimal part
+ */
+function decimalPartToWords(decimalPart) {
   let result = ''
   let i = 0
 
@@ -153,12 +169,14 @@ function decimalPartToWords (decimalPart) {
 
 /**
  * Converts a numeric value to Punjabi words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Punjabi 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 = ''
 
@@ -183,11 +201,10 @@ function toCardinal (value) {
  * Converts a positive integer to Punjabi ordinal words.
  *
  * Punjabi ordinals: First 6 are irregular, then add -ਵਾਂ suffix.
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Punjabi ordinal words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   // Special ordinals for 1-6
   if (n >= 1n && n <= 6n) {
     return ORDINAL_SPECIAL[Number(n)]
@@ -200,20 +217,20 @@ function integerToOrdinal (n) {
 
 /**
  * Converts a numeric value to Punjabi 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)
 }
 
@@ -223,19 +240,18 @@ function toOrdinal (value) {
 
 /**
  * Converts a numeric value to Punjabi currency words (Indian Rupee).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Punjabi 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/pl-PL.d.ts

@@ -1,33 +1,45 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
+/**
+ * @typedef {object} CardinalOptions
+ * @property {('masculine'|'feminine')} [gender] - Gender for numbers < 1000
+ */
+/** @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 = {
+    /**
+     * - Gender for numbers < 1000
+     */
+    gender?: "feminine" | "masculine" | undefined;
+};
 /**
  * Converts a numeric value to Polish 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
- * @param {Object} [options] - Conversion options
- * @param {string} [options.gender='masculine'] - Gender for numbers < 1000
+ * @param {CardinalOptions} [options] - Conversion options
  * @returns {string} The number in Polish words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCardinal(1)                          // 'jeden'
  * toCardinal(1, { gender: 'feminine' })  // 'jedna'
  * toCardinal(1000)                       // 'tysiąc'
  * toCardinal(2000)                       // 'dwa tysiące'
  */
-export function toCardinal(value: number | string | bigint, options?: {
-    gender?: string | undefined;
-}): string;
+export function toCardinal(value: number | string | bigint, options?: CardinalOptions): string;
 /**
  * Converts a numeric value to Polish 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 (e.g., "pierwszy", "czterdziesty drugi")
  * @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)    // 'pierwszy'
  * toOrdinal(2)    // 'drugi'
@@ -40,12 +52,10 @@ export function toCardinal(value: number | string | bigint, options?: {
 export function toOrdinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Polish currency words (Polish Złoty).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Polish 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)     // 'czterdzieści dwa złote'
  * toCurrency(1)      // 'jeden złoty'