n2words 4.0.0 → 5.1.0

package/src/ms-MY.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 { western } from './utils/scale.js'
 
 // ============================================================================
 // Vocabulary
@@ -26,6 +28,11 @@ const HUNDRED_WORD = 'ratus'
 const THOUSAND_WORD = 'ribu'
 const SCALE_WORDS = ['juta', 'bilion', 'trilion']
 
+// Supported magnitude ceiling (checked at the public entry points), derived from the scale table.
+export const cardinalMax = western(SCALE_WORDS.length + 1)
+export const ordinalMax = western(SCALE_WORDS.length + 1)
+export const currencyMax = western(SCALE_WORDS.length + 1)
+
 const ZERO = 'sifar'
 const NEGATIVE = 'minus'
 const DECIMAL_SEP = 'perpuluhan'
@@ -49,7 +56,12 @@ const SEN = 'sen'
 // Segment Building
 // ============================================================================
 
-function buildSegment (n) {
+/**
+ * Builds the words for a number segment (0-999).
+ * @param {number} n - Integer segment in range 0-999
+ * @returns {string} The segment in Malay words
+ */
+function buildSegment(n) {
   if (n === 0) return ''
 
   const onesDigit = n % 10
@@ -62,7 +74,8 @@ function buildSegment (n) {
   if (hundredsDigit > 0) {
     if (hundredsDigit === 1) {
       parts.push('se' + HUNDRED_WORD)
-    } else {
+    }
+    else {
       parts.push(ONES[hundredsDigit] + ' ' + HUNDRED_WORD)
     }
   }
@@ -72,13 +85,17 @@ function buildSegment (n) {
 
   if (tensOnes === 0) {
     // Just hundreds
-  } else if (tensOnes < 10) {
+  }
+  else if (tensOnes < 10) {
     parts.push(ONES[tensOnes])
-  } else if (tensOnes < 20) {
+  }
+  else if (tensOnes < 20) {
     parts.push(TEENS[tensOnes - 10])
-  } else if (onesDigit === 0) {
+  }
+  else if (onesDigit === 0) {
     parts.push(TENS[tensDigit])
-  } else {
+  }
+  else {
     parts.push(TENS[tensDigit] + ' ' + ONES[onesDigit])
   }
 
@@ -89,7 +106,12 @@ function buildSegment (n) {
 // Conversion Functions
 // ============================================================================
 
-function integerToWords (n) {
+/**
+ * Converts a non-negative integer to Malay words.
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} The integer in Malay words
+ */
+function integerToWords(n) {
   if (n === 0n) return ZERO
 
   if (n < 1000n) {
@@ -103,7 +125,8 @@ function integerToWords (n) {
     let result
     if (thousands === 1) {
       result = 'se' + THOUSAND_WORD
-    } else {
+    }
+    else {
       result = buildSegment(thousands) + ' ' + THOUSAND_WORD
     }
 
@@ -117,7 +140,12 @@ function integerToWords (n) {
   return buildLargeNumberWords(n)
 }
 
-function buildLargeNumberWords (n) {
+/**
+ * Builds words for large numbers (>= 1,000,000) using scale words.
+ * @param {bigint} n - Integer to convert (>= 1,000,000)
+ * @returns {string} The integer in Malay words
+ */
+function buildLargeNumberWords(n) {
   const numStr = n.toString()
   const len = numStr.length
 
@@ -144,18 +172,22 @@ function buildLargeNumberWords (n) {
     if (segment !== 0) {
       if (scaleIndex === 0) {
         parts.push(buildSegment(segment))
-      } else if (scaleIndex === 1) {
+      }
+      else if (scaleIndex === 1) {
         if (segment === 1) {
           parts.push('se' + THOUSAND_WORD)
-        } else {
+        }
+        else {
           parts.push(buildSegment(segment) + ' ' + THOUSAND_WORD)
         }
-      } else {
+      }
+      else {
         // Malay: "se-" prefix for ALL scale words when segment is 1
         const scaleWord = SCALE_WORDS[scaleIndex - 2]
         if (segment === 1) {
           parts.push('se' + scaleWord)
-        } else {
+        }
+        else {
           parts.push(buildSegment(segment) + ' ' + scaleWord)
         }
       }
@@ -167,7 +199,12 @@ function buildLargeNumberWords (n) {
   return parts.join(' ')
 }
 
-function decimalPartToWords (decimalPart) {
+/**
+ * Converts the decimal part (digit string) to Malay words.
+ * @param {string} decimalPart - Decimal digits as a string
+ * @returns {string} The decimal digits in Malay words
+ */
+function decimalPartToWords(decimalPart) {
   let result = ''
 
   let i = 0
@@ -188,12 +225,12 @@ function decimalPartToWords (decimalPart) {
 
 /**
  * Converts a numeric value to Malay words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Malay words
  */
-function toCardinal (value) {
+function toCardinal(value) {
   const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
+  checkMax(integerPart, cardinalMax, decimalPart)
 
   let result = ''
 
@@ -219,11 +256,10 @@ function toCardinal (value) {
  *
  * Malay ordinals use "ke-" prefix + cardinal number.
  * Special case: "pertama" for 1st (not "kesatu").
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Malay ordinal words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   // Special case: 1st is "pertama"
   if (n === 1n) {
     return ORDINAL_FIRST
@@ -235,19 +271,18 @@ function integerToOrdinal (n) {
 
 /**
  * Converts a numeric value to Malay 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'
  * toOrdinal(10)   // 'kesepuluh'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
+  checkMax(integerPart, ordinalMax)
   return integerToOrdinal(integerPart)
 }
 
@@ -259,19 +294,18 @@ function toOrdinal (value) {
  * Converts a numeric value to Malay currency words (Ringgit).
  *
  * Malaysian Ringgit uses sen as subunit (100 sen = 1 ringgit).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Malay 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 ringgit'
  * toCurrency(1.50)   // 'satu ringgit lima puluh sen'
  * toCurrency(-5)     // 'minus lima ringgit'
  */
-function toCurrency (value) {
+function toCurrency(value) {
   const { isNegative, dollars: ringgit, cents: sen } = parseCurrencyValue(value)
+  checkMax(ringgit, currencyMax)
 
   let result = ''
   if (isNegative) {

package/src/nb-NO.d.ts

@@ -1,11 +1,12 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
 /**
  * Converts a numeric value to Norwegian Bokmål words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Norwegian words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCardinal(21)       // 'tjue-en'
  * toCardinal(101)      // 'en hundre og en'
@@ -14,12 +15,10 @@
 export function toCardinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Norwegian Bokmål 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)    // 'andre'
@@ -30,12 +29,10 @@ export function toOrdinal(value: number | string | bigint): string;
  * Converts a numeric value to Norwegian currency words (Norwegian 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 Norwegian 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)     // 'førti-to kroner'

package/src/nb-NO.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 { western } from './utils/scale.js'
 
 // ============================================================================
 // Vocabulary (module-level constants)
@@ -33,11 +35,21 @@ const DECIMAL_SEP = 'komma'
 // Short scale: million, milliard, billion, etc.
 const SCALES = ['million', 'milliard', 'billion', 'billiard', 'kvintillion', 'sekstillion', 'septillion', 'oktillion']
 
+// Supported magnitude ceiling (checked at the public entry points). SCALES is
+// indexed [scaleIndex - 2] (units and thousands separate), so segments are
+// [units, thousands, then one per SCALES entry] -> ceiling 10^((SCALES.length +
+// 2) * 3) = 10^30. Ordinal (cardinal + suffix) and currency build on the
+// cardinal, and the decimal is spelled via integerToWords, so all share it.
+export const cardinalMax = western(SCALES.length + 1)
+export const ordinalMax = western(SCALES.length + 1)
+export const currencyMax = western(SCALES.length + 1)
+
 // ============================================================================
 // Ordinal Vocabulary
 // ============================================================================
 
 // Norwegian ordinals: 1st-12th special forms, then cardinal + -de/-te
+/** @type {Record<number, string>} */
 const ORDINAL_SPECIAL = {
   1: 'første',
   2: 'andre',
@@ -50,7 +62,7 @@ const ORDINAL_SPECIAL = {
   9: 'niende',
   10: 'tiende',
   11: 'ellevte',
-  12: 'tolvte'
+  12: 'tolvte',
 }
 
 // ============================================================================
@@ -68,8 +80,10 @@ const ORE = 'øre' // same singular and plural
 /**
  * Builds segment word for 0-999.
  * Returns object with word and hasHundred flag.
+ * @param {number} n - Integer 0-999
+ * @returns {{word: string, hasHundred: boolean}} Segment word and hundred flag
  */
-function buildSegment (n) {
+function buildSegment(n) {
   if (n === 0) return { word: '', hasHundred: false }
 
   const ones = n % 10
@@ -90,16 +104,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 {
     // Hyphenated: "tjue-en"
     parts.push(TENS[tens] + '-' + ONES[ones])
   }
@@ -117,11 +135,10 @@ function buildSegment (n) {
 
 /**
  * Converts a non-negative integer to Norwegian Bokmål words.
- *
  * @param {bigint} n - Non-negative integer to convert
  * @returns {string} Norwegian words
  */
-function integerToWords (n) {
+function integerToWords(n) {
   if (n === 0n) return ZERO
 
   // Fast path: numbers < 1000
@@ -141,7 +158,8 @@ function integerToWords (n) {
       // Comma before hundreds, " og " before small numbers
       if (remainderResult.hasHundred) {
         result += ', ' + remainderResult.word
-      } else {
+      }
+      else {
         result += ' og ' + remainderResult.word
       }
     }
@@ -155,11 +173,10 @@ function integerToWords (n) {
 
 /**
  * Builds words for numbers >= 1,000,000.
- *
  * @param {bigint} n - Number >= 1,000,000
  * @returns {string} Norwegian words
  */
-function buildLargeNumberWords (n) {
+function buildLargeNumberWords(n) {
   const numStr = n.toString()
   const len = numStr.length
 
@@ -191,10 +208,12 @@ function buildLargeNumberWords (n) {
       if (scaleIndex === 0) {
         // Units segment
         parts.push({ word: segmentResult.word, hasHundred: segmentResult.hasHundred, type: 'units' })
-      } else if (scaleIndex === 1) {
+      }
+      else if (scaleIndex === 1) {
         // Thousands
         parts.push({ word: segmentResult.word + ' ' + THOUSAND, hasHundred: false, type: 'thousand' })
-      } else {
+      }
+      else {
         // Millions+
         const scaleWord = SCALES[scaleIndex - 2]
         parts.push({ word: segmentResult.word + ' ' + scaleWord, hasHundred: false, type: 'million' })
@@ -210,11 +229,10 @@ function buildLargeNumberWords (n) {
 
 /**
  * Joins parts with Norwegian spacing and comma rules.
- *
- * @param {Array} parts - Parts with type metadata
+ * @param {Array<{word: string, hasHundred: boolean, type: string}>} parts - Parts with type metadata
  * @returns {string} Joined string
  */
-function joinNorwegianParts (parts) {
+function joinNorwegianParts(parts) {
   if (parts.length === 0) return ZERO
   if (parts.length === 1) return parts[0].word
 
@@ -231,17 +249,21 @@ function joinNorwegianParts (parts) {
         // After thousands: comma if next has hundred, else " og "
         if (nextPart.hasHundred) {
           result.push(', ')
-        } else {
+        }
+        else {
           result.push(' og ')
         }
-      } else if (part.type === 'million') {
+      }
+      else if (part.type === 'million') {
         // After millions: " og " for units without hundred, space otherwise
         if (nextPart.type === 'units' && !nextPart.hasHundred) {
           result.push(' og ')
-        } else {
+        }
+        else {
           result.push(' ')
         }
-      } else {
+      }
+      else {
         result.push(' ')
       }
     }
@@ -252,11 +274,10 @@ function joinNorwegianParts (parts) {
 
 /**
  * Converts decimal digits to Norwegian words.
- *
  * @param {string} decimalPart - Decimal digits (without the point)
  * @returns {string} Norwegian words for decimal part
  */
-function decimalPartToWords (decimalPart) {
+function decimalPartToWords(decimalPart) {
   let result = ''
 
   // Handle leading zeros
@@ -279,19 +300,20 @@ function decimalPartToWords (decimalPart) {
 
 /**
  * Converts a numeric value to Norwegian Bokmål words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Norwegian words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCardinal(21)       // 'tjue-en'
  * toCardinal(101)      // 'en hundre og en'
  * toCardinal(1000000)  // 'en 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 = ''
 
@@ -320,11 +342,10 @@ function toCardinal (value) {
  * Teens (13-19): drop -en and add -ende (tretten → trettende)
  * Numbers ending in 'en' (one): replace with 'ende' (tjue-en → tjue-ende)
  * Numbers ending in 9 (ni): add 'ede' (nitti-ni → nitti-niede)
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Norwegian ordinal words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   // Special forms for 1-12
   if (n >= 1n && n <= 12n) {
     return ORDINAL_SPECIAL[Number(n)]
@@ -357,19 +378,18 @@ function integerToOrdinal (n) {
 
 /**
  * Converts a numeric value to Norwegian Bokmål 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)    // 'andre'
  * toOrdinal(21)   // 'tjue-ende'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
+  checkMax(integerPart, ordinalMax)
   return integerToOrdinal(integerPart)
 }
 
@@ -381,19 +401,18 @@ function toOrdinal (value) {
  * Converts a numeric value to Norwegian currency words (Norwegian 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 Norwegian 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)     // 'førti-to kroner'
  * toCurrency(1.50)   // 'en krone og femti øre'
  */
-function toCurrency (value) {
+function toCurrency(value) {
   const { isNegative, dollars: kroner, cents: ore } = parseCurrencyValue(value)
+  checkMax(kroner, currencyMax)
 
   let result = ''
   if (isNegative) {
@@ -404,7 +423,8 @@ function toCurrency (value) {
   if (kroner > 0n || ore === 0n) {
     if (kroner === 1n) {
       result += 'en ' + KRONE
-    } else {
+    }
+    else {
       result += integerToWords(kroner) + ' ' + KRONER
     }
   }

package/src/nl-NL.d.ts

@@ -1,35 +1,61 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
+/**
+ * @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: Required<CardinalOptions>;
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [and] - Include "en" between euros and cents
+ */
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults: Required<CurrencyOptions>;
+export type CardinalOptions = {
+    /**
+     * - Use "één" instead of "een"
+     */
+    accentOne?: boolean | undefined;
+    /**
+     * - Include "en" before small numbers
+     */
+    includeOptionalAnd?: boolean | undefined;
+    /**
+     * - Disable hundred pairing (1104→duizend honderdvier)
+     */
+    noHundredPairing?: boolean | undefined;
+};
+export type CurrencyOptions = {
+    /**
+     * - Include "en" between euros and cents
+     */
+    and?: boolean | undefined;
+};
 /**
  * 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'
  */
-export function toCardinal(value: number | string | bigint, options?: {
-    accentOne?: boolean | undefined;
-    includeOptionalAnd?: boolean | undefined;
-    noHundredPairing?: boolean | undefined;
-}): string;
+export function toCardinal(value: number | string | bigint, options?: CardinalOptions): string;
 /**
  * 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'
@@ -38,17 +64,12 @@ export function toCardinal(value: number | string | bigint, options?: {
 export function toOrdinal(value: number | string | bigint): string;
 /**
  * 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'
  */
-export function toCurrency(value: number | string | bigint, options?: {
-    and?: boolean | undefined;
-}): string;
+export function toCurrency(value: number | string | bigint, options?: CurrencyOptions): string;