n2words 3.0.0 → 4.0.0

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

@@ -1,18 +1,21 @@
 /**
- * Tamil language converter - Functional Implementation
+ * Tamil (India) language converter
  *
- * Self-contained converter for South Asian numbering.
+ * CLDR: ta-IN | Tamil as used in India
  *
  * Key features:
  * - Indian numbering system (ஆயிரம், லட்சம், கோடி)
  * - Tamil script
  * - 3-2-2 grouping pattern
  * - Complete word forms for 0-99
- * - Special hundred word transformations
+ * - Special hundred word transformations (connected vs standalone)
  * - Per-digit decimal reading
+ * - BigInt modulo for efficient segment extraction
  */
 
-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
@@ -22,6 +25,26 @@ const ZERO = 'பூஜ்ஜியம்'
 const NEGATIVE = 'மைனஸ்'
 const DECIMAL_SEP = 'புள்ளி'
 
+// ============================================================================
+// Ordinal Vocabulary
+// ============================================================================
+
+// Ordinal suffix
+const ORDINAL_SUFFIX = 'ஆவது'
+
+// Special ordinals for first few numbers
+const ORDINAL_SPECIAL = ['', 'முதல்', 'இரண்டாவது', 'மூன்றாவது', 'நான்காவது', 'ஐந்தாவது', 'ஆறாவது']
+
+// ============================================================================
+// Currency Vocabulary (Indian Rupee)
+// ============================================================================
+
+// Rupee (singular/plural same in Tamil)
+const RUPEE = 'ரூபாய்'
+
+// Paisa (singular/plural same in Tamil)
+const PAISA = 'பைசா'
+
 const BELOW_HUNDRED = [
   'பூஜ்ஜியம்', 'ஒன்று', 'இரண்டு', 'மூன்று', 'நான்கு', 'ஐந்து', 'ஆறு', 'ஏழு', 'எட்டு', 'ஒன்பது',
   'பத்து', 'பதினொன்று', 'பன்னிரண்டு', 'பதிமூன்று', 'பதினான்கு', 'பதினைந்து', 'பதினாறு', 'பதினேழு', 'பதினெட்டு', 'பத்தொன்பது',
@@ -48,35 +71,16 @@ const ONES = ['ஒன்று', 'இரண்டு', 'மூன்று', '
 const SCALE_WORDS = ['', 'ஆயிரம்', 'லட்சம்', 'கோடி', 'அரபு', 'கராபு', 'நீல்', 'பத்ம', 'சங்கு']
 
 // ============================================================================
-// Segment Splitting (inlined for performance)
-// ============================================================================
-
-function groupByThreeThenTwos (n) {
-  const numStr = n.toString()
-
-  if (numStr.length <= 3) {
-    return [Number(numStr)]
-  }
-
-  const segments = []
-  const last3 = numStr.slice(-3)
-  segments.unshift(Number(last3))
-
-  let remaining = numStr.slice(0, -3)
-  while (remaining.length > 0) {
-    const segment = remaining.slice(-2)
-    segments.unshift(Number(segment))
-    remaining = remaining.slice(0, -2)
-  }
-
-  return segments
-}
-
-// ============================================================================
-// Conversion Functions
+// Segment Building
 // ============================================================================
 
-function convertBelowThousand (n) {
+/**
+ * Builds words for a 0-999 segment.
+ *
+ * @param {number} n - Number 0-999
+ * @returns {string} Tamil words for the segment
+ */
+function buildSegment (n) {
   if (n === 0) return ''
   if (n < 100) return BELOW_HUNDRED[n]
 
@@ -87,30 +91,61 @@ function convertBelowThousand (n) {
     return HUNDREDS[hundreds]
   }
 
-  // Use precomputed connected form
+  // Use connected form when followed by remainder
   return HUNDREDS_CONNECTED[hundreds] + ' ' + BELOW_HUNDRED[remainder]
 }
 
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Tamil words.
+ *
+ * Uses BigInt modulo for segment extraction (faster than string slicing).
+ * South Asian 3-2-2 grouping: first 3 digits, then groups of 2.
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} Tamil words
+ */
 function integerToWords (n) {
   if (n === 0n) return ZERO
 
-  const groups = groupByThreeThenTwos(n)
-  const groupCount = groups.length
-  const words = []
+  // Fast path: numbers < 1000
+  if (n < 1000n) {
+    return buildSegment(Number(n))
+  }
+
+  // Extract segments using BigInt modulo
+  const segments = []
+  segments.push(Number(n % 1000n))
+  let temp = n / 1000n
+
+  while (temp > 0n) {
+    segments.push(Number(temp % 100n))
+    temp = temp / 100n
+  }
 
-  for (let i = 0; i < groupCount; i++) {
-    const groupValue = groups[i]
-    if (groupValue === 0) continue
+  // Build result string (process from most-significant to least)
+  const words = []
+  for (let i = segments.length - 1; i >= 0; i--) {
+    const segment = segments[i]
+    if (segment === 0) continue
+
+    if (i === 0) {
+      words.push(buildSegment(segment))
+    } else {
+      // Use 'ஒரு' for 1 at scale positions
+      const groupWords = (segment === 1) ? 'ஒரு' : BELOW_HUNDRED[segment]
+      words.push(groupWords)
+    }
 
-    const scaleIndex = groupCount - i - 1
-    const groupWords = (groupValue === 1 && scaleIndex > 0) ? 'ஒரு' : convertBelowThousand(groupValue)
-    words.push(groupWords)
-    if (scaleIndex > 0 && SCALE_WORDS[scaleIndex]) {
-      words.push(SCALE_WORDS[scaleIndex])
+    if (i > 0 && SCALE_WORDS[i]) {
+      words.push(SCALE_WORDS[i])
     }
   }
 
-  return words.join(' ').trim()
+  return words.join(' ')
 }
 
 function decimalPartToWords (decimalPart) {
@@ -129,8 +164,8 @@ function decimalPartToWords (decimalPart) {
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Tamil words
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
 
@@ -147,8 +182,89 @@ function toWords (value) {
   return result
 }
 
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Converts a positive integer to Tamil ordinal words.
+ *
+ * Tamil ordinals: First has special form, 2-6 have special suffixes, then -ஆவது suffix.
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Tamil 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 Tamil 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 Tamil currency words (Indian Rupee).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Tamil 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) + ' ' + RUPEE
+  }
+
+  // Paise part
+  if (paise > 0n) {
+    if (rupees > 0n) {
+      result += ' '
+    }
+    result += integerToWords(paise) + ' ' + PAISA
+  }
+
+  return result
+}
+
 // ============================================================================
 // Exports
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/te-IN.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Converts a numeric value to Telugu words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Telugu words
+ */
+export function toCardinal(value: number | string | bigint): string;
+/**
+ * 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)   // 'పదివ'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * 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)   // 'ఒకటి పైసా'
+ */
+export function toCurrency(value: number | string | bigint): string;

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

@@ -1,7 +1,7 @@
 /**
- * Telugu language converter - Functional Implementation
+ * Telugu (India) language converter
  *
- * Self-contained converter for South Asian numbering.
+ * 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 = [
   'సున్నా', 'ఒకటి', 'రెండు', 'మూడు', 'నాలుగు', 'ఐదు', 'ఆరు', 'ఏడు', 'ఎనిమిది', 'తొమ్మిది',
   'పది', 'పదకొండు', 'పన్నెండు', 'పదమూడు', 'పద్నాలుగు', 'పదిహేను', 'పదహారు', 'పదిహేడు', 'పద్దెనిమిది', 'పంతొమ్మిది',
@@ -34,10 +58,6 @@ const BELOW_HUNDRED = [
   'తొంభై', 'తొంభై ఒకటి', 'తొంభై రెండు', 'తొంభై మూడు', 'తొంభై నాలుగు', 'తొంభై ఐదు', 'తొంభై ఆరు', 'తొంభై ఏడు', 'తొంభై ఎనిమిది', 'తొంభై తొమ్మిది'
 ]
 
-// ============================================================================
-// Vocabulary (continued)
-// ============================================================================
-
 const HUNDREDS = ['', 'వంద', 'రెండు వందలు', 'మూడు వందలు', 'నాలుగు వందలు', 'ఐదు వందలు', 'ఆరు వందలు', 'ఏడు వందలు', 'ఎనిమిది వందలు', 'తొమ్మిది వందలు']
 
 // Ones for decimal reading
@@ -47,13 +67,13 @@ const ONES = ['ఒకటి', 'రెండు', 'మూడు', 'నాలు
 const SCALE_WORDS = ['', 'వెయ్యి', 'లక్ష', 'కోటి', 'అరబ్', 'ఖరబ్', 'నిల్', 'పడ్మ', 'శంకు']
 
 // ============================================================================
-// Conversion Functions
+// Segment Building
 // ============================================================================
 
 /**
- * Converts 0-999 to Telugu words.
+ * Builds words for a 0-999 segment.
  */
-function convertBelowThousand (n) {
+function buildSegment (n) {
   if (n === 0) return ''
   if (n < 100) return BELOW_HUNDRED[n]
 
@@ -66,9 +86,15 @@ function convertBelowThousand (n) {
   return HUNDREDS[hundreds] + ' ' + BELOW_HUNDRED[remainder]
 }
 
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
 /**
  * Converts a non-negative integer to Telugu words.
- * Uses recursive approach for Indian 3-2-2 grouping pattern.
+ *
+ * Uses BigInt modulo for segment extraction (faster than string slicing).
+ * South Asian 3-2-2 grouping: first 3 digits, then groups of 2.
  *
  * @param {bigint} n - Non-negative integer to convert
  * @returns {string} Telugu words
@@ -78,49 +104,39 @@ function integerToWords (n) {
 
   // Fast path: numbers < 1000 (direct lookup)
   if (n < 1000n) {
-    return convertBelowThousand(Number(n))
+    return buildSegment(Number(n))
   }
 
-  return buildLargeNumberWords(n, 0)
-}
-
-/**
- * Recursively builds words for numbers >= 1000.
- * Indian grouping: first 3 digits, then 2-digit groups.
- *
- * @param {bigint} n - Number to convert
- * @param {number} scale - Current scale index (0=units, 1=thousands, etc.)
- * @returns {string} Telugu words
- */
-function buildLargeNumberWords (n, scale) {
-  if (n === 0n) return ''
-
-  // Determine divisor: 1000 for first split, 100 for rest
-  const divisor = scale === 0 ? 1000n : 100n
-  const segment = Number(n % divisor)
-  const rest = n / divisor
+  // Extract segments using BigInt modulo
+  const segments = []
+  segments.push(Number(n % 1000n))
+  let temp = n / 1000n
 
-  // Build higher segments first (recursive)
-  let result = ''
-  if (rest > 0n) {
-    result = buildLargeNumberWords(rest, scale + 1)
+  while (temp > 0n) {
+    segments.push(Number(temp % 100n))
+    temp = temp / 100n
   }
 
-  // Add current segment
-  if (segment > 0) {
-    if (result) result += ' '
+  // Build result string (process from most-significant to least)
+  const words = []
+  for (let i = segments.length - 1; i >= 0; i--) {
+    const segment = segments[i]
+    if (segment === 0) continue
 
-    if (scale === 0) {
-      // Units segment (0-999)
-      result += convertBelowThousand(segment)
+    if (i === 0) {
+      words.push(buildSegment(segment))
     } else {
-      // Scale segments (0-99)
+      // Use 'ఒక' for 1 at scale positions
       const groupWords = (segment === 1) ? 'ఒక' : BELOW_HUNDRED[segment]
-      result += groupWords + ' ' + SCALE_WORDS[scale]
+      words.push(groupWords)
+    }
+
+    if (i > 0 && SCALE_WORDS[i]) {
+      words.push(SCALE_WORDS[i])
     }
   }
 
-  return result
+  return words.join(' ')
 }
 
 function decimalPartToWords (decimalPart) {
@@ -139,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 = ''
 
@@ -157,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;