n2words 3.0.0 → 4.0.0

package/{lib/languages/ja.js → src/ja-JP.js}

@@ -1,20 +1,18 @@
 /**
- * Japanese language converter - Functional Implementation
+ * Japanese (Japan) language converter
  *
- * A performance-optimized number-to-words converter using precomputed lookup tables.
- * Self-contained module with its own input validation, ready for subpath exports.
+ * CLDR: ja-JP | Japanese as used in Japan
  *
- * Key optimization: Precompute all segment values (0-9999) at module load.
- * This eliminates all per-call string manipulation for segment conversion.
- *
- * Japanese-specific rules (handled in precomputation):
+ * Japanese-specific rules:
  * - Myriad (万-based) grouping: 4 digits per segment instead of 3
  * - 一 omission: Omit "一" before 十, 百, 千 but NOT before 万 and higher scales
  * - Kanji numerals: 零一二三四五六七八九
  * - No spaces between characters
  */
 
-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)
@@ -49,27 +47,43 @@ const ZERO = '零'
 const NEGATIVE = 'マイナス'
 const DECIMAL_SEP = '点'
 
+// ============================================================================
+// Ordinal Vocabulary
+// ============================================================================
+
+// Ordinal prefix
+const ORDINAL_PREFIX = '第'
+
+// ============================================================================
+// Currency Vocabulary (Japanese Yen)
+// ============================================================================
+
+// Yen (main unit)
+const YEN = '円'
+
+// Sen (1/100 yen) - historically used, now rare
+const SEN = '銭'
+
 // Internal scale words (within 4-digit segments)
 const TEN = '十'
 const HUNDRED = '百'
 const THOUSAND = '千'
 
 // ============================================================================
-// Precomputed Lookup Tables (built once at module load)
+// Segment Building
 // ============================================================================
 
 /**
  * Builds segment word for 0-9999 with 一 omission rules.
  * - Omit 一 before 十, 百, 千
- * Only used during table construction.
  */
 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 = ''
 
@@ -108,13 +122,6 @@ function buildSegment (n) {
   return result
 }
 
-// Precompute all 10000 segment words (0-9999)
-// SEGMENTS[n] gives the Japanese word for n within a segment
-const SEGMENTS = new Array(10000)
-for (let i = 0; i < 10000; i++) {
-  SEGMENTS[i] = buildSegment(i)
-}
-
 // ============================================================================
 // Conversion Functions
 // ============================================================================
@@ -128,9 +135,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))
   }
 
   // Fast path: numbers < 100,000,000 (万 range)
@@ -143,11 +150,11 @@ function integerToWords (n) {
     if (man === 1) {
       result = '一' + SCALES[0] // 一万
     } else {
-      result = SEGMENTS[man] + SCALES[0]
+      result = buildSegment(man) + SCALES[0]
     }
 
     if (remainder > 0) {
-      result += SEGMENTS[remainder]
+      result += buildSegment(remainder)
     }
 
     return result
@@ -186,11 +193,11 @@ function buildLargeNumberWords (n) {
       if (segment === 1) {
         result += '一' + SCALES[i - 1]
       } else {
-        result += SEGMENTS[segment] + SCALES[i - 1]
+        result += buildSegment(segment) + SCALES[i - 1]
       }
     } else {
       // Units segment (no scale word)
-      result += SEGMENTS[segment]
+      result += buildSegment(segment)
     }
   }
 
@@ -230,12 +237,12 @@ function decimalPartToWords (decimalPart) {
  * @throws {Error} If value is not a valid number format
  *
  * @example
- * toWords(42)           // '四十二'
- * toWords(10000)        // '一万'
- * toWords(100000000)    // '一億'
+ * toCardinal(42)           // '四十二'
+ * toCardinal(10000)        // '一万'
+ * toCardinal(100000000)    // '一億'
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
 
@@ -252,8 +259,88 @@ function toWords (value) {
   return result
 }
 
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Converts a positive integer to Japanese ordinal words.
+ *
+ * Japanese ordinals: 第 prefix + cardinal number.
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Japanese ordinal words
+ */
+function integerToOrdinal (n) {
+  return ORDINAL_PREFIX + integerToWords(n)
+}
+
+/**
+ * Converts a numeric value to Japanese 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(10)   // '第十'
+ * toOrdinal(100)  // '第百'
+ */
+function toOrdinal (value) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value, options?)
+// ============================================================================
+
+/**
+ * Converts a numeric value to Japanese currency words (Yen).
+ *
+ * Note: Sen (銭, 1/100 yen) is included for completeness but is rarely used
+ * in modern Japan. Most transactions are in whole yen.
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Japanese 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)      // '一円'
+ * toCurrency(0.50)   // '五十銭'
+ * toCurrency(42.50)  // '四十二円五十銭'
+ */
+function toCurrency (value) {
+  const { isNegative, dollars: yen, cents: sen } = parseCurrencyValue(value)
+
+  // Build result
+  let result = ''
+  if (isNegative) result = NEGATIVE
+
+  // Yen part
+  if (yen > 0n) {
+    result += integerToWords(yen) + YEN
+  }
+
+  // Sen part (1/100 yen)
+  if (sen > 0n) {
+    result += integerToWords(sen) + SEN
+  }
+
+  // Handle zero case
+  if (yen === 0n && sen === 0n) {
+    result += ZERO + YEN
+  }
+
+  return result
+}
+
 // ============================================================================
 // Public API
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/ka-GE.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Converts a numeric value to Georgian 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
+ * @returns {string} The number in Georgian 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(100)          // 'ასი'
+ * toCardinal(1000)         // 'ათასი'
+ */
+export function toCardinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Georgian ordinal words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The ordinal in Georgian words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a positive integer
+ *
+ * @example
+ * toOrdinal(1)   // 'პირველი'
+ * toOrdinal(10)  // 'მეათე'
+ * toOrdinal(21)  // 'მეოცდაერთე'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Georgian Lari currency words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The currency in Georgian words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCurrency(1)     // 'ერთი ლარი'
+ * toCurrency(2.50)  // 'ორი ლარი ორმოცდაათი თეთრი'
+ */
+export function toCurrency(value: number | string | bigint): string;

package/src/ka-GE.js

@@ -0,0 +1,393 @@
+/**
+ * Georgian (Georgia) language converter
+ *
+ * CLDR: ka-GE | Georgian as used in Georgia
+ *
+ * Georgian-specific rules:
+ * - Vigesimal (base-20) system for 20-99
+ * - 40 = ორმოცი (2×20), 60 = სამოცი (3×20), 80 = ოთხმოცი (4×20)
+ * - 30/50/70/90 use "და" + "ათი": ოცდაათი (20+10), ორმოცდაათი (40+10)
+ * - Compound numbers use "და" (da = "and") connector
+ * - Hundreds: unit prefix + ას (ორასი = 200)
+ * - Short scale for large numbers (მილიონი, მილიარდი, ტრილიონი)
+ */
+
+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)
+// ============================================================================
+
+// Numbers 0-9 (primitives)
+const ONES = ['ნული', 'ერთი', 'ორი', 'სამი', 'ოთხი', 'ხუთი', 'ექვსი', 'შვიდი', 'რვა', 'ცხრა']
+
+// Numbers 10-19
+const TEENS = ['ათი', 'თერთმეტი', 'თორმეტი', 'ცამეტი', 'თოთხმეტი', 'თხუთმეტი', 'თექვსმეტი', 'ჩვიდმეტი', 'თვრამეტი', 'ცხრამეტი']
+
+// Vigesimal bases: 20, 40, 60, 80 (with და connector forms)
+const VIGESIMAL = ['', 'ოცი', 'ორმოცი', 'სამოცი', 'ოთხმოცი']
+const VIGESIMAL_DA = ['', 'ოცდა', 'ორმოცდა', 'სამოცდა', 'ოთხმოცდა']
+
+// Prefixes for hundreds (unit forms without final vowel)
+const HUNDRED_PREFIXES = ['', '', 'ორ', 'სამ', 'ოთხ', 'ხუთ', 'ექვს', 'შვიდ', 'რვა', 'ცხრა']
+
+const HUNDRED = 'ასი'
+const HUNDRED_STEM = 'ას' // Without final vowel
+const THOUSAND = 'ათასი'
+const THOUSAND_STEM = 'ათას' // Without final vowel
+
+// Scale words (short scale) - indexed by segment position
+const SCALES = ['', '', 'მილიონი', 'მილიარდი', 'ტრილიონი', 'კვადრილიონი', 'კვინტილიონი', 'სექსტილიონი']
+
+const ZERO = 'ნული'
+const NEGATIVE = 'მინუს'
+const DECIMAL_SEP = 'მთელი'
+
+// Ordinal suffix (Georgian adds -ე to form ordinals)
+const ORDINAL_SUFFIX = 'ე'
+
+// Ordinal forms for 1-9 (these are special)
+const ORDINAL_ONES = ['', 'პირველი', 'მეორე', 'მესამე', 'მეოთხე', 'მეხუთე', 'მეექვსე', 'მეშვიდე', 'მერვე', 'მეცხრე']
+
+// Currency (Georgian Lari)
+const LARI = 'ლარი'
+const TETRI = 'თეთრი'
+
+// ============================================================================
+// Segment Building
+// ============================================================================
+
+/**
+ * Builds segment word for 0-99 using vigesimal system.
+ * @param {number} n - Number 0-99
+ * @returns {string} Georgian word
+ */
+function buildTens (n) {
+  if (n < 10) return ONES[n]
+  if (n < 20) return TEENS[n - 10]
+
+  const vigesimalGroup = Math.trunc(n / 20)
+  const remainder = n % 20
+
+  if (remainder === 0) {
+    return VIGESIMAL[vigesimalGroup]
+  }
+
+  // Use და connector: ოცდა + remainder
+  const base = VIGESIMAL_DA[vigesimalGroup]
+  if (remainder < 10) {
+    return base + ONES[remainder]
+  }
+  return base + TEENS[remainder - 10]
+}
+
+/**
+ * Builds segment word for 0-999.
+ * Returns object with full form and stem form (without final vowel).
+ * @param {number} n - Number 0-999
+ * @returns {{full: string, stem: string}} Georgian words
+ */
+function buildSegment (n) {
+  if (n === 0) return { full: '', stem: '' }
+  if (n < 100) {
+    const word = buildTens(n)
+    // Remove final vowel for stem
+    const lastChar = word.slice(-1)
+    const stem = (lastChar === 'ი' || lastChar === 'ა') ? word.slice(0, -1) : word
+    return { full: word, stem }
+  }
+
+  const hundreds = Math.trunc(n / 100)
+  const remainder = n % 100
+
+  // Build hundreds: ასი (100), ორასი (200), etc.
+  let hundredWord
+  if (hundreds === 1) {
+    hundredWord = remainder > 0 ? HUNDRED_STEM : HUNDRED
+  } else {
+    hundredWord = HUNDRED_PREFIXES[hundreds] + (remainder > 0 ? HUNDRED_STEM : HUNDRED)
+  }
+
+  if (remainder > 0) {
+    const remainderWord = buildTens(remainder)
+    const full = hundredWord + ' ' + remainderWord
+    // Stem removes final vowel from remainder
+    const lastChar = remainderWord.slice(-1)
+    const remainderStem = (lastChar === 'ი' || lastChar === 'ა') ? remainderWord.slice(0, -1) : remainderWord
+    return { full, stem: hundredWord + ' ' + remainderStem }
+  }
+
+  // Hundreds only - stem removes final ი
+  return { full: hundredWord, stem: hundredWord.slice(0, -1) }
+}
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Georgian words.
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} Georgian words
+ */
+function integerToWords (n) {
+  if (n === 0n) return ZERO
+
+  // Fast path: numbers < 1000
+  if (n < 1000n) {
+    const { full } = buildSegment(Number(n))
+    return full
+  }
+
+  // Fast path: numbers < 1,000,000 (thousands)
+  if (n < 1_000_000n) {
+    const thousands = Number(n / 1000n)
+    const remainder = Number(n % 1000n)
+
+    let result
+    if (thousands === 1) {
+      // "ათასი" not "ერთი ათასი"
+      result = remainder > 0 ? THOUSAND_STEM : THOUSAND
+    } else {
+      // Use stem form before ათასი
+      const { stem: thousandsPart } = buildSegment(thousands)
+      result = thousandsPart + ' ' + (remainder > 0 ? THOUSAND_STEM : THOUSAND)
+    }
+
+    if (remainder > 0) {
+      const { full: remainderWord } = buildSegment(remainder)
+      result += ' ' + remainderWord
+    }
+
+    return result
+  }
+
+  // For numbers >= 1,000,000, use scale decomposition
+  return buildLargeNumberWords(n)
+}
+
+/**
+ * Builds words for numbers >= 1,000,000.
+ *
+ * @param {bigint} n - Number >= 1,000,000
+ * @returns {string} Georgian words
+ */
+function buildLargeNumberWords (n) {
+  const numStr = n.toString()
+  const len = numStr.length
+
+  // Build segments of 3 digits from left to right
+  const segments = []
+  const segmentSize = 3
+
+  const remainderLen = len % segmentSize
+  let pos = 0
+  if (remainderLen > 0) {
+    segments.push(Number(numStr.slice(0, remainderLen)))
+    pos = remainderLen
+  }
+  while (pos < len) {
+    segments.push(Number(numStr.slice(pos, pos + segmentSize)))
+    pos += segmentSize
+  }
+
+  // Convert segments to words
+  const parts = []
+  let scaleIndex = segments.length - 1
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i]
+
+    if (segment !== 0) {
+      if (scaleIndex === 0) {
+        // Units (no scale)
+        const { full } = buildSegment(segment)
+        parts.push(full)
+      } else if (scaleIndex === 1) {
+        // Thousands - check if there's a remainder
+        const hasRemainder = segments.slice(i + 1).some(s => s !== 0)
+        const thousandWord = hasRemainder ? THOUSAND_STEM : THOUSAND
+
+        if (segment === 1) {
+          parts.push(thousandWord)
+        } else {
+          const { stem } = buildSegment(segment)
+          parts.push(stem + ' ' + thousandWord)
+        }
+      } else {
+        // Million and above
+        const scaleWord = SCALES[scaleIndex] || SCALES[SCALES.length - 1]
+        if (segment === 1) {
+          parts.push('ერთი ' + scaleWord)
+        } else {
+          const { full } = buildSegment(segment)
+          parts.push(full + ' ' + scaleWord)
+        }
+      }
+    }
+
+    scaleIndex--
+  }
+
+  return parts.join(' ')
+}
+
+/**
+ * Converts decimal digits to Georgian words.
+ *
+ * @param {string} decimalPart - Decimal digits (without the point)
+ * @returns {string} Georgian words for decimal part
+ */
+function decimalPartToWords (decimalPart) {
+  let result = ''
+
+  // Handle leading zeros
+  let i = 0
+  while (i < decimalPart.length && decimalPart[i] === '0') {
+    if (result) result += ' '
+    result += ZERO
+    i++
+  }
+
+  // Convert remainder as a single number
+  const remainder = decimalPart.slice(i)
+  if (remainder) {
+    if (result) result += ' '
+    result += integerToWords(BigInt(remainder))
+  }
+
+  return result
+}
+
+/**
+ * Converts a numeric value to Georgian 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
+ * @returns {string} The number in Georgian 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(100)          // 'ასი'
+ * toCardinal(1000)         // 'ათასი'
+ */
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
+
+  let result = ''
+
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  result += integerToWords(integerPart)
+
+  if (decimalPart) {
+    result += ' ' + DECIMAL_SEP + ' ' + decimalPartToWords(decimalPart)
+  }
+
+  return result
+}
+
+// ============================================================================
+// Ordinal Functions
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Georgian ordinal words.
+ * Georgian ordinals are formed by:
+ * - 1-9: special forms (პირველი, მეორე, მესამე, etc.)
+ * - 10+: მე- prefix + cardinal + -ე suffix
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} Georgian ordinal words
+ */
+function integerToOrdinal (n) {
+  if (n === 0n) return ''
+  if (n <= 9n) return ORDINAL_ONES[Number(n)]
+
+  // For 10+, use მე- + cardinal stem + -ე
+  const cardinal = integerToWords(n)
+
+  // Remove final vowel and add -ე suffix
+  const lastChar = cardinal.slice(-1)
+  let stem
+  if (lastChar === 'ი' || lastChar === 'ა') {
+    stem = cardinal.slice(0, -1)
+  } else {
+    stem = cardinal
+  }
+
+  return 'მე' + stem + ORDINAL_SUFFIX
+}
+
+/**
+ * Converts a numeric value to Georgian ordinal words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The ordinal in Georgian words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a positive integer
+ *
+ * @example
+ * toOrdinal(1)   // 'პირველი'
+ * toOrdinal(10)  // 'მეათე'
+ * toOrdinal(21)  // 'მეოცდაერთე'
+ */
+function toOrdinal (value) {
+  const n = parseOrdinalValue(value)
+  return integerToOrdinal(n)
+}
+
+// ============================================================================
+// Currency Functions
+// ============================================================================
+
+/**
+ * Converts a numeric value to Georgian Lari currency words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The currency in Georgian words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCurrency(1)     // 'ერთი ლარი'
+ * toCurrency(2.50)  // 'ორი ლარი ორმოცდაათი თეთრი'
+ */
+function toCurrency (value) {
+  const { isNegative, dollars, cents } = parseCurrencyValue(value)
+
+  const parts = []
+
+  if (isNegative) {
+    parts.push(NEGATIVE)
+  }
+
+  // Lari
+  if (dollars > 0n || cents === 0n) {
+    const lariWord = integerToWords(dollars)
+    parts.push(lariWord + ' ' + LARI)
+  }
+
+  // Tetri
+  if (cents > 0n) {
+    const tetriWord = integerToWords(cents)
+    parts.push(tetriWord + ' ' + TETRI)
+  }
+
+  return parts.join(' ')
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+export { toCardinal, toOrdinal, toCurrency }