n2words 5.0.0 → 5.1.0

package/src/da-DK.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)
@@ -38,12 +40,21 @@ const DECIMAL_SEP = 'komma'
 // Long scale: millioner, millarder, billioner, etc.
 const SCALES = ['millioner', 'millarder', 'billioner', 'billarder', 'trillioner', 'trillarder', 'quadrillioner', 'quadrillarder']
 
+// Supported magnitude ceiling (checked at the public entry points). Segments
+// are [units, thousands, then one per SCALES entry], so cardinals span at most
+// SCALES.length + 2 groups of 3 digits — they must stay below 10^30. Ordinals
+// and currency build on the cardinal, so they share the same ceiling.
+export const cardinalMax = western(SCALES.length + 1)
+export const ordinalMax = western(SCALES.length + 1)
+export const currencyMax = western(SCALES.length + 1)
+
 // ============================================================================
 // Ordinal Vocabulary
 // ============================================================================
 
 // Danish ordinals: 1st-2nd special, others use -te/-nde suffix
 // "anden/andet" for 2nd (common/neuter), we use common form
+/** @type {Record<number, string>} */
 const ORDINAL_SPECIAL = {
   1: 'første',
   2: 'anden',
@@ -56,7 +67,7 @@ const ORDINAL_SPECIAL = {
   9: 'niende',
   10: 'tiende',
   11: 'ellevte',
-  12: 'tolvte'
+  12: 'tolvte',
 }
 
 // ============================================================================
@@ -73,8 +84,10 @@ const ORE = 'øre' // same singular and plural
 
 /**
  * Builds segment word for 0-999.
+ * @param {number} n - Integer in range 0-999
+ * @returns {string} Danish words for the segment
  */
-function buildSegment (n) {
+function buildSegment(n) {
   if (n === 0) return ''
 
   const ones = n % 10
@@ -93,16 +106,20 @@ function buildSegment (n) {
 
   if (tensOnes === 0) {
     // Just hundreds
-  } else if (tensOnes < 10) {
+  }
+  else if (tensOnes < 10) {
     // Single digit
     parts.push(ONES[ones])
-  } else if (tensOnes < 20) {
+  }
+  else if (tensOnes < 20) {
     // Teens
     parts.push(TEENS[ones])
-  } else if (ones === 0) {
+  }
+  else if (ones === 0) {
     // Even tens
     parts.push(TENS[tens])
-  } else {
+  }
+  else {
     // Units-before-tens: "enogtyve", "treogfyrre"
     parts.push(ONES_VIGESIMAL[ones] + 'og' + TENS[tens])
   }
@@ -120,11 +137,10 @@ function buildSegment (n) {
 
 /**
  * Converts a non-negative integer to Danish words.
- *
  * @param {bigint} n - Non-negative integer to convert
  * @returns {string} Danish words
  */
-function integerToWords (n) {
+function integerToWords(n) {
   if (n === 0n) return ZERO
 
   // Fast path: numbers < 1000 (direct lookup)
@@ -154,11 +170,10 @@ function integerToWords (n) {
 
 /**
  * Builds words for numbers >= 1,000,000.
- *
  * @param {bigint} n - Number >= 1,000,000
  * @returns {string} Danish words
  */
-function buildLargeNumberWords (n) {
+function buildLargeNumberWords(n) {
   const numStr = n.toString()
   const len = numStr.length
 
@@ -178,6 +193,7 @@ function buildLargeNumberWords (n) {
   }
 
   // Convert segments to words with scale tracking
+  // Callers guard the magnitude (cardinalMax) before reaching here.
   // scaleIndex: 0 = units, 1 = thousands, 2 = millions, etc.
   const parts = []
   let scaleIndex = segments.length - 1
@@ -191,10 +207,12 @@ function buildLargeNumberWords (n) {
       if (scaleIndex === 0) {
         // Units segment
         parts.push({ word: segmentWord, type: 'units' })
-      } else if (scaleIndex === 1) {
+      }
+      else if (scaleIndex === 1) {
         // Thousands - compound form
         parts.push({ word: segmentWord + THOUSAND, type: 'thousand' })
-      } else {
+      }
+      else {
         // Millions+ - space-separated, use "en" for 1
         const scaleWord = SCALES[scaleIndex - 2]
         let numWord = segmentWord
@@ -217,50 +235,38 @@ function buildLargeNumberWords (n) {
  * Joins parts with Danish spacing rules.
  * - After thousands with remainder: "tusinde og"
  * - Millions are space-separated
- *
- * @param {Array} parts - Parts with type metadata
+ * @param {Array<{word: string, type: string}>} parts - Parts with type metadata
  * @returns {string} Joined string
  */
-function joinDanishParts (parts) {
+function joinDanishParts(parts) {
   if (parts.length === 0) return ZERO
-  if (parts.length === 1) return parts[0].word
 
-  const result = []
+  const tokens = []
 
   for (let i = 0; i < parts.length; i++) {
     const part = parts[i]
     const nextPart = parts[i + 1]
 
     if (part.type === 'thousand' && nextPart && nextPart.type === 'units') {
-      // Thousands followed by units: add "e og"
-      result.push(part.word + 'e og ' + nextPart.word)
-      i++ // Skip the units part
-    } else if (part.type === 'million') {
-      if (result.length > 0) {
-        result.push(' ')
-      }
-      result.push(part.word)
-      if (nextPart) {
-        result.push(' ')
-      }
-    } else {
-      if (result.length > 0 && !result[result.length - 1].endsWith(' ')) {
-        result.push(' ')
-      }
-      result.push(part.word)
+      // Thousands directly followed by the units segment: compound "…tusinde og …"
+      tokens.push(part.word + 'e og ' + nextPart.word)
+      i++ // consumed the units part
+    }
+    else {
+      tokens.push(part.word)
     }
   }
 
-  return result.join('')
+  // Every remaining boundary (between scale groups) is a single space.
+  return tokens.join(' ')
 }
 
 /**
  * Converts decimal digits to Danish words.
- *
  * @param {string} decimalPart - Decimal digits (without the point)
  * @returns {string} Danish words for decimal part
  */
-function decimalPartToWords (decimalPart) {
+function decimalPartToWords(decimalPart) {
   let result = ''
 
   // Handle leading zeros
@@ -283,19 +289,20 @@ function decimalPartToWords (decimalPart) {
 
 /**
  * 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'
  * toCardinal(1000000)  // 'en millioner'
  */
-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 = ''
 
@@ -321,11 +328,10 @@ function toCardinal (value) {
  *
  * Danish ordinals: første (1st), anden (2nd), tredje (3rd), etc.
  * 1-12 have special forms, others use cardinal + -de/-nde suffix.
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Danish ordinal words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   // Special forms for 1-12
   if (n >= 1n && n <= 12n) {
     return ORDINAL_SPECIAL[Number(n)]
@@ -338,19 +344,18 @@ function integerToOrdinal (n) {
 
 /**
  * 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'
  * toOrdinal(21)   // 'enogtyvede'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
+  checkMax(integerPart, ordinalMax)
   return integerToOrdinal(integerPart)
 }
 
@@ -362,19 +367,18 @@ function toOrdinal (value) {
  * 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'
  * toCurrency(1.50)   // 'en krone og halvtreds øre'
  */
-function toCurrency (value) {
+function toCurrency(value) {
   const { isNegative, dollars: kroner, cents: ore } = parseCurrencyValue(value)
+  checkMax(kroner, currencyMax)
 
   let result = ''
   if (isNegative) {
@@ -385,7 +389,8 @@ function toCurrency (value) {
   if (kroner > 0n || ore === 0n) {
     if (kroner === 1n) {
       result += 'en ' + KRONE
-    } else {
+    }
+    else {
       result += integerToWords(kroner) + ' ' + KRONER
     }
   }

package/src/de-DE.d.ts

@@ -1,14 +1,27 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [and] - Use "und" between euros and cents
+ */
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults: Required<CurrencyOptions>;
+export type CurrencyOptions = {
+    /**
+     * - Use "und" between euros and cents
+     */
+    and?: boolean | undefined;
+};
 /**
  * Converts a numeric value to German 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 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'
@@ -20,12 +33,10 @@ export function toCardinal(value: number | string | bigint): string;
  *
  * 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'
@@ -37,14 +48,11 @@ export function toCardinal(value: number | string | bigint): string;
 export function toOrdinal(value: number | string | bigint): string;
 /**
  * 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'
@@ -52,6 +60,4 @@ export function toOrdinal(value: number | string | bigint): string;
  * toCurrency(0.01)                  // 'ein Cent'
  * toCurrency(42.50, { and: false }) // 'zweiundvierzig Euro fünfzig Cent'
  */
-export function toCurrency(value: number | string | bigint, options?: {
-    and?: boolean | undefined;
-}): string;
+export function toCurrency(value: number | string | bigint, options?: CurrencyOptions): string;