n2words 5.0.0 → 5.1.0

package/src/th-TH.js

@@ -14,6 +14,14 @@
 import { parseCardinalValue } from './utils/parse-cardinal.js'
 import { parseCurrencyValue } from './utils/parse-currency.js'
 import { parseOrdinalValue } from './utils/parse-ordinal.js'
+import { UNBOUNDED } from './utils/scale.js'
+
+// Thai spells large numbers by repeating ล้าน (10^6), so every form is
+// magnitude-preserving with no fixed ceiling. Declared per form so the gate
+// switches to its injectivity check and the docs read "no fixed limit".
+export const cardinalMax = UNBOUNDED
+export const ordinalMax = UNBOUNDED
+export const currencyMax = UNBOUNDED
 
 // ============================================================================
 // Vocabulary
@@ -43,7 +51,11 @@ const BAHT_ONLY = 'ถ้วน' // "exactly" suffix when no satang
 // Conversion Functions
 // ============================================================================
 
-function convertBelowMillion (n) {
+/**
+ * @param {number} n A value below one million to convert.
+ * @returns {string} The number in Thai words.
+ */
+function convertBelowMillion(n) {
   if (n === 0) return ''
 
   let value = n
@@ -67,7 +79,8 @@ function convertBelowMillion (n) {
   if (tenThousands > 0) {
     if (tenThousands === 1) {
       parts.push('หนึ่งหมื่น')
-    } else {
+    }
+    else {
       parts.push(ONES[tenThousands - 1] + 'หมื่น')
     }
   }
@@ -83,9 +96,11 @@ function convertBelowMillion (n) {
   if (tens > 0) {
     if (tens === 1) {
       parts.push('สิบ')
-    } else if (tens === 2) {
+    }
+    else if (tens === 2) {
       parts.push('ยี่สิบ')
-    } else {
+    }
+    else {
       parts.push(ONES[tens - 1] + 'สิบ')
     }
   }
@@ -94,7 +109,8 @@ function convertBelowMillion (n) {
     const hasHigher = hundredThousands > 0 || tenThousands > 0 || thousands > 0 || hundreds > 0 || tens > 0
     if (ones === 1 && (tens > 0 || hasHigher)) {
       parts.push('เอ็ด')
-    } else {
+    }
+    else {
       parts.push(ONES[ones - 1])
     }
   }
@@ -102,7 +118,11 @@ function convertBelowMillion (n) {
   return parts.join('')
 }
 
-function splitMillionGroups (n) {
+/**
+ * @param {bigint} n The integer to split into million-based groups.
+ * @returns {number[]} The groups in most-significant-first order.
+ */
+function splitMillionGroups(n) {
   const groups = []
   let remaining = n
 
@@ -116,7 +136,11 @@ function splitMillionGroups (n) {
   return groups
 }
 
-function integerToWords (n) {
+/**
+ * @param {bigint} n The integer to convert.
+ * @returns {string} The integer in Thai words.
+ */
+function integerToWords(n) {
   if (n === 0n) return ZERO
 
   const groups = splitMillionGroups(n)
@@ -136,7 +160,11 @@ function integerToWords (n) {
   return parts.join('')
 }
 
-function decimalPartToWords (decimalPart) {
+/**
+ * @param {string} decimalPart The fractional digits to read.
+ * @returns {string} The decimal digits in Thai words.
+ */
+function decimalPartToWords(decimalPart) {
   // Per-digit decimal reading
   const digits = []
   for (const char of decimalPart) {
@@ -148,11 +176,10 @@ function decimalPartToWords (decimalPart) {
 
 /**
  * Converts a numeric value to Thai words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Thai words
  */
-function toCardinal (value) {
+function toCardinal(value) {
   const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
@@ -178,28 +205,25 @@ function toCardinal (value) {
  * Converts a non-negative integer to Thai ordinal words.
  *
  * Thai ordinals use "ที่" prefix + cardinal number.
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Thai ordinal words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   return ORDINAL_PREFIX + integerToWords(n)
 }
 
 /**
  * Converts a numeric value to Thai 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(10)   // 'ที่สิบ'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
   return integerToOrdinal(integerPart)
 }
@@ -213,18 +237,16 @@ function toOrdinal (value) {
  *
  * Thai Baht uses satang as subunit (100 satang = 1 baht).
  * When whole amounts, adds "ถ้วน" (exactly) suffix.
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Thai 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)     // 'สี่สิบสองบาทถ้วน'
  * toCurrency(1.50)   // 'หนึ่งบาทห้าสิบสตางค์'
  * toCurrency(-5)     // 'ลบห้าบาทถ้วน'
  */
-function toCurrency (value) {
+function toCurrency(value) {
   const { isNegative, dollars: baht, cents: satang } = parseCurrencyValue(value)
 
   let result = ''
@@ -240,7 +262,8 @@ function toCurrency (value) {
   if (satang > 0n) {
     result += integerToWords(satang)
     result += SATANG
-  } else {
+  }
+  else {
     result += BAHT_ONLY
   }
 

package/src/tr-TR.d.ts

@@ -1,29 +1,37 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
+/**
+ * @typedef {object} CardinalOptions
+ * @property {boolean} [dropSpaces] - Remove spaces for compound form
+ */
+/** @type {Required<CardinalOptions>} */
+export const cardinalDefaults: Required<CardinalOptions>;
+export type CardinalOptions = {
+    /**
+     * - Remove spaces for compound form
+     */
+    dropSpaces?: boolean | undefined;
+};
 /**
  * Converts a numeric value to Turkish words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
- * @param {Object} [options] - Conversion options
- * @param {boolean} [options.dropSpaces=false] - Remove spaces for compound form
+ * @param {CardinalOptions} [options] - Conversion options
  * @returns {string} The number in Turkish words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCardinal(21)                        // 'yirmi bir'
  * toCardinal(21, { dropSpaces: true })  // 'yirmibir'
  * toCardinal(1000)                      // 'bin'
  */
-export function toCardinal(value: number | string | bigint, options?: {
-    dropSpaces?: boolean | undefined;
-}): string;
+export function toCardinal(value: number | string | bigint, options?: CardinalOptions): string;
 /**
  * Converts a numeric value to Turkish 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)    // 'birinci'
  * toOrdinal(2)    // 'ikinci'
@@ -34,12 +42,10 @@ export function toOrdinal(value: number | string | bigint): string;
  * Converts a numeric value to Turkish currency words (Turkish Lira).
  *
  * Uses lira and kuruş (100 kuruş = 1 lira).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Turkish 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)     // 'kırk iki lira'
  * toCurrency(1.50)   // 'bir lira elli kuruş'

package/src/tr-TR.js

@@ -12,7 +12,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)
@@ -33,12 +35,23 @@ const DECIMAL_SEP = 'virgül'
 // Short scale
 const SCALES = ['milyon', 'milyar', 'trilyon', 'katrilyon', 'kentilyon']
 
+// Supported magnitude ceiling (checked at the public entry points). SCALES is
+// indexed [scaleIndex - 2] (units and thousands are separate), so segments are
+// [units, thousands, then one per SCALES entry] -> the ceiling is
+// 10^((SCALES.length + 2) * 3) = 10^21. Ordinal (integerToWords + suffix),
+// currency, and the decimal all route through the cardinal builder, so all
+// share the ceiling.
+export const cardinalMax = western(SCALES.length + 1)
+export const ordinalMax = western(SCALES.length + 1)
+export const currencyMax = western(SCALES.length + 1)
+
 // ============================================================================
 // Ordinal Vocabulary
 // ============================================================================
 
 // Turkish ordinals use -(i/ı/u/ü)nci/ncı/ncu/ncü suffix with vowel harmony
 // Special forms for 1-10
+/** @type {Record<number, string>} */
 const ORDINAL_SPECIAL = {
   1: 'birinci',
   2: 'ikinci',
@@ -49,7 +62,7 @@ const ORDINAL_SPECIAL = {
   7: 'yedinci',
   8: 'sekizinci',
   9: 'dokuzuncu',
-  10: 'onuncu'
+  10: 'onuncu',
 }
 
 // ============================================================================
@@ -66,8 +79,11 @@ const KURUS = 'kuruş' // subunit (100 kuruş = 1 lira)
 /**
  * Builds segment word for 0-999.
  * Omits "bir" before "yüz" (hundred).
+ * @param {number} n - Segment value (0-999)
+ * @param {string} [separator] - Separator between words
+ * @returns {string} Segment words
  */
-function buildSegment (n, separator = ' ') {
+function buildSegment(n, separator = ' ') {
   if (n === 0) return ''
 
   const ones = n % 10
@@ -80,7 +96,8 @@ function buildSegment (n, separator = ' ') {
   if (hundreds > 0) {
     if (hundreds === 1) {
       parts.push(HUNDRED)
-    } else {
+    }
+    else {
       parts.push(ONES[hundreds] + separator + HUNDRED)
     }
   }
@@ -90,13 +107,17 @@ function buildSegment (n, separator = ' ') {
 
   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].replace(' ', separator))
-  } else if (ones === 0) {
+  }
+  else if (ones === 0) {
     parts.push(TENS[tens])
-  } else {
+  }
+  else {
     parts.push(TENS[tens] + separator + ONES[ones])
   }
 
@@ -109,12 +130,11 @@ function buildSegment (n, separator = ' ') {
 
 /**
  * Converts a non-negative integer to Turkish words.
- *
  * @param {bigint} n - Non-negative integer to convert
- * @param {Object} options - Conversion options
+ * @param {boolean} dropSpaces - Remove spaces for compound form
  * @returns {string} Turkish words
  */
-function integerToWords (n, dropSpaces) {
+function integerToWords(n, dropSpaces) {
   if (n === 0n) return ZERO
 
   const sep = dropSpaces ? '' : ' '
@@ -133,7 +153,8 @@ function integerToWords (n, dropSpaces) {
     let result
     if (thousands === 1) {
       result = THOUSAND
-    } else {
+    }
+    else {
       result = buildSegment(thousands, sep) + sep + THOUSAND
     }
 
@@ -150,12 +171,11 @@ function integerToWords (n, dropSpaces) {
 
 /**
  * Builds words for numbers >= 1,000,000.
- *
  * @param {bigint} n - Number >= 1,000,000
- * @param {Object} options - Conversion options
+ * @param {boolean} dropSpaces - Remove spaces for compound form
  * @returns {string} Turkish words
  */
-function buildLargeNumberWords (n, dropSpaces) {
+function buildLargeNumberWords(n, dropSpaces) {
   const sep = dropSpaces ? '' : ' '
 
   const numStr = n.toString()
@@ -189,14 +209,17 @@ function buildLargeNumberWords (n, dropSpaces) {
       if (scaleIndex === 0) {
         // Units segment
         parts.push(segmentWord)
-      } else if (scaleIndex === 1) {
+      }
+      else if (scaleIndex === 1) {
         // Thousands - omit "bir" before bin
         if (segment === 1) {
           parts.push(THOUSAND)
-        } else {
+        }
+        else {
           parts.push(segmentWord + sep + THOUSAND)
         }
-      } else {
+      }
+      else {
         // Millions+ - "bir" is kept before scale words
         const scaleWord = SCALES[scaleIndex - 2]
         parts.push(segmentWord + sep + scaleWord)
@@ -211,12 +234,11 @@ function buildLargeNumberWords (n, dropSpaces) {
 
 /**
  * Converts decimal digits to Turkish words.
- *
  * @param {string} decimalPart - Decimal digits (without the point)
- * @param {Object} options - Conversion options
+ * @param {boolean} dropSpaces - Remove spaces for compound form
  * @returns {string} Turkish words for decimal part
  */
-function decimalPartToWords (decimalPart, dropSpaces) {
+function decimalPartToWords(decimalPart, dropSpaces) {
   const sep = dropSpaces ? '' : ' '
   let result = ''
 
@@ -238,27 +260,34 @@ function decimalPartToWords (decimalPart, dropSpaces) {
   return result
 }
 
+/**
+ * @typedef {object} CardinalOptions
+ * @property {boolean} [dropSpaces] - Remove spaces for compound form
+ */
+
+/** @type {Required<CardinalOptions>} */
+export const cardinalDefaults = { dropSpaces: false }
+
 /**
  * Converts a numeric value to Turkish words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
- * @param {Object} [options] - Conversion options
- * @param {boolean} [options.dropSpaces=false] - Remove spaces for compound form
+ * @param {CardinalOptions} [options] - Conversion options
  * @returns {string} The number in Turkish words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCardinal(21)                        // 'yirmi bir'
  * toCardinal(21, { dropSpaces: true })  // 'yirmibir'
  * toCardinal(1000)                      // 'bin'
  */
-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 { dropSpaces = false } = options
+  const { dropSpaces } = resolveOptions(options, cardinalDefaults)
 
   const sep = dropSpaces ? '' : ' '
   let result = ''
@@ -285,7 +314,7 @@ function toCardinal (value, options) {
  * @param {string} word - The cardinal word
  * @returns {string} The appropriate suffix
  */
-function getOrdinalSuffix (word) {
+function getOrdinalSuffix(word) {
   // Turkish vowel harmony: back vowels (a,ı,o,u) vs front vowels (e,i,ö,ü)
   // Find last vowel to determine suffix
   const backVowels = 'aıou'
@@ -313,11 +342,10 @@ function getOrdinalSuffix (word) {
  *
  * Turkish ordinals: birinci (1st), ikinci (2nd), üçüncü (3rd), etc.
  * Uses vowel harmony for suffix selection.
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Turkish ordinal words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   // Special forms for 1-10
   if (n >= 1n && n <= 10n) {
     return ORDINAL_SPECIAL[Number(n)]
@@ -331,19 +359,18 @@ function integerToOrdinal (n) {
 
 /**
  * Converts a numeric value to Turkish 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)    // 'birinci'
  * toOrdinal(2)    // 'ikinci'
  * toOrdinal(21)   // 'yirmibirinci'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
+  checkMax(integerPart, ordinalMax)
   return integerToOrdinal(integerPart)
 }
 
@@ -355,19 +382,18 @@ function toOrdinal (value) {
  * Converts a numeric value to Turkish currency words (Turkish Lira).
  *
  * Uses lira and kuruş (100 kuruş = 1 lira).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Turkish 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)     // 'kırk iki lira'
  * toCurrency(1.50)   // 'bir lira elli kuruş'
  * toCurrency(-5)     // 'eksi beş lira'
  */
-function toCurrency (value) {
+function toCurrency(value) {
   const { isNegative, dollars: lira, cents: kurus } = parseCurrencyValue(value)
+  checkMax(lira, currencyMax)
 
   let result = ''
   if (isNegative) {

package/src/uk-UA.d.ts

@@ -1,22 +1,35 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
+/**
+ * @typedef {object} CardinalOptions
+ * @property {('masculine'|'feminine')} [gender] - Grammatical gender
+ */
+/** @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 = {
+    /**
+     * - Grammatical gender
+     */
+    gender?: "feminine" | "masculine" | undefined;
+};
 /**
  * Converts a numeric value to Ukrainian words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
- * @param {Object} [options] - Optional configuration
- * @param {('masculine'|'feminine')} [options.gender='masculine'] - Grammatical gender
+ * @param {CardinalOptions} [options] - Optional configuration
  * @returns {string} The number in Ukrainian words
  */
-export function toCardinal(value: number | string | bigint, options?: {
-    gender?: "masculine" | "feminine" | undefined;
-}): string;
+export function toCardinal(value: number | string | bigint, options?: CardinalOptions): string;
 /**
  * Converts a numeric value to Ukrainian 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
  * @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)    // 'другий'
@@ -27,12 +40,10 @@ export function toCardinal(value: number | string | bigint, options?: {
 export function toOrdinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Ukrainian currency words (Hryvnia).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Ukrainian 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)     // 'сорок двi гривнi'
  * toCurrency(1)      // 'одна гривня'