n2words 3.1.0 → 4.0.0

package/{lib/languages/te.js → src/te-IN.js}

@@ -1,7 +1,7 @@
 /**
- * Telugu language converter - Functional Implementation
+ * Telugu (India) language converter
  *
- * Self-contained module with its own input validation, ready for subpath exports.
+ * CLDR: te-IN | Telugu as used in India
  *
  * Key features:
  * - Indian numbering system (వెయ్యి, లక్ష, కోటి)
@@ -11,7 +11,9 @@
  * - Per-digit decimal reading
  */
 
-import { parseNumericValue } from '../utils/parse-numeric.js'
+import { parseCardinalValue } from './utils/parse-cardinal.js'
+import { parseCurrencyValue } from './utils/parse-currency.js'
+import { parseOrdinalValue } from './utils/parse-ordinal.js'
 
 // ============================================================================
 // Vocabulary
@@ -21,6 +23,28 @@ const ZERO = 'సున్నా'
 const NEGATIVE = 'మైనస్'
 const DECIMAL_SEP = 'పాయింట్'
 
+// ============================================================================
+// Ordinal Vocabulary
+// ============================================================================
+
+// Ordinal suffix (adds to cardinal for numbers >= 7)
+const ORDINAL_SUFFIX = 'వ'
+
+// Special ordinals for first few numbers
+const ORDINAL_SPECIAL = ['', 'మొదటి', 'రెండవ', 'మూడవ', 'నాలుగవ', 'ఐదవ', 'ఆరవ']
+
+// ============================================================================
+// Currency Vocabulary (Indian Rupee)
+// ============================================================================
+
+// Rupee (singular/plural same in Telugu)
+const RUPEE = 'రూపాయి'
+const RUPEES = 'రూపాయలు'
+
+// Paisa (singular/plural same in Telugu)
+const PAISA = 'పైసా'
+const PAISE = 'పైసలు'
+
 const BELOW_HUNDRED = [
   'సున్నా', 'ఒకటి', 'రెండు', 'మూడు', 'నాలుగు', 'ఐదు', 'ఆరు', 'ఏడు', 'ఎనిమిది', 'తొమ్మిది',
   'పది', 'పదకొండు', 'పన్నెండు', 'పదమూడు', 'పద్నాలుగు', 'పదిహేను', 'పదహారు', 'పదిహేడు', 'పద్దెనిమిది', 'పంతొమ్మిది',
@@ -131,8 +155,8 @@ function decimalPartToWords (decimalPart) {
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Telugu words
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
 
@@ -149,8 +173,93 @@ function toWords (value) {
   return result
 }
 
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Converts a positive integer to Telugu ordinal words.
+ *
+ * Telugu ordinals: First 6 are irregular, then add -వ suffix.
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Telugu ordinal words
+ */
+function integerToOrdinal (n) {
+  // Special ordinals for 1-6
+  if (n >= 1n && n <= 6n) {
+    return ORDINAL_SPECIAL[Number(n)]
+  }
+
+  // For 7 and above, add suffix to cardinal
+  const cardinal = integerToWords(n)
+  return cardinal + ORDINAL_SUFFIX
+}
+
+/**
+ * Converts a numeric value to Telugu 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) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value, options?)
+// ============================================================================
+
+/**
+ * Converts a numeric value to Telugu currency words (Indian Rupee).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Telugu 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)  // 'నలభై రెండు రూపాయలు యాభై పైసలు'
+ * toCurrency(1)      // 'ఒకటి రూపాయి'
+ * toCurrency(0.01)   // 'ఒకటి పైసా'
+ */
+function toCurrency (value) {
+  const { isNegative, dollars: rupees, cents: paise } = parseCurrencyValue(value)
+
+  // Build result
+  let result = ''
+  if (isNegative) result = NEGATIVE + ' '
+
+  // Rupees part - show if non-zero, or if no paise
+  if (rupees > 0n || paise === 0n) {
+    result += integerToWords(rupees)
+    // Singular for 1 rupee, plural otherwise
+    result += ' ' + (rupees === 1n ? RUPEE : RUPEES)
+  }
+
+  // Paise part
+  if (paise > 0n) {
+    if (rupees > 0n) {
+      result += ' '
+    }
+    result += integerToWords(paise)
+    // Singular for 1 paisa, plural otherwise
+    result += ' ' + (paise === 1n ? PAISA : PAISE)
+  }
+
+  return result
+}
+
 // ============================================================================
 // Exports
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/th-TH.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Converts a numeric value to Thai words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Thai words
+ */
+export function toCardinal(value: number | string | bigint): string;
+/**
+ * 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)   // 'ที่สิบ'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Thai currency words (Baht).
+ *
+ * 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)     // 'ลบห้าบาทถ้วน'
+ */
+export function toCurrency(value: number | string | bigint): string;

package/{lib/languages/th.js → src/th-TH.js}

@@ -1,7 +1,7 @@
 /**
- * Thai language converter - Functional Implementation
+ * Thai (Thailand) language converter
  *
- * Self-contained converter with precomputed lookup tables.
+ * CLDR: th-TH | Thai as used in Thailand
  *
  * Key features:
  * - No word separators (continuous Thai script)
@@ -11,7 +11,9 @@
  * - Per-digit decimal reading
  */
 
-import { parseNumericValue } from '../utils/parse-numeric.js'
+import { parseCardinalValue } from './utils/parse-cardinal.js'
+import { parseCurrencyValue } from './utils/parse-currency.js'
+import { parseOrdinalValue } from './utils/parse-ordinal.js'
 
 // ============================================================================
 // Vocabulary
@@ -23,6 +25,20 @@ const ZERO = 'ศูนย์'
 const NEGATIVE = 'ลบ'
 const DECIMAL_SEP = 'จุด'
 
+// ============================================================================
+// Ordinal Vocabulary
+// ============================================================================
+
+const ORDINAL_PREFIX = 'ที่'
+
+// ============================================================================
+// Currency Vocabulary (Thai Baht)
+// ============================================================================
+
+const BAHT = 'บาท'
+const SATANG = 'สตางค์'
+const BAHT_ONLY = 'ถ้วน' // "exactly" suffix when no satang
+
 // ============================================================================
 // Conversion Functions
 // ============================================================================
@@ -136,8 +152,8 @@ function decimalPartToWords (decimalPart) {
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Thai words
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
 
@@ -154,8 +170,85 @@ function toWords (value) {
   return result
 }
 
+// ============================================================================
+// ORDINAL: toOrdinal(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) {
+  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) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value)
+// ============================================================================
+
+/**
+ * Converts a numeric value to Thai currency words (Baht).
+ *
+ * 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) {
+  const { isNegative, dollars: baht, cents: satang } = parseCurrencyValue(value)
+
+  let result = ''
+  if (isNegative) {
+    result = NEGATIVE
+  }
+
+  // Baht part - always show
+  result += integerToWords(baht)
+  result += BAHT
+
+  // Satang part or "exactly" suffix
+  if (satang > 0n) {
+    result += integerToWords(satang)
+    result += SATANG
+  } else {
+    result += BAHT_ONLY
+  }
+
+  return result
+}
+
 // ============================================================================
 // Exports
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/tr-TR.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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
+ * @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;
+/**
+ * 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'
+ */
+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ş'
+ * toCurrency(-5)     // 'eksi beş lira'
+ */
+export function toCurrency(value: number | string | bigint): string;

package/{lib/languages/tr.js → src/tr-TR.js}

@@ -1,7 +1,7 @@
 /**
- * Turkish language converter - Functional Implementation
+ * Turkish (Turkey) language converter
  *
- * Self-contained module with its own input validation, ready for subpath exports.
+ * CLDR: tr-TR | Turkish as used in Turkey
  *
  * Key features:
  * - Omits 'bir' (one) before hundreds and thousands
@@ -9,8 +9,10 @@
  * - Short scale naming
  */
 
-import { parseNumericValue } from '../utils/parse-numeric.js'
-import { validateOptions } from '../utils/validate-options.js'
+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'
 
 // ============================================================================
 // Vocabulary (module-level constants)
@@ -31,6 +33,32 @@ const DECIMAL_SEP = 'virgül'
 // Short scale
 const SCALES = ['milyon', 'milyar', 'trilyon', 'katrilyon', 'kentilyon']
 
+// ============================================================================
+// Ordinal Vocabulary
+// ============================================================================
+
+// Turkish ordinals use -(i/ı/u/ü)nci/ncı/ncu/ncü suffix with vowel harmony
+// Special forms for 1-10
+const ORDINAL_SPECIAL = {
+  1: 'birinci',
+  2: 'ikinci',
+  3: 'üçüncü',
+  4: 'dördüncü',
+  5: 'beşinci',
+  6: 'altıncı',
+  7: 'yedinci',
+  8: 'sekizinci',
+  9: 'dokuzuncu',
+  10: 'onuncu'
+}
+
+// ============================================================================
+// Currency Vocabulary (Turkish Lira)
+// ============================================================================
+
+const LIRA = 'lira' // same singular and plural
+const KURUS = 'kuruş' // subunit (100 kuruş = 1 lira)
+
 // ============================================================================
 // Segment Building
 // ============================================================================
@@ -43,8 +71,8 @@ function buildSegment (n, separator = ' ') {
   if (n === 0) return ''
 
   const ones = n % 10
-  const tens = Math.floor(n / 10) % 10
-  const hundreds = Math.floor(n / 100)
+  const tens = Math.trunc(n / 10) % 10
+  const hundreds = Math.trunc(n / 100)
 
   const parts = []
 
@@ -86,10 +114,10 @@ function buildSegment (n, separator = ' ') {
  * @param {Object} options - Conversion options
  * @returns {string} Turkish words
  */
-function integerToWords (n, options = {}) {
+function integerToWords (n, dropSpaces) {
   if (n === 0n) return ZERO
 
-  const sep = options.dropSpaces ? '' : ' '
+  const sep = dropSpaces ? '' : ' '
 
   // Fast path: numbers < 1000
   if (n < 1000n) {
@@ -117,7 +145,7 @@ function integerToWords (n, options = {}) {
   }
 
   // For numbers >= 1,000,000, use scale decomposition
-  return buildLargeNumberWords(n, options)
+  return buildLargeNumberWords(n, dropSpaces)
 }
 
 /**
@@ -127,8 +155,8 @@ function integerToWords (n, options = {}) {
  * @param {Object} options - Conversion options
  * @returns {string} Turkish words
  */
-function buildLargeNumberWords (n, options) {
-  const sep = options.dropSpaces ? '' : ' '
+function buildLargeNumberWords (n, dropSpaces) {
+  const sep = dropSpaces ? '' : ' '
 
   const numStr = n.toString()
   const len = numStr.length
@@ -188,8 +216,8 @@ function buildLargeNumberWords (n, options) {
  * @param {Object} options - Conversion options
  * @returns {string} Turkish words for decimal part
  */
-function decimalPartToWords (decimalPart, options) {
-  const sep = options.dropSpaces ? '' : ' '
+function decimalPartToWords (decimalPart, dropSpaces) {
+  const sep = dropSpaces ? '' : ' '
   let result = ''
 
   // Handle leading zeros
@@ -204,7 +232,7 @@ function decimalPartToWords (decimalPart, options) {
   const remainder = decimalPart.slice(i)
   if (remainder) {
     if (result) result += sep
-    result += integerToWords(BigInt(remainder), options)
+    result += integerToWords(BigInt(remainder), dropSpaces)
   }
 
   return result
@@ -221,25 +249,142 @@ function decimalPartToWords (decimalPart, options) {
  * @throws {Error} If value is not a valid number format
  *
  * @example
- * toWords(21)                        // 'yirmi bir'
- * toWords(21, { dropSpaces: true })  // 'yirmibir'
- * toWords(1000)                      // 'bin'
+ * toCardinal(21)                        // 'yirmi bir'
+ * toCardinal(21, { dropSpaces: true })  // 'yirmibir'
+ * toCardinal(1000)                      // 'bin'
  */
-function toWords (value, options) {
+function toCardinal (value, options) {
   options = validateOptions(options)
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
+
+  // Apply option defaults
+  const { dropSpaces = false } = options
 
-  const sep = options.dropSpaces ? '' : ' '
+  const sep = dropSpaces ? '' : ' '
   let result = ''
 
   if (isNegative) {
     result = NEGATIVE + sep
   }
 
-  result += integerToWords(integerPart, options)
+  result += integerToWords(integerPart, dropSpaces)
 
   if (decimalPart) {
-    result += sep + DECIMAL_SEP + sep + decimalPartToWords(decimalPart, options)
+    result += sep + DECIMAL_SEP + sep + decimalPartToWords(decimalPart, dropSpaces)
+  }
+
+  return result
+}
+
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Determines the ordinal suffix based on Turkish vowel harmony.
+ * @param {string} word - The cardinal word
+ * @returns {string} The appropriate suffix
+ */
+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'
+  const frontVowels = 'eiöü'
+
+  // Scan from end for last vowel
+  for (let i = word.length - 1; i >= 0; i--) {
+    const char = word[i]
+    if (backVowels.includes(char)) {
+      // Back vowels: -ıncı (after ı,a) or -uncu (after o,u)
+      if ('ou'.includes(char)) return 'uncu'
+      return 'ıncı'
+    }
+    if (frontVowels.includes(char)) {
+      // Front vowels: -inci (after e,i) or -üncü (after ö,ü)
+      if ('öü'.includes(char)) return 'üncü'
+      return 'inci'
+    }
+  }
+  return 'inci' // default
+}
+
+/**
+ * Converts a non-negative integer to Turkish ordinal words.
+ *
+ * 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) {
+  // Special forms for 1-10
+  if (n >= 1n && n <= 10n) {
+    return ORDINAL_SPECIAL[Number(n)]
+  }
+
+  // For numbers > 10, add appropriate suffix to cardinal (dropSpaces=true)
+  const cardinal = integerToWords(n, true)
+  const suffix = getOrdinalSuffix(cardinal)
+  return cardinal + suffix
+}
+
+/**
+ * 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) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(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) {
+  const { isNegative, dollars: lira, cents: kurus } = parseCurrencyValue(value)
+
+  let result = ''
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  // Lira part
+  if (lira > 0n || kurus === 0n) {
+    result += integerToWords(lira, false) + ' ' + LIRA
+  }
+
+  // Kuruş part
+  if (kurus > 0n) {
+    if (lira > 0n) {
+      result += ' '
+    }
+    result += integerToWords(kurus, false) + ' ' + KURUS
   }
 
   return result
@@ -249,4 +394,4 @@ function toWords (value, options) {
 // Public API
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }