n2words 5.0.0 → 5.1.0

package/src/pl-PL.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)
@@ -31,6 +33,7 @@ const TENS = ['', '', 'dwadzieścia', 'trzydzieści', 'czterdzieści', 'pięćdz
 const HUNDREDS = ['', 'sto', 'dwieście', 'trzysta', 'czterysta', 'pięćset', 'sześćset', 'siedemset', 'osiemset', 'dziewięćset']
 
 // Scale words: [singular, few (2-4), many (5+)]
+/** @type {Record<number, string[]>} */
 const PLURAL_FORMS = {
   1: ['tysiąc', 'tysiące', 'tysięcy'],
   2: ['milion', 'miliony', 'milionów'],
@@ -41,7 +44,7 @@ const PLURAL_FORMS = {
   7: ['tryliard', 'tryliardy', 'tryliardów'],
   8: ['kwadrylion', 'kwadryliony', 'kwadrylionów'],
   9: ['kwaryliard', 'kwadryliardy', 'kwadryliardów'],
-  10: ['kwintylion', 'kwintyliony', 'kwintylionów']
+  10: ['kwintylion', 'kwintyliony', 'kwintylionów'],
 }
 
 const ZERO = 'zero'
@@ -86,7 +89,7 @@ const GROSZ_FORMS = ['grosz', 'grosze', 'groszy']
  * @param {number} n - Segment value
  * @returns {string} Polish word
  */
-function buildSegment (n) {
+function buildSegment(n) {
   if (n === 0) return ''
 
   const ones = n % 10
@@ -104,7 +107,8 @@ function buildSegment (n) {
   if (tens === 1) {
     // Teens (10-19)
     parts.push(TEENS[ones])
-  } else {
+  }
+  else {
     if (tens >= 2) {
       parts.push(TENS[tens])
     }
@@ -121,7 +125,7 @@ function buildSegment (n) {
  * @param {number} n - Segment value
  * @returns {string} Polish word
  */
-function buildSegmentFeminine (n) {
+function buildSegmentFeminine(n) {
   if (n === 0) return ''
 
   const ones = n % 10
@@ -138,7 +142,8 @@ function buildSegmentFeminine (n) {
   // Tens and ones - feminine for ones only
   if (tens === 1) {
     parts.push(TEENS[ones])
-  } else {
+  }
+  else {
     if (tens >= 2) {
       parts.push(TENS[tens])
     }
@@ -157,12 +162,11 @@ function buildSegmentFeminine (n) {
 /**
  * Polish pluralization: 1 = singular, 2-4 = few, else = many.
  * Special case: 11-19 always use many form.
- *
  * @param {bigint} n - Number to pluralize
  * @param {string[]} forms - [singular, few, many]
  * @returns {string} Correct plural form
  */
-function pluralize (n, forms) {
+function pluralize(n, forms) {
   if (n === 1n) {
     return forms[0]
   }
@@ -185,12 +189,11 @@ function pluralize (n, forms) {
 
 /**
  * Converts a non-negative integer to Polish words.
- *
  * @param {bigint} n - Non-negative integer to convert
- * @param {Object} options - Conversion options
+ * @param {string} gender - Gender for numbers < 1000 ('masculine' or 'feminine')
  * @returns {string} Polish words
  */
-function integerToWords (n, gender) {
+function integerToWords(n, gender) {
   if (n === 0n) return ZERO
 
   // Fast path: numbers < 1000
@@ -209,7 +212,8 @@ function integerToWords (n, gender) {
     if (thousands === 1) {
       // Omit "jeden" before tysiąc
       result = scaleWord
-    } else {
+    }
+    else {
       result = buildSegment(thousands) + ' ' + scaleWord
     }
 
@@ -221,18 +225,16 @@ function integerToWords (n, gender) {
   }
 
   // For numbers >= 1,000,000, use scale decomposition
-  return buildLargeNumberWords(n, gender)
+  return buildLargeNumberWords(n)
 }
 
 /**
  * Builds words for numbers >= 1,000,000.
  * Uses BigInt division for faster segment extraction.
- *
  * @param {bigint} n - Number >= 1,000,000
- * @param {Object} options - Conversion options
  * @returns {string} Polish words
  */
-function buildLargeNumberWords (n, gender) {
+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 = []
@@ -256,7 +258,8 @@ function buildLargeNumberWords (n, gender) {
     if (i === 0) {
       // Units segment
       result += segmentWord
-    } else {
+    }
+    else {
       // Scale word needed
       const forms = PLURAL_FORMS[i]
       if (forms) {
@@ -265,7 +268,8 @@ function buildLargeNumberWords (n, gender) {
         if (segment === 1n) {
           // Omit "jeden" before scale words
           result += scaleWord
-        } else {
+        }
+        else {
           result += segmentWord + ' ' + scaleWord
         }
       }
@@ -277,12 +281,11 @@ function buildLargeNumberWords (n, gender) {
 
 /**
  * Converts decimal digits to Polish words.
- *
  * @param {string} decimalPart - Decimal digits (without the point)
- * @param {Object} options - Conversion options
+ * @param {string} gender - Gender for numbers < 1000 ('masculine' or 'feminine')
  * @returns {string} Polish words for decimal part
  */
-function decimalPartToWords (decimalPart, gender) {
+function decimalPartToWords(decimalPart, gender) {
   let result = ''
 
   // Handle leading zeros
@@ -303,31 +306,52 @@ function decimalPartToWords (decimalPart, gender) {
   return result
 }
 
+// Supported magnitude ceilings (checked at the public entry points). PLURAL_FORMS
+// is keyed by scale level (1 = thousands, …), units separate, so cardinal/
+// currency reach 10^((maxScaleKey + 1) * 3) = 10^33; the shorter ORDINAL_SCALES
+// bounds ordinals at 10^((length + 1) * 3) = 10^24. (Past the cardinal ceiling
+// the fraction would spell silently-wrong, so the decimal is guarded too.)
+// Derive from the max numeric key (robust to gaps / non-scale keys).
+const MAX_SCALE_KEY = Math.max(...Object.keys(PLURAL_FORMS).map(Number))
+export const cardinalMax = western(MAX_SCALE_KEY)
+export const ordinalMax = western(ORDINAL_SCALES.length)
+export const currencyMax = western(MAX_SCALE_KEY)
+
+/**
+ * @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 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'
  */
-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 = ''
 
@@ -351,11 +375,10 @@ function toCardinal (value, options) {
 /**
  * Builds ordinal for a 0-99 segment when it's the final (ordinal) part.
  * Returns ordinal form: "pierwszy", "dwudziesty pierwszy", etc.
- *
  * @param {number} n - Number 0-99
  * @returns {string} Ordinal words
  */
-function buildOrdinalTensOnes (n) {
+function buildOrdinalTensOnes(n) {
   if (n === 0) return ''
 
   const onesDigit = n % 10
@@ -386,11 +409,10 @@ function buildOrdinalTensOnes (n) {
  *
  * In Polish ordinals, only the LAST component becomes ordinal.
  * E.g., 121 = "sto dwudziesty pierwszy" (one hundred twenty-first)
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Ordinal Polish words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   // Fast path: numbers < 100
   if (n < 100n) {
     return buildOrdinalTensOnes(Number(n))
@@ -438,11 +460,10 @@ function integerToOrdinal (n) {
 /**
  * Builds ordinal words for numbers >= 1,000,000.
  * All segments except the final one are cardinal; final segment is ordinal.
- *
  * @param {bigint} n - Number >= 1,000,000
  * @returns {string} Ordinal Polish words
  */
-function buildLargeOrdinal (n) {
+function buildLargeOrdinal(n) {
   const numStr = n.toString()
   const len = numStr.length
 
@@ -480,26 +501,31 @@ function buildLargeOrdinal (n) {
         // Units position (no scale)
         if (isLastNonZero) {
           parts.push(integerToOrdinal(BigInt(segment)))
-        } else {
+        }
+        else {
           parts.push(buildSegment(segment))
         }
-      } else {
+      }
+      else {
         // Has scale word
         if (isLastNonZero) {
           // This scale position is the final ordinal
           if (segment === 1) {
             parts.push(ORDINAL_SCALES[scaleIndex - 1])
-          } else {
+          }
+          else {
             // Use cardinal segment + ordinal scale
             parts.push(buildSegment(segment) + ' ' + ORDINAL_SCALES[scaleIndex - 1])
           }
-        } else {
+        }
+        else {
           // Not the final segment: use cardinal
           const forms = PLURAL_FORMS[scaleIndex]
           const scaleWord = forms ? pluralize(BigInt(segment), forms) : ''
           if (segment === 1) {
             parts.push(scaleWord)
-          } else {
+          }
+          else {
             parts.push(buildSegment(segment) + ' ' + scaleWord)
           }
         }
@@ -514,12 +540,10 @@ function buildLargeOrdinal (n) {
 
 /**
  * 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'
@@ -529,8 +553,9 @@ function buildLargeOrdinal (n) {
  * toOrdinal(100)  // 'setny'
  * toOrdinal(1000) // 'tysięczny'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
+  checkMax(integerPart, ordinalMax)
   return integerToOrdinal(integerPart)
 }
 
@@ -540,20 +565,19 @@ function toOrdinal (value) {
 
 /**
  * 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'
  * toCurrency(1.50)   // 'jeden złoty pięćdziesiąt groszy'
  * toCurrency(-5)     // 'minus pięć złotych'
  */
-function toCurrency (value) {
+function toCurrency(value) {
   const { isNegative, dollars: zloty, cents: grosze } = parseCurrencyValue(value)
+  checkMax(zloty, currencyMax)
 
   let result = ''
   if (isNegative) {

package/src/pt-BR.d.ts

@@ -1,31 +1,42 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [and] - Include "e" between major and minor units
+ * @property {string} [currency] - Currency code (e.g., 'BRL', 'USD'); empty means auto-detect for pt-BR
+ */
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults: Required<CurrencyOptions>;
+export type CurrencyOptions = {
+    /**
+     * - Include "e" between major and minor units
+     */
+    and?: boolean | undefined;
+    /**
+     * - Currency code (e.g., 'BRL', 'USD'); empty means auto-detect for pt-BR
+     */
+    currency?: string | undefined;
+};
 /**
  * Converts a numeric value to Portuguese words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Portuguese words
  */
 export function toCardinal(value: number | string | bigint): string;
 /**
  * Converts a number to Portuguese ordinal words.
- *
  * @param {number | string | bigint} value - The number to convert
  * @returns {string} Portuguese ordinal words
  */
 export function toOrdinal(value: number | string | bigint): string;
 /**
  * Converts a number to Brazilian Portuguese currency words.
- *
  * @param {number | string | bigint} value - The amount to convert
- * @param {Object} [options]
- * @param {boolean} [options.and=true] - Include "e" between major and minor units
- * @param {string} [options.currency] - Currency code (e.g., 'BRL', 'USD')
+ * @param {CurrencyOptions} [options] Currency formatting options
  * @returns {string} Brazilian Portuguese currency words
- *
  * @example
  * toCurrency(42.50)                    // 'quarenta e dois reais e cinquenta centavos'
  * toCurrency(42.50, {currency: 'USD'}) // 'quarenta e dois dólares e cinquenta centavos'
  */
-export function toCurrency(value: number | string | bigint, options?: {
-    and?: boolean | undefined;
-    currency?: string | undefined;
-}): string;
+export function toCurrency(value: number | string | bigint, options?: CurrencyOptions): string;