n2words 3.1.0 → 5.0.0

package/{lib/languages/en.js → src/en-NZ.js}

@@ -1,17 +1,26 @@
 /**
- * English language converter - Functional Implementation
+ * New Zealand English language converter
  *
- * Self-contained module with its own input validation, ready for subpath exports.
+ * CLDR: en-NZ | English as used in New Zealand
  *
- * Key features:
- * - Western numbering system (thousand, million, billion)
+ * Exports:
+ * - toCardinal(value)            - Cardinal numbers: 42 → "forty-two"
+ * - toOrdinal(value)             - Ordinal numbers: 42 → "forty-second"
+ * - toCurrency(value, options?)  - Currency: 42.50 → "forty-two dollars and fifty cents"
+ *
+ * New Zealand English conventions:
+ * - Follows British English style
  * - "and" after hundreds: "one hundred and twenty-three"
+ * - "and" before final segment: "one million and one"
  * - Hyphenated tens-ones: "twenty-one", "forty-two"
- * - "and" before final segment when following scale word
- * - BigInt modulo for efficient segment extraction
+ * - Western numbering system (short scale: billion = 10^9)
+ * - Currency: New Zealand Dollar (NZD) - dollar/dollars, cent/cents
  */
 
-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'
+import { validateOptions } from './utils/validate-options.js'
 
 // ============================================================================
 // Vocabulary (module-level constants)
@@ -21,13 +30,30 @@ const ONES = ['', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight'
 const TEENS = ['ten', 'eleven', 'twelve', 'thirteen', 'fourteen', 'fifteen', 'sixteen', 'seventeen', 'eighteen', 'nineteen']
 const TENS = ['', '', 'twenty', 'thirty', 'forty', 'fifty', 'sixty', 'seventy', 'eighty', 'ninety']
 
-const SCALES = ['thousand', 'million', 'billion', 'trillion', 'quadrillion', 'quintillion', 'sextillion', 'septillion', 'octillion']
+const SCALES = [
+  'thousand', 'million', 'billion', 'trillion', 'quadrillion',
+  'quintillion', 'sextillion', 'septillion', 'octillion', 'nonillion',
+  'decillion', 'undecillion', 'duodecillion', 'tredecillion', 'quattuordecillion',
+  'quindecillion', 'sexdecillion', 'septendecillion', 'octodecillion', 'novemdecillion',
+  'vigintillion'
+]
 
 const HUNDRED = 'hundred'
 const ZERO = 'zero'
 const NEGATIVE = 'minus'
 const DECIMAL_SEP = 'point'
 
+// Ordinal vocabulary
+const ORDINAL_ONES = ['', 'first', 'second', 'third', 'fourth', 'fifth', 'sixth', 'seventh', 'eighth', 'ninth']
+const ORDINAL_TEENS = ['tenth', 'eleventh', 'twelfth', 'thirteenth', 'fourteenth', 'fifteenth', 'sixteenth', 'seventeenth', 'eighteenth', 'nineteenth']
+const ORDINAL_TENS = ['', '', 'twentieth', 'thirtieth', 'fortieth', 'fiftieth', 'sixtieth', 'seventieth', 'eightieth', 'ninetieth']
+
+// Currency vocabulary (New Zealand Dollar)
+const DOLLAR = 'dollar'
+const DOLLARS = 'dollars'
+const CENT = 'cent'
+const CENTS = 'cents'
+
 // ============================================================================
 // Segment Building
 // ============================================================================
@@ -118,14 +144,11 @@ function integerToWords (n) {
 
 /**
  * Builds words for numbers >= 1,000,000.
- * Uses BigInt division for faster segment extraction.
  *
  * @param {bigint} n - Number >= 1,000,000
  * @returns {string} English words
  */
 function buildLargeNumberWords (n) {
-  // Extract segments using BigInt division
-  // Segments are stored least-significant first (index 0 = ones, 1 = thousands, etc.)
   const segments = []
   let temp = n
   while (temp > 0n) {
@@ -133,7 +156,6 @@ function buildLargeNumberWords (n) {
     temp = temp / 1000n
   }
 
-  // Find the first (smallest index) non-zero segment - this is processed last
   let firstNonZeroIdx = -1
   for (let i = 0; i < segments.length; i++) {
     if (segments[i] !== 0) {
@@ -142,7 +164,6 @@ function buildLargeNumberWords (n) {
     }
   }
 
-  // Build result string (process from most-significant to least)
   let result = ''
   let prevWasScale = false
 
@@ -153,16 +174,13 @@ function buildLargeNumberWords (n) {
     const { word, hasHundred } = buildSegment(segment)
     const isLastSegment = (i === firstNonZeroIdx)
 
-    // Add "and" only before FINAL segment if it follows scale and doesn't have hundred
     if (result && isLastSegment && prevWasScale && !hasHundred) {
       result += ' and'
     }
 
-    // Add segment word
     if (result) result += ' '
     result += word
 
-    // Add scale word (i=0 is units, i=1 is thousands, etc.)
     if (i > 0) {
       result += ' ' + SCALES[i - 1]
       prevWasScale = true
@@ -183,7 +201,6 @@ function buildLargeNumberWords (n) {
 function decimalPartToWords (decimalPart) {
   let result = ''
 
-  // Handle leading zeros
   let i = 0
   while (i < decimalPart.length && decimalPart[i] === '0') {
     if (result) result += ' '
@@ -191,7 +208,6 @@ function decimalPartToWords (decimalPart) {
     i++
   }
 
-  // Convert remainder as a single number
   const remainder = decimalPart.slice(i)
   if (remainder) {
     if (result) result += ' '
@@ -202,23 +218,15 @@ function decimalPartToWords (decimalPart) {
 }
 
 /**
- * Converts a numeric value to English words.
- *
- * This is the main public API. It accepts any valid numeric input
- * (number, string, or bigint) and handles parsing internally.
+ * Converts a numeric value to New Zealand English words.
  *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in English words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
- * @example
- * toWords(42)           // 'forty-two'
- * toWords(-3.14)        // 'minus three point one four'
- * toWords('1000000')    // 'one million'
  */
-function toWords (value) {
-  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+function toCardinal (value) {
+  const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
 
   let result = ''
 
@@ -236,7 +244,132 @@ function toWords (value) {
 }
 
 // ============================================================================
-// Public API
+// ORDINAL
+// ============================================================================
+
+function buildOrdinalSegment (n) {
+  const ones = n % 10
+  const tens = Math.trunc(n / 10) % 10
+  const hundreds = Math.trunc(n / 100)
+
+  let tensOnesOrdinal = ''
+  if (tens === 1) {
+    tensOnesOrdinal = ORDINAL_TEENS[ones]
+  } else if (tens >= 2) {
+    if (ones > 0) {
+      tensOnesOrdinal = TENS[tens] + '-' + ORDINAL_ONES[ones]
+    } else {
+      tensOnesOrdinal = ORDINAL_TENS[tens]
+    }
+  } else if (ones > 0) {
+    tensOnesOrdinal = ORDINAL_ONES[ones]
+  }
+
+  if (hundreds > 0) {
+    if (tensOnesOrdinal) {
+      return ONES[hundreds] + ' ' + HUNDRED + ' ' + tensOnesOrdinal
+    } else {
+      return ONES[hundreds] + ' hundredth'
+    }
+  }
+
+  return tensOnesOrdinal
+}
+
+function integerToOrdinal (n) {
+  if (n < 1000n) {
+    return buildOrdinalSegment(Number(n))
+  }
+
+  if (n < 1_000_000n) {
+    const thousands = Number(n / 1000n)
+    const remainder = Number(n % 1000n)
+
+    if (remainder === 0) {
+      return buildSegment(thousands).word + ' ' + SCALES[0] + 'th'
+    }
+
+    const { word: thousandsWord } = buildSegment(thousands)
+    return thousandsWord + ' ' + SCALES[0] + ' ' + buildOrdinalSegment(remainder)
+  }
+
+  return buildLargeOrdinal(n)
+}
+
+function buildLargeOrdinal (n) {
+  const segments = []
+  let temp = n
+  while (temp > 0n) {
+    segments.push(Number(temp % 1000n))
+    temp = temp / 1000n
+  }
+
+  let lowestNonZeroIdx = 0
+  for (let i = 0; i < segments.length; i++) {
+    if (segments[i] !== 0) {
+      lowestNonZeroIdx = i
+      break
+    }
+  }
+
+  let result = ''
+
+  for (let i = segments.length - 1; i >= 0; i--) {
+    const segment = segments[i]
+    if (segment === 0) continue
+
+    const isLowestSegment = (i === lowestNonZeroIdx)
+
+    if (result) result += ' '
+
+    if (isLowestSegment) {
+      if (i === 0) {
+        result += buildOrdinalSegment(segment)
+      } else {
+        result += buildSegment(segment).word + ' ' + SCALES[i - 1] + 'th'
+      }
+    } else {
+      result += buildSegment(segment).word
+      if (i > 0) {
+        result += ' ' + SCALES[i - 1]
+      }
+    }
+  }
+
+  return result
+}
+
+function toOrdinal (value) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY
 // ============================================================================
 
-export { toWords }
+function toCurrency (value, options) {
+  options = validateOptions(options)
+  const { isNegative, dollars, cents } = parseCurrencyValue(value)
+  const { and: useAnd = true } = options
+
+  let result = ''
+  if (isNegative) result = NEGATIVE + ' '
+
+  if (dollars > 0n || cents === 0n) {
+    result += integerToWords(dollars)
+    result += ' ' + (dollars === 1n ? DOLLAR : DOLLARS)
+  }
+
+  if (cents > 0n) {
+    if (dollars > 0n) {
+      result += useAnd ? ' and ' : ' '
+    }
+    result += integerToWords(cents)
+    result += ' ' + (cents === 1n ? CENT : CENTS)
+  }
+
+  return result
+}
+
+export { toCardinal, toOrdinal, toCurrency }

package/src/en-PH.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Converts a numeric value to Philippine English words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in English words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ */
+export function toCardinal(value: number | string | bigint): string;
+export function toOrdinal(value: any): string;
+export function toCurrency(value: any, options: any): string;

package/src/en-PH.js

@@ -0,0 +1,345 @@
+/**
+ * Philippine English language converter
+ *
+ * CLDR: en-PH | English as used in the Philippines
+ *
+ * Exports:
+ * - toCardinal(value)            - Cardinal numbers: 42 → "forty-two"
+ * - toOrdinal(value)             - Ordinal numbers: 42 → "forty-second"
+ * - toCurrency(value, options?)  - Currency: 42.50 → "forty-two pesos and fifty centavos"
+ *
+ * Philippine English conventions:
+ * - Follows British English style
+ * - "and" after hundreds: "one hundred and twenty-three"
+ * - "and" before final segment: "one million and one"
+ * - Hyphenated tens-ones: "twenty-one", "forty-two"
+ * - Western numbering system (short scale: billion = 10^9)
+ * - Currency: Philippine Peso (PHP) - peso/pesos, centavo/centavos
+ */
+
+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)
+// ============================================================================
+
+const ONES = ['', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine']
+const TEENS = ['ten', 'eleven', 'twelve', 'thirteen', 'fourteen', 'fifteen', 'sixteen', 'seventeen', 'eighteen', 'nineteen']
+const TENS = ['', '', 'twenty', 'thirty', 'forty', 'fifty', 'sixty', 'seventy', 'eighty', 'ninety']
+
+const SCALES = [
+  'thousand', 'million', 'billion', 'trillion', 'quadrillion',
+  'quintillion', 'sextillion', 'septillion', 'octillion', 'nonillion',
+  'decillion', 'undecillion', 'duodecillion', 'tredecillion', 'quattuordecillion',
+  'quindecillion', 'sexdecillion', 'septendecillion', 'octodecillion', 'novemdecillion',
+  'vigintillion'
+]
+
+const HUNDRED = 'hundred'
+const ZERO = 'zero'
+const NEGATIVE = 'minus'
+const DECIMAL_SEP = 'point'
+
+// Ordinal vocabulary
+const ORDINAL_ONES = ['', 'first', 'second', 'third', 'fourth', 'fifth', 'sixth', 'seventh', 'eighth', 'ninth']
+const ORDINAL_TEENS = ['tenth', 'eleventh', 'twelfth', 'thirteenth', 'fourteenth', 'fifteenth', 'sixteenth', 'seventeenth', 'eighteenth', 'nineteenth']
+const ORDINAL_TENS = ['', '', 'twentieth', 'thirtieth', 'fortieth', 'fiftieth', 'sixtieth', 'seventieth', 'eightieth', 'ninetieth']
+
+// Currency vocabulary (Philippine Peso)
+const PESO = 'peso'
+const PESOS = 'pesos'
+const CENTAVO = 'centavo'
+const CENTAVOS = 'centavos'
+
+// ============================================================================
+// Segment Building
+// ============================================================================
+
+const segmentResult = { word: '', hasHundred: false }
+
+function buildSegment (n) {
+  if (n === 0) {
+    segmentResult.word = ''
+    segmentResult.hasHundred = false
+    return segmentResult
+  }
+
+  const ones = n % 10
+  const tens = Math.trunc(n / 10) % 10
+  const hundreds = Math.trunc(n / 100)
+
+  let tensOnes = ''
+  if (tens === 1) {
+    tensOnes = TEENS[ones]
+  } else if (tens >= 2) {
+    tensOnes = ones > 0 ? TENS[tens] + '-' + ONES[ones] : TENS[tens]
+  } else if (ones > 0) {
+    tensOnes = ONES[ones]
+  }
+
+  if (hundreds > 0) {
+    if (tensOnes) {
+      segmentResult.word = ONES[hundreds] + ' ' + HUNDRED + ' and ' + tensOnes
+    } else {
+      segmentResult.word = ONES[hundreds] + ' ' + HUNDRED
+    }
+    segmentResult.hasHundred = true
+  } else {
+    segmentResult.word = tensOnes
+    segmentResult.hasHundred = false
+  }
+
+  return segmentResult
+}
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+function integerToWords (n) {
+  if (n === 0n) return ZERO
+
+  if (n < 1000n) {
+    return buildSegment(Number(n)).word
+  }
+
+  if (n < 1_000_000n) {
+    const thousands = Number(n / 1000n)
+    const remainder = Number(n % 1000n)
+
+    const { word: thousandsWord } = buildSegment(thousands)
+    let result = thousandsWord + ' ' + SCALES[0]
+
+    if (remainder > 0) {
+      const { word: remainderWord, hasHundred } = buildSegment(remainder)
+      result += hasHundred ? ' ' + remainderWord : ' and ' + remainderWord
+    }
+
+    return result
+  }
+
+  return buildLargeNumberWords(n)
+}
+
+function buildLargeNumberWords (n) {
+  const segments = []
+  let temp = n
+  while (temp > 0n) {
+    segments.push(Number(temp % 1000n))
+    temp = temp / 1000n
+  }
+
+  let firstNonZeroIdx = -1
+  for (let i = 0; i < segments.length; i++) {
+    if (segments[i] !== 0) {
+      firstNonZeroIdx = i
+      break
+    }
+  }
+
+  let result = ''
+  let prevWasScale = false
+
+  for (let i = segments.length - 1; i >= 0; i--) {
+    const segment = segments[i]
+    if (segment === 0) continue
+
+    const { word, hasHundred } = buildSegment(segment)
+    const isLastSegment = (i === firstNonZeroIdx)
+
+    if (result && isLastSegment && prevWasScale && !hasHundred) {
+      result += ' and'
+    }
+
+    if (result) result += ' '
+    result += word
+
+    if (i > 0) {
+      result += ' ' + SCALES[i - 1]
+      prevWasScale = true
+    } else {
+      prevWasScale = false
+    }
+  }
+
+  return result
+}
+
+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 Philippine English words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in English words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ */
+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
+// ============================================================================
+
+function buildOrdinalSegment (n) {
+  const ones = n % 10
+  const tens = Math.trunc(n / 10) % 10
+  const hundreds = Math.trunc(n / 100)
+
+  let tensOnesOrdinal = ''
+  if (tens === 1) {
+    tensOnesOrdinal = ORDINAL_TEENS[ones]
+  } else if (tens >= 2) {
+    if (ones > 0) {
+      tensOnesOrdinal = TENS[tens] + '-' + ORDINAL_ONES[ones]
+    } else {
+      tensOnesOrdinal = ORDINAL_TENS[tens]
+    }
+  } else if (ones > 0) {
+    tensOnesOrdinal = ORDINAL_ONES[ones]
+  }
+
+  if (hundreds > 0) {
+    if (tensOnesOrdinal) {
+      return ONES[hundreds] + ' ' + HUNDRED + ' ' + tensOnesOrdinal
+    } else {
+      return ONES[hundreds] + ' hundredth'
+    }
+  }
+
+  return tensOnesOrdinal
+}
+
+function integerToOrdinal (n) {
+  if (n < 1000n) {
+    return buildOrdinalSegment(Number(n))
+  }
+
+  if (n < 1_000_000n) {
+    const thousands = Number(n / 1000n)
+    const remainder = Number(n % 1000n)
+
+    if (remainder === 0) {
+      return buildSegment(thousands).word + ' ' + SCALES[0] + 'th'
+    }
+
+    const { word: thousandsWord } = buildSegment(thousands)
+    return thousandsWord + ' ' + SCALES[0] + ' ' + buildOrdinalSegment(remainder)
+  }
+
+  return buildLargeOrdinal(n)
+}
+
+function buildLargeOrdinal (n) {
+  const segments = []
+  let temp = n
+  while (temp > 0n) {
+    segments.push(Number(temp % 1000n))
+    temp = temp / 1000n
+  }
+
+  let lowestNonZeroIdx = 0
+  for (let i = 0; i < segments.length; i++) {
+    if (segments[i] !== 0) {
+      lowestNonZeroIdx = i
+      break
+    }
+  }
+
+  let result = ''
+
+  for (let i = segments.length - 1; i >= 0; i--) {
+    const segment = segments[i]
+    if (segment === 0) continue
+
+    const isLowestSegment = (i === lowestNonZeroIdx)
+
+    if (result) result += ' '
+
+    if (isLowestSegment) {
+      if (i === 0) {
+        result += buildOrdinalSegment(segment)
+      } else {
+        result += buildSegment(segment).word + ' ' + SCALES[i - 1] + 'th'
+      }
+    } else {
+      result += buildSegment(segment).word
+      if (i > 0) {
+        result += ' ' + SCALES[i - 1]
+      }
+    }
+  }
+
+  return result
+}
+
+function toOrdinal (value) {
+  const integerPart = parseOrdinalValue(value)
+  return integerToOrdinal(integerPart)
+}
+
+// ============================================================================
+// CURRENCY
+// ============================================================================
+
+function toCurrency (value, options) {
+  options = validateOptions(options)
+  const { isNegative, dollars: pesos, cents: centavos } = parseCurrencyValue(value)
+  const { and: useAnd = true } = options
+
+  let result = ''
+  if (isNegative) result = NEGATIVE + ' '
+
+  if (pesos > 0n || centavos === 0n) {
+    result += integerToWords(pesos)
+    result += ' ' + (pesos === 1n ? PESO : PESOS)
+  }
+
+  if (centavos > 0n) {
+    if (pesos > 0n) {
+      result += useAnd ? ' and ' : ' '
+    }
+    result += integerToWords(centavos)
+    result += ' ' + (centavos === 1n ? CENTAVO : CENTAVOS)
+  }
+
+  return result
+}
+
+export { toCardinal, toOrdinal, toCurrency }

package/src/en-PK.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Converts a numeric value to English words using Indian numbering.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in English words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toCardinal(42)           // 'forty-two'
+ * toCardinal(100000)       // 'one lakh'
+ * toCardinal(10000000)     // 'one crore'
+ * toCardinal(1234567)      // 'twelve lakh thirty-four thousand five hundred and sixty-seven'
+ */
+export function toCardinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to English ordinal words using Indian numbering.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert (must be a 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)       // 'first'
+ * toOrdinal(100000)  // 'one lakhth'
+ * toOrdinal(100001)  // 'one lakh first'
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Pakistani English currency words.
+ *
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @param {Object} [options] - Optional configuration
+ * @param {boolean} [options.and=true] - Use "and" between rupees and paise
+ * @returns {string} The amount in Pakistani English 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)                    // 'forty-two rupees and fifty paise'
+ * toCurrency(100000)                   // 'one lakh rupees'
+ * toCurrency(1)                        // 'one rupee'
+ * toCurrency(0.50)                     // 'fifty paise'
+ * toCurrency(42.50, { and: false })    // 'forty-two rupees fifty paise'
+ */
+export function toCurrency(value: number | string | bigint, options?: {
+    and?: boolean | undefined;
+}): string;