n2words 5.0.0 → 5.1.0

package/src/de-DE.js

@@ -15,7 +15,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)
@@ -39,6 +41,15 @@ const SCALES = ['tausend', 'Million', 'Milliarde', 'Billion', 'Billiarde', 'Tril
 // Pluralized scale words (million+)
 const SCALES_PLURAL = ['tausend', 'Millionen', 'Milliarden', 'Billionen', 'Billiarden', 'Trillionen', 'Trilliarden', 'Quadrillionen', 'Quadrilliarden']
 
+// Supported magnitude ceiling (checked at the public entry points). SCALES is
+// indexed [scaleIndex - 1] starting at 'tausend' (10^3), so segments are
+// [units, then one per SCALES entry] -> ceiling 10^((SCALES.length + 1) * 3) =
+// 10^30. Ordinal (cardinal + suffix) and currency build on the cardinal, and
+// the decimal is spelled via integerToWords, so all share the ceiling.
+export const cardinalMax = western(SCALES.length)
+export const ordinalMax = western(SCALES.length)
+export const currencyMax = western(SCALES.length)
+
 const HUNDRED = 'hundert'
 const ZERO = 'null'
 const NEGATIVE = 'minus'
@@ -75,11 +86,10 @@ const CENT = 'Cent'
 /**
  * Builds segment word for 0-999 (standalone form, uses "eins").
  * German inverts ones and tens: "einundzwanzig" = one-and-twenty
- *
  * @param {number} n - Number 0-999
  * @returns {string} German words for the segment
  */
-function buildSegment (n) {
+function buildSegment(n) {
   if (n === 0) return ''
 
   const ones = n % 10
@@ -97,14 +107,17 @@ function buildSegment (n) {
   if (tens === 1) {
     // Teens
     result += TEENS[ones]
-  } else if (tens >= 2 && ones > 0) {
+  }
+  else if (tens >= 2 && ones > 0) {
     // Inverted: "einundzwanzig" (one-and-twenty)
     // Use "ein" before "und", not "eins"
     result += (ones === 1 ? EIN : ONES[ones]) + 'und' + TENS[tens]
-  } else if (tens >= 2) {
+  }
+  else if (tens >= 2) {
     // Just tens
     result += TENS[tens]
-  } else if (ones > 0) {
+  }
+  else if (ones > 0) {
     // Just ones (no tens, possibly after hundreds)
     // Use "eins" for standalone/after hundreds
     result += ONES[ones]
@@ -116,11 +129,10 @@ function buildSegment (n) {
 /**
  * Builds segment word for use before "tausend".
  * Uses "ein" instead of "eins" for 1.
- *
  * @param {number} n - Number 0-999
  * @returns {string} German words for thousand context
  */
-function buildSegmentForThousand (n) {
+function buildSegmentForThousand(n) {
   if (n === 0) return ''
   if (n === 1) return EIN // "eintausend"
 
@@ -136,13 +148,17 @@ function buildSegmentForThousand (n) {
 
   if (tens === 1) {
     result += TEENS[ones]
-  } else if (tens >= 2 && ones > 0) {
+  }
+  else if (tens >= 2 && ones > 0) {
     result += (ones === 1 ? EIN : ONES[ones]) + 'und' + TENS[tens]
-  } else if (tens >= 2) {
+  }
+  else if (tens >= 2) {
     result += TENS[tens]
-  } else if (ones > 0 && hundreds > 0) {
+  }
+  else if (ones > 0 && hundreds > 0) {
     result += ONES[ones]
-  } else if (ones > 0) {
+  }
+  else if (ones > 0) {
     result += ONES[ones]
   }
 
@@ -155,11 +171,10 @@ function buildSegmentForThousand (n) {
 
 /**
  * Converts a non-negative integer to German words.
- *
  * @param {bigint} n - Non-negative integer to convert
  * @returns {string} German words
  */
-function integerToWords (n) {
+function integerToWords(n) {
   if (n === 0n) return ZERO
 
   // Fast path: numbers < 1000
@@ -188,11 +203,10 @@ function integerToWords (n) {
 
 /**
  * Builds words for numbers >= 1,000,000.
- *
  * @param {bigint} n - Number >= 1,000,000
  * @returns {string} German words
  */
-function buildLargeNumberWords (n) {
+function buildLargeNumberWords(n) {
   const numStr = n.toString()
   const len = numStr.length
 
@@ -222,16 +236,19 @@ function buildLargeNumberWords (n) {
       if (scaleIndex === 0) {
         // Units segment (no scale word)
         parts.push({ words: buildSegment(segment), isScale: false, scaleLevel: 0 })
-      } else if (scaleIndex === 1) {
+      }
+      else if (scaleIndex === 1) {
         // Thousands: compound without space
         const segWords = buildSegmentForThousand(segment)
         parts.push({ words: segWords + SCALES[0], isScale: false, scaleLevel: 1 })
-      } else {
+      }
+      else {
         // Million+ : space around scale word
         let segWords
         if (segment === 1) {
           segWords = 'eine' // "eine Million"
-        } else {
+        }
+        else {
           segWords = buildSegment(segment)
         }
         const scaleWord = segment === 1 ? SCALES[scaleIndex - 1] : SCALES_PLURAL[scaleIndex - 1]
@@ -250,11 +267,10 @@ function buildLargeNumberWords (n) {
 /**
  * Joins parts with German spacing rules.
  * Spaces only around million+ scale words.
- *
- * @param {Array} parts - Parts with metadata
+ * @param {Array<{words: string, isScale: boolean, scaleLevel: number}>} parts - Parts with metadata
  * @returns {string} Joined string
  */
-function joinGermanParts (parts) {
+function joinGermanParts(parts) {
   if (parts.length === 0) return ZERO
 
   let result = ''
@@ -281,11 +297,10 @@ function joinGermanParts (parts) {
 
 /**
  * Converts decimal digits to German words.
- *
  * @param {string} decimalPart - Decimal digits (without the point)
  * @returns {string} German words for decimal part
  */
-function decimalPartToWords (decimalPart) {
+function decimalPartToWords(decimalPart) {
   let result = ''
 
   // Handle leading zeros
@@ -311,19 +326,20 @@ 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 German words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCardinal(21)           // 'einundzwanzig'
  * toCardinal(1000)         // 'eintausend'
  * toCardinal(1000000)      // 'eine Million'
  */
-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 = ''
 
@@ -348,12 +364,11 @@ function toCardinal (value) {
  * Builds ordinal segment for 0-999.
  * Only the final component becomes ordinal.
  * Uses -te for 1-19, -ste for 20+.
- *
  * @param {number} n - Number 0-999
  * @param {boolean} isFinal - Whether this is the final segment (gets ordinal suffix)
  * @returns {string} German ordinal words for this segment
  */
-function buildOrdinalSegment (n, isFinal) {
+function buildOrdinalSegment(n, isFinal) {
   if (n === 0) return ''
 
   const ones = n % 10
@@ -372,28 +387,35 @@ function buildOrdinalSegment (n, isFinal) {
     // Teens: 10-19
     if (isFinal) {
       result += ORDINAL_TEENS[ones]
-    } else {
+    }
+    else {
       result += TEENS[ones]
     }
-  } else if (tens >= 2 && ones > 0) {
+  }
+  else if (tens >= 2 && ones > 0) {
     // Compound: einundzwanzig → einundzwanzigste
     if (isFinal) {
       result += (ones === 1 ? EIN : ONES[ones]) + 'und' + ORDINAL_TENS[tens]
-    } else {
+    }
+    else {
       result += (ones === 1 ? EIN : ONES[ones]) + 'und' + TENS[tens]
     }
-  } else if (tens >= 2) {
+  }
+  else if (tens >= 2) {
     // Just tens: zwanzig → zwanzigste
     if (isFinal) {
       result += ORDINAL_TENS[tens]
-    } else {
+    }
+    else {
       result += TENS[tens]
     }
-  } else if (ones > 0) {
+  }
+  else if (ones > 0) {
     // Just ones: eins → erste
     if (isFinal) {
       result += ORDINAL_ONES[ones]
-    } else {
+    }
+    else {
       result += ONES[ones]
     }
   }
@@ -408,11 +430,10 @@ function buildOrdinalSegment (n, isFinal) {
 
 /**
  * Converts integer to German ordinal words.
- *
  * @param {bigint} n - Positive integer
  * @returns {string} German ordinal words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   // Fast path: numbers < 1000
   if (n < 1000n) {
     return buildOrdinalSegment(Number(n), true)
@@ -438,11 +459,10 @@ function integerToOrdinal (n) {
 
 /**
  * Builds ordinal words for numbers >= 1,000,000.
- *
  * @param {bigint} n - Number >= 1,000,000
  * @returns {string} German ordinal words
  */
-function buildLargeOrdinal (n) {
+function buildLargeOrdinal(n) {
   const numStr = n.toString()
   const len = numStr.length
 
@@ -482,27 +502,32 @@ function buildLargeOrdinal (n) {
       if (scaleIndex === 0) {
         // Units segment
         parts.push({ words: buildOrdinalSegment(segment, true), isScale: false, scaleLevel: 0 })
-      } else if (scaleIndex === 1) {
+      }
+      else if (scaleIndex === 1) {
         // Thousands
         const segWords = buildSegmentForThousand(segment)
         if (isLowestSegment) {
           parts.push({ words: segWords + SCALES[0] + ORDINAL_SUFFIX, isScale: false, scaleLevel: 1 })
-        } else {
+        }
+        else {
           parts.push({ words: segWords + SCALES[0], isScale: false, scaleLevel: 1 })
         }
-      } else {
+      }
+      else {
         // Million+
         let segWords
         if (segment === 1) {
           segWords = 'eine'
-        } else {
+        }
+        else {
           segWords = buildSegment(segment)
         }
         const scaleWord = segment === 1 ? SCALES[scaleIndex - 1] : SCALES_PLURAL[scaleIndex - 1]
         parts.push({ words: segWords, isScale: false, scaleLevel: scaleIndex })
         if (isLowestSegment) {
           parts.push({ words: scaleWord + ORDINAL_SUFFIX, isScale: true, scaleLevel: scaleIndex })
-        } else {
+        }
+        else {
           parts.push({ words: scaleWord, isScale: true, scaleLevel: scaleIndex })
         }
       }
@@ -519,12 +544,10 @@ function buildLargeOrdinal (n) {
  *
  * German ordinals add -te for 1-19 and -ste for 20+.
  * Irregular forms: erste (1st), dritte (3rd), siebte (7th), achte (8th).
- *
  * @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)    // 'erste'
  * toOrdinal(2)    // 'zweite'
@@ -533,8 +556,9 @@ function buildLargeOrdinal (n) {
  * toOrdinal(100)  // 'einhundertste'
  * toOrdinal(1000) // 'eintausendste'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
+  checkMax(integerPart, ordinalMax)
   return integerToOrdinal(integerPart)
 }
 
@@ -542,16 +566,21 @@ function toOrdinal (value) {
 // CURRENCY: toCurrency(value, options?)
 // ============================================================================
 
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [and] - Use "und" between euros and cents
+ */
+
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults = { and: true }
+
 /**
  * Converts a numeric value to German currency words (Euro).
- *
  * @param {number | string | bigint} value - The currency amount to convert
- * @param {Object} [options] - Optional configuration
- * @param {boolean} [options.and=true] - Use "und" between euros and cents
+ * @param {CurrencyOptions} [options] - Optional configuration
  * @returns {string} The amount in German 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)                 // 'zweiundvierzig Euro und fünfzig Cent'
  * toCurrency(1)                     // 'ein Euro'
@@ -559,10 +588,10 @@ function toOrdinal (value) {
  * toCurrency(0.01)                  // 'ein Cent'
  * toCurrency(42.50, { and: false }) // 'zweiundvierzig Euro fünfzig Cent'
  */
-function toCurrency (value, options) {
-  options = validateOptions(options)
+function toCurrency(value, options) {
   const { isNegative, dollars: euros, cents } = parseCurrencyValue(value)
-  const { and: useAnd = true } = options
+  checkMax(euros, currencyMax)
+  const { and: useAnd } = resolveOptions(options, currencyDefaults)
 
   // Build result
   let result = ''
@@ -573,7 +602,8 @@ function toCurrency (value, options) {
     // Use "ein" instead of "eins" before Euro
     if (euros === 1n) {
       result += EIN
-    } else {
+    }
+    else {
       result += integerToWords(euros)
     }
     result += ' ' + EURO
@@ -587,7 +617,8 @@ function toCurrency (value, options) {
     // Use "ein" instead of "eins" before Cent
     if (cents === 1n) {
       result += EIN
-    } else {
+    }
+    else {
       result += integerToWords(cents)
     }
     result += ' ' + CENT

package/src/el-GR.d.ts

@@ -1,11 +1,12 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
 /**
  * Converts a numeric value to Greek words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Greek words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCardinal(21)       // 'είκοσι ένα'
  * toCardinal(1000)     // 'χίλια'
@@ -14,12 +15,10 @@
 export function toCardinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Greek ordinal words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The ordinal in Greek 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)  // 'εικοστός πρώτος'
@@ -27,12 +26,10 @@ export function toCardinal(value: number | string | bigint): string;
 export function toOrdinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Greek Euro currency words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The currency in Greek 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)  // 'δύο ευρώ πενήντα λεπτά'

package/src/el-GR.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 { bounded, western } from './utils/scale.js'
 
 // ============================================================================
 // Vocabulary (module-level constants)
@@ -36,6 +38,11 @@ const DECIMAL_SEP = 'κόμμα'
 // Short scale
 const SCALES = ['εκατομμύριο', 'δισεκατομμύριο', 'τρισεκατομμύριο']
 
+// Supported magnitude ceiling (checked at the public entry points), derived from the scale table.
+export const cardinalMax = western(SCALES.length + 1)
+export const ordinalMax = bounded(9)
+export const currencyMax = western(SCALES.length + 1)
+
 // Ordinal vocabulary
 const ORDINAL_ONES = ['', 'πρώτος', 'δεύτερος', 'τρίτος', 'τέταρτος', 'πέμπτος', 'έκτος', 'έβδομος', 'όγδοος', 'ένατος']
 
@@ -58,8 +65,10 @@ const CENT_FORMS = ['λεπτό', 'λεπτά'] // Singular, plural
 
 /**
  * Builds segment word for 0-999.
+ * @param {number} n - Number 0-999
+ * @returns {string} Greek words for the segment
  */
-function buildSegment (n) {
+function buildSegment(n) {
   if (n === 0) return ''
 
   const ones = n % 10
@@ -78,13 +87,17 @@ function buildSegment (n) {
 
   if (tensOnes === 0) {
     // Just hundreds
-  } else if (tensOnes < 10) {
+  }
+  else if (tensOnes < 10) {
     parts.push(ONES[ones])
-  } else if (tensOnes < 20) {
+  }
+  else if (tensOnes < 20) {
     parts.push(TEENS[ones])
-  } else if (ones === 0) {
+  }
+  else if (ones === 0) {
     parts.push(TENS[tens])
-  } else {
+  }
+  else {
     parts.push(TENS[tens] + ' ' + ONES[ones])
   }
 
@@ -97,11 +110,10 @@ function buildSegment (n) {
 
 /**
  * Converts a non-negative integer to Greek words.
- *
  * @param {bigint} n - Non-negative integer to convert
  * @returns {string} Greek words
  */
-function integerToWords (n) {
+function integerToWords(n) {
   if (n === 0n) return ZERO
 
   // Fast path: numbers < 1000 (direct lookup)
@@ -118,7 +130,8 @@ function integerToWords (n) {
     let result
     if (thousands === 1) {
       result = THOUSAND
-    } else {
+    }
+    else {
       result = buildSegment(thousands) + ' ' + THOUSAND
     }
 
@@ -135,11 +148,10 @@ function integerToWords (n) {
 
 /**
  * Builds words for numbers >= 1,000,000.
- *
  * @param {bigint} n - Number >= 1,000,000
  * @returns {string} Greek words
  */
-function buildLargeNumberWords (n) {
+function buildLargeNumberWords(n) {
   const numStr = n.toString()
   const len = numStr.length
 
@@ -171,19 +183,23 @@ function buildLargeNumberWords (n) {
       if (scaleIndex === 0) {
         // Units segment
         parts.push(segmentWord)
-      } else if (scaleIndex === 1) {
+      }
+      else if (scaleIndex === 1) {
         // Thousands - omit "ένα" before χίλια
         if (segment === 1) {
           parts.push(THOUSAND)
-        } else {
+        }
+        else {
           parts.push(segmentWord + ' ' + THOUSAND)
         }
-      } else {
+      }
+      else {
         // Millions+ - omit "ένα" before scale words
         const scaleWord = SCALES[scaleIndex - 2]
         if (segment === 1) {
           parts.push(scaleWord)
-        } else {
+        }
+        else {
           parts.push(segmentWord + ' ' + scaleWord)
         }
       }
@@ -197,18 +213,18 @@ function buildLargeNumberWords (n) {
 
 /**
  * Converts decimal digits to Greek words (per-digit).
- *
  * @param {string} decimalPart - Decimal digits (without the point)
  * @returns {string} Greek words for decimal part
  */
-function decimalPartToWords (decimalPart) {
+function decimalPartToWords(decimalPart) {
   const parts = []
 
   for (const digit of decimalPart) {
     const d = parseInt(digit, 10)
     if (d === 0) {
       parts.push(ZERO)
-    } else {
+    }
+    else {
       parts.push(ONES[d])
     }
   }
@@ -218,19 +234,18 @@ function decimalPartToWords (decimalPart) {
 
 /**
  * Converts a numeric value to Greek words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Greek words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCardinal(21)       // 'είκοσι ένα'
  * toCardinal(1000)     // 'χίλια'
  * toCardinal('3.14')   // 'τρία κόμμα ένα τέσσερα'
  */
-function toCardinal (value) {
+function toCardinal(value) {
   const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
+  checkMax(integerPart, cardinalMax)
 
   let result = ''
 
@@ -253,11 +268,10 @@ function toCardinal (value) {
 
 /**
  * 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]
@@ -273,11 +287,10 @@ function buildOrdinalTensOnes (n) {
 
 /**
  * Converts a non-negative integer to Greek ordinal words.
- *
  * @param {bigint} n - Non-negative integer to convert
  * @returns {string} Greek ordinal words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   if (n === 0n) return ''
   if (n === 1n) return ORDINAL_ONES[1]
 
@@ -313,7 +326,8 @@ function integerToOrdinal (n) {
     let result
     if (thousands === 1) {
       result = THOUSAND
-    } else {
+    }
+    else {
       result = buildSegment(thousands) + ' ' + THOUSAND
     }
 
@@ -345,7 +359,8 @@ function integerToOrdinal (n) {
   let result
   if (millions === 1) {
     result = SCALES[0]
-  } else {
+  }
+  else {
     result = buildSegment(millions) + ' ' + SCALES[0]
   }
 
@@ -354,18 +369,17 @@ function integerToOrdinal (n) {
 
 /**
  * Converts a numeric value to Greek ordinal words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The ordinal in Greek 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)
 }
 
@@ -375,18 +389,17 @@ function toOrdinal (value) {
 
 /**
  * Converts a numeric value to Greek Euro currency words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The currency in Greek 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 = []