n2words 3.1.0 → 4.0.0

package/{lib/languages/mr.js → src/mr-IN.js}

@@ -1,7 +1,7 @@
 /**
- * Marathi language converter - Functional Implementation
+ * Marathi (India) language converter
  *
- * Self-contained module with its own input validation, ready for subpath exports.
+ * CLDR: mr-IN | Marathi as used in India
  *
  * Key features:
  * - Indian numbering system (हजार, लाख, कोटी)
@@ -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
@@ -22,6 +24,28 @@ 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 = [
   'शून्य', 'एक', 'दोन', 'तीन', 'चार', 'पाच', 'सहा', 'सात', 'आठ', 'नऊ',
   'दहा', 'अकरा', 'बारा', 'तेरा', 'चौदा', 'पंधरा', 'सोळा', 'सतरा', 'अठरा', 'एकोणीस',
@@ -125,8 +149,8 @@ function decimalPartToWords (decimalPart) {
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Marathi words
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
 
@@ -143,8 +167,94 @@ function toWords (value) {
   return result
 }
 
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Converts a positive integer to Marathi ordinal words.
+ *
+ * Marathi ordinals: First 6 are irregular, then add -वा suffix.
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Marathi 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 Marathi 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)   // 'दहावा'
+ */
+function toOrdinal (value) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value, options?)
+// ============================================================================
+
+/**
+ * Converts a numeric value to Marathi currency words (Indian Rupee).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Marathi 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 { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/ms-MY.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Converts a numeric value to Malay words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Malay words
+ */
+export function toCardinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Malay 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)    // 'pertama'
+ * toOrdinal(2)    // 'kedua'
+ * toOrdinal(10)   // 'kesepuluh'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Malay currency words (Ringgit).
+ *
+ * Malaysian Ringgit uses sen as subunit (100 sen = 1 ringgit).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Malay 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)     // 'empat puluh dua ringgit'
+ * toCurrency(1.50)   // 'satu ringgit lima puluh sen'
+ * toCurrency(-5)     // 'minus lima ringgit'
+ */
+export function toCurrency(value: number | string | bigint): string;

package/{lib/languages/ms.js → src/ms-MY.js}

@@ -1,7 +1,7 @@
 /**
- * Malay (Bahasa Melayu) language converter - Functional Implementation
+ * Malay (Malaysia) language converter
  *
- * Self-contained module with its own input validation, ready for subpath exports.
+ * CLDR: ms-MY | Malay (Bahasa Melayu) as used in Malaysia
  *
  * Key features:
  * - "Se-" prefix for ALL singular scale units (seratus, seribu, sejuta, sebilion)
@@ -10,7 +10,9 @@
  * - Note: "lapan" (8) differs from Indonesian "delapan"
  */
 
-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
@@ -28,6 +30,21 @@ const ZERO = 'sifar'
 const NEGATIVE = 'minus'
 const DECIMAL_SEP = 'perpuluhan'
 
+// ============================================================================
+// Ordinal Vocabulary
+// ============================================================================
+
+const ORDINAL_PREFIX = 'ke'
+// First is special: "pertama" (not "kesatu")
+const ORDINAL_FIRST = 'pertama'
+
+// ============================================================================
+// Currency Vocabulary (Malaysian Ringgit)
+// ============================================================================
+
+const RINGGIT = 'ringgit'
+const SEN = 'sen'
+
 // ============================================================================
 // Segment Building
 // ============================================================================
@@ -36,8 +53,8 @@ function buildSegment (n) {
   if (n === 0) return ''
 
   const onesDigit = 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 = []
 
@@ -175,8 +192,8 @@ function decimalPartToWords (decimalPart) {
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Malay words
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
 
@@ -193,8 +210,94 @@ function toWords (value) {
   return result
 }
 
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Malay ordinal words.
+ *
+ * Malay ordinals use "ke-" prefix + cardinal number.
+ * Special case: "pertama" for 1st (not "kesatu").
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Malay ordinal words
+ */
+function integerToOrdinal (n) {
+  // Special case: 1st is "pertama"
+  if (n === 1n) {
+    return ORDINAL_FIRST
+  }
+
+  // All others: "ke" + cardinal (no hyphen in Malay)
+  return ORDINAL_PREFIX + integerToWords(n)
+}
+
+/**
+ * Converts a numeric value to Malay 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)    // 'pertama'
+ * toOrdinal(2)    // 'kedua'
+ * toOrdinal(10)   // 'kesepuluh'
+ */
+function toOrdinal (value) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value)
+// ============================================================================
+
+/**
+ * Converts a numeric value to Malay currency words (Ringgit).
+ *
+ * Malaysian Ringgit uses sen as subunit (100 sen = 1 ringgit).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Malay 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)     // 'empat puluh dua ringgit'
+ * toCurrency(1.50)   // 'satu ringgit lima puluh sen'
+ * toCurrency(-5)     // 'minus lima ringgit'
+ */
+function toCurrency (value) {
+  const { isNegative, dollars: ringgit, cents: sen } = parseCurrencyValue(value)
+
+  let result = ''
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  // Ringgit part - show if non-zero, or if no sen
+  if (ringgit > 0n || sen === 0n) {
+    result += integerToWords(ringgit)
+    result += ' ' + RINGGIT
+  }
+
+  // Sen part
+  if (sen > 0n) {
+    if (ringgit > 0n) {
+      result += ' '
+    }
+    result += integerToWords(sen)
+    result += ' ' + SEN
+  }
+
+  return result
+}
+
 // ============================================================================
 // Exports
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/nb-NO.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Converts a numeric value to Norwegian Bokmål words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Norwegian words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCardinal(21)       // 'tjue-en'
+ * toCardinal(101)      // 'en hundre og en'
+ * toCardinal(1000000)  // 'en million'
+ */
+export function toCardinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Norwegian Bokmål 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)    // 'første'
+ * toOrdinal(2)    // 'andre'
+ * toOrdinal(21)   // 'tjue-ende'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Norwegian currency words (Norwegian Krone).
+ *
+ * Uses krone/kroner and øre (100 øre = 1 krone).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Norwegian 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)      // 'en krone'
+ * toCurrency(42)     // 'førti-to kroner'
+ * toCurrency(1.50)   // 'en krone og femti øre'
+ */
+export function toCurrency(value: number | string | bigint): string;

package/{lib/languages/nb.js → src/nb-NO.js}

@@ -1,7 +1,7 @@
 /**
- * Norwegian Bokmål language converter - Functional Implementation
+ * Norwegian Bokmål (Norway) language converter
  *
- * Self-contained module with its own input validation, ready for subpath exports.
+ * CLDR: nb-NO | Norwegian Bokmål as used in Norway
  *
  * Key features:
  * - Hyphenated tens+ones: "tjue-en" (21)
@@ -10,7 +10,9 @@
  * - Short scale: million, milliard, billion, etc.
  */
 
-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)
@@ -31,6 +33,34 @@ const DECIMAL_SEP = 'komma'
 // Short scale: million, milliard, billion, etc.
 const SCALES = ['million', 'milliard', 'billion', 'billiard', 'kvintillion', 'sekstillion', 'septillion', 'oktillion']
 
+// ============================================================================
+// Ordinal Vocabulary
+// ============================================================================
+
+// Norwegian ordinals: 1st-12th special forms, then cardinal + -de/-te
+const ORDINAL_SPECIAL = {
+  1: 'første',
+  2: 'andre',
+  3: 'tredje',
+  4: 'fjerde',
+  5: 'femte',
+  6: 'sjette',
+  7: 'sjuende',
+  8: 'åttende',
+  9: 'niende',
+  10: 'tiende',
+  11: 'ellevte',
+  12: 'tolvte'
+}
+
+// ============================================================================
+// Currency Vocabulary (Norwegian Krone)
+// ============================================================================
+
+const KRONE = 'krone'
+const KRONER = 'kroner' // plural
+const ORE = 'øre' // same singular and plural
+
 // ============================================================================
 // Segment Building
 // ============================================================================
@@ -43,8 +73,8 @@ function buildSegment (n) {
   if (n === 0) return { word: '', hasHundred: false }
 
   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 = []
   let hasHundred = false
@@ -256,12 +286,12 @@ function decimalPartToWords (decimalPart) {
  * @throws {Error} If value is not a valid number format
  *
  * @example
- * toWords(21)       // 'tjue-en'
- * toWords(101)      // 'en hundre og en'
- * toWords(1000000)  // 'en million'
+ * toCardinal(21)       // 'tjue-en'
+ * toCardinal(101)      // 'en hundre og en'
+ * toCardinal(1000000)  // 'en million'
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
 
@@ -278,8 +308,120 @@ function toWords (value) {
   return result
 }
 
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Converts a non-negative integer to Norwegian Bokmål ordinal words.
+ *
+ * Norwegian ordinals: første (1st), andre (2nd), tredje (3rd), etc.
+ * 1-12 have special forms, others use cardinal + de/te suffix.
+ * Teens (13-19): drop -en and add -ende (tretten → trettende)
+ * Numbers ending in 'en' (one): replace with 'ende' (tjue-en → tjue-ende)
+ * Numbers ending in 9 (ni): add 'ede' (nitti-ni → nitti-niede)
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Norwegian ordinal words
+ */
+function integerToOrdinal (n) {
+  // Special forms for 1-12
+  if (n >= 1n && n <= 12n) {
+    return ORDINAL_SPECIAL[Number(n)]
+  }
+
+  const num = Number(n)
+  const cardinal = integerToWords(n)
+
+  // Teens 13-19: drop -en and add -ende
+  if (num >= 13 && num <= 19) {
+    // tretten → trettende, nitten → nittende
+    return cardinal.slice(0, -2) + 'ende'
+  }
+
+  // For other numbers, check if cardinal ends with 'en' (one)
+  // tjue-en → tjue-ende, en hundre og en → en hundre og ende
+  if (cardinal.endsWith('en')) {
+    return cardinal.slice(0, -2) + 'ende'
+  }
+
+  // Numbers ending in 'ni' (9): add 'ede'
+  // nitti-ni → nitti-niede
+  if (cardinal.endsWith('ni')) {
+    return cardinal + 'ede'
+  }
+
+  // Others use -de suffix
+  return cardinal + 'de'
+}
+
+/**
+ * Converts a numeric value to Norwegian Bokmål 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)    // 'første'
+ * toOrdinal(2)    // 'andre'
+ * toOrdinal(21)   // 'tjue-ende'
+ */
+function toOrdinal (value) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY: toCurrency(value)
+// ============================================================================
+
+/**
+ * Converts a numeric value to Norwegian currency words (Norwegian Krone).
+ *
+ * Uses krone/kroner and øre (100 øre = 1 krone).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Norwegian 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)      // 'en krone'
+ * toCurrency(42)     // 'førti-to kroner'
+ * toCurrency(1.50)   // 'en krone og femti øre'
+ */
+function toCurrency (value) {
+  const { isNegative, dollars: kroner, cents: ore } = parseCurrencyValue(value)
+
+  let result = ''
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  // Kroner part
+  if (kroner > 0n || ore === 0n) {
+    if (kroner === 1n) {
+      result += 'en ' + KRONE
+    } else {
+      result += integerToWords(kroner) + ' ' + KRONER
+    }
+  }
+
+  // Øre part
+  if (ore > 0n) {
+    if (kroner > 0n) {
+      result += ' og '
+    }
+    result += integerToWords(ore) + ' ' + ORE
+  }
+
+  return result
+}
+
 // ============================================================================
 // Public API
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/nl-NL.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Converts a numeric value to Dutch 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.accentOne=true] - Use "één" instead of "een"
+ * @param {boolean} [options.includeOptionalAnd=false] - Include "en" before small numbers
+ * @param {boolean} [options.noHundredPairing=false] - Disable hundred pairing (1104→duizend honderdvier)
+ * @returns {string} The number in Dutch words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCardinal(21)                        // 'eenentwintig'
+ * toCardinal(1)                         // 'één'
+ * toCardinal(1, {accentOne: false})     // 'een'
+ * toCardinal(1104)                      // 'elfhonderd vier'
+ */
+export function toCardinal(value: number | string | bigint, options?: {
+    accentOne?: boolean | undefined;
+    includeOptionalAnd?: boolean | undefined;
+    noHundredPairing?: boolean | undefined;
+}): string;
+/**
+ * Converts a number to Dutch ordinal words.
+ *
+ * @param {number | string | bigint} value - The number to convert
+ * @returns {string} Dutch ordinal words
+ *
+ * @example
+ * toOrdinal(1)     // 'eerste'
+ * toOrdinal(21)    // 'eenentwintigste'
+ * toOrdinal(100)   // 'honderdste'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a number to Dutch currency words (Euro).
+ *
+ * @param {number | string | bigint} value - The amount to convert
+ * @param {Object} [options]
+ * @param {boolean} [options.and=true] - Include "en" between euros and cents
+ * @returns {string} Dutch currency words
+ *
+ * @example
+ * toCurrency(42.50)  // 'tweeënveertig euro en vijftig cent'
+ * toCurrency(1)      // 'één euro'
+ * toCurrency(0.01)   // 'één cent'
+ */
+export function toCurrency(value: number | string | bigint, options?: {
+    and?: boolean | undefined;
+}): string;