n2words 3.0.0 → 4.0.0

package/{lib/languages/fr.js → src/fr-FR.js}

@@ -1,13 +1,9 @@
 /**
- * French language converter - Functional Implementation
+ * French (France) 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: fr-FR | French as used in France
  *
- * Key optimization: Precompute all segment values (0-999) at module load.
- * This eliminates all per-call string manipulation for segment conversion.
- *
- * French-specific rules (handled in precomputation):
+ * French-specific rules:
  * - Vigesimal patterns: 70 = soixante-dix, 80 = quatre-vingts, 90 = quatre-vingt-dix
  * - "et" conjunction: vingt et un (21), soixante et onze (71), but NOT quatre-vingt-un
  * - Pluralization: "cents" loses 's' when followed by more digits
@@ -15,8 +11,10 @@
  * - Omit "un" before mille
  */
 
-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 (module-level constants)
@@ -37,7 +35,26 @@ const NEGATIVE = 'moins'
 const DECIMAL_SEP = 'virgule'
 
 // ============================================================================
-// Precomputed Lookup Tables (built once at module load)
+// Ordinal Vocabulary
+// ============================================================================
+
+// Ordinal suffix
+const ORDINAL_SUFFIX = 'ième'
+
+// Special ordinals
+const PREMIER = 'premier'
+
+// ============================================================================
+// Currency Vocabulary (Euro)
+// ============================================================================
+
+const EURO = 'euro'
+const EUROS = 'euros'
+const CENTIME = 'centime'
+const CENTIMES = 'centimes'
+
+// ============================================================================
+// Segment Building
 // ============================================================================
 
 /**
@@ -48,7 +65,7 @@ function buildSegment (n) {
   if (n === 0) return { word: '', endsWithCents: false, endsWithVingts: false }
 
   const tensOnes = n % 100
-  const hundreds = Math.floor(n / 100)
+  const hundreds = Math.trunc(n / 100)
 
   const parts = []
   let endsWithCents = false
@@ -88,7 +105,7 @@ function buildSegment (n) {
     parts.push(TEENS[tensOnes - 10])
   } else if (tensOnes < 70) {
     // 20-69: standard tens + ones
-    const t = Math.floor(tensOnes / 10)
+    const t = Math.trunc(tensOnes / 10)
     const o = tensOnes % 10
     if (o === 0) {
       parts.push(TENS[t])
@@ -128,18 +145,6 @@ function buildSegment (n) {
   return { word: parts.join(' '), endsWithCents, endsWithVingts }
 }
 
-// Precompute all 1000 segment words (0-999)
-const SEGMENTS = new Array(1000)
-const SEGMENTS_ENDS_CENTS = new Array(1000)
-const SEGMENTS_ENDS_VINGTS = new Array(1000)
-
-for (let i = 0; i < 1000; i++) {
-  const result = buildSegment(i)
-  SEGMENTS[i] = result.word
-  SEGMENTS_ENDS_CENTS[i] = result.endsWithCents
-  SEGMENTS_ENDS_VINGTS[i] = result.endsWithVingts
-}
-
 // ============================================================================
 // Helper Functions
 // ============================================================================
@@ -183,9 +188,9 @@ function getScaleWord (scaleIndex, segment) {
 function integerToWords (n, withHyphen = false) {
   if (n === 0n) return ZERO
 
-  // Fast path: numbers < 1000 (direct lookup)
+  // Fast path: numbers < 1000
   if (n < 1000n) {
-    const word = SEGMENTS[Number(n)]
+    const { word } = buildSegment(Number(n))
     return withHyphen ? word.replace(/ /g, '-') : word
   }
 
@@ -200,15 +205,17 @@ function integerToWords (n, withHyphen = false) {
       result = THOUSAND
     } else {
       // Check if segment ends with "cents" or "vingts" - need to strip 's' before mille
-      let thousandsWord = SEGMENTS[thousands]
-      if (SEGMENTS_ENDS_CENTS[thousands] || SEGMENTS_ENDS_VINGTS[thousands]) {
-        thousandsWord = thousandsWord.slice(0, -1) // Remove trailing 's'
+      const { word: thousandsWord, endsWithCents, endsWithVingts } = buildSegment(thousands)
+      let adjustedWord = thousandsWord
+      if (endsWithCents || endsWithVingts) {
+        adjustedWord = thousandsWord.slice(0, -1) // Remove trailing 's'
       }
-      result = thousandsWord + (withHyphen ? '-' : ' ') + THOUSAND
+      result = adjustedWord + (withHyphen ? '-' : ' ') + THOUSAND
     }
 
     if (remainder > 0) {
-      result += (withHyphen ? '-' : ' ') + SEGMENTS[remainder]
+      const { word: remainderWord } = buildSegment(remainder)
+      result += (withHyphen ? '-' : ' ') + remainderWord
     }
 
     if (withHyphen) {
@@ -257,26 +264,27 @@ function buildLargeNumberWords (n, withHyphen) {
 
     if (segment !== 0) {
       const scaleWord = scaleIndex > 0 ? getScaleWord(scaleIndex, BigInt(segment)) : ''
+      const { word: segWords, endsWithCents, endsWithVingts } = buildSegment(segment)
 
       if (scaleIndex === 0) {
         // Units segment
-        parts.push(SEGMENTS[segment])
+        parts.push(segWords)
       } else if (scaleIndex === 1) {
         // Thousands: "mille" not "un mille"
         if (segment === 1) {
           parts.push(THOUSAND)
         } else {
-          let segWords = SEGMENTS[segment]
           // Strip 's' from cents/vingts before mille
-          if (SEGMENTS_ENDS_CENTS[segment] || SEGMENTS_ENDS_VINGTS[segment]) {
-            segWords = segWords.slice(0, -1)
+          let adjustedWord = segWords
+          if (endsWithCents || endsWithVingts) {
+            adjustedWord = segWords.slice(0, -1)
           }
-          parts.push(segWords)
+          parts.push(adjustedWord)
           parts.push(scaleWord)
         }
       } else {
         // Million and above
-        parts.push(SEGMENTS[segment])
+        parts.push(segWords)
         parts.push(scaleWord)
       }
     }
@@ -337,26 +345,171 @@ function decimalPartToWords (decimalPart, withHyphen) {
  * @throws {Error} If value is not a valid number format
  *
  * @example
- * toWords(21)           // 'vingt et un'
- * toWords(80)           // 'quatre-vingts'
- * toWords(1000000)      // 'un million'
+ * toCardinal(21)           // 'vingt et un'
+ * toCardinal(80)           // 'quatre-vingts'
+ * toCardinal(1000000)      // 'un million'
  */
-function toWords (value, options) {
+function toCardinal (value, options) {
   options = validateOptions(options)
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
-  const withHyphen = options.withHyphenSeparator || false
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
+
+  // Apply option defaults
+  const { withHyphenSeparator = false } = options
 
   let result = ''
-  const sep = withHyphen ? '-' : ' '
+  const sep = withHyphenSeparator ? '-' : ' '
 
   if (isNegative) {
     result = NEGATIVE + sep
   }
 
-  result += integerToWords(integerPart, withHyphen)
+  result += integerToWords(integerPart, withHyphenSeparator)
 
   if (decimalPart) {
-    result += sep + DECIMAL_SEP + sep + decimalPartToWords(decimalPart, withHyphen)
+    result += sep + DECIMAL_SEP + sep + decimalPartToWords(decimalPart, withHyphenSeparator)
+  }
+
+  return result
+}
+
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Converts a cardinal number word to its ordinal form.
+ * Rules:
+ * - 1 → premier (special case)
+ * - Drop final -e before adding -ième (quatre → quatrième)
+ * - cinq → cinquième (add -u- before -ième)
+ * - neuf → neuvième (f → v before -ième)
+ *
+ * @param {string} cardinalWord - Cardinal word to convert
+ * @returns {string} Ordinal form
+ */
+function cardinalToOrdinal (cardinalWord) {
+  // Handle special endings
+  if (cardinalWord.endsWith('cinq')) {
+    // cinq → cinquième (add 'u')
+    return cardinalWord + 'u' + ORDINAL_SUFFIX
+  }
+
+  if (cardinalWord.endsWith('neuf')) {
+    // neuf → neuvième (f → v)
+    return cardinalWord.slice(0, -1) + 'v' + ORDINAL_SUFFIX
+  }
+
+  // Drop plural -s from cents/vingts/millions/etc. (quatre-vingts → quatre-vingtième)
+  // Note: "trois", "six" also end in s but that's not a plural
+  if (cardinalWord.endsWith('cents') ||
+      cardinalWord.endsWith('vingts') ||
+      cardinalWord.endsWith('millions') ||
+      cardinalWord.endsWith('milliards') ||
+      cardinalWord.endsWith('billions') ||
+      cardinalWord.endsWith('billiards') ||
+      cardinalWord.endsWith('trillions') ||
+      cardinalWord.endsWith('trilliards') ||
+      cardinalWord.endsWith('quadrillions') ||
+      cardinalWord.endsWith('quadrilliards')) {
+    return cardinalWord.slice(0, -1) + ORDINAL_SUFFIX
+  }
+
+  // Drop final -e before adding -ième (quatre → quatrième)
+  if (cardinalWord.endsWith('e')) {
+    return cardinalWord.slice(0, -1) + ORDINAL_SUFFIX
+  }
+
+  // Default: just add -ième
+  return cardinalWord + ORDINAL_SUFFIX
+}
+
+/**
+ * Converts a positive integer to French ordinal words.
+ *
+ * @param {bigint} n - Positive integer
+ * @returns {string} French ordinal words
+ */
+function integerToOrdinal (n) {
+  // Special case: 1 → premier
+  if (n === 1n) {
+    return PREMIER
+  }
+
+  // Get cardinal form and convert to ordinal
+  const cardinalWord = integerToWords(n, false)
+  return cardinalToOrdinal(cardinalWord)
+}
+
+/**
+ * Converts a numeric value to French ordinal words.
+ *
+ * French ordinals: premier (1st), then cardinal + ième.
+ * Special rules: quatre→quatrième, cinq→cinquième, neuf→neuvième.
+ *
+ * @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)    // 'premier'
+ * toOrdinal(2)    // 'deuxième'
+ * toOrdinal(4)    // 'quatrième'
+ * toOrdinal(5)    // 'cinquième'
+ * toOrdinal(9)    // 'neuvième'
+ * toOrdinal(21)   // 'vingt et unième'
+ * toOrdinal(100)  // 'centième'
+ * toOrdinal(1000) // 'millième'
+ */
+function toOrdinal (value) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value, options?)
+// ============================================================================
+
+/**
+ * Converts a numeric value to French currency words (Euro).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @param {Object} [options] - Optional configuration
+ * @param {boolean} [options.and=true] - Use "et" between euros and centimes
+ * @returns {string} The amount in French 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)                 // 'quarante-deux euros et cinquante centimes'
+ * toCurrency(1)                     // 'un euro'
+ * toCurrency(0.99)                  // 'quatre-vingt-dix-neuf centimes'
+ * toCurrency(0.01)                  // 'un centime'
+ * toCurrency(42.50, { and: false }) // 'quarante-deux euros cinquante centimes'
+ */
+function toCurrency (value, options) {
+  options = validateOptions(options)
+  const { isNegative, dollars: euros, cents: centimes } = parseCurrencyValue(value)
+  const { and: useAnd = true } = options
+
+  // Build result
+  let result = ''
+  if (isNegative) result = NEGATIVE + ' '
+
+  // Euros part
+  if (euros > 0n || centimes === 0n) {
+    result += integerToWords(euros, false)
+    // In French, 0 and 1 are singular: "zéro euro", "un euro"
+    result += ' ' + (euros <= 1n ? EURO : EUROS)
+  }
+
+  // Centimes part
+  if (centimes > 0n) {
+    if (euros > 0n) {
+      result += useAnd ? ' et ' : ' '
+    }
+    result += integerToWords(centimes, false)
+    result += ' ' + (centimes === 1n ? CENTIME : CENTIMES)
   }
 
   return result
@@ -366,4 +519,4 @@ function toWords (value, options) {
 // Public API
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/gu-IN.d.ts

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

@@ -0,0 +1,259 @@
+/**
+ * Gujarati (India) language converter
+ *
+ * CLDR: gu-IN | Gujarati as used in India
+ *
+ * Key features:
+ * - Indian numbering system (હજાર, લાખ, કરોડ)
+ * - Gujarati script
+ * - 3-2-2 grouping pattern (last 3 digits, then groups of 2)
+ * - Complete word forms for 0-99
+ * - Per-digit decimal reading
+ */
+
+import { parseCardinalValue } from './utils/parse-cardinal.js'
+import { parseCurrencyValue } from './utils/parse-currency.js'
+import { parseOrdinalValue } from './utils/parse-ordinal.js'
+
+// ============================================================================
+// Vocabulary
+// ============================================================================
+
+const ZERO = 'શૂન્ય'
+const NEGATIVE = 'ઋણ'
+const DECIMAL_SEP = 'દશાંશ'
+const HUNDRED = 'સો'
+
+// ============================================================================
+// Ordinal Vocabulary
+// ============================================================================
+
+// Ordinal suffix (adds to cardinal for numbers >= 7)
+const ORDINAL_SUFFIX = 'મું'
+
+// Special ordinals for first few numbers (1-6 have irregular forms)
+const ORDINAL_SPECIAL = ['', 'પહેલું', 'બીજું', 'ત્રીજું', 'ચોથું', 'પાંચમું', 'છઠ્ઠું']
+
+// ============================================================================
+// Currency Vocabulary (Indian Rupee)
+// ============================================================================
+
+// Rupee: singular/plural
+const RUPEE = 'રૂપિયો'
+const RUPEES = 'રૂપિયા'
+
+// Paisa: singular/plural
+const PAISA = 'પૈસો'
+const PAISE = 'પૈસા'
+
+const BELOW_HUNDRED = [
+  'શૂન્ય', 'એક', 'બે', 'ત્રણ', 'ચાર', 'પાંચ', 'છ', 'સાત', 'આઠ', 'નવ',
+  'દસ', 'અગિયાર', 'બાર', 'તેર', 'ચૌદ', 'પંદર', 'સોળ', 'સત્તર', 'અઢાર', 'ઓગણીસ',
+  'વીસ', 'એકવીસ', 'બાવીસ', 'ત્રેવીસ', 'ચોવીસ', 'પચીસ', 'છવ્વીસ', 'સત્તાવીસ', 'અઠ્ઠાવીસ', 'ઓગણત્રીસ',
+  'ત્રીસ', 'એકત્રીસ', 'બત્રીસ', 'તેત્રીસ', 'ચોત્રીસ', 'પાંત્રીસ', 'છત્રીસ', 'સાડત્રીસ', 'અડત્રીસ', 'ઓગણચાલીસ',
+  'ચાલીસ', 'એકતાલીસ', 'બેતાળીસ', 'ત્રેતાળીસ', 'ચુંમાલીસ', 'પિસ્તાલીસ', 'છેતાળીસ', 'સુડતાળીસ', 'અડતાળીસ', 'ઓગણપચાસ',
+  'પચાસ', 'એકાવન', 'બાવન', 'ત્રેપન', 'ચોપન', 'પંચાવન', 'છપ્પન', 'સત્તાવન', 'અઠ્ઠાવન', 'ઓગણસાઠ',
+  'સાઠ', 'એકસઠ', 'બાસઠ', 'ત્રેસઠ', 'ચોસઠ', 'પાંસઠ', 'છાસઠ', 'સડસઠ', 'અડસઠ', 'અગણોસિત્તેર',
+  'સિત્તેર', 'એકોતેર', 'બોતેર', 'તોતેર', 'ચુમોતેર', 'પંચોતેર', 'છોતેર', 'સિત્યોતેર', 'ઇઠ્યોતેર', 'ઓગણાએંસી',
+  'એંસી', 'એક્યાસી', 'બ્યાસી', 'ત્યાસી', 'ચોર્યાસી', 'પંચાસી', 'છ્યાસી', 'સિત્યાસી', 'અઠ્યાસી', 'નેવ્યાસી',
+  'નેવું', 'એકાણું', 'બાણું', 'ત્રાણું', 'ચોરાણું', 'પંચાણું', 'છન્નું', 'સત્તાણું', 'અઠ્ઠાણું', 'નવ્વાણું'
+]
+
+// Scale words: index 0 = units (empty), 1 = thousand, 2 = lakh, 3 = crore, etc.
+const SCALE_WORDS = ['', 'હજાર', 'લાખ', 'કરોડ', 'અબજ', 'ખરબ', 'નીલ', 'પદ્મ', 'શંખ']
+
+// ============================================================================
+// Segment Building
+// ============================================================================
+
+/**
+ * Builds words for a 0-999 segment.
+ */
+function buildSegment (n) {
+  if (n === 0) return ''
+  if (n < 100) return BELOW_HUNDRED[n]
+
+  const hundreds = Math.trunc(n / 100)
+  const remainder = n % 100
+
+  if (remainder === 0) {
+    return BELOW_HUNDRED[hundreds] + ' ' + HUNDRED
+  }
+  return BELOW_HUNDRED[hundreds] + ' ' + HUNDRED + ' ' + BELOW_HUNDRED[remainder]
+}
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Gujarati 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} Gujarati words
+ */
+function integerToWords (n) {
+  if (n === 0n) return ZERO
+
+  // 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
+
+    if (i === 0) {
+      words.push(buildSegment(segment))
+    } else {
+      words.push(BELOW_HUNDRED[segment])
+    }
+
+    if (i > 0 && SCALE_WORDS[i]) {
+      words.push(SCALE_WORDS[i])
+    }
+  }
+
+  return words.join(' ')
+}
+
+function decimalPartToWords (decimalPart) {
+  // Per-digit decimal reading
+  const digits = []
+  for (const char of decimalPart) {
+    const d = parseInt(char, 10)
+    digits.push(d === 0 ? ZERO : BELOW_HUNDRED[d])
+  }
+  return digits.join(' ')
+}
+
+/**
+ * Converts a numeric value to Gujarati words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Gujarati 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)
+// ============================================================================
+
+/**
+ * Converts a positive integer to Gujarati ordinal words.
+ *
+ * Gujarati ordinals: First 6 are irregular, then add -મું suffix.
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Gujarati 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 Gujarati 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 Gujarati currency words (Indian Rupee).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Gujarati 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 { toCardinal, toOrdinal, toCurrency }

package/src/ha-NG.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Converts a numeric value to Hausa words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Hausa words
+ */
+export function toCardinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Hausa 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)    // 'na farko'
+ * toOrdinal(2)    // 'na biyu'
+ * toOrdinal(10)   // 'na goma'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Hausa currency words (Nigerian Naira).
+ *
+ * Uses naira and kobo (100 kobo = 1 naira).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Hausa 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)     // 'arba'in da biyu naira'
+ * toCurrency(1.50)   // 'ɗaya naira da hamsin kobo'
+ * toCurrency(-5)     // 'babu biyar naira'
+ */
+export function toCurrency(value: number | string | bigint): string;