n2words 4.0.0 → 5.1.0

package/src/utils/parse-cardinal.js

@@ -10,24 +10,23 @@ import { expandScientificNotation, hasScientificNotation, numberToString } from
 /**
  * Parses a value for cardinal conversion.
  * Cardinals accept any numeric value: integers, decimals, negatives.
- *
  * @param {number|string|bigint} value - The value to parse
- * @returns {{isNegative: boolean, integerPart: bigint, decimalPart?: string}}
+ * @returns {{isNegative: boolean, integerPart: bigint, decimalPart?: string}} The parsed cardinal components
  * @throws {TypeError} If value is not number, string, or bigint
  * @throws {RangeError} If value is not finite
  */
-export function parseCardinalValue (value) {
+export function parseCardinalValue(value) {
   const type = typeof value
 
   // BigInt: simplest case
-  if (type === 'bigint') {
+  if (typeof value === 'bigint') {
     return value < 0n
       ? { isNegative: true, integerPart: -value }
       : { isNegative: false, integerPart: value }
   }
 
   // Number: fast path for safe integers
-  if (type === 'number') {
+  if (typeof value === 'number') {
     if (!Number.isFinite(value)) {
       throw new RangeError('Number must be finite (NaN and Infinity are not supported)')
     }
@@ -40,19 +39,21 @@ export function parseCardinalValue (value) {
   }
 
   // String input
-  if (type === 'string') {
+  if (typeof value === 'string') {
     return parseNumericString(normalizeString(value))
   }
 
   throw new TypeError(
-    `Invalid value type: expected number, string, or bigint, received ${type}`
+    `Invalid value type: expected number, string, or bigint, received ${type}`,
   )
 }
 
 /**
  * Validates and normalizes a string numeric input.
+ * @param {string} value - The string to normalize
+ * @returns {string} The normalized numeric string
  */
-function normalizeString (value) {
+function normalizeString(value) {
   const trimmed = value.trim()
   if (trimmed.length === 0 || Number.isNaN(Number(trimmed))) {
     throw new RangeError(`Invalid number format: "${value}"`)
@@ -62,8 +63,10 @@ function normalizeString (value) {
 
 /**
  * Parses a normalized numeric string into components.
+ * @param {string} str - The normalized numeric string
+ * @returns {{isNegative: boolean, integerPart: bigint, decimalPart?: string}} The parsed numeric components
  */
-function parseNumericString (str) {
+function parseNumericString(str) {
   const isNegative = str[0] === '-'
   if (isNegative) str = str.slice(1)
 

package/src/utils/parse-currency.d.ts

@@ -1,9 +1,8 @@
 /**
  * Parses a value for currency conversion.
  * Returns dollars and cents as separate bigints, plus negative flag.
- *
  * @param {number|string|bigint} value - The value to parse
- * @returns {{isNegative: boolean, dollars: bigint, cents: bigint}}
+ * @returns {{isNegative: boolean, dollars: bigint, cents: bigint}} The parsed dollars and cents with a negative flag.
  * @throws {TypeError} If value is not number, string, or bigint
  * @throws {RangeError} If value is not finite
  */

package/src/utils/parse-currency.js

@@ -9,24 +9,23 @@ import { expandScientificNotation, hasScientificNotation, numberToString } from
 /**
  * Parses a value for currency conversion.
  * Returns dollars and cents as separate bigints, plus negative flag.
- *
  * @param {number|string|bigint} value - The value to parse
- * @returns {{isNegative: boolean, dollars: bigint, cents: bigint}}
+ * @returns {{isNegative: boolean, dollars: bigint, cents: bigint}} The parsed dollars and cents with a negative flag.
  * @throws {TypeError} If value is not number, string, or bigint
  * @throws {RangeError} If value is not finite
  */
-export function parseCurrencyValue (value) {
+export function parseCurrencyValue(value) {
   const type = typeof value
 
   // BigInt: whole dollars only
-  if (type === 'bigint') {
+  if (typeof value === 'bigint') {
     return value < 0n
       ? { isNegative: true, dollars: -value, cents: 0n }
       : { isNegative: false, dollars: value, cents: 0n }
   }
 
   // Number: fast path for safe integers
-  if (type === 'number') {
+  if (typeof value === 'number') {
     if (!Number.isFinite(value)) {
       throw new RangeError('Currency must be a finite number')
     }
@@ -40,22 +39,21 @@ export function parseCurrencyValue (value) {
   }
 
   // String input
-  if (type === 'string') {
+  if (typeof value === 'string') {
     return parseCurrencyString(value)
   }
 
   throw new TypeError(
-    `Invalid value type: expected number, string, or bigint, received ${type}`
+    `Invalid value type: expected number, string, or bigint, received ${type}`,
   )
 }
 
 /**
  * Parses a string for currency conversion.
- *
  * @param {string} value - The string to parse
- * @returns {{isNegative: boolean, dollars: bigint, cents: bigint}}
+ * @returns {{isNegative: boolean, dollars: bigint, cents: bigint}} The parsed dollars and cents with a negative flag.
  */
-function parseCurrencyString (value) {
+function parseCurrencyString(value) {
   let str = value.trim()
 
   if (str.length === 0 || Number.isNaN(Number(str))) {
@@ -86,6 +84,6 @@ function parseCurrencyString (value) {
   return {
     isNegative,
     dollars: BigInt(dollarStr),
-    cents: BigInt(centStr)
+    cents: BigInt(centStr),
   }
 }

package/src/utils/parse-ordinal.d.ts

@@ -1,7 +1,6 @@
 /**
  * Parses a value for ordinal conversion.
  * Ordinals require positive integers only (no zero, negatives, or decimals).
- *
  * @param {number|string|bigint} value - The value to parse
  * @returns {bigint} The positive integer value
  * @throws {TypeError} If value is not number, string, or bigint

package/src/utils/parse-ordinal.js

@@ -9,17 +9,16 @@ import { expandScientificNotation, hasScientificNotation } from './expand-scient
 /**
  * Parses a value for ordinal conversion.
  * Ordinals require positive integers only (no zero, negatives, or decimals).
- *
  * @param {number|string|bigint} value - The value to parse
  * @returns {bigint} The positive integer value
  * @throws {TypeError} If value is not number, string, or bigint
  * @throws {RangeError} If value is zero, negative, or has a decimal part
  */
-export function parseOrdinalValue (value) {
+export function parseOrdinalValue(value) {
   const type = typeof value
 
   // BigInt: simplest case
-  if (type === 'bigint') {
+  if (typeof value === 'bigint') {
     if (value <= 0n) {
       throw new RangeError('Ordinals must be positive integers')
     }
@@ -27,7 +26,7 @@ export function parseOrdinalValue (value) {
   }
 
   // Number: fast path for safe integers
-  if (type === 'number') {
+  if (typeof value === 'number') {
     if (!Number.isFinite(value)) {
       throw new RangeError('Ordinals must be finite numbers')
     }
@@ -41,23 +40,22 @@ export function parseOrdinalValue (value) {
   }
 
   // String input
-  if (type === 'string') {
+  if (typeof value === 'string') {
     return parseOrdinalString(value)
   }
 
   throw new TypeError(
-    `Invalid value type: expected number, string, or bigint, received ${type}`
+    `Invalid value type: expected number, string, or bigint, received ${type}`,
   )
 }
 
 /**
  * Parses a string for ordinal conversion.
- *
  * @param {string} value - The string to parse
  * @returns {bigint} The positive integer value
  * @throws {RangeError} If string is not a valid positive integer
  */
-function parseOrdinalString (value) {
+function parseOrdinalString(value) {
   const trimmed = value.trim()
 
   if (trimmed.length === 0) {
@@ -96,8 +94,9 @@ function parseOrdinalString (value) {
       throw new RangeError('Ordinals must be positive integers')
     }
     return result
-  } catch (e) {
+  }
+  catch (e) {
     if (e instanceof RangeError) throw e
-    throw new RangeError(`Invalid ordinal format: "${value}"`)
+    throw new RangeError(`Invalid ordinal format: "${value}"`, { cause: e })
   }
 }

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

@@ -0,0 +1,17 @@
+/**
+ * Apply a form's option defaults and reject anything it doesn't declare.
+ *
+ * The exported defaults map (e.g. `cardinalDefaults`) is the single source of
+ * truth for each option's default value — the form never restates it, and the
+ * docs generator imports it rather than scraping the body. A malformed options
+ * argument (unknown key, wrong-typed value, inherited key) throws `TypeError`;
+ * a known option with a value outside its declared allowed set (an exported
+ * `<form>Values` map, e.g. gender) throws `RangeError` — right kind of value,
+ * out of range — instead of silently falling back to the default.
+ * @template {object} T
+ * @param {T | undefined} options - Caller-provided options, or undefined
+ * @param {Required<T>} defaults - The form's default for every option
+ * @param {Partial<Record<keyof T & string, readonly unknown[]>>} [values] - Allowed set per enum-valued option
+ * @returns {Required<T>} The options with every default applied
+ */
+export function resolveOptions<T extends object>(options: T | undefined, defaults: Required<T>, values?: Partial<Record<keyof T & string, readonly unknown[]>>): Required<T>;

package/src/utils/resolve-options.js

@@ -0,0 +1,56 @@
+import { isPlainObject } from './is-plain-object.js'
+
+/**
+ * Apply a form's option defaults and reject anything it doesn't declare.
+ *
+ * The exported defaults map (e.g. `cardinalDefaults`) is the single source of
+ * truth for each option's default value — the form never restates it, and the
+ * docs generator imports it rather than scraping the body. A malformed options
+ * argument (unknown key, wrong-typed value, inherited key) throws `TypeError`;
+ * a known option with a value outside its declared allowed set (an exported
+ * `<form>Values` map, e.g. gender) throws `RangeError` — right kind of value,
+ * out of range — instead of silently falling back to the default.
+ * @template {object} T
+ * @param {T | undefined} options - Caller-provided options, or undefined
+ * @param {Required<T>} defaults - The form's default for every option
+ * @param {Partial<Record<keyof T & string, readonly unknown[]>>} [values] - Allowed set per enum-valued option
+ * @returns {Required<T>} The options with every default applied
+ */
+export function resolveOptions(options, defaults, values) {
+  /** @type {Record<string, unknown>} */
+  const resolved = { ...defaults }
+  if (options === undefined) return /** @type {Required<T>} */ (resolved)
+
+  if (!isPlainObject(options)) {
+    throw new TypeError(`Invalid options: expected plain object or undefined, got ${typeof options}`)
+  }
+  const allowed = Object.keys(defaults)
+  for (const [key, value] of Object.entries(options)) {
+    // Own-property check: inherited keys (__proto__, constructor, …) are not
+    // options. Using `key in defaults` here would let them past the guard and
+    // into `resolved[key] = value` — a prototype-pollution vector. An unknown
+    // key is a malformed-argument (shape) error, hence TypeError — RangeError is
+    // reserved for a value outside an allowed range/set (see checkMax).
+    if (!Object.hasOwn(defaults, key)) {
+      throw new TypeError(`Unknown option "${key}" — expected one of: ${allowed.join(', ')}`)
+    }
+    // `{ key: undefined }` means "use the default": `key?: T` is `T | undefined`
+    // without exactOptionalPropertyTypes, and the old destructuring defaults
+    // treated undefined the same way. Omit it rather than reject it as a type.
+    if (value === undefined) continue
+    if (typeof value !== typeof resolved[key]) {
+      throw new TypeError(`Option "${key}" must be a ${typeof resolved[key]}, got ${typeof value}`)
+    }
+    if (values !== undefined && Object.hasOwn(values, key)) {
+      const set = /** @type {Record<string, readonly unknown[]>} */ (values)[key]
+      if (!set.includes(value)) {
+        // The received value is caller-supplied and arbitrary — stringify it so
+        // quotes/newlines can't garble the message. The allowed set is our own
+        // gate-verified declaration and reads cleaner unquoted.
+        throw new RangeError(`Option "${key}" must be one of: ${set.join(', ')} — got ${JSON.stringify(value)}`)
+      }
+    }
+    resolved[key] = value
+  }
+  return /** @type {Required<T>} */ (resolved)
+}

package/src/utils/scale.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 3-digit grouping, scale array starting at "thousand" (en-US, de-DE, ru-RU, …).
+ * @param {number} scaleCount Number of scale words in the table
+ * @returns {bigint} The first unsupported value (10^((scaleCount + 1) * 3))
+ */
+export function western(scaleCount: number): bigint;
+/**
+ * Myriad (4-digit) grouping — one scale word per power of 10,000 (ja-JP, ko-KR).
+ * @param {number} scaleCount Number of scale words in the table
+ * @returns {bigint} The first unsupported value
+ */
+export function myriad(scaleCount: number): bigint;
+/**
+ * South Asian 3-2-2 grouping: a 3-digit base segment then 2 digits per scale
+ * word, with the table's index 0 reserved for the (empty) units slot.
+ * @param {number} wordCount Length of the scale-word table (including the units slot)
+ * @returns {bigint} The first unsupported value
+ */
+export function indian(wordCount: number): bigint;
+/**
+ * Long scale — each unit (a base scale word, or a prefix) yields two levels
+ * (-illion / -illiard), spanning 6 powers of ten. es-*, fr-*, it-IT.
+ * @param {number} unitCount Number of base scale words or prefixes
+ * @returns {bigint} The first unsupported value (10^(6 * (unitCount + 1)))
+ */
+export function longScale(unitCount: number): bigint;
+/**
+ * Escape hatch: a structural bound given as its base-10 exponent (zh: `bounded(16)`).
+ * @param {number} exponent The base-10 exponent of the ceiling
+ * @returns {bigint} 10^exponent
+ */
+export function bounded(exponent: number): bigint;
+/**
+ * Scale-range helpers — pure.
+ *
+ * Each form declares its maximum supported value as a bigint export
+ * (`cardinalMax`, `ordinalMax`, `currencyMax`): the smallest value the form
+ * refuses, so the largest it converts is that minus one. `UNBOUNDED` (null)
+ * means no fixed limit.
+ *
+ * These helpers derive that bigint from a language's own scale-table size, so
+ * the ceiling tracks the vocabulary and can't drift. A language whose shape
+ * fits none of them declares the value directly (`bounded(n)` or a literal
+ * bigint). They only *produce* a max — the range check that consumes one
+ * (`checkMax`) lives in check-max.js, and the verification checks (boundary,
+ * gaps, injectivity) live in the gate. Nothing here throws.
+ */
+/** No fixed ceiling — recursive/compounding spellers (th-TH, fa-IR, …). */
+export const UNBOUNDED: null;

package/src/utils/scale.js

@@ -0,0 +1,65 @@
+/**
+ * Scale-range helpers — pure.
+ *
+ * Each form declares its maximum supported value as a bigint export
+ * (`cardinalMax`, `ordinalMax`, `currencyMax`): the smallest value the form
+ * refuses, so the largest it converts is that minus one. `UNBOUNDED` (null)
+ * means no fixed limit.
+ *
+ * These helpers derive that bigint from a language's own scale-table size, so
+ * the ceiling tracks the vocabulary and can't drift. A language whose shape
+ * fits none of them declares the value directly (`bounded(n)` or a literal
+ * bigint). They only *produce* a max — the range check that consumes one
+ * (`checkMax`) lives in check-max.js, and the verification checks (boundary,
+ * gaps, injectivity) live in the gate. Nothing here throws.
+ */
+
+/** No fixed ceiling — recursive/compounding spellers (th-TH, fa-IR, …). */
+export const UNBOUNDED = null
+
+/**
+ * 3-digit grouping, scale array starting at "thousand" (en-US, de-DE, ru-RU, …).
+ * @param {number} scaleCount Number of scale words in the table
+ * @returns {bigint} The first unsupported value (10^((scaleCount + 1) * 3))
+ */
+export function western(scaleCount) {
+  return 10n ** BigInt((scaleCount + 1) * 3)
+}
+
+/**
+ * Myriad (4-digit) grouping — one scale word per power of 10,000 (ja-JP, ko-KR).
+ * @param {number} scaleCount Number of scale words in the table
+ * @returns {bigint} The first unsupported value
+ */
+export function myriad(scaleCount) {
+  return 10n ** BigInt((scaleCount + 1) * 4)
+}
+
+/**
+ * South Asian 3-2-2 grouping: a 3-digit base segment then 2 digits per scale
+ * word, with the table's index 0 reserved for the (empty) units slot.
+ * @param {number} wordCount Length of the scale-word table (including the units slot)
+ * @returns {bigint} The first unsupported value
+ */
+export function indian(wordCount) {
+  return 10n ** BigInt(3 + 2 * (wordCount - 1))
+}
+
+/**
+ * Long scale — each unit (a base scale word, or a prefix) yields two levels
+ * (-illion / -illiard), spanning 6 powers of ten. es-*, fr-*, it-IT.
+ * @param {number} unitCount Number of base scale words or prefixes
+ * @returns {bigint} The first unsupported value (10^(6 * (unitCount + 1)))
+ */
+export function longScale(unitCount) {
+  return 10n ** BigInt(6 * (unitCount + 1))
+}
+
+/**
+ * Escape hatch: a structural bound given as its base-10 exponent (zh: `bounded(16)`).
+ * @param {number} exponent The base-10 exponent of the ceiling
+ * @returns {bigint} 10^exponent
+ */
+export function bounded(exponent) {
+  return 10n ** BigInt(exponent)
+}

package/src/vi-VN.d.ts

@@ -1,14 +1,15 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
 /**
  * Converts a numeric value to Vietnamese 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 Vietnamese words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCardinal(42)           // 'bốn mươi hai'
  * toCardinal(101)          // 'một trăm lẻ một'
@@ -17,12 +18,10 @@
 export function toCardinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Vietnamese 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)    // 'thứ nhất'
  * toOrdinal(2)    // 'thứ hai'
@@ -34,12 +33,10 @@ export function toOrdinal(value: number | string | bigint): string;
  *
  * Vietnamese Dong has no subunit in modern usage (xu are historical).
  * Amounts are rounded to whole đồng.
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Vietnamese 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)     // 'bốn mươi hai đồng'
  * toCurrency(1000)   // 'một nghìn đồng'

package/src/vi-VN.js

@@ -12,6 +12,8 @@
 import { parseCardinalValue } from './utils/parse-cardinal.js'
 import { parseCurrencyValue } from './utils/parse-currency.js'
 import { parseOrdinalValue } from './utils/parse-ordinal.js'
+import { checkMax } from './utils/check-max.js'
+import { western } from './utils/scale.js'
 
 // ============================================================================
 // Vocabulary (module-level constants)
@@ -21,14 +23,20 @@ import { parseOrdinalValue } from './utils/parse-ordinal.js'
 const ONES = ['không', 'một', 'hai', 'ba', 'bốn', 'năm', 'sáu', 'bảy', 'tám', 'chín']
 
 // Scale words indexed by scale level (0 = units, 1 = thousands, etc.)
+// Vietnamese composes large numbers by cycling nghìn/triệu/tỷ and appending
+// another tỷ every three groups. The recursion past tỷ tỷ (10^18) is rarely used
+// and not firmly fixed, so the table stops at that scale word rather than invent
+// more; the ceiling then falls where the next one would be needed (see below).
 const SCALES = [
-  '', 'nghìn', 'triệu', 'tỷ', 'nghìn tỷ', 'trăm nghìn tỷ',
-  'Quintillion', 'Sextillion', 'Septillion', 'Octillion',
-  'Nonillion', 'Decillion', 'Undecillion', 'Duodecillion',
-  'Tredecillion', 'Quattuordecillion', 'Sexdecillion',
-  'Septendecillion', 'Octodecillion', 'Novemdecillion', 'Vigintillion'
+  '', 'nghìn', 'triệu', 'tỷ', 'nghìn tỷ', 'triệu tỷ', 'tỷ tỷ',
 ]
 
+// 3-digit grouping with SCALES[0] = '' (units); the highest scale word is
+// tỷ tỷ at index 6 (10^18), so values from 10^(3 * SCALES.length) up have no scale word.
+export const cardinalMax = western(SCALES.length - 1)
+export const ordinalMax = western(SCALES.length - 1)
+export const currencyMax = western(SCALES.length - 1)
+
 const HUNDRED = 'trăm'
 const ZERO = 'không'
 const NEGATIVE = 'âm'
@@ -59,8 +67,10 @@ const LAM = 'lăm' // 5 in tens position (25, 35, etc.)
 
 /**
  * Builds word for 0-99 with special forms (mốt, lăm).
+ * @param {number} n - Integer in range 0-99
+ * @returns {string} Vietnamese words
  */
-function buildBelowHundred (n) {
+function buildBelowHundred(n) {
   if (n === 0) return ONES[0]
   if (n < 10) return ONES[n]
 
@@ -85,8 +95,10 @@ function buildBelowHundred (n) {
 
 /**
  * Builds segment word for 0-999.
+ * @param {number} n - Integer in range 0-999
+ * @returns {string} Vietnamese words
  */
-function buildSegment (n) {
+function buildSegment(n) {
   if (n === 0) return ''
 
   const hundreds = Math.trunc(n / 100)
@@ -105,10 +117,12 @@ function buildSegment (n) {
         result += ' ' + LE + ' '
         // Use "năm" not "lăm" after lẻ
         result += remainder === 5 ? 'năm' : ONES[remainder]
-      } else {
+      }
+      else {
         result = ONES[remainder]
       }
-    } else {
+    }
+    else {
       // 10-99 after hundreds
       if (result) result += ' '
       result += buildBelowHundred(remainder)
@@ -120,8 +134,10 @@ function buildSegment (n) {
 
 /**
  * Builds "lẻ" prefixed word for small remainders (1-99) after scale words.
+ * @param {number} n - Integer in range 0-99
+ * @returns {string} Vietnamese words
  */
-function buildLeSegment (n) {
+function buildLeSegment(n) {
   if (n === 0) return ''
   if (n < 10) {
     // Use "năm" not "lăm" after lẻ
@@ -136,11 +152,10 @@ function buildLeSegment (n) {
 
 /**
  * Converts a non-negative integer to Vietnamese words.
- *
  * @param {bigint} n - Non-negative integer to convert
  * @returns {string} Vietnamese words
  */
-function integerToWords (n) {
+function integerToWords(n) {
   if (n === 0n) return ZERO
 
   // Fast path: numbers < 100
@@ -178,11 +193,10 @@ function integerToWords (n) {
 
 /**
  * Builds words for numbers >= 1,000,000.
- *
  * @param {bigint} n - Number >= 1,000,000
  * @returns {string} Vietnamese words
  */
-function buildLargeNumberWords (n) {
+function buildLargeNumberWords(n) {
   const numStr = n.toString()
   const len = numStr.length
 
@@ -212,7 +226,8 @@ function buildLargeNumberWords (n) {
       if (words) {
         if (scaleIndex > 0) {
           parts.push(words + ' ' + SCALES[scaleIndex])
-        } else {
+        }
+        else {
           parts.push(words)
         }
       }
@@ -246,11 +261,10 @@ function buildLargeNumberWords (n) {
 
 /**
  * Converts decimal digits to Vietnamese words.
- *
  * @param {string} decimalPart - Decimal digits (without the point)
  * @returns {string} Vietnamese words for decimal part
  */
-function decimalPartToWords (decimalPart) {
+function decimalPartToWords(decimalPart) {
   let result = ''
 
   // Handle leading zeros
@@ -276,19 +290,20 @@ function decimalPartToWords (decimalPart) {
  *
  * 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 Vietnamese words
  * @throws {TypeError} If value is not a valid numeric type
  * @throws {Error} If value is not a valid number format
- *
  * @example
  * toCardinal(42)           // 'bốn mươi hai'
  * toCardinal(101)          // 'một trăm lẻ một'
  * toCardinal(1000000)      // 'một triệu'
  */
-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 = ''
 
@@ -314,11 +329,10 @@ function toCardinal (value) {
  *
  * Vietnamese ordinals use "thứ" prefix + cardinal number.
  * Special case: "thứ nhất" for 1st (not "thứ một").
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Vietnamese ordinal words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   // Special case: 1st is "thứ nhất"
   if (n === 1n) {
     return ORDINAL_PREFIX + ' ' + ORDINAL_ONE
@@ -330,19 +344,19 @@ function integerToOrdinal (n) {
 
 /**
  * Converts a numeric value to Vietnamese 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)    // 'thứ nhất'
  * toOrdinal(2)    // 'thứ hai'
  * toOrdinal(10)   // 'thứ mười'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
+  // Ordinals are built from the cardinal speller, so they share its ceiling.
+  checkMax(integerPart, ordinalMax)
   return integerToOrdinal(integerPart)
 }
 
@@ -355,19 +369,18 @@ function toOrdinal (value) {
  *
  * Vietnamese Dong has no subunit in modern usage (xu are historical).
  * Amounts are rounded to whole đồng.
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Vietnamese 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)     // 'bốn mươi hai đồng'
  * toCurrency(1000)   // 'một nghìn đồng'
  * toCurrency(-5)     // 'âm năm đồng'
  */
-function toCurrency (value) {
+function toCurrency(value) {
   const { isNegative, dollars: dong } = parseCurrencyValue(value)
+  checkMax(dong, currencyMax)
 
   let result = ''
   if (isNegative) {