n2words 4.0.0 → 5.1.0

package/src/zh-Hant-TW.d.ts

@@ -1,50 +1,75 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
+/**
+ * @typedef {object} CardinalOptions
+ * @property {boolean} [formal] - Use formal/financial numerals
+ */
+/** @type {Required<CardinalOptions>} */
+export const cardinalDefaults: Required<CardinalOptions>;
+/**
+ * @typedef {object} OrdinalOptions
+ * @property {boolean} [formal] - Use formal/financial numerals
+ */
+/** @type {Required<OrdinalOptions>} */
+export const ordinalDefaults: Required<OrdinalOptions>;
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [formal] - Use formal/financial numerals
+ */
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults: Required<CurrencyOptions>;
+export type CardinalOptions = {
+    /**
+     * - Use formal/financial numerals
+     */
+    formal?: boolean | undefined;
+};
+export type OrdinalOptions = {
+    /**
+     * - Use formal/financial numerals
+     */
+    formal?: boolean | undefined;
+};
+export type CurrencyOptions = {
+    /**
+     * - Use formal/financial numerals
+     */
+    formal?: boolean | undefined;
+};
 /**
  * Converts a numeric value to Traditional Chinese words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
- * @param {Object} [options] - Optional configuration
- * @param {boolean} [options.formal=true] - Use formal/financial numerals
+ * @param {CardinalOptions} [options] - Optional configuration
  * @returns {string} The number in Traditional Chinese words
  */
-export function toCardinal(value: number | string | bigint, options?: {
-    formal?: boolean | undefined;
-}): string;
+export function toCardinal(value: number | string | bigint, options?: CardinalOptions): string;
 /**
  * Converts a numeric value to Traditional Chinese ordinal words.
- *
  * @param {number | string | bigint} value - The numeric value to convert (positive integer)
- * @param {Object} [options] - Optional configuration
- * @param {boolean} [options.formal=true] - Use formal/financial numerals
+ * @param {OrdinalOptions} [options] - Optional configuration
  * @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(1, { formal: false }) // '第一'
  */
-export function toOrdinal(value: number | string | bigint, options?: {
-    formal?: boolean | undefined;
-}): string;
+export function toOrdinal(value: number | string | bigint, options?: OrdinalOptions): string;
 /**
  * Converts a numeric value to Traditional Chinese currency words (New Taiwan Dollar).
  *
  * Uses 圓 (yuan), 角 (jiao, 1/10), 分 (fen, 1/100).
  * Formal writing adds 整 (zheng) for whole amounts.
- *
  * @param {number | string | bigint} value - The currency amount to convert
- * @param {Object} [options] - Optional configuration
- * @param {boolean} [options.formal=true] - Use formal/financial numerals
+ * @param {CurrencyOptions} [options] - Optional configuration
  * @returns {string} The amount in Traditional Chinese 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)                    // '肆拾貳圓整'
  * toCurrency(1.50)                  // '壹圓伍角整'
  * toCurrency(42, { formal: false }) // '四十二元整'
  */
-export function toCurrency(value: number | string | bigint, options?: {
-    formal?: boolean | undefined;
-}): string;
+export function toCurrency(value: number | string | bigint, options?: CurrencyOptions): string;

package/src/zh-Hant-TW.js

@@ -17,7 +17,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 { bounded } from './utils/scale.js'
+import { resolveOptions } from './utils/resolve-options.js'
 
 // ============================================================================
 // Vocabulary
@@ -39,6 +41,15 @@ const THOUSAND_FORMAL = '仟'
 const WAN_WORD = '萬' // 10,000
 const YI_WORD = '億' // 100,000,000
 
+// Supported magnitude ceiling (checked at the public entry points). Numbers
+// >= 億 (10^8) split into n / 10^8, which is then spelled by convertBelowYi —
+// itself only valid below 億. So the ceiling is 億² = 10^16. Ordinal (第 +
+// cardinal) and currency build on the cardinal, so they share it. Decimals are
+// spelled digit-by-digit, so they have no ceiling.
+export const cardinalMax = bounded(16)
+export const ordinalMax = bounded(16)
+export const currencyMax = bounded(16)
+
 const ZERO = '零'
 const NEGATIVE = '負'
 const DECIMAL_SEP = '點'
@@ -66,7 +77,13 @@ const YUAN_COMMON = '元'
 // Conversion Functions
 // ============================================================================
 
-function integerToWords (n, formal = true) {
+/**
+ * Converts a non-negative integer to Traditional Chinese words.
+ * @param {bigint} n - The integer value to convert
+ * @param {boolean} [formal] - Use formal/financial numerals
+ * @returns {string} The integer in Traditional Chinese words
+ */
+function integerToWords(n, formal = true) {
   if (n === 0n) return ZERO
 
   const ones = formal ? ONES_FORMAL : ONES_COMMON
@@ -75,7 +92,11 @@ function integerToWords (n, formal = true) {
   const thousand = formal ? THOUSAND_FORMAL : THOUSAND_COMMON
 
   // Convert number below 萬 (10,000)
-  function convertBelowWan (value) {
+  /**
+   * @param {bigint} value The number below 10,000 to convert
+   * @returns {string} The number in Traditional Chinese words
+   */
+  function convertBelowWan(value) {
     if (value === 0n) return ''
 
     const parts = []
@@ -95,11 +116,11 @@ function integerToWords (n, formal = true) {
     if (hundredsVal > 0n) {
       if (needsZero) {
         parts.push(ZERO)
-        needsZero = false
       }
       parts.push(ones[Number(hundredsVal)] + hundred)
       needsZero = hundredsRemainder > 0n && hundredsRemainder < 10n
-    } else if (thousandsVal > 0n && hundredsRemainder > 0n) {
+    }
+    else if (thousandsVal > 0n && hundredsRemainder > 0n) {
       needsZero = true
     }
 
@@ -112,7 +133,8 @@ function integerToWords (n, formal = true) {
         needsZero = false
       }
       parts.push(ones[Number(tensVal)] + ten)
-    } else if ((hundredsVal > 0n || thousandsVal > 0n) && onesVal > 0n) {
+    }
+    else if ((hundredsVal > 0n || thousandsVal > 0n) && onesVal > 0n) {
       needsZero = true
     }
 
@@ -128,7 +150,11 @@ function integerToWords (n, formal = true) {
   }
 
   // Convert number below 億 (100 million)
-  function convertBelowYi (value) {
+  /**
+   * @param {bigint} value The number below 100,000,000 to convert
+   * @returns {string} The number in Traditional Chinese words
+   */
+  function convertBelowYi(value) {
     if (value === 0n) return ''
 
     const parts = []
@@ -148,7 +174,8 @@ function integerToWords (n, formal = true) {
         }
         parts.push(convertBelowWan(wanRemainder))
       }
-    } else {
+    }
+    else {
       parts.push(convertBelowWan(value))
     }
 
@@ -172,14 +199,21 @@ function integerToWords (n, formal = true) {
       }
       parts.push(convertBelowYi(yiRemainder))
     }
-  } else {
+  }
+  else {
     parts.push(convertBelowYi(n))
   }
 
   return parts.join('')
 }
 
-function decimalDigitsToWords (decimalString, formal = true) {
+/**
+ * Converts each digit of a decimal string to Traditional Chinese words.
+ * @param {string} decimalString - The decimal digits to convert
+ * @param {boolean} [formal] - Use formal/financial numerals
+ * @returns {string[]} The decimal digits as Traditional Chinese words
+ */
+function decimalDigitsToWords(decimalString, formal = true) {
   const ones = formal ? ONES_FORMAL : ONES_COMMON
   const words = []
   for (const char of decimalString) {
@@ -188,20 +222,26 @@ function decimalDigitsToWords (decimalString, formal = true) {
   return words
 }
 
+/**
+ * @typedef {object} CardinalOptions
+ * @property {boolean} [formal] - Use formal/financial numerals
+ */
+
+/** @type {Required<CardinalOptions>} */
+export const cardinalDefaults = { formal: true }
+
 /**
  * Converts a numeric value to Traditional Chinese words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
- * @param {Object} [options] - Optional configuration
- * @param {boolean} [options.formal=true] - Use formal/financial numerals
+ * @param {CardinalOptions} [options] - Optional configuration
  * @returns {string} The number in Traditional Chinese words
  */
-function toCardinal (value, options) {
-  options = validateOptions(options)
+function toCardinal(value, options) {
   const { isNegative, integerPart, decimalPart } = parseCardinalValue(value)
+  checkMax(integerPart, cardinalMax)
 
   // Apply option defaults
-  const { formal = true } = options
+  const { formal } = resolveOptions(options, cardinalDefaults)
 
   let result = ''
 
@@ -226,34 +266,38 @@ function toCardinal (value, options) {
  * Converts a non-negative integer to Traditional Chinese ordinal words.
  *
  * Traditional Chinese ordinals use "第" prefix + cardinal number.
- *
  * @param {bigint} n - Positive integer to convert
  * @param {boolean} formal - Use formal/financial numerals
  * @returns {string} Traditional Chinese ordinal words
  */
-function integerToOrdinal (n, formal = true) {
+function integerToOrdinal(n, formal = true) {
   return ORDINAL_PREFIX + integerToWords(n, formal)
 }
 
+/**
+ * @typedef {object} OrdinalOptions
+ * @property {boolean} [formal] - Use formal/financial numerals
+ */
+
+/** @type {Required<OrdinalOptions>} */
+export const ordinalDefaults = { formal: true }
+
 /**
  * Converts a numeric value to Traditional Chinese ordinal words.
- *
  * @param {number | string | bigint} value - The numeric value to convert (positive integer)
- * @param {Object} [options] - Optional configuration
- * @param {boolean} [options.formal=true] - Use formal/financial numerals
+ * @param {OrdinalOptions} [options] - Optional configuration
  * @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(1, { formal: false }) // '第一'
  */
-function toOrdinal (value, options) {
-  options = validateOptions(options)
+function toOrdinal(value, options) {
   const integerPart = parseOrdinalValue(value)
-  const { formal = true } = options
+  checkMax(integerPart, ordinalMax)
+  const { formal } = resolveOptions(options, ordinalDefaults)
   return integerToOrdinal(integerPart, formal)
 }
 
@@ -261,28 +305,33 @@ function toOrdinal (value, options) {
 // CURRENCY: toCurrency(value, options?)
 // ============================================================================
 
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [formal] - Use formal/financial numerals
+ */
+
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults = { formal: true }
+
 /**
  * Converts a numeric value to Traditional Chinese currency words (New Taiwan Dollar).
  *
  * Uses 圓 (yuan), 角 (jiao, 1/10), 分 (fen, 1/100).
  * Formal writing adds 整 (zheng) for whole amounts.
- *
  * @param {number | string | bigint} value - The currency amount to convert
- * @param {Object} [options] - Optional configuration
- * @param {boolean} [options.formal=true] - Use formal/financial numerals
+ * @param {CurrencyOptions} [options] - Optional configuration
  * @returns {string} The amount in Traditional Chinese 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)                    // '肆拾貳圓整'
  * toCurrency(1.50)                  // '壹圓伍角整'
  * toCurrency(42, { formal: false }) // '四十二元整'
  */
-function toCurrency (value, options) {
-  options = validateOptions(options)
+function toCurrency(value, options) {
   const { isNegative, dollars: yuan, cents } = parseCurrencyValue(value)
-  const { formal = true } = options
+  checkMax(yuan, currencyMax)
+  const { formal } = resolveOptions(options, currencyDefaults)
 
   const yuanWord = formal ? YUAN_FORMAL : YUAN_COMMON
 
@@ -315,10 +364,12 @@ function toCurrency (value, options) {
       result += ZERO
     }
     result += ones[Number(fen)] + FEN_FORMAL
-  } else if (jiao > 0n) {
+  }
+  else if (jiao > 0n) {
     // Has jiao but no fen - add 整
     result += ZHENG_FORMAL
-  } else {
+  }
+  else {
     // Whole yuan only - add 整
     result += ZHENG_FORMAL
   }

package/src/utils/validate-options.d.ts

@@ -1,8 +0,0 @@
-/**
- * Validates and normalizes the options parameter.
- *
- * @param {*} options The options value to validate
- * @returns {Object} A valid options object (empty object if undefined)
- * @throws {TypeError} If options is not undefined or a plain object
- */
-export function validateOptions(options: any): Object;

package/src/utils/validate-options.js

@@ -1,16 +0,0 @@
-import { isPlainObject } from './is-plain-object.js'
-
-/**
- * Validates and normalizes the options parameter.
- *
- * @param {*} options The options value to validate
- * @returns {Object} A valid options object (empty object if undefined)
- * @throws {TypeError} If options is not undefined or a plain object
- */
-export function validateOptions (options) {
-  if (options === undefined) return {}
-  if (isPlainObject(options)) return options
-  throw new TypeError(
-    `Invalid options: expected plain object or undefined, got ${typeof options}`
-  )
-}