n2words 3.1.0 → 4.0.0

package/{lib/languages/sv.js → src/sv-SE.js}

@@ -1,7 +1,7 @@
 /**
- * Swedish language converter - Functional Implementation
+ * Swedish (Sweden) language converter
  *
- * Self-contained module with its own input validation, ready for subpath exports.
+ * CLDR: sv-SE | Swedish as used in Sweden
  *
  * Key features:
  * - Hyphenation for tens-ones (tjugo-ett)
@@ -11,7 +11,9 @@
  * - Long scale naming with -ard forms
  */
 
-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,6 +33,35 @@ const DECIMAL_SEP = 'komma'
 // Scale words (long scale with -ard forms)
 const SCALES = ['tusen', 'miljon', 'miljard', 'biljon', 'biljard', 'triljon', 'triljard', 'kvadriljon']
 
+// ============================================================================
+// Ordinal Vocabulary
+// ============================================================================
+
+// Swedish ordinals: 1st-2nd use -a (första, andra), then -de suffix
+// Numbers ending in 1, 2 (except 11, 12) use special forms
+const ORDINAL_ONES = {
+  1: 'första',
+  2: 'andra',
+  3: 'tredje',
+  4: 'fjärde',
+  5: 'femte',
+  6: 'sjätte',
+  7: 'sjunde',
+  8: 'åttonde',
+  9: 'nionde',
+  10: 'tionde',
+  11: 'elfte',
+  12: 'tolfte'
+}
+
+// ============================================================================
+// Currency Vocabulary (Swedish Krona)
+// ============================================================================
+
+const KRONA = 'krona'
+const KRONOR = 'kronor' // plural
+const ORE = 'öre' // same singular and plural
+
 // ============================================================================
 // Segment Building
 // ============================================================================
@@ -43,8 +74,8 @@ function buildSegment (n) {
   if (n === 0) return { word: '', hasHundred: false, lessThan100: false }
 
   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 = []
   let hasHundred = false
@@ -265,12 +296,12 @@ function decimalPartToWords (decimalPart) {
  * @throws {Error} If value is not a valid number format
  *
  * @example
- * toWords(42)       // 'fyrtio-två'
- * toWords(101)      // 'hundra och ett'
- * toWords(1000000)  // 'en miljon'
+ * toCardinal(42)       // 'fyrtio-två'
+ * toCardinal(101)      // 'hundra och ett'
+ * toCardinal(1000000)  // 'en miljon'
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
 
@@ -287,8 +318,102 @@ function toWords (value) {
   return result
 }
 
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Swedish ordinal words.
+ *
+ * Swedish ordinals: första (1st), andra (2nd), tredje (3rd), etc.
+ * Most use cardinal + de suffix, with special forms 1-12.
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Swedish ordinal words
+ */
+function integerToOrdinal (n) {
+  // Special forms for 1-12
+  if (n >= 1n && n <= 12n) {
+    return ORDINAL_ONES[Number(n)]
+  }
+
+  // For numbers > 12, add -de suffix to cardinal
+  // But need to handle endings in 1, 2 specially
+  const cardinal = integerToWords(n)
+
+  // Numbers ending in ett -> första pattern not used for compound
+  // Swedish ordinals mostly add -de for >12
+  return cardinal + 'de'
+}
+
+/**
+ * Converts a numeric value to Swedish 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)    // 'första'
+ * toOrdinal(2)    // 'andra'
+ * toOrdinal(21)   // 'tjugo-ettde'
+ */
+function toOrdinal (value) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value)
+// ============================================================================
+
+/**
+ * Converts a numeric value to Swedish currency words (Swedish Krona).
+ *
+ * Uses krona/kronor and öre (100 öre = 1 krona).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Swedish currency words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCurrency(1)      // 'en krona'
+ * toCurrency(42)     // 'fyrtio-två kronor'
+ * toCurrency(1.50)   // 'en krona och femtio öre'
+ */
+function toCurrency (value) {
+  const { isNegative, dollars: kronor, cents: ore } = parseCurrencyValue(value)
+
+  let result = ''
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  // Kronor part
+  if (kronor > 0n || ore === 0n) {
+    // Use "en" for 1 krona (not "ett")
+    if (kronor === 1n) {
+      result += 'en ' + KRONA
+    } else {
+      result += integerToWords(kronor) + ' ' + KRONOR
+    }
+  }
+
+  // Öre part
+  if (ore > 0n) {
+    if (kronor > 0n) {
+      result += ' och '
+    }
+    result += integerToWords(ore) + ' ' + ORE
+  }
+
+  return result
+}
+
 // ============================================================================
 // Public API
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/sw-KE.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Converts a numeric value to Swahili words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Swahili words
+ */
+export function toCardinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Swahili 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)    // 'wa kwanza'
+ * toOrdinal(2)    // 'wa pili'
+ * toOrdinal(10)   // 'wa kumi'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Swahili currency words (Kenyan Shilling).
+ *
+ * Uses shilingi and senti (100 senti = 1 shilingi).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Swahili 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)     // 'shilingi arobaini na mbili'
+ * toCurrency(1.50)   // 'shilingi moja na senti hamsini'
+ * toCurrency(-5)     // 'minus shilingi tano'
+ */
+export function toCurrency(value: number | string | bigint): string;

package/{lib/languages/sw.js → src/sw-KE.js}

@@ -1,7 +1,7 @@
 /**
- * Swahili language converter - Functional Implementation
+ * Swahili (Kenya) language converter
  *
- * Self-contained converter with precomputed lookup tables.
+ * CLDR: sw-KE | Swahili as used in Kenya
  *
  * Key features:
  * - "na" connector for compound numbers
@@ -9,7 +9,9 @@
  * - Scale words: elfu, milioni, bilioni
  */
 
-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
@@ -24,6 +26,32 @@ const ZERO = 'sifuri'
 const NEGATIVE = 'minus'
 const DECIMAL_SEP = 'nukta'
 
+// ============================================================================
+// Ordinal Vocabulary
+// ============================================================================
+
+// Swahili ordinals use "wa" + cardinal: wa kwanza (1st), wa pili (2nd)
+// First few have special forms
+const ORDINAL_ONES = {
+  1: 'wa kwanza',
+  2: 'wa pili',
+  3: 'wa tatu',
+  4: 'wa nne',
+  5: 'wa tano',
+  6: 'wa sita',
+  7: 'wa saba',
+  8: 'wa nane',
+  9: 'wa tisa'
+}
+const ORDINAL_PREFIX = 'wa'
+
+// ============================================================================
+// Currency Vocabulary (Kenyan Shilling)
+// ============================================================================
+
+const SHILLING = 'shilingi'
+const CENT = 'senti'
+
 // ============================================================================
 // Conversion Functions
 // ============================================================================
@@ -128,8 +156,8 @@ function decimalPartToWords (decimalPart) {
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Swahili words
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
 
@@ -146,8 +174,91 @@ function toWords (value) {
   return result
 }
 
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Swahili ordinal words.
+ *
+ * Swahili ordinals: wa kwanza (1st), wa pili (2nd), wa tatu (3rd), etc.
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Swahili ordinal words
+ */
+function integerToOrdinal (n) {
+  // Special forms for 1-9
+  if (n >= 1n && n <= 9n) {
+    return ORDINAL_ONES[Number(n)]
+  }
+
+  // For 10+, use "wa" prefix + cardinal
+  return ORDINAL_PREFIX + ' ' + integerToWords(n)
+}
+
+/**
+ * Converts a numeric value to Swahili 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)    // 'wa kwanza'
+ * toOrdinal(2)    // 'wa pili'
+ * toOrdinal(10)   // 'wa kumi'
+ */
+function toOrdinal (value) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value)
+// ============================================================================
+
+/**
+ * Converts a numeric value to Swahili currency words (Kenyan Shilling).
+ *
+ * Uses shilingi and senti (100 senti = 1 shilingi).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Swahili 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)     // 'shilingi arobaini na mbili'
+ * toCurrency(1.50)   // 'shilingi moja na senti hamsini'
+ * toCurrency(-5)     // 'minus shilingi tano'
+ */
+function toCurrency (value) {
+  const { isNegative, dollars: shillings, cents: senti } = parseCurrencyValue(value)
+
+  let result = ''
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  // Shillings part
+  if (shillings > 0n || senti === 0n) {
+    result += SHILLING + ' ' + integerToWords(shillings)
+  }
+
+  // Senti part
+  if (senti > 0n) {
+    if (shillings > 0n) {
+      result += ' na '
+    }
+    result += CENT + ' ' + integerToWords(senti)
+  }
+
+  return result
+}
+
 // ============================================================================
 // Exports
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/ta-IN.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Converts a numeric value to Tamil words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Tamil words
+ */
+export function toCardinal(value: number | string | bigint): string;
+/**
+ * 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)   // 'பத்துஆவது'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * 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)   // 'ஒன்று பைசா'
+ */
+export function toCurrency(value: number | string | bigint): string;

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

@@ -1,7 +1,7 @@
 /**
- * Tamil language converter - Functional Implementation
+ * Tamil (India) language converter
  *
- * Self-contained module with its own input validation, ready for subpath exports.
+ * CLDR: ta-IN | Tamil as used in India
  *
  * Key features:
  * - Indian numbering system (ஆயிரம், லட்சம், கோடி)
@@ -13,7 +13,9 @@
  * - 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
@@ -23,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 = [
   'பூஜ்ஜியம்', 'ஒன்று', 'இரண்டு', 'மூன்று', 'நான்கு', 'ஐந்து', 'ஆறு', 'ஏழு', 'எட்டு', 'ஒன்பது',
   'பத்து', 'பதினொன்று', 'பன்னிரண்டு', 'பதிமூன்று', 'பதினான்கு', 'பதினைந்து', 'பதினாறு', 'பதினேழு', 'பதினெட்டு', 'பத்தொன்பது',
@@ -142,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 = ''
 
@@ -160,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;