n2words 4.0.0 → 5.1.0

package/src/en-PH.js

@@ -20,7 +20,9 @@
 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'
+import { checkMax } from './utils/check-max.js'
+import { western } from './utils/scale.js'
+import { resolveOptions } from './utils/resolve-options.js'
 
 // ============================================================================
 // Vocabulary (module-level constants)
@@ -35,9 +37,13 @@ const SCALES = [
   'quintillion', 'sextillion', 'septillion', 'octillion', 'nonillion',
   'decillion', 'undecillion', 'duodecillion', 'tredecillion', 'quattuordecillion',
   'quindecillion', 'sexdecillion', 'septendecillion', 'octodecillion', 'novemdecillion',
-  'vigintillion'
+  'vigintillion',
 ]
 
+export const cardinalMax = western(SCALES.length)
+export const ordinalMax = western(SCALES.length)
+export const currencyMax = western(SCALES.length)
+
 const HUNDRED = 'hundred'
 const ZERO = 'zero'
 const NEGATIVE = 'minus'
@@ -60,7 +66,11 @@ const CENTAVOS = 'centavos'
 
 const segmentResult = { word: '', hasHundred: false }
 
-function buildSegment (n) {
+/**
+ * @param {number} n The 0-999 segment value to convert.
+ * @returns {{word: string, hasHundred: boolean}} The segment words and whether it includes a hundreds place.
+ */
+function buildSegment(n) {
   if (n === 0) {
     segmentResult.word = ''
     segmentResult.hasHundred = false
@@ -74,20 +84,24 @@ function buildSegment (n) {
   let tensOnes = ''
   if (tens === 1) {
     tensOnes = TEENS[ones]
-  } else if (tens >= 2) {
+  }
+  else if (tens >= 2) {
     tensOnes = ones > 0 ? TENS[tens] + '-' + ONES[ones] : TENS[tens]
-  } else if (ones > 0) {
+  }
+  else if (ones > 0) {
     tensOnes = ONES[ones]
   }
 
   if (hundreds > 0) {
     if (tensOnes) {
       segmentResult.word = ONES[hundreds] + ' ' + HUNDRED + ' and ' + tensOnes
-    } else {
+    }
+    else {
       segmentResult.word = ONES[hundreds] + ' ' + HUNDRED
     }
     segmentResult.hasHundred = true
-  } else {
+  }
+  else {
     segmentResult.word = tensOnes
     segmentResult.hasHundred = false
   }
@@ -99,7 +113,11 @@ function buildSegment (n) {
 // Conversion Functions
 // ============================================================================
 
-function integerToWords (n) {
+/**
+ * @param {bigint} n The non-negative integer to convert.
+ * @returns {string} The integer in English words.
+ */
+function integerToWords(n) {
   if (n === 0n) return ZERO
 
   if (n < 1000n) {
@@ -124,7 +142,11 @@ function integerToWords (n) {
   return buildLargeNumberWords(n)
 }
 
-function buildLargeNumberWords (n) {
+/**
+ * @param {bigint} n The integer of one million or greater to convert.
+ * @returns {string} The integer in English words.
+ */
+function buildLargeNumberWords(n) {
   const segments = []
   let temp = n
   while (temp > 0n) {
@@ -160,7 +182,8 @@ function buildLargeNumberWords (n) {
     if (i > 0) {
       result += ' ' + SCALES[i - 1]
       prevWasScale = true
-    } else {
+    }
+    else {
       prevWasScale = false
     }
   }
@@ -168,7 +191,11 @@ function buildLargeNumberWords (n) {
   return result
 }
 
-function decimalPartToWords (decimalPart) {
+/**
+ * @param {string} decimalPart The fractional digits to convert.
+ * @returns {string} The decimal digits in English words.
+ */
+function decimalPartToWords(decimalPart) {
   let result = ''
 
   let i = 0
@@ -189,14 +216,16 @@ function decimalPartToWords (decimalPart) {
 
 /**
  * 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) {
+function toCardinal(value) {
   const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
+  // Both the integer part and the decimal's significant digits are spelled via
+  // the scale builder, so both must clear the ceiling.
+  checkMax(integerPart, cardinalMax, decimalPart)
 
   let result = ''
 
@@ -217,7 +246,11 @@ function toCardinal (value) {
 // ORDINAL
 // ============================================================================
 
-function buildOrdinalSegment (n) {
+/**
+ * @param {number} n The 0-999 segment value to convert.
+ * @returns {string} The segment as ordinal words.
+ */
+function buildOrdinalSegment(n) {
   const ones = n % 10
   const tens = Math.trunc(n / 10) % 10
   const hundreds = Math.trunc(n / 100)
@@ -225,20 +258,24 @@ function buildOrdinalSegment (n) {
   let tensOnesOrdinal = ''
   if (tens === 1) {
     tensOnesOrdinal = ORDINAL_TEENS[ones]
-  } else if (tens >= 2) {
+  }
+  else if (tens >= 2) {
     if (ones > 0) {
       tensOnesOrdinal = TENS[tens] + '-' + ORDINAL_ONES[ones]
-    } else {
+    }
+    else {
       tensOnesOrdinal = ORDINAL_TENS[tens]
     }
-  } else if (ones > 0) {
+  }
+  else if (ones > 0) {
     tensOnesOrdinal = ORDINAL_ONES[ones]
   }
 
   if (hundreds > 0) {
     if (tensOnesOrdinal) {
       return ONES[hundreds] + ' ' + HUNDRED + ' ' + tensOnesOrdinal
-    } else {
+    }
+    else {
       return ONES[hundreds] + ' hundredth'
     }
   }
@@ -246,7 +283,11 @@ function buildOrdinalSegment (n) {
   return tensOnesOrdinal
 }
 
-function integerToOrdinal (n) {
+/**
+ * @param {bigint} n The positive integer to convert.
+ * @returns {string} The integer as ordinal words.
+ */
+function integerToOrdinal(n) {
   if (n < 1000n) {
     return buildOrdinalSegment(Number(n))
   }
@@ -266,7 +307,11 @@ function integerToOrdinal (n) {
   return buildLargeOrdinal(n)
 }
 
-function buildLargeOrdinal (n) {
+/**
+ * @param {bigint} n The integer of one million or greater to convert.
+ * @returns {string} The integer as ordinal words.
+ */
+function buildLargeOrdinal(n) {
   const segments = []
   let temp = n
   while (temp > 0n) {
@@ -295,10 +340,12 @@ function buildLargeOrdinal (n) {
     if (isLowestSegment) {
       if (i === 0) {
         result += buildOrdinalSegment(segment)
-      } else {
+      }
+      else {
         result += buildSegment(segment).word + ' ' + SCALES[i - 1] + 'th'
       }
-    } else {
+    }
+    else {
       result += buildSegment(segment).word
       if (i > 0) {
         result += ' ' + SCALES[i - 1]
@@ -309,8 +356,16 @@ function buildLargeOrdinal (n) {
   return result
 }
 
-function toOrdinal (value) {
+/**
+ * Converts a numeric value to Philippine English ordinal words.
+ * @param {number | string | bigint} value - The numeric value to convert (must be a positive integer)
+ * @returns {string} The number as ordinal words (e.g., "first", "forty-second")
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {RangeError} If value is negative, zero, or has a decimal part
+ */
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
+  checkMax(integerPart, ordinalMax)
   return integerToOrdinal(integerPart)
 }
 
@@ -318,10 +373,26 @@ function toOrdinal (value) {
 // CURRENCY
 // ============================================================================
 
-function toCurrency (value, options) {
-  options = validateOptions(options)
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [and] - Use "and" between pesos and centavos
+ */
+
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults = { and: true }
+
+/**
+ * Converts a numeric value to Philippine English currency words.
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @param {CurrencyOptions} [options] - Optional configuration
+ * @returns {string} The amount in Philippine English currency words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ */
+function toCurrency(value, options) {
   const { isNegative, dollars: pesos, cents: centavos } = parseCurrencyValue(value)
-  const { and: useAnd = true } = options
+  checkMax(pesos, currencyMax)
+  const { and: useAnd } = resolveOptions(options, currencyDefaults)
 
   let result = ''
   if (isNegative) result = NEGATIVE + ' '

package/src/en-PK.d.ts

@@ -1,11 +1,24 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [and] - Use "and" between rupees and paise
+ */
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults: Required<CurrencyOptions>;
+export type CurrencyOptions = {
+    /**
+     * - Use "and" between rupees and paise
+     */
+    and?: boolean | undefined;
+};
 /**
  * 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'
@@ -15,12 +28,10 @@
 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'
@@ -29,14 +40,11 @@ export function toCardinal(value: number | string | bigint): string;
 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
+ * @param {CurrencyOptions} [options] - Optional configuration
  * @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'
@@ -44,6 +52,4 @@ export function toOrdinal(value: number | string | bigint): string;
  * 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;
+export function toCurrency(value: number | string | bigint, options?: CurrencyOptions): string;

package/src/en-PK.js

@@ -13,7 +13,9 @@
 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'
+import { checkMax } from './utils/check-max.js'
+import { indian } from './utils/scale.js'
+import { resolveOptions } from './utils/resolve-options.js'
 
 // ============================================================================
 // Vocabulary (module-level constants)
@@ -26,6 +28,11 @@ const TENS = ['', '', 'twenty', 'thirty', 'forty', 'fifty', 'sixty', 'seventy',
 // Indian numbering scales: 10^3, 10^5, 10^7, 10^9, 10^11, 10^13, 10^15, 10^17
 const SCALES = ['thousand', 'lakh', 'crore', 'arab', 'kharab', 'neel', 'padma', 'shankh']
 
+// 3-2-2 grouping: a 3-digit base segment then 2 digits per Indian scale word.
+export const cardinalMax = indian(SCALES.length + 1)
+export const ordinalMax = indian(SCALES.length + 1)
+export const currencyMax = indian(SCALES.length + 1)
+
 const HUNDRED = 'hundred'
 const ZERO = 'zero'
 const NEGATIVE = 'minus'
@@ -51,11 +58,10 @@ const segmentResult = { word: '', hasHundred: false }
 
 /**
  * Builds words for a 0-999 segment (British-style with "and" after hundreds).
- *
  * @param {number} n - Number 0-999
- * @returns {{ word: string, hasHundred: boolean }}
+ * @returns {{ word: string, hasHundred: boolean }} The segment words and whether it includes a hundreds place
  */
-function buildSegment (n) {
+function buildSegment(n) {
   if (n === 0) {
     segmentResult.word = ''
     segmentResult.hasHundred = false
@@ -70,9 +76,11 @@ function buildSegment (n) {
   let tensOnes = ''
   if (tens === 1) {
     tensOnes = TEENS[ones]
-  } else if (tens >= 2) {
+  }
+  else if (tens >= 2) {
     tensOnes = ones > 0 ? TENS[tens] + '-' + ONES[ones] : TENS[tens]
-  } else if (ones > 0) {
+  }
+  else if (ones > 0) {
     tensOnes = ONES[ones]
   }
 
@@ -80,11 +88,13 @@ function buildSegment (n) {
   if (hundreds > 0) {
     if (tensOnes) {
       segmentResult.word = ONES[hundreds] + ' ' + HUNDRED + ' and ' + tensOnes
-    } else {
+    }
+    else {
       segmentResult.word = ONES[hundreds] + ' ' + HUNDRED
     }
     segmentResult.hasHundred = true
-  } else {
+  }
+  else {
     segmentResult.word = tensOnes
     segmentResult.hasHundred = false
   }
@@ -94,11 +104,10 @@ function buildSegment (n) {
 
 /**
  * Builds words for a 0-99 segment (no hundreds).
- *
  * @param {number} n - Number 0-99
- * @returns {string}
+ * @returns {string} The number in words
  */
-function buildSmallSegment (n) {
+function buildSmallSegment(n) {
   if (n === 0) return ''
 
   const ones = n % 10
@@ -106,7 +115,8 @@ function buildSmallSegment (n) {
 
   if (tens === 1) {
     return TEENS[ones]
-  } else if (tens >= 2) {
+  }
+  else if (tens >= 2) {
     return ones > 0 ? TENS[tens] + '-' + ONES[ones] : TENS[tens]
   }
   return ONES[ones]
@@ -121,11 +131,10 @@ function buildSmallSegment (n) {
  *
  * Uses BigInt modulo for segment extraction.
  * South Asian 3-2-2 grouping: first 3 digits, then groups of 2.
- *
  * @param {bigint} n - Non-negative integer to convert
  * @returns {string} English words
  */
-function integerToWords (n) {
+function integerToWords(n) {
   if (n === 0n) return ZERO
 
   // Fast path: numbers < 1000
@@ -162,7 +171,8 @@ function integerToWords (n) {
         words.push('and')
       }
       words.push(word)
-    } else {
+    }
+    else {
       // Other segments are 0-99
       words.push(buildSmallSegment(segment))
       // Add scale word
@@ -177,11 +187,10 @@ function integerToWords (n) {
 
 /**
  * Converts decimal digits to English words.
- *
  * @param {string} decimalPart - Decimal digits (without the point)
  * @returns {string} English words for decimal part
  */
-function decimalPartToWords (decimalPart) {
+function decimalPartToWords(decimalPart) {
   let result = ''
 
   // Handle leading zeros
@@ -204,20 +213,21 @@ function decimalPartToWords (decimalPart) {
 
 /**
  * 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'
  */
-function toCardinal (value) {
+function toCardinal(value) {
   const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
+  // Both the integer part and the decimal's significant digits are spelled via
+  // the scale builder, so both must clear the ceiling.
+  checkMax(integerPart, cardinalMax, decimalPart)
 
   let result = ''
 
@@ -240,11 +250,10 @@ function toCardinal (value) {
 
 /**
  * Builds ordinal words for a 0-999 segment (final segment only).
- *
  * @param {number} n - Number 0-999
  * @returns {string} Ordinal words for this segment
  */
-function buildOrdinalSegment (n) {
+function buildOrdinalSegment(n) {
   const ones = n % 10
   const tens = Math.trunc(n / 10) % 10
   const hundreds = Math.trunc(n / 100)
@@ -253,13 +262,16 @@ function buildOrdinalSegment (n) {
   let tensOnesOrdinal = ''
   if (tens === 1) {
     tensOnesOrdinal = ORDINAL_TEENS[ones]
-  } else if (tens >= 2) {
+  }
+  else if (tens >= 2) {
     if (ones > 0) {
       tensOnesOrdinal = TENS[tens] + '-' + ORDINAL_ONES[ones]
-    } else {
+    }
+    else {
       tensOnesOrdinal = ORDINAL_TENS[tens]
     }
-  } else if (ones > 0) {
+  }
+  else if (ones > 0) {
     tensOnesOrdinal = ORDINAL_ONES[ones]
   }
 
@@ -267,7 +279,8 @@ function buildOrdinalSegment (n) {
   if (hundreds > 0) {
     if (tensOnesOrdinal) {
       return ONES[hundreds] + ' ' + HUNDRED + ' ' + tensOnesOrdinal
-    } else {
+    }
+    else {
       return ONES[hundreds] + ' hundredth'
     }
   }
@@ -277,11 +290,10 @@ function buildOrdinalSegment (n) {
 
 /**
  * Converts a positive integer to ordinal words using Indian numbering.
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Ordinal English words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   // Fast path: numbers < 1000
   if (n < 1000n) {
     return buildOrdinalSegment(Number(n))
@@ -323,16 +335,19 @@ function integerToOrdinal (n) {
       if (i === 0) {
         // Units position: use ordinal segment
         words.push(buildOrdinalSegment(segment))
-      } else {
+      }
+      else {
         // Scale position with no remainder below: "one lakhth"
         words.push(buildSmallSegment(segment))
         words.push(SCALES[i - 1] + 'th')
       }
-    } else {
+    }
+    else {
       // Non-final segments are cardinal
       if (i === 0) {
         words.push(buildSegment(segment).word)
-      } else {
+      }
+      else {
         words.push(buildSmallSegment(segment))
         words.push(SCALES[i - 1])
       }
@@ -344,19 +359,18 @@ function integerToOrdinal (n) {
 
 /**
  * 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'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
+  checkMax(integerPart, ordinalMax)
   return integerToOrdinal(integerPart)
 }
 
@@ -364,16 +378,21 @@ function toOrdinal (value) {
 // CURRENCY: toCurrency(value, options?)
 // ============================================================================
 
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [and] - Use "and" between rupees and paise
+ */
+
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults = { and: true }
+
 /**
  * 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
+ * @param {CurrencyOptions} [options] - Optional configuration
  * @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'
@@ -381,10 +400,10 @@ function toOrdinal (value) {
  * toCurrency(0.50)                     // 'fifty paise'
  * toCurrency(42.50, { and: false })    // 'forty-two rupees fifty paise'
  */
-function toCurrency (value, options) {
-  options = validateOptions(options)
+function toCurrency(value, options) {
   const { isNegative, dollars: rupees, cents: paise } = parseCurrencyValue(value)
-  const { and: useAnd = true } = options
+  checkMax(rupees, currencyMax)
+  const { and: useAnd } = resolveOptions(options, currencyDefaults)
 
   // Build result
   let result = ''

package/src/en-SG.d.ts

@@ -1,11 +1,36 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [and] - Use "and" between dollars and cents
+ */
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults: Required<CurrencyOptions>;
+export type CurrencyOptions = {
+    /**
+     * - Use "and" between dollars and cents
+     */
+    and?: boolean | undefined;
+};
 /**
  * Converts a numeric value to Singaporean 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;
+/**
+ * Converts a numeric value to Singaporean English ordinal words.
+ * @param {number | string | bigint} value - The numeric value to convert (must be a positive integer)
+ * @returns {string} The number as ordinal words (e.g., "first", "forty-second")
+ */
+export function toOrdinal(value: number | string | bigint): string;
+/**
+ * Converts a numeric value to Singaporean English currency words.
+ * @param {number | string | bigint} value - The currency amount to convert
+ * @param {CurrencyOptions} [options] - Optional configuration
+ * @returns {string} The amount in Singaporean English currency words
+ */
+export function toCurrency(value: number | string | bigint, options?: CurrencyOptions): string;