n2words 3.0.0 → 4.0.0

package/{lib/languages/ha.js → src/ha-NG.js}

@@ -1,7 +1,7 @@
 /**
- * Hausa language converter - Functional Implementation
+ * Hausa (Nigeria) language converter
  *
- * Self-contained converter with precomputed lookup tables.
+ * CLDR: ha-NG | Hausa as used in Nigeria
  *
  * Key features:
  * - Authentic Boko orthography with ɗ (hooked d) and ' (glottal stop)
@@ -13,7 +13,9 @@
  * - Per-digit decimal reading
  */
 
-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
@@ -34,6 +36,22 @@ const DECIMAL_SEP = 'digo'
 // Short scale
 const SCALE_WORDS = ['', THOUSAND, 'miliyan', 'biliyan']
 
+// ============================================================================
+// Ordinal Vocabulary
+// ============================================================================
+
+// Hausa ordinals: "na" + cardinal (na ɗaya = 1st, na biyu = 2nd)
+// First has special form "na fari" or "farko"
+const ORDINAL_PREFIX = 'na'
+const ORDINAL_FIRST = 'na farko'
+
+// ============================================================================
+// Currency Vocabulary (Nigerian Naira)
+// ============================================================================
+
+const NAIRA = 'naira'
+const KOBO = 'kobo'
+
 // ============================================================================
 // Precomputed Lookup Table
 // ============================================================================
@@ -47,8 +65,8 @@ function buildSegment (n) {
   if (n === 0) return ''
 
   const ones = 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 = []
 
@@ -88,11 +106,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
 // ============================================================================
@@ -101,7 +114,7 @@ function integerToWords (n) {
   if (n === 0n) return ZERO
 
   if (n < 1000n) {
-    return SEGMENTS[Number(n)]
+    return buildSegment(Number(n))
   }
 
   return buildLargeNumberWords(n)
@@ -143,9 +156,9 @@ function buildLargeNumberWords (n) {
       const scaleWord = SCALE_WORDS[scaleIndex] || ''
 
       if (scaleIndex === 0) {
-        rawParts.push(SEGMENTS[segment])
+        rawParts.push(buildSegment(segment))
       } else {
-        rawParts.push(SEGMENTS[segment])
+        rawParts.push(buildSegment(segment))
         rawParts.push(scaleWord)
       }
     }
@@ -205,8 +218,8 @@ function decimalPartToWords (decimalPart) {
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Hausa words
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
 
@@ -223,8 +236,89 @@ function toWords (value) {
   return result
 }
 
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Hausa ordinal words.
+ *
+ * Hausa ordinals: na farko (1st), na biyu (2nd), na uku (3rd), etc.
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Hausa ordinal words
+ */
+function integerToOrdinal (n) {
+  // Special form for first
+  if (n === 1n) return ORDINAL_FIRST
+
+  // For 2+, use "na" prefix + cardinal
+  return ORDINAL_PREFIX + ' ' + integerToWords(n)
+}
+
+/**
+ * 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'
+ */
+function toOrdinal (value) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value)
+// ============================================================================
+
+/**
+ * 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'
+ */
+function toCurrency (value) {
+  const { isNegative, dollars: naira, cents: kobo } = parseCurrencyValue(value)
+
+  let result = ''
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  // Naira part
+  if (naira > 0n || kobo === 0n) {
+    result += integerToWords(naira) + ' ' + NAIRA
+  }
+
+  // Kobo part
+  if (kobo > 0n) {
+    if (naira > 0n) {
+      result += ' da '
+    }
+    result += integerToWords(kobo) + ' ' + KOBO
+  }
+
+  return result
+}
+
 // ============================================================================
 // Exports
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/hbo-IL.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Converts a numeric value to Biblical Hebrew words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @param {Object} [options] - Optional configuration
+ * @param {('masculine'|'feminine')} [options.gender='masculine'] - Grammatical gender
+ * @param {string} [options.andWord='ו'] - Custom conjunction word
+ * @returns {string} The number in Biblical Hebrew words
+ */
+export function toCardinal(value: number | string | bigint, options?: {
+    gender?: "masculine" | "feminine" | undefined;
+    andWord?: string | undefined;
+}): string;
+/**
+ * Converts a numeric value to Biblical Hebrew ordinal words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The ordinal in Biblical Hebrew words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a positive integer
+ *
+ * @example
+ * toOrdinal(1)   // 'ראשון'
+ * toOrdinal(21)  // 'עשרים וראשון'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Biblical Hebrew Shekel currency words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The currency in Biblical Hebrew 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/{lib/languages/hbo.js → src/hbo-IL.js}

@@ -1,7 +1,7 @@
 /**
- * Biblical Hebrew language converter - Functional Implementation
+ * Biblical Hebrew (Israel) language converter
  *
- * Self-contained converter with segment-based decomposition.
+ * CLDR: hbo-IL | Biblical/Ancient Hebrew
  *
  * Key features:
  * - Gender agreement (masculine default, feminine via option)
@@ -9,12 +9,12 @@
  * - Special 1-9 thousands construct state
  * - "ו" (ve) conjunction rules vary by position
  * - Per-digit decimal reading
- *
- * Optimization: Precomputed segment lookup tables for both genders.
  */
 
-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 (arrays for indexed access - faster than object property lookup)
@@ -43,8 +43,20 @@ const ZERO = 'אפס'
 const NEGATIVE = 'מינוס'
 const DECIMAL_SEP = 'נקודה'
 
+// Ordinal forms (masculine) - used in Biblical Hebrew
+const ORDINAL_ONES = ['', 'ראשון', 'שני', 'שלישי', 'רביעי', 'חמישי', 'שישי', 'שביעי', 'שמיני', 'תשיעי']
+const ORDINAL_TEENS = ['עשירי', 'אחד עשר', 'שנים עשר', 'שלשה עשר', 'ארבעה עשר', 'חמשה עשר', 'ששה עשר', 'שבעה עשר', 'שמונה עשר', 'תשעה עשר']
+const ORDINAL_TENS = ['', '', 'עשרים', 'שלשים', 'ארבעים', 'חמישים', 'ששים', 'שבעים', 'שמונים', 'תשעים']
+const ORDINAL_HUNDRED = 'מאה'
+
+// Currency (Biblical Shekel - historical usage)
+const SHEKEL = 'שקל'
+const SHEKEL_PLURAL = 'שקלים'
+const GERAH = 'גרה'
+const GERAH_PLURAL = 'גרות'
+
 // ============================================================================
-// Precomputed Lookup Tables (built once at module load)
+// Segment Building
 // ============================================================================
 
 /**
@@ -55,8 +67,8 @@ function buildScaleSegment (n, andWord, ONES, TEENS, HUNDREDS_ARR) {
   if (n === 0) return ''
 
   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)
 
   let result = ''
 
@@ -105,8 +117,8 @@ function buildUnitsSegment (n, andWord, ONES, TEENS, HUNDREDS_ARR) {
   if (n === 0) return ''
 
   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)
 
   let result = ''
 
@@ -145,19 +157,6 @@ function buildUnitsSegment (n, andWord, ONES, TEENS, HUNDREDS_ARR) {
   return result
 }
 
-// Precompute all 1000 segment words for masculine (default) with default conjunction
-const SCALE_SEGMENTS_MASC = new Array(1000)
-const UNITS_SEGMENTS_MASC = new Array(1000)
-const SCALE_SEGMENTS_FEM = new Array(1000)
-const UNITS_SEGMENTS_FEM = new Array(1000)
-
-for (let i = 0; i < 1000; i++) {
-  SCALE_SEGMENTS_MASC[i] = buildScaleSegment(i, 'ו', ONES_MASC, TEENS_MASC, HUNDREDS)
-  UNITS_SEGMENTS_MASC[i] = buildUnitsSegment(i, 'ו', ONES_MASC, TEENS_MASC, HUNDREDS)
-  SCALE_SEGMENTS_FEM[i] = buildScaleSegment(i, 'ו', ONES_FEM, TEENS_FEM, HUNDREDS_FEM)
-  UNITS_SEGMENTS_FEM[i] = buildUnitsSegment(i, 'ו', ONES_FEM, TEENS_FEM, HUNDREDS_FEM)
-}
-
 // ============================================================================
 // Conversion Functions
 // ============================================================================
@@ -169,25 +168,20 @@ for (let i = 0; i < 1000; i++) {
  * @param {Object} options - Conversion options
  * @returns {string} Biblical Hebrew words
  */
-function integerToWords (n, options) {
+function integerToWords (n, gender, andWord) {
   if (n === 0n) return ZERO
 
-  const andWord = options.andWord ?? 'ו'
-  const gender = options.gender || 'masculine'
   const isFeminine = gender === 'feminine'
-  const usePrecomputed = andWord === 'ו'
 
   // Select vocabulary based on gender
   const ONES = isFeminine ? ONES_FEM : ONES_MASC
   const TEENS = isFeminine ? TEENS_FEM : TEENS_MASC
   const THOUSANDS_SPECIAL = isFeminine ? THOUSANDS_FEM : THOUSANDS_MASC
   const HUNDREDS_ARR = isFeminine ? HUNDREDS_FEM : HUNDREDS
-  const SCALE_SEGS = isFeminine ? SCALE_SEGMENTS_FEM : SCALE_SEGMENTS_MASC
-  const UNITS_SEGS = isFeminine ? UNITS_SEGMENTS_FEM : UNITS_SEGMENTS_MASC
 
-  // Fast path: numbers < 1000 (direct lookup)
+  // Fast path: numbers < 1000
   if (n < 1000n) {
-    return usePrecomputed ? UNITS_SEGS[Number(n)] : buildUnitsSegment(Number(n), andWord, ONES, TEENS, HUNDREDS_ARR)
+    return buildUnitsSegment(Number(n), andWord, ONES, TEENS, HUNDREDS_ARR)
   }
 
   // Extract segments using BigInt modulo
@@ -207,7 +201,7 @@ function integerToWords (n, options) {
 
     if (i === 0) {
       // Units segment (no scale word)
-      const segmentWord = usePrecomputed ? UNITS_SEGS[segment] : buildUnitsSegment(segment, andWord, ONES, TEENS, HUNDREDS_ARR)
+      const segmentWord = buildUnitsSegment(segment, andWord, ONES, TEENS, HUNDREDS_ARR)
       if (result) {
         // Add "ו" before single-digit units when following scale words
         if (segment <= 9) {
@@ -224,7 +218,7 @@ function integerToWords (n, options) {
         if (result) result += ' '
         result += THOUSANDS_SPECIAL[segment]
       } else {
-        const segmentWord = usePrecomputed ? SCALE_SEGS[segment] : buildScaleSegment(segment, andWord, ONES, TEENS, HUNDREDS_ARR)
+        const segmentWord = buildScaleSegment(segment, andWord, ONES, TEENS, HUNDREDS_ARR)
         if (result) result += ' '
         result += segmentWord + ' ' + SCALE[1]
       }
@@ -234,7 +228,7 @@ function integerToWords (n, options) {
         if (result) result += ' '
         result += SCALE[i]
       } else {
-        const segmentWord = usePrecomputed ? SCALE_SEGS[segment] : buildScaleSegment(segment, andWord, ONES, TEENS, HUNDREDS_ARR)
+        const segmentWord = buildScaleSegment(segment, andWord, ONES, TEENS, HUNDREDS_ARR)
         if (result) result += ' '
         result += segmentWord + ' ' + SCALE_PLURAL[i]
       }
@@ -251,8 +245,7 @@ function integerToWords (n, options) {
  * @param {Object} options - Conversion options
  * @returns {string} Biblical Hebrew words for decimal part
  */
-function decimalPartToWords (decimalPart, options) {
-  const gender = options.gender || 'masculine'
+function decimalPartToWords (decimalPart, gender, andWord) {
   const ONES = gender === 'feminine' ? ONES_FEM : ONES_MASC
 
   let result = ''
@@ -271,12 +264,18 @@ function decimalPartToWords (decimalPart, options) {
  * @param {number | string | bigint} value - The numeric value to convert
  * @param {Object} [options] - Optional configuration
  * @param {('masculine'|'feminine')} [options.gender='masculine'] - Grammatical gender
- * @param {string} [options.andWord] - Custom conjunction word
+ * @param {string} [options.andWord='ו'] - Custom conjunction word
  * @returns {string} The number in Biblical Hebrew words
  */
-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',
+    andWord = 'ו'
+  } = options
 
   let result = ''
 
@@ -284,17 +283,192 @@ function toWords (value, options) {
     result = NEGATIVE + ' '
   }
 
-  result += integerToWords(integerPart, options)
+  result += integerToWords(integerPart, gender, andWord)
 
   if (decimalPart) {
-    result += ' ' + DECIMAL_SEP + ' ' + decimalPartToWords(decimalPart, options)
+    result += ' ' + DECIMAL_SEP + ' ' + decimalPartToWords(decimalPart, gender, andWord)
   }
 
   return result
 }
 
+// ============================================================================
+// Ordinal Functions
+// ============================================================================
+
+/**
+ * Builds ordinal for tens and ones (0-99).
+ *
+ * @param {number} n - Number 0-99
+ * @returns {string} Ordinal word
+ */
+function buildOrdinalTensOnes (n) {
+  if (n === 0) return ''
+  if (n < 10) return ORDINAL_ONES[n]
+  if (n < 20) return ORDINAL_TEENS[n - 10]
+
+  const ones = n % 10
+  const tens = Math.trunc(n / 10)
+
+  if (ones === 0) {
+    // Round tens: add "וראשון"
+    return ORDINAL_TENS[tens] + ' ו' + ORDINAL_ONES[1]
+  }
+  // Compound: cardinal tens + ordinal ones
+  return ORDINAL_TENS[tens] + ' ו' + ORDINAL_ONES[ones]
+}
+
+/**
+ * Converts a non-negative integer to Biblical Hebrew ordinal words.
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} Biblical Hebrew ordinal words
+ */
+function integerToOrdinal (n) {
+  if (n === 0n) return ''
+  if (n === 1n) return ORDINAL_ONES[1]
+
+  // Numbers < 100
+  if (n < 100n) {
+    return buildOrdinalTensOnes(Number(n))
+  }
+
+  // Numbers < 1000
+  if (n < 1000n) {
+    const hundreds = Number(n / 100n)
+    const remainder = Number(n % 100n)
+
+    if (remainder === 0) {
+      return ORDINAL_HUNDRED
+    }
+    return HUNDREDS[hundreds] + ' ' + buildOrdinalTensOnes(remainder)
+  }
+
+  // Numbers < 1,000,000
+  if (n < 1_000_000n) {
+    const thousands = Number(n / 1000n)
+    const remainder = Number(n % 1000n)
+
+    if (remainder === 0) {
+      if (thousands <= 9) {
+        return THOUSANDS_MASC[thousands]
+      }
+      return buildScaleSegment(thousands, 'ו', ONES_MASC, TEENS_MASC, HUNDREDS) + ' ' + SCALE[1]
+    }
+
+    // Cardinal thousands + ordinal remainder
+    let result
+    if (thousands <= 9) {
+      result = THOUSANDS_MASC[thousands]
+    } else {
+      result = buildScaleSegment(thousands, 'ו', ONES_MASC, TEENS_MASC, HUNDREDS) + ' ' + SCALE[1]
+    }
+
+    if (remainder < 100) {
+      return result + ' ' + buildOrdinalTensOnes(remainder)
+    }
+
+    const remHundreds = Math.trunc(remainder / 100)
+    const remTensOnes = remainder % 100
+
+    if (remTensOnes === 0) {
+      return result + ' ' + HUNDREDS[remHundreds]
+    }
+    return result + ' ' + HUNDREDS[remHundreds] + ' ' + buildOrdinalTensOnes(remTensOnes)
+  }
+
+  // Numbers >= 1,000,000
+  const millions = Number(n / 1_000_000n)
+  const remainder = n % 1_000_000n
+
+  if (remainder === 0n) {
+    if (millions === 1) {
+      return SCALE[2]
+    }
+    return buildScaleSegment(millions, 'ו', ONES_MASC, TEENS_MASC, HUNDREDS) + ' ' + SCALE_PLURAL[2]
+  }
+
+  // Cardinal millions + ordinal remainder
+  let result
+  if (millions === 1) {
+    result = SCALE[2]
+  } else {
+    result = buildScaleSegment(millions, 'ו', ONES_MASC, TEENS_MASC, HUNDREDS) + ' ' + SCALE_PLURAL[2]
+  }
+
+  return result + ' ' + integerToOrdinal(remainder)
+}
+
+/**
+ * Converts a numeric value to Biblical Hebrew ordinal words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The ordinal in Biblical Hebrew words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a positive integer
+ *
+ * @example
+ * toOrdinal(1)   // 'ראשון'
+ * toOrdinal(21)  // 'עשרים וראשון'
+ */
+function toOrdinal (value) {
+  const n = parseOrdinalValue(value)
+  return integerToOrdinal(n)
+}
+
+// ============================================================================
+// Currency Functions
+// ============================================================================
+
+/**
+ * Converts a numeric value to Biblical Hebrew Shekel currency words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The currency in Biblical Hebrew 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)
+  }
+
+  // Shekels (masculine)
+  if (dollars > 0n || cents === 0n) {
+    if (dollars === 1n) {
+      parts.push(SHEKEL + ' ' + ONES_MASC[1])
+    } else if (dollars === 2n) {
+      parts.push(ONES_MASC[2] + ' ' + SHEKEL_PLURAL)
+    } else {
+      const shekelWord = integerToWords(dollars, 'masculine', 'ו')
+      parts.push(shekelWord + ' ' + SHEKEL_PLURAL)
+    }
+  }
+
+  // Gerah (feminine subunit)
+  if (cents > 0n) {
+    const centNum = Number(cents)
+    if (centNum === 1) {
+      parts.push(GERAH + ' ' + ONES_FEM[1])
+    } else {
+      const gerahWord = integerToWords(cents, 'feminine', 'ו')
+      parts.push(gerahWord + ' ' + GERAH_PLURAL)
+    }
+  }
+
+  return parts.join(' ')
+}
+
 // ============================================================================
 // Exports
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/he-IL.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Converts a numeric value to Modern Hebrew words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @param {Object} [options] - Optional configuration
+ * @param {string} [options.andWord='ו'] - Custom conjunction word
+ * @returns {string} The number in Modern Hebrew words
+ */
+export function toCardinal(value: number | string | bigint, options?: {
+    andWord?: string | undefined;
+}): string;
+/**
+ * Converts a numeric value to Hebrew ordinal words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The ordinal in Hebrew words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a positive integer
+ *
+ * @example
+ * toOrdinal(1)   // 'ראשון'
+ * toOrdinal(21)  // 'עשרים וראשון'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Hebrew New Israeli Shekel currency words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The currency in Hebrew 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;