n2words 3.1.0 → 4.0.0

package/src/fa-IR.js

@@ -0,0 +1,246 @@
+/**
+ * Persian (Iran) language converter
+ *
+ * CLDR: fa-IR | Persian as used in Iran
+ *
+ * Key features:
+ * - "و" (and) conjunction for compound numbers
+ * - Omit "یک" (one) before thousand
+ * - Pre-composed hundreds (دویست, سيصد, etc.)
+ */
+
+import { parseCardinalValue } from './utils/parse-cardinal.js'
+import { parseCurrencyValue } from './utils/parse-currency.js'
+import { parseOrdinalValue } from './utils/parse-ordinal.js'
+
+// ============================================================================
+// Vocabulary
+// ============================================================================
+
+const ONES = { 1: 'یک', 2: 'دو', 3: 'سه', 4: 'چهار', 5: 'پنج', 6: 'شش', 7: 'هفت', 8: 'هشت', 9: 'نه' }
+const TEENS = { 10: 'ده', 11: 'یازده', 12: 'دوازده', 13: 'سیزده', 14: 'چهارده', 15: 'پانزده', 16: 'شانزده', 17: 'هفده', 18: 'هجده', 19: 'نوزده' }
+const TENS = { 20: 'بیست', 30: 'سی', 40: 'چهل', 50: 'پنجاه', 60: 'شصت', 70: 'هفتاد', 80: 'هشتاد', 90: 'نود' }
+const HUNDREDS = { 100: 'صد', 200: 'دویست', 300: 'سيصد', 400: 'چهار صد', 500: 'پانصد', 600: 'ششصد', 700: 'هفتصد', 800: 'هشتصد', 900: 'نهصد' }
+
+const THOUSAND = 'هزار'
+const MILLION = 'میلیون'
+const MILLIARD = 'میلیارد'
+
+const ZERO = 'صفر'
+const NEGATIVE = 'منفى'
+const DECIMAL_SEP = 'ممیّز'
+
+// ============================================================================
+// Ordinal Vocabulary
+// ============================================================================
+
+// Persian ordinals: add -ُم (-om) suffix to cardinal
+// Special forms for 1st, 2nd, 3rd
+const ORDINAL_SUFFIX = 'م' // ـُم (-om)
+const ORDINAL_ONES = {
+  1: 'اول', // avval (first)
+  2: 'دوم', // dovvom (second)
+  3: 'سوم', // sevvom (third)
+  4: 'چهارم',
+  5: 'پنجم',
+  6: 'ششم',
+  7: 'هفتم',
+  8: 'هشتم',
+  9: 'نهم'
+}
+
+// ============================================================================
+// Currency Vocabulary (Iranian Rial)
+// ============================================================================
+
+const RIAL = 'ریال'
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+function integerToWords (n) {
+  if (n === 0n) return ZERO
+
+  // 1-9
+  if (n <= 9n) {
+    return ONES[Number(n)]
+  }
+
+  // 10-19
+  if (n <= 19n) {
+    return TEENS[Number(n)]
+  }
+
+  // 20-99
+  if (n < 100n) {
+    const ones = n % 10n
+    const tens = n - ones
+    if (ones === 0n) {
+      return TENS[Number(tens)]
+    }
+    return `${TENS[Number(tens)]} و ${ONES[Number(ones)]}`
+  }
+
+  // 100-999
+  if (n < 1000n) {
+    const hundreds = 100n * (n / 100n)
+    const remainder = n - hundreds
+    if (remainder === 0n) {
+      return HUNDREDS[Number(hundreds)]
+    }
+    return `${HUNDREDS[Number(hundreds)]} و ${integerToWords(remainder)}`
+  }
+
+  // 1000-999999
+  if (n < 1_000_000n) {
+    const thousandMultiplier = n / 1000n
+    // Persian omits "one" before thousand: 1000 is just "هزار", not "یک هزار"
+    const thousandPrefix = thousandMultiplier === 1n
+      ? ''
+      : integerToWords(thousandMultiplier) + ' '
+    const remainder = n % 1000n
+    const suffix = remainder === 0n ? '' : ' ' + integerToWords(remainder)
+    return `${thousandPrefix}${THOUSAND}${suffix}`
+  }
+
+  // 1000000-999999999 (millions)
+  if (n < 1_000_000_000n) {
+    const millionMultiplier = n / 1_000_000n
+    const millionPrefix = integerToWords(millionMultiplier) + ' ' + MILLION
+    const remainder = n % 1_000_000n
+    const suffix = remainder === 0n ? '' : ' و ' + integerToWords(remainder)
+    return `${millionPrefix}${suffix}`
+  }
+
+  // 1000000000+ (milliards - 10^9)
+  const milliardMultiplier = n / 1_000_000_000n
+  const milliardPrefix = integerToWords(milliardMultiplier) + ' ' + MILLIARD
+  const remainder = n % 1_000_000_000n
+  const suffix = remainder === 0n ? '' : ' و ' + integerToWords(remainder)
+  return `${milliardPrefix}${suffix}`
+}
+
+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 Persian words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Persian 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 non-negative integer to Persian ordinal words.
+ *
+ * Persian ordinals: اول (1st), دوم (2nd), سوم (3rd), then cardinal + م suffix.
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Persian ordinal words
+ */
+function integerToOrdinal (n) {
+  // Special forms for 1-9
+  if (n >= 1n && n <= 9n) {
+    return ORDINAL_ONES[Number(n)]
+  }
+
+  // For 10+, add -م suffix to cardinal
+  const cardinal = integerToWords(n)
+  return cardinal + ORDINAL_SUFFIX
+}
+
+/**
+ * Converts a numeric value to Persian 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)
+// ============================================================================
+
+/**
+ * Converts a numeric value to Persian currency words (Rial).
+ *
+ * Iranian Rial has no subunit in modern usage.
+ * (Historically dinar was 1/100 rial, but not used today)
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Persian 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)     // 'چهل و دو ریال'
+ * toCurrency(1000)   // 'هزار ریال'
+ * toCurrency(-5)     // 'منفى پنج ریال'
+ */
+function toCurrency (value) {
+  const { isNegative, dollars: rial } = parseCurrencyValue(value)
+
+  let result = ''
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  result += integerToWords(rial)
+  result += ' ' + RIAL
+
+  return result
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export { toCardinal, toOrdinal, toCurrency }

package/src/fi-FI.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Converts a numeric value to Finnish words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Finnish words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCardinal(21)       // 'kaksikymmentäyksi'
+ * toCardinal(1000)     // 'tuhat'
+ * toCardinal('3.14')   // 'kolme pilkku yksi neljä'
+ */
+export function toCardinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Finnish 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)    // 'ensimmäinen'
+ * toOrdinal(2)    // 'toinen'
+ * toOrdinal(3)    // 'kolmas'
+ * toOrdinal(10)   // 'kymmenes'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Finnish currency words (Euro).
+ *
+ * Euro uses sentti as subunit (100 senttiä = 1 euro).
+ * Finnish has singular/plural: 1 euro vs 2 euroa, 1 sentti vs 2 senttiä.
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Finnish 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)      // 'yksi euro'
+ * toCurrency(42)     // 'neljäkymmentäkaksi euroa'
+ * toCurrency(1.50)   // 'yksi euro viisikymmentä senttiä'
+ */
+export function toCurrency(value: number | string | bigint): string;

package/{lib/languages/fi.js → src/fi-FI.js}

@@ -1,7 +1,7 @@
 /**
- * Finnish language converter - Functional Implementation
+ * Finnish (Finland) language converter
  *
- * Self-contained module with its own input validation, ready for subpath exports.
+ * CLDR: fi-FI | Finnish as used in Finland
  *
  * Key features:
  * - Compound tens+ones without spaces: "kaksikymmentäyksi" (21)
@@ -11,7 +11,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 (module-level constants)
@@ -34,6 +36,29 @@ const DECIMAL_SEP = 'pilkku'
 // Long scale
 const SCALES = ['miljoona', 'miljardi', 'biljoona', 'triljoona']
 
+// ============================================================================
+// Ordinal Vocabulary
+// ============================================================================
+
+// Finnish ordinals: special forms for 1st-2nd, then -s suffix
+const ORDINAL_FIRST = 'ensimmäinen'
+const ORDINAL_SECOND = 'toinen'
+const ORDINAL_SUFFIX = 's' // e.g., kolmas, neljäs
+
+// Ordinal forms for basic numbers
+const ORDINAL_ONES = ['', 'ensimmäinen', 'toinen', 'kolmas', 'neljäs', 'viides', 'kuudes', 'seitsemäs', 'kahdeksas', 'yhdeksäs']
+const ORDINAL_TEENS = ['kymmenes', 'yhdestoista', 'kahdestoista', 'kolmastoista', 'neljästoista', 'viidestoista', 'kuudestoista', 'seitsemästoista', 'kahdeksastoista', 'yhdeksästoista']
+const ORDINAL_TENS = ['', '', 'kahdeskymmenes', 'kolmaskymmenes', 'neljäskymmenes', 'viideskymmenes', 'kuudeskymmenes', 'seitsemäskymmenes', 'kahdeksaskymmenes', 'yhdeksäskymmenes']
+
+// ============================================================================
+// Currency Vocabulary (Euro)
+// ============================================================================
+
+const EURO = 'euroa'
+const EURO_SINGULAR = 'euro'
+const CENT = 'senttiä'
+const CENT_SINGULAR = 'sentti'
+
 // ============================================================================
 // Segment Building
 // ============================================================================
@@ -46,8 +71,8 @@ function buildSegment (n) {
   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)
 
   const parts = []
 
@@ -209,12 +234,12 @@ function decimalPartToWords (decimalPart) {
  * @throws {Error} If value is not a valid number format
  *
  * @example
- * toWords(21)       // 'kaksikymmentäyksi'
- * toWords(1000)     // 'tuhat'
- * toWords('3.14')   // 'kolme pilkku yksi neljä'
+ * toCardinal(21)       // 'kaksikymmentäyksi'
+ * toCardinal(1000)     // 'tuhat'
+ * toCardinal('3.14')   // 'kolme pilkku yksi neljä'
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
 
@@ -231,8 +256,124 @@ function toWords (value) {
   return result
 }
 
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Builds ordinal segment for 0-99.
+ * Finnish ordinals have special forms.
+ */
+function buildOrdinalSegment (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) {
+    return ORDINAL_TENS[tens]
+  }
+
+  // Compound: kahdeskymmenes + first/second/third etc
+  // For compound ordinals, only the last part is ordinal form
+  return TENS[tens] + ORDINAL_ONES[ones]
+}
+
+/**
+ * Converts a non-negative integer to Finnish ordinal words.
+ *
+ * Finnish ordinals: ensimmäinen (1st), toinen (2nd), kolmas (3rd), etc.
+ * For larger numbers, use cardinal + ordinal ending.
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Finnish ordinal words
+ */
+function integerToOrdinal (n) {
+  // Special cases
+  if (n === 1n) return ORDINAL_FIRST
+  if (n === 2n) return ORDINAL_SECOND
+
+  // For numbers < 100, use ordinal forms
+  if (n < 100n) {
+    return buildOrdinalSegment(Number(n))
+  }
+
+  // For larger numbers, use cardinal form with ordinal suffix on last part
+  // This is a simplification - full Finnish ordinal grammar is complex
+  const cardinal = integerToWords(n)
+  // Add ordinal suffix approximation
+  return cardinal + ORDINAL_SUFFIX
+}
+
+/**
+ * Converts a numeric value to Finnish 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)    // 'ensimmäinen'
+ * toOrdinal(2)    // 'toinen'
+ * toOrdinal(3)    // 'kolmas'
+ * toOrdinal(10)   // 'kymmenes'
+ */
+function toOrdinal (value) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value)
+// ============================================================================
+
+/**
+ * Converts a numeric value to Finnish currency words (Euro).
+ *
+ * Euro uses sentti as subunit (100 senttiä = 1 euro).
+ * Finnish has singular/plural: 1 euro vs 2 euroa, 1 sentti vs 2 senttiä.
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Finnish 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)      // 'yksi euro'
+ * toCurrency(42)     // 'neljäkymmentäkaksi euroa'
+ * toCurrency(1.50)   // 'yksi euro viisikymmentä senttiä'
+ */
+function toCurrency (value) {
+  const { isNegative, dollars: euros, cents } = parseCurrencyValue(value)
+
+  let result = ''
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  // Euro part - always show if non-zero, or if no cents
+  if (euros > 0n || cents === 0n) {
+    result += integerToWords(euros)
+    result += ' ' + (euros === 1n ? EURO_SINGULAR : EURO)
+  }
+
+  // Cent part
+  if (cents > 0n) {
+    if (euros > 0n) {
+      result += ' '
+    }
+    result += integerToWords(cents)
+    result += ' ' + (cents === 1n ? CENT_SINGULAR : CENT)
+  }
+
+  return result
+}
+
 // ============================================================================
 // Public API
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/fil-PH.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Converts a numeric value to Filipino words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Filipino words
+ */
+export function toCardinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Filipino 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)    // 'una'
+ * toOrdinal(2)    // 'ikalawa'
+ * toOrdinal(3)    // 'ika-tatlo'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Filipino currency words (Philippine Peso).
+ *
+ * Uses piso (peso) and sentimo (centavo).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Filipino 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)     // 'apatnapu dalawang piso'
+ * toCurrency(1.50)   // 'isang piso at limampung sentimo'
+ * toCurrency(-5)     // 'negatibo limang piso'
+ */
+export function toCurrency(value: number | string | bigint): string;