n2words 3.1.0 → 4.0.0

package/{lib/languages/nl.js → src/nl-NL.js}

@@ -1,7 +1,7 @@
 /**
- * Dutch language converter - Functional Implementation
+ * Dutch (Netherlands) language converter
  *
- * Self-contained module with its own input validation, ready for subpath exports.
+ * CLDR: nl-NL | Dutch as used in the Netherlands
  *
  * Dutch-specific rules:
  * - Inverted tens-ones: eenentwintig (one-and-twenty)
@@ -13,8 +13,10 @@
  * - Long scale with -ard forms
  */
 
-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)
@@ -33,6 +35,12 @@ const ZERO = 'nul'
 const NEGATIVE = 'min'
 const DECIMAL_SEP = 'komma'
 
+// Currency vocabulary (Euro)
+const EURO = 'euro'
+const EUROS = 'euro' // Euro doesn't pluralize in Dutch
+const CENT = 'cent'
+const CENTEN = 'cent' // Cent doesn't pluralize in written currency
+
 // ============================================================================
 // Segment Building
 // ============================================================================
@@ -47,8 +55,8 @@ function buildSegment (n, withAnd) {
   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 tensOnes = n % 100
 
   let result = ''
@@ -284,20 +292,23 @@ function decimalPartToWords (decimalPart, options) {
  * @throws {Error} If value is not a valid number format
  *
  * @example
- * toWords(21)                        // 'eenentwintig'
- * toWords(1)                         // 'één'
- * toWords(1, {accentOne: false})     // 'een'
- * toWords(1104)                      // 'elfhonderd vier'
+ * toCardinal(21)                        // 'eenentwintig'
+ * toCardinal(1)                         // 'één'
+ * toCardinal(1, {accentOne: false})     // 'een'
+ * toCardinal(1104)                      // 'elfhonderd vier'
  */
-function toWords (value, options) {
+function toCardinal (value, options) {
   options = validateOptions(options)
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
-  const opts = {
-    accentOne: options.accentOne !== false, // default true
-    includeOptionalAnd: options.includeOptionalAnd || false,
-    noHundredPairing: options.noHundredPairing || false
-  }
+  // Apply option defaults
+  const {
+    accentOne = true,
+    includeOptionalAnd = false,
+    noHundredPairing = false
+  } = options
+
+  const opts = { accentOne, includeOptionalAnd, noHundredPairing }
 
   let result = ''
 
@@ -314,8 +325,239 @@ function toWords (value, options) {
   return result
 }
 
+// ============================================================================
+// Ordinal Functions
+// ============================================================================
+
+// Ordinal forms for 1-9
+const ORDINAL_ONES = ['', 'eerste', 'tweede', 'derde', 'vierde', 'vijfde', 'zesde', 'zevende', 'achtste', 'negende']
+
+/**
+ * Converts a small cardinal to ordinal.
+ * Rules: 1-19 add -de (except eerste, derde, achtste), 20+ add -ste
+ *
+ * @param {string} cardinalWord - Cardinal word
+ * @param {number} n - The number value (0-99)
+ * @returns {string} Ordinal word
+ */
+function smallCardinalToOrdinal (cardinalWord, n) {
+  // Special cases for 1-9
+  if (n >= 1 && n <= 9) return ORDINAL_ONES[n]
+
+  // 10-19: add -de or -e if ends in d
+  if (n < 20) {
+    if (cardinalWord.endsWith('d')) {
+      return cardinalWord + 'e'
+    }
+    return cardinalWord + 'de'
+  }
+
+  // 20+: add -ste
+  return cardinalWord + 'ste'
+}
+
+/**
+ * Builds ordinal words for 0-999.
+ *
+ * @param {number} n - Number 0-999
+ * @returns {string} Dutch ordinal words
+ */
+function buildOrdinalSegment (n) {
+  if (n === 0) return ''
+
+  const hundreds = Math.trunc(n / 100)
+  const tensOnes = n % 100
+
+  // Simple cases: 1-99
+  if (hundreds === 0) {
+    const cardinalWord = buildSegment(n, false)
+    return smallCardinalToOrdinal(cardinalWord, n)
+  }
+
+  // Hundreds: need to build prefix + ordinal suffix
+  let prefix = ''
+  if (hundreds === 1) {
+    prefix = HUNDRED
+  } else {
+    prefix = ONES[hundreds] + HUNDRED
+  }
+
+  if (tensOnes === 0) {
+    // Exact hundred: honderdste, tweehonderdste
+    return prefix + 'ste'
+  }
+
+  // Hundreds + remainder: honderd eerste, tweehonderd drieëntwintigste
+  // Dutch ordinals with hundreds use a space before the ordinal part
+  const ordinalPart = smallCardinalToOrdinal(buildSegment(tensOnes, false), tensOnes)
+  return prefix + ' ' + ordinalPart
+}
+
+/**
+ * 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'
+ */
+function toOrdinal (value) {
+  const n = parseOrdinalValue(value)
+
+  // Fast path: 1-9
+  if (n < 10n) return ORDINAL_ONES[Number(n)]
+
+  // Fast path: 10-99
+  if (n < 100n) {
+    const cardinalWord = buildSegment(Number(n), false)
+    return smallCardinalToOrdinal(cardinalWord, Number(n))
+  }
+
+  // Fast path: 100-999
+  if (n < 1000n) {
+    return buildOrdinalSegment(Number(n))
+  }
+
+  // Large numbers: build with cardinal then convert last segment
+  return buildLargeOrdinal(n)
+}
+
+/**
+ * Builds ordinal words for large numbers.
+ *
+ * @param {bigint} n - Non-negative integer >= 1000
+ * @returns {string} Dutch ordinal words
+ */
+function buildLargeOrdinal (n) {
+  // Extract segments
+  const segments = []
+  let temp = n
+  while (temp > 0n) {
+    segments.push(Number(temp % 1000n))
+    temp = temp / 1000n
+  }
+
+  // Find the lowest non-zero segment
+  let lowestNonZeroIdx = 0
+  for (let i = 0; i < segments.length; i++) {
+    if (segments[i] !== 0) {
+      lowestNonZeroIdx = i
+      break
+    }
+  }
+
+  // Scale ordinal words
+  const SCALE_ORDINAL = ['', 'duizendste', 'miljoenste', 'miljardste', 'biljoenste', 'biljardste', 'triljoenste']
+
+  let result = ''
+
+  for (let i = segments.length - 1; i >= 0; i--) {
+    const segment = segments[i]
+    if (segment === 0) continue
+
+    if (result) result += ' '
+
+    if (i === lowestNonZeroIdx) {
+      // Last non-zero segment gets ordinal form
+      if (i === 0) {
+        // Units segment: use ordinal segment builder
+        result += buildOrdinalSegment(segment)
+      } else if (segment === 1 && i > 0) {
+        // Exact scale: duizendste, miljoenste, etc.
+        if (i === 1) {
+          result += SCALE_ORDINAL[i]
+        } else {
+          result += 'een ' + SCALE_ORDINAL[i]
+        }
+      } else {
+        // Segment + scale ordinal
+        if (i === 1) {
+          result += buildSegment(segment, false) + SCALE_ORDINAL[i]
+        } else {
+          result += buildSegment(segment, false) + ' ' + SCALE_ORDINAL[i]
+        }
+      }
+    } else {
+      // Higher segments use cardinal form
+      if (i === 1) {
+        if (segment === 1) {
+          result += SCALES[0]
+        } else {
+          result += buildSegment(segment, false) + SCALES[0]
+        }
+      } else {
+        const scaleWord = SCALES[i - 1]
+        if (segment === 1) {
+          result += 'een ' + scaleWord
+        } else {
+          result += buildSegment(segment, false) + ' ' + scaleWord
+        }
+      }
+    }
+  }
+
+  return result
+}
+
+// ============================================================================
+// Currency Functions
+// ============================================================================
+
+/**
+ * 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'
+ */
+function toCurrency (value, options) {
+  options = validateOptions(options)
+  const { isNegative, dollars: euros, cents } = parseCurrencyValue(value)
+  const { and = true } = options
+
+  let result = ''
+
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  const hasEuros = euros > 0n
+  const hasCents = cents > 0n
+
+  if (!hasEuros && !hasCents) {
+    return ZERO + ' ' + EUROS
+  }
+
+  // Use accentOne: true for currency (één euro, één cent)
+  const opts = { accentOne: true, includeOptionalAnd: false, noHundredPairing: true }
+
+  if (hasEuros) {
+    const euroWords = integerToWords(euros, opts)
+    result += euroWords + ' ' + (euros === 1n ? EURO : EUROS)
+  }
+
+  if (hasCents) {
+    if (hasEuros) {
+      result += and ? ' en ' : ' '
+    }
+    const centWords = integerToWords(cents, opts)
+    result += centWords + ' ' + (cents === 1n ? CENT : CENTEN)
+  }
+
+  return result
+}
+
 // ============================================================================
 // Public API
 // ============================================================================
 
-export { toWords }
+export { toCardinal, toOrdinal, toCurrency }

package/src/pa-IN.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Converts a numeric value to Punjabi words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Punjabi words
+ */
+export function toCardinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Punjabi 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)   // 'ਦੱਸਵਾਂ'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Punjabi currency words (Indian Rupee).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Punjabi 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/{lib/languages/pa.js → src/pa-IN.js}

@@ -1,7 +1,7 @@
 /**
- * Punjabi language converter - Functional Implementation
+ * Punjabi (India) language converter
  *
- * Self-contained module with its own input validation, ready for subpath exports.
+ * CLDR: pa-IN | Punjabi (Gurmukhi) as used in India
  *
  * Key features:
  * - Indian numbering system (ਹਜ਼ਾਰ, ਲੱਖ, ਕਰੋੜ)
@@ -10,7 +10,9 @@
  * - Complete word forms for 0-99
  */
 
-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
@@ -21,6 +23,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 = [
   'ਸਿਫ਼ਰ', 'ਇੱਕ', 'ਦੋ', 'ਤਿੰਨ', 'ਚਾਰ', 'ਪੰਜ', 'ਛੇ', 'ਸੱਤ', 'ਅੱਠ', 'ਨੌਂ',
   'ਦੱਸ', 'ਗਿਆਰਾਂ', 'ਬਾਰਾਂ', 'ਤੇਰਾਂ', 'ਚੌਦਾਂ', 'ਪੰਦਰਾਂ', 'ਸੋਲਾਂ', 'ਸਤਾਰਾਂ', 'ਅਠਾਰਾਂ', 'ਉੱਨੀ',
@@ -133,8 +157,8 @@ function decimalPartToWords (decimalPart) {
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Punjabi words
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
 
@@ -151,8 +175,94 @@ function toWords (value) {
   return result
 }
 
+// ============================================================================
+// ORDINAL: toOrdinal(value)
+// ============================================================================
+
+/**
+ * Converts a positive integer to Punjabi ordinal words.
+ *
+ * Punjabi ordinals: First 6 are irregular, then add -ਵਾਂ suffix.
+ *
+ * @param {bigint} n - Positive integer to convert
+ * @returns {string} Punjabi 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 Punjabi 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 Punjabi currency words (Indian Rupee).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Punjabi 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/pl-PL.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Converts a numeric value to Polish 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] - Conversion options
+ * @param {string} [options.gender='masculine'] - Gender for numbers < 1000
+ * @returns {string} The number in Polish words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCardinal(1)                          // 'jeden'
+ * toCardinal(1, { gender: 'feminine' })  // 'jedna'
+ * toCardinal(1000)                       // 'tysiąc'
+ * toCardinal(2000)                       // 'dwa tysiące'
+ */
+export function toCardinal(value: number | string | bigint, options?: {
+    gender?: string | undefined;
+}): string;
+/**
+ * Converts a numeric value to Polish ordinal words (masculine nominative).
+ *
+ * @param {number | string | bigint} value - The numeric value to convert (must be a positive integer)
+ * @returns {string} The number as ordinal words (e.g., "pierwszy", "czterdziesty drugi")
+ * @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)    // 'pierwszy'
+ * toOrdinal(2)    // 'drugi'
+ * toOrdinal(3)    // 'trzeci'
+ * toOrdinal(21)   // 'dwudziesty pierwszy'
+ * toOrdinal(42)   // 'czterdziesty drugi'
+ * toOrdinal(100)  // 'setny'
+ * toOrdinal(1000) // 'tysięczny'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Polish currency words (Polish Złoty).
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @returns {string} The amount in Polish 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)     // 'czterdzieści dwa złote'
+ * toCurrency(1)      // 'jeden złoty'
+ * toCurrency(1.50)   // 'jeden złoty pięćdziesiąt groszy'
+ * toCurrency(-5)     // 'minus pięć złotych'
+ */
+export function toCurrency(value: number | string | bigint): string;