n2words 3.0.0 → 4.0.0

package/src/id-ID.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Converts a numeric value to Indonesian words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Indonesian words
+ */
+export function toCardinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Indonesian 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)    // 'pertama'
+ * toOrdinal(2)    // 'kedua'
+ * toOrdinal(10)   // 'kesepuluh'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Indonesian currency words (Rupiah).
+ *
+ * Indonesian Rupiah has no subunit in modern usage (sen are historical).
+ * Amounts are rounded to whole rupiah.
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Indonesian 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)     // 'empat puluh dua rupiah'
+ * toCurrency(1000)   // 'seribu rupiah'
+ * toCurrency(-5)     // 'min lima rupiah'
+ */
+export function toCurrency(value: number | string | bigint): string;

package/{lib/languages/id.js → src/id-ID.js}

@@ -1,7 +1,7 @@
 /**
- * Indonesian language converter - Functional Implementation
+ * Indonesian (Indonesia) language converter
  *
- * Self-contained converter with precomputed lookup tables.
+ * CLDR: id-ID | Indonesian as used in Indonesia
  *
  * Key features:
  * - "Se-" prefix for 100 (seratus) and 1000 (seribu)
@@ -10,7 +10,9 @@
  * - Indonesian uses "satu juta" (not "sejuta") for millions+
  */
 
-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
@@ -29,15 +31,29 @@ const NEGATIVE = 'min'
 const DECIMAL_SEP = 'koma'
 
 // ============================================================================
-// Precomputed Lookup Tables
+// Ordinal Vocabulary
+// ============================================================================
+
+const ORDINAL_PREFIX = 'ke'
+// First is special: "pertama" (not "kesatu")
+const ORDINAL_FIRST = 'pertama'
+
+// ============================================================================
+// Currency Vocabulary (Indonesian Rupiah)
+// ============================================================================
+
+const RUPIAH = 'rupiah'
+
+// ============================================================================
+// Segment Building
 // ============================================================================
 
 function buildSegment (n) {
   if (n === 0) return ''
 
   const onesDigit = n % 10
-  const tensDigit = Math.floor(n / 10) % 10
-  const hundredsDigit = Math.floor(n / 100)
+  const tensDigit = Math.trunc(n / 10) % 10
+  const hundredsDigit = Math.trunc(n / 100)
 
   const parts = []
 
@@ -68,11 +84,6 @@ function buildSegment (n) {
   return parts.join(' ')
 }
 
-const SEGMENTS = new Array(1000)
-for (let i = 0; i < 1000; i++) {
-  SEGMENTS[i] = buildSegment(i)
-}
-
 // ============================================================================
 // Conversion Functions
 // ============================================================================
@@ -81,7 +92,7 @@ function integerToWords (n) {
   if (n === 0n) return ZERO
 
   if (n < 1000n) {
-    return SEGMENTS[Number(n)]
+    return buildSegment(Number(n))
   }
 
   if (n < 1_000_000n) {
@@ -92,11 +103,11 @@ function integerToWords (n) {
     if (thousands === 1) {
       result = 'se' + THOUSAND_WORD
     } else {
-      result = SEGMENTS[thousands] + ' ' + THOUSAND_WORD
+      result = buildSegment(thousands) + ' ' + THOUSAND_WORD
     }
 
     if (remainder > 0) {
-      result += ' ' + SEGMENTS[remainder]
+      result += ' ' + buildSegment(remainder)
     }
 
     return result
@@ -131,17 +142,17 @@ function buildLargeNumberWords (n) {
 
     if (segment !== 0) {
       if (scaleIndex === 0) {
-        parts.push(SEGMENTS[segment])
+        parts.push(buildSegment(segment))
       } else if (scaleIndex === 1) {
         if (segment === 1) {
           parts.push('se' + THOUSAND_WORD)
         } else {
-          parts.push(SEGMENTS[segment] + ' ' + THOUSAND_WORD)
+          parts.push(buildSegment(segment) + ' ' + THOUSAND_WORD)
         }
       } else {
         // Indonesian: "satu juta" not "sejuta"
         const scaleWord = SCALE_WORDS[scaleIndex - 2]
-        parts.push(SEGMENTS[segment] + ' ' + scaleWord)
+        parts.push(buildSegment(segment) + ' ' + scaleWord)
       }
     }
 
@@ -176,8 +187,8 @@ function decimalPartToWords (decimalPart) {
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Indonesian words
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
 
@@ -194,8 +205,83 @@ function toWords (value) {
   return result
 }
 
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Indonesian ordinal words.
+ *
+ * Indonesian ordinals use "ke-" prefix + cardinal number.
+ * Special case: "pertama" for 1st (not "kesatu").
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Indonesian ordinal words
+ */
+function integerToOrdinal (n) {
+  // Special case: 1st is "pertama"
+  if (n === 1n) {
+    return ORDINAL_FIRST
+  }
+
+  // All others: "ke" + cardinal (no hyphen in Indonesian)
+  return ORDINAL_PREFIX + integerToWords(n)
+}
+
+/**
+ * Converts a numeric value to Indonesian 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)    // 'pertama'
+ * toOrdinal(2)    // 'kedua'
+ * toOrdinal(10)   // 'kesepuluh'
+ */
+function toOrdinal (value) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value)
+// ============================================================================
+
+/**
+ * Converts a numeric value to Indonesian currency words (Rupiah).
+ *
+ * Indonesian Rupiah has no subunit in modern usage (sen are historical).
+ * Amounts are rounded to whole rupiah.
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Indonesian 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)     // 'empat puluh dua rupiah'
+ * toCurrency(1000)   // 'seribu rupiah'
+ * toCurrency(-5)     // 'min lima rupiah'
+ */
+function toCurrency (value) {
+  const { isNegative, dollars: rupiah } = parseCurrencyValue(value)
+
+  let result = ''
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  result += integerToWords(rupiah)
+  result += ' ' + RUPIAH
+
+  return result
+}
+
 // ============================================================================
 // Exports
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/it-IT.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Converts a numeric value to Italian 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 Italian words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCardinal(28)           // 'ventotto'
+ * toCardinal(23)           // 'ventitré'
+ * toCardinal(1000)         // 'mille'
+ * toCardinal(2000)         // 'duemila'
+ * toCardinal(1000000)      // 'un milione'
+ */
+export function toCardinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Italian ordinal words.
+ *
+ * Italian ordinals: primo, secondo, terzo... (1-10 irregular)
+ * For 11+: cardinal word (drop final vowel) + -esimo
+ *
+ * @param {number | string | bigint} value - The numeric value to convert (positive integer)
+ * @returns {string} The number as ordinal words (masculine form)
+ * @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)    // 'primo'
+ * toOrdinal(2)    // 'secondo'
+ * toOrdinal(11)   // 'undicesimo'
+ * toOrdinal(21)   // 'ventunesimo'
+ * toOrdinal(100)  // 'centesimo'
+ * toOrdinal(1000) // 'millesimo'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Italian currency words (Euro).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @param {Object} [options] - Optional configuration
+ * @param {boolean} [options.and=true] - Use "e" between euros and centesimi
+ * @returns {string} The amount in Italian 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)                 // 'quarantadue euro e cinquanta centesimi'
+ * toCurrency(1)                     // 'un euro'
+ * toCurrency(0.99)                  // 'novantanove centesimi'
+ * toCurrency(0.01)                  // 'un centesimo'
+ * toCurrency(42.50, { and: false }) // 'quarantadue euro cinquanta centesimi'
+ */
+export function toCurrency(value: number | string | bigint, options?: {
+    and?: boolean | undefined;
+}): string;