n2words 3.1.0 → 4.0.0

package/{lib/languages/ar.js → src/ar-SA.js}

@@ -1,5 +1,7 @@
 /**
- * Arabic language converter - Functional Implementation
+ * Arabic (Saudi Arabia) language converter
+ *
+ * CLDR: ar-SA | Modern Standard Arabic as used in Saudi Arabia
  *
  * Self-contained converter with gender agreement and complex pluralization.
  *
@@ -10,8 +12,10 @@
  * - "و" (and) conjunction between segments
  */
 
-import { parseNumericValue } from '../utils/parse-numeric.js'
-import { validateOptions } from '../utils/validate-options.js'
+import { parseCardinalValue } from './utils/parse-cardinal.js'
+import { parseCurrencyValue } from './utils/parse-currency.js'
+import { parseOrdinalValue } from './utils/parse-ordinal.js'
+import { validateOptions } from './utils/validate-options.js'
 
 // ============================================================================
 // Vocabulary
@@ -38,6 +42,32 @@ const NEGATIVE = 'ناقص'
 const DECIMAL_SEP = 'فاصلة'
 const AND = 'و'
 
+// ============================================================================
+// Ordinal Vocabulary
+// ============================================================================
+
+// Masculine ordinal forms (1-10)
+const ORDINAL_MASC = ['الأول', 'الثاني', 'الثالث', 'الرابع', 'الخامس', 'السادس', 'السابع', 'الثامن', 'التاسع', 'العاشر']
+
+// Feminine ordinal forms (1-10)
+const ORDINAL_FEM = ['الأولى', 'الثانية', 'الثالثة', 'الرابعة', 'الخامسة', 'السادسة', 'السابعة', 'الثامنة', 'التاسعة', 'العاشرة']
+
+// ============================================================================
+// Currency Vocabulary (Saudi Riyal)
+// ============================================================================
+
+// Riyal: singular, dual, plural (3-10), plural (11+)
+const RIYAL_SINGULAR = 'ريال'
+const RIYAL_DUAL = 'ريالان'
+const RIYAL_PLURAL_3_10 = 'ريالات'
+const RIYAL_PLURAL_11 = 'ريالاً'
+
+// Halala: singular, dual, plural (3-10), plural (11+)
+const HALALA_SINGULAR = 'هللة'
+const HALALA_DUAL = 'هللتان'
+const HALALA_PLURAL_3_10 = 'هللات'
+const HALALA_PLURAL_11 = 'هللة'
+
 // ============================================================================
 // Conversion Functions
 // ============================================================================
@@ -97,10 +127,9 @@ function segmentToWords (groupNumber, groupLevel, fullNumber, ones) {
   return result
 }
 
-function integerToWords (n, options) {
+function integerToWords (n, gender) {
   if (n === 0n) return ZERO
 
-  const gender = options.gender || 'masculine'
   const ones = gender === 'feminine' ? ONES_FEM : ONES_MASC
 
   let temp = n
@@ -148,7 +177,7 @@ function integerToWords (n, options) {
   return result
 }
 
-function decimalPartToWords (decimalPart, options) {
+function decimalPartToWords (decimalPart, gender) {
   const parts = []
   let i = 0
 
@@ -159,7 +188,7 @@ function decimalPartToWords (decimalPart, options) {
 
   const remainder = decimalPart.slice(i)
   if (remainder) {
-    parts.push(integerToWords(BigInt(remainder), options))
+    parts.push(integerToWords(BigInt(remainder), gender))
   }
 
   return parts.join(' ')
@@ -175,31 +204,164 @@ function decimalPartToWords (decimalPart, options) {
  * @returns {string} The number in Arabic words
  *
  * @example
- * toWords(1)                        // 'واحد'
- * toWords(1, {gender: 'feminine'})  // 'واحدة'
+ * toCardinal(1)                        // 'واحد'
+ * toCardinal(1, {gender: 'feminine'})  // 'واحدة'
  */
-function toWords (value, options) {
+function toCardinal (value, options) {
   options = validateOptions(options)
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
+
+  // Apply option defaults
+  const {
+    gender = 'masculine',
+    negativeWord = NEGATIVE
+  } = options
 
   const parts = []
 
   if (isNegative) {
-    parts.push(options.negativeWord || NEGATIVE)
+    parts.push(negativeWord)
   }
 
-  parts.push(integerToWords(integerPart, options))
+  parts.push(integerToWords(integerPart, gender))
 
   if (decimalPart) {
     parts.push(DECIMAL_SEP)
-    parts.push(decimalPartToWords(decimalPart, options))
+    parts.push(decimalPartToWords(decimalPart, gender))
   }
 
   return parts.join(' ')
 }
 
+// ============================================================================
+// ORDINAL: toOrdinal(value, options?)
+// ============================================================================
+
+/**
+ * Gets the Arabic ordinal form for a number.
+ *
+ * Arabic ordinals 1-10 have special forms, beyond 10 use cardinal + position.
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @param {string} gender - 'masculine' or 'feminine'
+ * @returns {string} Arabic ordinal words
+ */
+function integerToOrdinal (n, gender) {
+  const ordinals = gender === 'feminine' ? ORDINAL_FEM : ORDINAL_MASC
+
+  // Special ordinals for 1-10
+  if (n >= 1n && n <= 10n) {
+    return ordinals[Number(n) - 1]
+  }
+
+  // For 11 and above, use cardinal form with "ال" prefix for definiteness
+  const cardinal = integerToWords(n, gender)
+  return 'ال' + cardinal
+}
+
+/**
+ * Converts a numeric value to Arabic ordinal words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert (positive integer)
+ * @param {Object} [options] - Optional configuration
+ * @param {('masculine'|'feminine')} [options.gender='masculine'] - Grammatical gender
+ * @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(1, {gender: 'feminine'})  // 'الأولى'
+ * toOrdinal(3)                        // 'الثالث'
+ */
+function toOrdinal (value, options) {
+  options = validateOptions(options)
+  const integerPart = parseOrdinalValue(value)
+  const { gender = 'masculine' } = options
+  return integerToOrdinal(integerPart, gender)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value, options?)
+// ============================================================================
+
+/**
+ * Gets the appropriate currency word form based on number.
+ *
+ * Arabic has complex pluralization:
+ * - 1: singular
+ * - 2: dual
+ * - 3-10: plural form 1
+ * - 11+: plural form 2 (different ending)
+ */
+function getRiyalForm (n) {
+  if (n === 1n) return RIYAL_SINGULAR
+  if (n === 2n) return RIYAL_DUAL
+  if (n >= 3n && n <= 10n) return RIYAL_PLURAL_3_10
+  return RIYAL_PLURAL_11
+}
+
+function getHalalaForm (n) {
+  if (n === 1n) return HALALA_SINGULAR
+  if (n === 2n) return HALALA_DUAL
+  if (n >= 3n && n <= 10n) return HALALA_PLURAL_3_10
+  return HALALA_PLURAL_11
+}
+
+/**
+ * Converts a numeric value to Arabic currency words (Saudi Riyal).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Arabic 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: riyals, cents: halalas } = parseCurrencyValue(value)
+
+  // Build result
+  let result = ''
+  if (isNegative) result = NEGATIVE + ' '
+
+  // Riyals part - show if non-zero, or if no halalas
+  if (riyals > 0n || halalas === 0n) {
+    // Special case for 1 and 2: currency word comes first
+    if (riyals === 1n) {
+      result += RIYAL_SINGULAR + ' ' + ONES_MASC[0]
+    } else if (riyals === 2n) {
+      result += RIYAL_DUAL
+    } else {
+      const riyalWord = integerToWords(riyals, 'masculine')
+      result += riyalWord + ' ' + getRiyalForm(riyals)
+    }
+  }
+
+  // Halalas part
+  if (halalas > 0n) {
+    if (riyals > 0n) {
+      result += ' ' + AND
+    }
+    // Special case for 1 and 2: currency word comes first
+    if (halalas === 1n) {
+      result += HALALA_SINGULAR + ' ' + ONES_FEM[0]
+    } else if (halalas === 2n) {
+      result += HALALA_DUAL
+    } else {
+      const halalaWord = integerToWords(halalas, 'feminine')
+      result += halalaWord + ' ' + getHalalaForm(halalas)
+    }
+  }
+
+  return result
+}
+
 // ============================================================================
 // Exports
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/az-AZ.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Converts a numeric value to Azerbaijani words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Azerbaijani words
+ */
+export function toCardinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Azerbaijani 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)    // 'birinci'
+ * toOrdinal(2)    // 'ikinci'
+ * toOrdinal(21)   // 'iyirmibirinci'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Azerbaijani currency words (Manat).
+ *
+ * Uses manat and qəpik (100 qəpik = 1 manat).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Azerbaijani 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)     // 'qırx iki manat'
+ * toCurrency(1.50)   // 'bir manat əlli qəpik'
+ * toCurrency(-5)     // 'mənfi beş manat'
+ */
+export function toCurrency(value: number | string | bigint): string;

package/src/az-AZ.js

@@ -0,0 +1,312 @@
+/**
+ * Azerbaijani (Azerbaijan) language converter
+ *
+ * CLDR: az-AZ | Azerbaijani as used in Azerbaijan
+ *
+ * Key features:
+ * - Turkic language patterns
+ * - Implicit "bir" (one) omission before hundreds and thousands
+ * - Short scale naming
+ */
+
+import { parseCardinalValue } from './utils/parse-cardinal.js'
+import { parseCurrencyValue } from './utils/parse-currency.js'
+import { parseOrdinalValue } from './utils/parse-ordinal.js'
+
+// ============================================================================
+// Vocabulary
+// ============================================================================
+
+const ONES = ['', 'bir', 'iki', 'üç', 'dörd', 'beş', 'altı', 'yeddi', 'səkkiz', 'doqquz']
+const TEENS = ['on', 'on bir', 'on iki', 'on üç', 'on dörd', 'on beş', 'on altı', 'on yeddi', 'on səkkiz', 'on doqquz']
+const TENS = ['', '', 'iyirmi', 'otuz', 'qırx', 'əlli', 'altmış', 'yetmiş', 'səksən', 'doxsan']
+
+const HUNDRED = 'yüz'
+const THOUSAND = 'min'
+
+const ZERO = 'sıfır'
+const NEGATIVE = 'mənfi'
+const DECIMAL_SEP = 'nöqtə'
+
+// Short scale
+const SCALE_WORDS = ['', THOUSAND, 'milyon', 'milyar', 'trilyon', 'katrilyon', 'kentilyon']
+
+// ============================================================================
+// Ordinal Vocabulary
+// ============================================================================
+
+// Azerbaijani ordinals use -(i/ı/u/ü)nci/ncı/ncu/ncü suffix with vowel harmony
+// Special forms for 1-10
+const ORDINAL_SPECIAL = {
+  1: 'birinci',
+  2: 'ikinci',
+  3: 'üçüncü',
+  4: 'dördüncü',
+  5: 'beşinci',
+  6: 'altıncı',
+  7: 'yeddinci',
+  8: 'səkkizinci',
+  9: 'doqquzuncu',
+  10: 'onuncu'
+}
+
+// ============================================================================
+// Currency Vocabulary (Azerbaijani Manat)
+// ============================================================================
+
+const MANAT = 'manat'
+const QEPIK = 'qəpik' // subunit (100 qəpik = 1 manat)
+
+// ============================================================================
+// Precomputed Lookup Table
+// ============================================================================
+
+function buildSegment (n) {
+  if (n === 0) return ''
+
+  const ones = n % 10
+  const tensDigit = Math.trunc(n / 10) % 10
+  const hundredsDigit = Math.trunc(n / 100)
+
+  const parts = []
+
+  if (hundredsDigit > 0) {
+    if (hundredsDigit === 1) {
+      parts.push(HUNDRED)
+    } else {
+      parts.push(ONES[hundredsDigit] + ' ' + HUNDRED)
+    }
+  }
+
+  if (tensDigit === 1) {
+    parts.push(TEENS[ones])
+  } else {
+    if (tensDigit > 1) {
+      parts.push(TENS[tensDigit])
+    }
+    if (ones > 0) {
+      parts.push(ONES[ones])
+    }
+  }
+
+  return parts.join(' ')
+}
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+function integerToWords (n) {
+  if (n === 0n) return ZERO
+
+  if (n < 1000n) {
+    return buildSegment(Number(n))
+  }
+
+  return buildLargeNumberWords(n)
+}
+
+function buildLargeNumberWords (n) {
+  const numStr = n.toString()
+  const len = numStr.length
+
+  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
+  }
+
+  const parts = []
+  let scaleIndex = segments.length - 1
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i]
+
+    if (segment !== 0) {
+      const scaleWord = SCALE_WORDS[scaleIndex] || ''
+
+      if (scaleIndex === 0) {
+        parts.push(buildSegment(segment))
+      } else if (scaleIndex === 1 && segment === 1) {
+        // Omit "bir" before thousand
+        parts.push(scaleWord)
+      } else {
+        parts.push(buildSegment(segment) + ' ' + scaleWord)
+      }
+    }
+
+    scaleIndex--
+  }
+
+  return parts.join(' ')
+}
+
+function decimalPartToWords (decimalPart) {
+  let result = ''
+  let i = 0
+
+  while (i < decimalPart.length && decimalPart[i] === '0') {
+    if (result) result += ' '
+    result += ZERO
+    i++
+  }
+
+  const remainder = decimalPart.slice(i)
+  if (remainder) {
+    if (result) result += ' '
+    result += integerToWords(BigInt(remainder))
+  }
+
+  return result
+}
+
+/**
+ * Converts a numeric value to Azerbaijani words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Azerbaijani words
+ */
+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: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Determines the ordinal suffix based on Azerbaijani vowel harmony.
+ * @param {string} word - The cardinal word
+ * @returns {string} The appropriate suffix
+ */
+function getOrdinalSuffix (word) {
+  // Azerbaijani vowel harmony: back vowels (a,ı,o,u) vs front vowels (ə,e,i,ö,ü)
+  const backVowels = 'aıou'
+  const frontVowels = 'əeiöü'
+
+  // Scan from end for last vowel
+  for (let i = word.length - 1; i >= 0; i--) {
+    const char = word[i]
+    if (backVowels.includes(char)) {
+      // Back vowels: -ıncı (after a,ı) or -uncu (after o,u)
+      if ('ou'.includes(char)) return 'uncu'
+      return 'ıncı'
+    }
+    if (frontVowels.includes(char)) {
+      // Front vowels: -inci (after ə,e,i) or -üncü (after ö,ü)
+      if ('öü'.includes(char)) return 'üncü'
+      return 'inci'
+    }
+  }
+  return 'inci' // default
+}
+
+/**
+ * Converts a non-negative integer to Azerbaijani ordinal words.
+ *
+ * Azerbaijani ordinals: birinci (1st), ikinci (2nd), üçüncü (3rd), etc.
+ * Uses vowel harmony for suffix selection.
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Azerbaijani ordinal words
+ */
+function integerToOrdinal (n) {
+  // Special forms for 1-10
+  if (n >= 1n && n <= 10n) {
+    return ORDINAL_SPECIAL[Number(n)]
+  }
+
+  // For numbers > 10, get cardinal without spaces and add appropriate suffix
+  const cardinal = integerToWords(n).replace(/ /g, '')
+  const suffix = getOrdinalSuffix(cardinal)
+  return cardinal + suffix
+}
+
+/**
+ * Converts a numeric value to Azerbaijani 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)    // 'birinci'
+ * toOrdinal(2)    // 'ikinci'
+ * toOrdinal(21)   // 'iyirmibirinci'
+ */
+function toOrdinal (value) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value)
+// ============================================================================
+
+/**
+ * Converts a numeric value to Azerbaijani currency words (Manat).
+ *
+ * Uses manat and qəpik (100 qəpik = 1 manat).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Azerbaijani 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)     // 'qırx iki manat'
+ * toCurrency(1.50)   // 'bir manat əlli qəpik'
+ * toCurrency(-5)     // 'mənfi beş manat'
+ */
+function toCurrency (value) {
+  const { isNegative, dollars: manat, cents: qepik } = parseCurrencyValue(value)
+
+  let result = ''
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  // Manat part
+  if (manat > 0n || qepik === 0n) {
+    result += integerToWords(manat) + ' ' + MANAT
+  }
+
+  // Qəpik part
+  if (qepik > 0n) {
+    if (manat > 0n) {
+      result += ' '
+    }
+    result += integerToWords(qepik) + ' ' + QEPIK
+  }
+
+  return result
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export { toCardinal, toOrdinal, toCurrency }

package/src/bn-BD.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Converts a numeric value to Bengali words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Bengali words
+ */
+export function toCardinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Bengali 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(3)    // 'তৃতীয়'
+ * toOrdinal(10)   // 'দশতম'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Bengali currency words (Bangladeshi Taka).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Bengali 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;