n2words 3.0.0 → 4.0.0

package/src/kn-IN.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Converts a numeric value to Kannada words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Kannada words
+ */
+export function toCardinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Kannada 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 Kannada currency words (Indian Rupee).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Kannada 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/kn.js → src/kn-IN.js}

@@ -1,7 +1,7 @@
 /**
- * Kannada language converter - Functional Implementation
+ * Kannada (India) language converter
  *
- * Self-contained converter for South Asian numbering.
+ * CLDR: kn-IN | Kannada 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
@@ -22,6 +24,28 @@ const NEGATIVE = 'ಋಣಾತ್ಮಕ'
 const DECIMAL_SEP = 'ದಶಮಾಂಶ'
 const HUNDRED = 'ನೂರು'
 
+// ============================================================================
+// 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 Kannada)
+const RUPEE = 'ರೂಪಾಯಿ'
+const RUPEES = 'ರೂಪಾಯಿಗಳು'
+
+// Paisa (singular/plural same in Kannada)
+const PAISA = 'ಪೈಸೆ'
+const PAISE = 'ಪೈಸೆಗಳು'
+
 const BELOW_HUNDRED = [
   'ಸೊನ್ನೆ', 'ಒಂದು', 'ಎರಡು', 'ಮೂರು', 'ನಾಲ್ಕು', 'ಐದು', 'ಆರು', 'ಏಳು', 'ಎಂಟು', 'ಒಂಬತ್ತು',
   'ಹತ್ತು', 'ಹನ್ನೊಂದು', 'ಹನ್ನೆರಡು', 'ಹದಿಮೂರು', 'ಹದಿನಾಲ್ಕು', 'ಹದಿನೈದು', 'ಹದಿನಾರು', 'ಹದಿನೇಳು', 'ಹದಿನೆಂಟು', 'ಹತ್ತೊಂಬತ್ತು',
@@ -39,26 +63,13 @@ const BELOW_HUNDRED = [
 const SCALE_WORDS = ['', 'ಸಾವಿರ', 'ಲಕ್ಷ', 'ಕೋಟಿ', 'ಅಬ್ಜ', 'ಖರ್ವ', 'ನೀಲ', 'ಪದ್ಮ', 'ಶಂಖ']
 
 // ============================================================================
-// Segment Splitting (inlined for performance)
+// Segment Building
 // ============================================================================
 
-function groupByThreeThenTwos (n) {
-  const numStr = n.toString()
-  if (numStr.length <= 3) return [Number(numStr)]
-
-  const segments = []
-  segments.unshift(Number(numStr.slice(-3)))
-
-  let remaining = numStr.slice(0, -3)
-  while (remaining.length > 0) {
-    segments.unshift(Number(remaining.slice(-2)))
-    remaining = remaining.slice(0, -2)
-  }
-
-  return segments
-}
-
-function segmentToWords (n) {
+/**
+ * Builds words for a 0-999 segment.
+ */
+function buildSegment (n) {
   if (n === 0) return ''
   if (n < 100) return BELOW_HUNDRED[n]
 
@@ -75,25 +86,51 @@ function segmentToWords (n) {
 // Conversion Functions
 // ============================================================================
 
+/**
+ * Converts a non-negative integer to Kannada 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} Kannada words
+ */
 function integerToWords (n) {
   if (n === 0n) return ZERO
 
-  const segments = groupByThreeThenTwos(n)
-  const segmentCount = segments.length
+  // Fast path: numbers < 1000 (direct lookup)
+  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
+  }
+
+  // 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
 
-  for (let i = 0; i < segmentCount; i++) {
-    const segmentValue = segments[i]
-    if (segmentValue === 0) continue
+    if (i === 0) {
+      words.push(buildSegment(segment))
+    } else {
+      words.push(BELOW_HUNDRED[segment])
+    }
 
-    const scaleIndex = segmentCount - i - 1
-    words.push(segmentToWords(segmentValue))
-    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) {
@@ -112,8 +149,8 @@ function decimalPartToWords (decimalPart) {
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Kannada words
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
 
@@ -130,8 +167,93 @@ function toWords (value) {
   return result
 }
 
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Converts a positive integer to Kannada ordinal words.
+ *
+ * Kannada ordinals: First 6 are special, then add -ನೇ suffix.
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Kannada 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 Kannada 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 Kannada currency words (Indian Rupee).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Kannada 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/ko-KR.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Converts a numeric value to Korean words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Korean words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCardinal(21)         // '이십일'
+ * toCardinal(10000)      // '만'
+ * toCardinal(1000000)    // '백만'
+ */
+export function toCardinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Korean 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 Korean currency words (Won).
+ *
+ * Korean Won has no subunit (jeon are historical).
+ * Amounts are rounded to whole won.
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Korean 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(1000)   // '천원'
+ * toCurrency(-5)     // '마이너스 오원'
+ */
+export function toCurrency(value: number | string | bigint): string;

package/{lib/languages/ko.js → src/ko-KR.js}

@@ -1,7 +1,7 @@
 /**
- * Korean language converter - Functional Implementation
+ * Korean (South Korea) language converter
  *
- * A performance-optimized number-to-words converter using precomputed lookup tables.
+ * CLDR: ko-KR | Korean as used in South Korea
  *
  * Key features:
  * - Myriad-based (만) grouping - 4 digits
@@ -10,7 +10,9 @@
  * - Hangul numerals
  */
 
-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 (module-level constants)
@@ -31,7 +33,19 @@ const DECIMAL_SEP = '점'
 const SCALES = ['만', '억', '조', '경', '해', '자', '양']
 
 // ============================================================================
-// Precomputed Lookup Tables (built once at module load)
+// Ordinal Vocabulary
+// ============================================================================
+
+const ORDINAL_PREFIX = '제'
+
+// ============================================================================
+// Currency Vocabulary (Korean Won)
+// ============================================================================
+
+const WON = '원'
+
+// ============================================================================
+// Segment Building
 // ============================================================================
 
 /**
@@ -42,9 +56,9 @@ function buildSegment (n) {
   if (n === 0) return ''
 
   const ones = n % 10
-  const tens = Math.floor(n / 10) % 10
-  const hundreds = Math.floor(n / 100) % 10
-  const thousands = Math.floor(n / 1000)
+  const tens = Math.trunc(n / 10) % 10
+  const hundreds = Math.trunc(n / 100) % 10
+  const thousands = Math.trunc(n / 1000)
 
   let result = ''
 
@@ -83,13 +97,6 @@ function buildSegment (n) {
   return result
 }
 
-// Precompute all 10000 segment words (0-9999) for myriad grouping
-const SEGMENTS = new Array(10000)
-
-for (let i = 0; i < 10000; i++) {
-  SEGMENTS[i] = buildSegment(i)
-}
-
 // ============================================================================
 // Conversion Functions
 // ============================================================================
@@ -103,9 +110,9 @@ for (let i = 0; i < 10000; i++) {
 function integerToWords (n) {
   if (n === 0n) return ZERO
 
-  // Fast path: numbers < 10000 (direct lookup)
+  // Fast path: numbers < 10000
   if (n < 10000n) {
-    return SEGMENTS[Number(n)]
+    return buildSegment(Number(n))
   }
 
   // For numbers >= 10000, use myriad decomposition
@@ -148,7 +155,7 @@ function buildLargeNumberWords (n) {
     if (segment !== 0) {
       if (scaleIndex === 0) {
         // Units segment (no scale word)
-        parts.push({ word: SEGMENTS[segment], isScale: false })
+        parts.push({ word: buildSegment(segment), isScale: false })
       } else {
         // Segment with scale word
         const scaleWord = SCALES[scaleIndex - 1]
@@ -157,7 +164,7 @@ function buildLargeNumberWords (n) {
         if (segment === 1) {
           parts.push({ word: scaleWord, isScale: true })
         } else {
-          parts.push({ word: SEGMENTS[segment], isScale: false })
+          parts.push({ word: buildSegment(segment), isScale: false })
           parts.push({ word: scaleWord, isScale: true })
         }
       }
@@ -233,12 +240,12 @@ function decimalPartToWords (decimalPart) {
  * @throws {Error} If value is not a valid number format
  *
  * @example
- * toWords(21)         // '이십일'
- * toWords(10000)      // '만'
- * toWords(1000000)    // '백만'
+ * toCardinal(21)         // '이십일'
+ * toCardinal(10000)      // '만'
+ * toCardinal(1000000)    // '백만'
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   const parts = []
 
@@ -256,8 +263,76 @@ function toWords (value) {
   return parts.join(' ')
 }
 
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Korean ordinal words.
+ *
+ * Korean ordinals use "제" prefix + Sino-Korean numeral.
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Korean ordinal words
+ */
+function integerToOrdinal (n) {
+  return ORDINAL_PREFIX + integerToWords(n)
+}
+
+/**
+ * Converts a numeric value to Korean 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 Korean currency words (Won).
+ *
+ * Korean Won has no subunit (jeon are historical).
+ * Amounts are rounded to whole won.
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Korean 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(1000)   // '천원'
+ * toCurrency(-5)     // '마이너스 오원'
+ */
+function toCurrency (value) {
+  const { isNegative, dollars: won } = parseCurrencyValue(value)
+
+  let result = ''
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  result += integerToWords(won)
+  result += WON
+
+  return result
+}
+
 // ============================================================================
 // Public API
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/lt-LT.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Converts a numeric value to Lithuanian words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @param {Object} [options] - Conversion options
+ * @param {string} [options.gender='masculine'] - Gender for numbers < 1000
+ * @returns {string} The number in Lithuanian words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCardinal(42)                          // 'keturiasdešimt du'
+ * toCardinal(1, { gender: 'feminine' })   // 'viena'
+ * toCardinal(1000000)                     // 'vienas milijonas'
+ */
+export function toCardinal(value: number | string | bigint, options?: {
+    gender?: string | undefined;
+}): string;
+/**
+ * Converts a numeric value to Lithuanian 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)    // 'pirmas'
+ * toOrdinal(2)    // 'antras'
+ * toOrdinal(21)   // 'dvidešimt pirmas'
+ * toOrdinal(100)  // 'šimtasis'
+ * toOrdinal(1000) // 'tūkstantasis'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Lithuanian currency words (Euro).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Lithuanian 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)     // 'keturiasdešimt du eurai'
+ * toCurrency(1)      // 'vienas euras'
+ * toCurrency(1.50)   // 'vienas euras penkiasdešimt centų'
+ * toCurrency(-5)     // 'minus penki eurai'
+ */
+export function toCurrency(value: number | string | bigint): string;