n2words 3.1.0 → 5.0.0

package/{lib/languages/fil.js → src/fil-PH.js}

@@ -1,7 +1,7 @@
 /**
- * Filipino language converter - Functional Implementation
+ * Filipino (Philippines) language converter
  *
- * Self-contained module with its own input validation, ready for subpath exports.
+ * CLDR: fil-PH | Filipino as used in the Philippines
  *
  * Key features:
  * - Linker "ng" after vowels: "isang daang" (100)
@@ -10,7 +10,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
@@ -31,6 +33,25 @@ const DECIMAL_SEP = 'punto'
 // Short scale with linker
 const SCALE_WORDS = ['', THOUSAND, 'milyong', 'bilyong', 'trilyong']
 
+// ============================================================================
+// Ordinal Vocabulary
+// ============================================================================
+
+// Filipino ordinals use "ika-" prefix: ika-isa (1st), ikalawa (2nd), etc.
+// Special forms for 1st and 2nd
+const ORDINAL_PREFIX = 'ika'
+const ORDINAL_SPECIAL = {
+  1: 'una', // first
+  2: 'ikalawa' // second (contracted form)
+}
+
+// ============================================================================
+// Currency Vocabulary (Philippine Peso)
+// ============================================================================
+
+const PESO = 'piso'
+const SENTIMO = 'sentimo'
+
 // ============================================================================
 // Helper Functions
 // ============================================================================
@@ -53,8 +74,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 = []
 
@@ -186,8 +207,8 @@ function decimalPartToWords (decimalPart) {
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Filipino words
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
 
@@ -204,8 +225,123 @@ function toWords (value) {
   return result
 }
 
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Filipino ordinal words.
+ *
+ * Filipino ordinals: una (1st), ikalawa (2nd), then ika- + cardinal.
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Filipino ordinal words
+ */
+function integerToOrdinal (n) {
+  // Special forms for 1st and 2nd
+  if (n === 1n) return ORDINAL_SPECIAL[1]
+  if (n === 2n) return ORDINAL_SPECIAL[2]
+
+  // For 3+, use ika- prefix + cardinal
+  return ORDINAL_PREFIX + '-' + integerToWords(n)
+}
+
+/**
+ * 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'
+ */
+function toOrdinal (value) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value)
+// ============================================================================
+
+/**
+ * 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'
+ */
+function toCurrency (value) {
+  const { isNegative, dollars: pesos, cents: sentimos } = parseCurrencyValue(value)
+
+  let result = ''
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  // Pesos part
+  if (pesos > 0n || sentimos === 0n) {
+    // Add linker before "piso"
+    const pesoWords = integerToWords(pesos)
+    if (pesos === 0n) {
+      result += pesoWords + ' ' + PESO
+    } else {
+      // Need to add linker to the last word before "piso"
+      const lastSpaceIdx = pesoWords.lastIndexOf(' ')
+      if (lastSpaceIdx === -1) {
+        // Single word
+        result += addLinker(pesoWords) + ' ' + PESO
+      } else {
+        const prefix = pesoWords.slice(0, lastSpaceIdx + 1)
+        const lastWord = pesoWords.slice(lastSpaceIdx + 1)
+        if (lastWord.endsWith('ng')) {
+          result += pesoWords + ' ' + PESO
+        } else {
+          result += prefix + addLinker(lastWord) + ' ' + PESO
+        }
+      }
+    }
+  }
+
+  // Sentimos part
+  if (sentimos > 0n) {
+    if (pesos > 0n) {
+      result += ' at '
+    }
+    const sentimoWords = integerToWords(sentimos)
+    // Add linker before "sentimo"
+    const lastSpaceIdx = sentimoWords.lastIndexOf(' ')
+    if (lastSpaceIdx === -1) {
+      // Single word
+      result += addLinker(sentimoWords) + ' ' + SENTIMO
+    } else {
+      const prefix = sentimoWords.slice(0, lastSpaceIdx + 1)
+      const lastWord = sentimoWords.slice(lastSpaceIdx + 1)
+      if (lastWord.endsWith('ng')) {
+        result += sentimoWords + ' ' + SENTIMO
+      } else {
+        result += prefix + addLinker(lastWord) + ' ' + SENTIMO
+      }
+    }
+  }
+
+  return result
+}
+
 // ============================================================================
 // Exports
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/fr-BE.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Converts a numeric value to Belgian French words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @param {Object} [options] - Optional configuration
+ * @param {boolean} [options.withHyphenSeparator=false] - Use hyphens between words
+ * @returns {string} The number in Belgian French words
+ */
+export function toCardinal(value: number | string | bigint, options?: {
+    withHyphenSeparator?: boolean | undefined;
+}): string;
+/**
+ * Converts a numeric value to Belgian French ordinal words.
+ *
+ * Belgian 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(70)   // 'septantième'
+ * toOrdinal(90)   // 'nonantième'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Belgian 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 Belgian 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)                  // 'nonante-neuf centimes'
+ * toCurrency(0.01)                  // 'un centime'
+ * toCurrency(42.50, { and: false }) // 'quarante-deux euros cinquante centimes'
+ */
+export function toCurrency(value: number | string | bigint, options?: {
+    and?: boolean | undefined;
+}): string;

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

@@ -1,7 +1,7 @@
 /**
- * French (Belgium) language converter - Functional Implementation
+ * French (Belgium) language converter
  *
- * Self-contained module with its own input validation, ready for subpath exports.
+ * CLDR: fr-BE | French as used in Belgium
  *
  * Belgian French differences from standard French:
  * - septante (70) instead of soixante-dix
@@ -10,8 +10,10 @@
  * - Uses "septante et un" (71), "nonante et un" (91)
  */
 
-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
@@ -31,6 +33,25 @@ const ZERO = 'zéro'
 const NEGATIVE = 'moins'
 const DECIMAL_SEP = 'virgule'
 
+// ============================================================================
+// 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
 // ============================================================================
@@ -39,7 +60,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
@@ -70,7 +91,7 @@ function buildSegment (n) {
     parts.push(TEENS[tensOnes - 10])
   } else if (tensOnes < 70) {
     // 20-69: standard pattern
-    const t = Math.floor(tensOnes / 10)
+    const t = Math.trunc(tensOnes / 10)
     const o = tensOnes % 10
     if (o === 0) {
       parts.push(TENS[t])
@@ -263,22 +284,163 @@ function decimalPartToWords (decimalPart, withHyphen) {
  * @param {boolean} [options.withHyphenSeparator=false] - Use hyphens between words
  * @returns {string} The number in Belgian French words
  */
-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 Belgian French ordinal words.
+ *
+ * @param {bigint} n - Positive integer
+ * @returns {string} Belgian 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 Belgian French ordinal words.
+ *
+ * Belgian 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(70)   // 'septantième'
+ * toOrdinal(90)   // 'nonantième'
+ */
+function toOrdinal (value) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value, options?)
+// ============================================================================
+
+/**
+ * Converts a numeric value to Belgian 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 Belgian 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)                  // 'nonante-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
@@ -288,4 +450,4 @@ function toWords (value, options) {
 // Exports
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/fr-FR.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Converts a numeric value to French words.
+ *
+ * This is the main public API. It accepts any valid numeric input
+ * (number, string, or bigint) and handles parsing internally.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @param {Object} [options] - Optional configuration
+ * @param {boolean} [options.withHyphenSeparator=false] - Use hyphens between all words
+ * @returns {string} The number in French words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCardinal(21)           // 'vingt et un'
+ * toCardinal(80)           // 'quatre-vingts'
+ * toCardinal(1000000)      // 'un million'
+ */
+export function toCardinal(value: number | string | bigint, options?: {
+    withHyphenSeparator?: boolean | undefined;
+}): string;
+/**
+ * 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'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * 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'
+ */
+export function toCurrency(value: number | string | bigint, options?: {
+    and?: boolean | undefined;
+}): string;