n2words 4.0.0 → 5.1.0

package/src/en-CA.d.ts

@@ -1,17 +1,45 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
+/**
+ * @typedef {object} CardinalOptions
+ * @property {boolean} [hundredPairing] - Use hundred-pairing for 1100-9999 (e.g., "fifteen hundred" instead of "one thousand five hundred")
+ * @property {boolean} [and] - Use "and" after hundreds and before final small numbers (default: true, Canadian/British style)
+ */
+/** @type {Required<CardinalOptions>} */
+export const cardinalDefaults: Required<CardinalOptions>;
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [and] - Use "and" between dollars and cents (e.g., "one dollar and fifty cents")
+ */
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults: Required<CurrencyOptions>;
+export type CardinalOptions = {
+    /**
+     * - Use hundred-pairing for 1100-9999 (e.g., "fifteen hundred" instead of "one thousand five hundred")
+     */
+    hundredPairing?: boolean | undefined;
+    /**
+     * - Use "and" after hundreds and before final small numbers (default: true, Canadian/British style)
+     */
+    and?: boolean | undefined;
+};
+export type CurrencyOptions = {
+    /**
+     * - Use "and" between dollars and cents (e.g., "one dollar and fifty cents")
+     */
+    and?: boolean | undefined;
+};
 /**
  * Converts a numeric value to Canadian English 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.hundredPairing=false] - Use hundred-pairing for 1100-9999 (e.g., "fifteen hundred" instead of "one thousand five hundred")
- * @param {boolean} [options.and=true] - Use "and" after hundreds and before final small numbers (default: true, Canadian/British style)
+ * @param {CardinalOptions} [options] - Optional configuration
  * @returns {string} The number in Canadian 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(101)                           // 'one hundred and one'
@@ -19,18 +47,13 @@
  * toCardinal(1500)                          // 'one thousand five hundred'
  * toCardinal(1500, { hundredPairing: true }) // 'fifteen hundred'
  */
-export function toCardinal(value: number | string | bigint, options?: {
-    hundredPairing?: boolean | undefined;
-    and?: boolean | undefined;
-}): string;
+export function toCardinal(value: number | string | bigint, options?: CardinalOptions): string;
 /**
  * Converts a numeric value to Canadian 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
- *
  * @example
  * toOrdinal(1)    // 'first'
  * toOrdinal(2)    // 'second'
@@ -44,20 +67,15 @@ export function toCardinal(value: number | string | bigint, options?: {
 export function toOrdinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Canadian 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 dollars and cents (e.g., "one dollar and fifty cents")
+ * @param {CurrencyOptions} [options] - Optional configuration
  * @returns {string} The amount in Canadian 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 dollars and fifty cents'
  * toCurrency(1)                        // 'one dollar'
  * toCurrency(0.99)                     // 'ninety-nine cents'
  * toCurrency(42.50, { and: false })    // 'forty-two dollars fifty cents'
  */
-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-CA.js

@@ -22,7 +22,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
@@ -37,8 +39,12 @@ 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'
@@ -64,12 +70,11 @@ const segmentResult = { word: '', hasHundred: false }
 
 /**
  * Builds words for a 0-999 segment.
- *
  * @param {number} n - Number 0-999
  * @param {boolean} useAnd - Whether to use "and" after hundreds
- * @returns {{ word: string, hasHundred: boolean }}
+ * @returns {{ word: string, hasHundred: boolean }} The segment words and whether a hundreds place is present
  */
-function buildSegment (n, useAnd) {
+function buildSegment(n, useAnd) {
   if (n === 0) {
     segmentResult.word = ''
     segmentResult.hasHundred = false
@@ -84,9 +89,11 @@ function buildSegment (n, useAnd) {
   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]
   }
 
@@ -95,11 +102,13 @@ function buildSegment (n, useAnd) {
     if (tensOnes) {
       const connector = useAnd ? ' and ' : ' '
       segmentResult.word = ONES[hundreds] + ' ' + HUNDRED + connector + tensOnes
-    } else {
+    }
+    else {
       segmentResult.word = ONES[hundreds] + ' ' + HUNDRED
     }
     segmentResult.hasHundred = true
-  } else {
+  }
+  else {
     segmentResult.word = tensOnes
     segmentResult.hasHundred = false
   }
@@ -113,13 +122,12 @@ function buildSegment (n, useAnd) {
 
 /**
  * Converts a non-negative integer to English words.
- *
  * @param {bigint} n - Non-negative integer to convert
  * @param {boolean} hundredPairing - Use hundred-pairing for 1100-9999
  * @param {boolean} useAnd - Use "and" after hundreds and before final segment
  * @returns {string} English words
  */
-function integerToWords (n, hundredPairing, useAnd) {
+function integerToWords(n, hundredPairing, useAnd) {
   if (n === 0n) return ZERO
 
   // Fast path: numbers < 1000
@@ -175,12 +183,11 @@ function integerToWords (n, hundredPairing, useAnd) {
 /**
  * Builds words for numbers >= 1,000,000.
  * Uses BigInt division for faster segment extraction.
- *
  * @param {bigint} n - Number >= 1,000,000
  * @param {boolean} useAnd - Use "and" after hundreds and before final segment
  * @returns {string} English words
  */
-function buildLargeNumberWords (n, useAnd) {
+function buildLargeNumberWords(n, useAnd) {
   // Extract segments using BigInt division
   // Segments are stored least-significant first (index 0 = ones, 1 = thousands, etc.)
   const segments = []
@@ -225,7 +232,8 @@ function buildLargeNumberWords (n, useAnd) {
     if (i > 0) {
       result += ' ' + SCALES[i - 1]
       prevWasScale = true
-    } else {
+    }
+    else {
       prevWasScale = false
     }
   }
@@ -235,12 +243,11 @@ function buildLargeNumberWords (n, useAnd) {
 
 /**
  * Converts decimal digits to English words.
- *
  * @param {string} decimalPart - Decimal digits (without the point)
  * @param {boolean} useAnd - Use "and" in number conversion
  * @returns {string} English words for decimal part
  */
-function decimalPartToWords (decimalPart, useAnd) {
+function decimalPartToWords(decimalPart, useAnd) {
   let result = ''
 
   // Handle leading zeros
@@ -261,20 +268,25 @@ function decimalPartToWords (decimalPart, useAnd) {
   return result
 }
 
+/**
+ * @typedef {object} CardinalOptions
+ * @property {boolean} [hundredPairing] - Use hundred-pairing for 1100-9999 (e.g., "fifteen hundred" instead of "one thousand five hundred")
+ * @property {boolean} [and] - Use "and" after hundreds and before final small numbers (default: true, Canadian/British style)
+ */
+
+/** @type {Required<CardinalOptions>} */
+export const cardinalDefaults = { hundredPairing: false, and: true }
+
 /**
  * Converts a numeric value to Canadian English 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.hundredPairing=false] - Use hundred-pairing for 1100-9999 (e.g., "fifteen hundred" instead of "one thousand five hundred")
- * @param {boolean} [options.and=true] - Use "and" after hundreds and before final small numbers (default: true, Canadian/British style)
+ * @param {CardinalOptions} [options] - Optional configuration
  * @returns {string} The number in Canadian 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(101)                           // 'one hundred and one'
@@ -282,12 +294,14 @@ function decimalPartToWords (decimalPart, useAnd) {
  * toCardinal(1500)                          // 'one thousand five hundred'
  * toCardinal(1500, { hundredPairing: true }) // 'fifteen hundred'
  */
-function toCardinal (value, options) {
-  options = validateOptions(options)
+function toCardinal(value, options) {
   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)
 
   // Extract options with defaults (Canadian English uses "and" like British English)
-  const { hundredPairing = false, and: useAnd = true } = options
+  const { hundredPairing, and: useAnd } = resolveOptions(options, cardinalDefaults)
 
   let result = ''
 
@@ -311,11 +325,10 @@ function toCardinal (value, options) {
 /**
  * Builds ordinal words for a 0-999 segment (final segment only).
  * Returns ordinal form: "first", "twenty-third", "one hundred forty-fifth"
- *
  * @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)
@@ -325,15 +338,18 @@ function buildOrdinalSegment (n) {
   if (tens === 1) {
     // Teens: 10-19 → "tenth" through "nineteenth"
     tensOnesOrdinal = ORDINAL_TEENS[ones]
-  } else if (tens >= 2) {
+  }
+  else if (tens >= 2) {
     if (ones > 0) {
       // Compound: "twenty-first", "thirty-second", etc.
       tensOnesOrdinal = TENS[tens] + '-' + ORDINAL_ONES[ones]
-    } else {
+    }
+    else {
       // Round tens: "twentieth", "thirtieth", etc.
       tensOnesOrdinal = ORDINAL_TENS[tens]
     }
-  } else if (ones > 0) {
+  }
+  else if (ones > 0) {
     // Single digit: "first", "second", etc.
     tensOnesOrdinal = ORDINAL_ONES[ones]
   }
@@ -343,7 +359,8 @@ function buildOrdinalSegment (n) {
     if (tensOnesOrdinal) {
       // "one hundred twenty-first"
       return ONES[hundreds] + ' ' + HUNDRED + ' ' + tensOnesOrdinal
-    } else {
+    }
+    else {
       // "one hundredth", "two hundredth", etc.
       return ONES[hundreds] + ' hundredth'
     }
@@ -355,11 +372,10 @@ function buildOrdinalSegment (n) {
 /**
  * Converts a positive integer to ordinal words.
  * Generates ordinals directly without string manipulation.
- *
  * @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))
@@ -387,11 +403,10 @@ function integerToOrdinal (n) {
 /**
  * Builds ordinal words for numbers >= 1,000,000.
  * All segments except the final one are cardinal; final segment is ordinal.
- *
  * @param {bigint} n - Number >= 1,000,000
  * @returns {string} Ordinal English words
  */
-function buildLargeOrdinal (n) {
+function buildLargeOrdinal(n) {
   // Extract segments (least-significant first)
   const segments = []
   let temp = n
@@ -425,11 +440,13 @@ function buildLargeOrdinal (n) {
       if (i === 0) {
         // Units position: use ordinal segment
         result += buildOrdinalSegment(segment)
-      } else {
+      }
+      else {
         // Scale position with no remainder below: "one millionth"
         result += buildSegment(segment, false).word + ' ' + SCALES[i - 1] + 'th'
       }
-    } else {
+    }
+    else {
       // Non-final segments are cardinal
       result += buildSegment(segment, false).word
       if (i > 0) {
@@ -443,12 +460,10 @@ function buildLargeOrdinal (n) {
 
 /**
  * Converts a numeric value to Canadian 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
- *
  * @example
  * toOrdinal(1)    // 'first'
  * toOrdinal(2)    // 'second'
@@ -459,8 +474,9 @@ function buildLargeOrdinal (n) {
  * toOrdinal(101)  // 'one hundred first'
  * toOrdinal(1000) // 'one thousandth'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
+  checkMax(integerPart, ordinalMax)
   return integerToOrdinal(integerPart)
 }
 
@@ -468,26 +484,31 @@ function toOrdinal (value) {
 // CURRENCY: toCurrency(value, options?)
 // ============================================================================
 
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [and] - Use "and" between dollars and cents (e.g., "one dollar and fifty cents")
+ */
+
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults = { and: true }
+
 /**
  * Converts a numeric value to Canadian 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 dollars and cents (e.g., "one dollar and fifty cents")
+ * @param {CurrencyOptions} [options] - Optional configuration
  * @returns {string} The amount in Canadian 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 dollars and fifty cents'
  * toCurrency(1)                        // 'one dollar'
  * toCurrency(0.99)                     // 'ninety-nine cents'
  * toCurrency(42.50, { and: false })    // 'forty-two dollars fifty cents'
  */
-function toCurrency (value, options) {
-  options = validateOptions(options)
+function toCurrency(value, options) {
   const { isNegative, dollars, cents } = parseCurrencyValue(value)
-  const { and: useAnd = true } = options
+  checkMax(dollars, currencyMax)
+  const { and: useAnd } = resolveOptions(options, currencyDefaults)
 
   // Build result
   let result = ''

package/src/en-GB.d.ts

@@ -1,14 +1,27 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [and] - Use "and" between pounds and pence (e.g., "one pound and fifty pence")
+ */
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults: Required<CurrencyOptions>;
+export type CurrencyOptions = {
+    /**
+     * - Use "and" between pounds and pence (e.g., "one pound and fifty pence")
+     */
+    and?: boolean | undefined;
+};
 /**
  * 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.
- *
  * @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(-3.14)        // 'minus three point fourteen'
@@ -17,12 +30,10 @@
 export function toCardinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to British 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
- *
  * @example
  * toOrdinal(1)    // 'first'
  * toOrdinal(2)    // 'second'
@@ -36,14 +47,11 @@ export function toCardinal(value: number | string | bigint): string;
 export function toOrdinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to British 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 pounds and pence (e.g., "one pound and fifty pence")
+ * @param {CurrencyOptions} [options] - Optional configuration
  * @returns {string} The amount in British 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 pounds and fifty pence'
  * toCurrency(1)                        // 'one pound'
@@ -51,6 +59,4 @@ export function toOrdinal(value: number | string | bigint): string;
  * toCurrency(0.01)                     // 'one penny'
  * toCurrency(42.50, { and: false })    // 'forty-two pounds fifty pence'
  */
-export function toCurrency(value: number | string | bigint, options?: {
-    and?: boolean | undefined;
-}): string;
+export function toCurrency(value: number | string | bigint, options?: CurrencyOptions): string;