n2words 4.0.0 → 5.1.0

package/src/uk-UA.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 { western } from './utils/scale.js'
+import { resolveOptions } from './utils/resolve-options.js'
 
 // ============================================================================
 // Vocabulary
@@ -71,14 +73,20 @@ const SCALE_FORMS = [
   ['квiнтильйон', 'квiнтильйони', 'квiнтильйонiв'],
   ['секстильйон', 'секстильйони', 'секстильйонiв'],
   ['септильйон', 'септильйони', 'септильйонiв'],
-  ['октильйон', 'октильйони', 'октильйонiв']
+  ['октильйон', 'октильйони', 'октильйонiв'],
 ]
 
 // ============================================================================
 // Segment Building
 // ============================================================================
 
-function pluralize (n, forms) {
+/**
+ * Selects the correct plural form for a count.
+ * @param {number | bigint} n - The count
+ * @param {string[]} forms - Plural forms [one, few, many]
+ * @returns {string} The selected plural form
+ */
+function pluralize(n, forms) {
   const num = typeof n === 'bigint' ? Number(n) : n
   const lastDigit = num % 10
   const lastTwoDigits = num % 100
@@ -92,7 +100,12 @@ function pluralize (n, forms) {
   return forms[2]
 }
 
-function buildSegmentMasc (n) {
+/**
+ * Builds the masculine words for a 0-999 segment.
+ * @param {number} n - Number 0-999
+ * @returns {string} Segment words
+ */
+function buildSegmentMasc(n) {
   if (n === 0) return ''
 
   const onesDigit = n % 10
@@ -111,14 +124,20 @@ function buildSegmentMasc (n) {
 
   if (tensDigit === 1) {
     parts.push(TEENS[onesDigit])
-  } else if (onesDigit > 0) {
+  }
+  else if (onesDigit > 0) {
     parts.push(ONES_MASC[onesDigit])
   }
 
   return parts.join(' ')
 }
 
-function buildSegmentFem (n) {
+/**
+ * Builds the feminine words for a 0-999 segment.
+ * @param {number} n - Number 0-999
+ * @returns {string} Segment words
+ */
+function buildSegmentFem(n) {
   if (n === 0) return ''
 
   const onesDigit = n % 10
@@ -137,7 +156,8 @@ function buildSegmentFem (n) {
 
   if (tensDigit === 1) {
     parts.push(TEENS[onesDigit])
-  } else if (onesDigit > 0) {
+  }
+  else if (onesDigit > 0) {
     parts.push(ONES_FEM[onesDigit])
   }
 
@@ -148,7 +168,13 @@ function buildSegmentFem (n) {
 // Conversion Functions
 // ============================================================================
 
-function integerToWords (n, gender) {
+/**
+ * Converts a non-negative integer to Ukrainian words.
+ * @param {bigint} n - The integer to convert
+ * @param {('masculine'|'feminine')} gender - Grammatical gender
+ * @returns {string} The integer in Ukrainian words
+ */
+function integerToWords(n, gender) {
   if (n === 0n) return ZERO
 
   if (n < 1000n) {
@@ -158,7 +184,13 @@ function integerToWords (n, gender) {
   return buildLargeNumberWords(n, gender)
 }
 
-function buildLargeNumberWords (n, gender) {
+/**
+ * Builds Ukrainian words for numbers >= 1000.
+ * @param {bigint} n - The integer to convert
+ * @param {('masculine'|'feminine')} gender - Grammatical gender
+ * @returns {string} The integer in Ukrainian words
+ */
+function buildLargeNumberWords(n, gender) {
   const numStr = n.toString()
   const len = numStr.length
 
@@ -185,7 +217,8 @@ function buildLargeNumberWords (n, gender) {
     if (segment !== 0) {
       if (scaleIndex === 0) {
         parts.push(gender === 'feminine' ? buildSegmentFem(segment) : buildSegmentMasc(segment))
-      } else {
+      }
+      else {
         const scaleForms = SCALE_FORMS[scaleIndex - 1]
         const scaleWord = pluralize(segment, scaleForms)
         // Thousands (scaleIndex=1) are feminine, others masculine
@@ -201,7 +234,13 @@ function buildLargeNumberWords (n, gender) {
   return parts.join(' ')
 }
 
-function decimalPartToWords (decimalPart, gender) {
+/**
+ * Converts a decimal fractional string to Ukrainian words.
+ * @param {string} decimalPart - The fractional digits
+ * @param {('masculine'|'feminine')} gender - Grammatical gender
+ * @returns {string} The fractional part in Ukrainian words
+ */
+function decimalPartToWords(decimalPart, gender) {
   let result = ''
   let i = 0
 
@@ -220,20 +259,38 @@ function decimalPartToWords (decimalPart, gender) {
   return result
 }
 
+// Supported magnitude ceilings (checked at the public entry points). Both
+// tables are indexed [scaleIndex - 1] (units separate), so the ceiling is
+// 10^((length + 1) * 3): cardinal/currency 10^30, ordinal 10^15.
+export const cardinalMax = western(SCALE_FORMS.length)
+export const ordinalMax = western(ORDINAL_SCALES.length)
+export const currencyMax = western(SCALE_FORMS.length)
+
+/**
+ * @typedef {object} CardinalOptions
+ * @property {('masculine'|'feminine')} [gender] - Grammatical gender
+ */
+
+/** @type {Required<CardinalOptions>} */
+export const cardinalDefaults = { gender: 'masculine' }
+
+/** @type {{ gender: ReadonlyArray<Required<CardinalOptions>['gender']> }} */
+export const cardinalValues = { gender: ['masculine', 'feminine'] }
+
 /**
  * Converts a numeric value to Ukrainian words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
- * @param {Object} [options] - Optional configuration
- * @param {('masculine'|'feminine')} [options.gender='masculine'] - Grammatical gender
+ * @param {CardinalOptions} [options] - Optional configuration
  * @returns {string} The number in Ukrainian words
  */
-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)
 
   // Apply option defaults
-  const { gender = 'masculine' } = options
+  const { gender } = resolveOptions(options, cardinalDefaults, cardinalValues)
 
   let result = ''
 
@@ -256,11 +313,10 @@ function toCardinal (value, options) {
 
 /**
  * Builds ordinal for a 0-99 segment when it's the final (ordinal) part.
- *
  * @param {number} n - Number 0-99
  * @returns {string} Ordinal words
  */
-function buildOrdinalTensOnes (n) {
+function buildOrdinalTensOnes(n) {
   if (n === 0) return ''
 
   const onesDigit = n % 10
@@ -283,11 +339,10 @@ function buildOrdinalTensOnes (n) {
 
 /**
  * Converts a positive integer to Ukrainian ordinal words (masculine nominative).
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Ordinal Ukrainian words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   if (n < 100n) {
     return buildOrdinalTensOnes(Number(n))
   }
@@ -325,11 +380,10 @@ function integerToOrdinal (n) {
 
 /**
  * Builds ordinal words for numbers >= 1,000,000.
- *
  * @param {bigint} n - Number >= 1,000,000
  * @returns {string} Ordinal Ukrainian words
  */
-function buildLargeOrdinal (n) {
+function buildLargeOrdinal(n) {
   const numStr = n.toString()
   const len = numStr.length
 
@@ -364,19 +418,23 @@ function buildLargeOrdinal (n) {
       if (scaleIndex === 0) {
         if (isLastNonZero) {
           parts.push(integerToOrdinal(BigInt(segment)))
-        } else {
+        }
+        else {
           parts.push(buildSegmentMasc(segment))
         }
-      } else {
+      }
+      else {
         if (isLastNonZero) {
           if (segment === 1) {
             parts.push(ORDINAL_SCALES[scaleIndex - 1])
-          } else {
+          }
+          else {
             const isFeminine = scaleIndex === 1
             const segmentWord = isFeminine ? buildSegmentFem(segment) : buildSegmentMasc(segment)
             parts.push(segmentWord + ' ' + ORDINAL_SCALES[scaleIndex - 1])
           }
-        } else {
+        }
+        else {
           const scaleForms = SCALE_FORMS[scaleIndex - 1]
           const scaleWord = pluralize(segment, scaleForms)
           const isFeminine = scaleIndex === 1
@@ -394,12 +452,10 @@ function buildLargeOrdinal (n) {
 
 /**
  * Converts a numeric value to Ukrainian ordinal words (masculine nominative).
- *
  * @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)    // 'перший'
  * toOrdinal(2)    // 'другий'
@@ -407,8 +463,9 @@ function buildLargeOrdinal (n) {
  * toOrdinal(100)  // 'сотий'
  * toOrdinal(1000) // 'тисячний'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
+  checkMax(integerPart, ordinalMax)
   return integerToOrdinal(integerPart)
 }
 
@@ -418,20 +475,19 @@ function toOrdinal (value) {
 
 /**
  * Converts a numeric value to Ukrainian currency words (Hryvnia).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Ukrainian 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)     // 'сорок двi гривнi'
  * toCurrency(1)      // 'одна гривня'
  * toCurrency(1.50)   // 'одна гривня п\'ятдесят копiйок'
  * toCurrency(-5)     // 'мiнус п\'ять гривень'
  */
-function toCurrency (value) {
+function toCurrency(value) {
   const { isNegative, dollars: hryvnia, cents: kopiyky } = parseCurrencyValue(value)
+  checkMax(hryvnia, currencyMax)
 
   let result = ''
   if (isNegative) {

package/src/ur-PK.d.ts

@@ -1,18 +1,18 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
 /**
  * Converts a numeric value to Urdu words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Urdu words
  */
 export function toCardinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Urdu 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)    // 'پہلا'
  * toOrdinal(2)    // 'دوسرا'
@@ -22,12 +22,10 @@ export function toCardinal(value: number | string | bigint): string;
 export function toOrdinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Urdu currency words (Pakistani Rupee).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Urdu 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)  // 'بیالیس روپے پچاس پیسے'
  * toCurrency(1)      // 'ایک روپیہ'

package/src/ur-PK.js

@@ -13,6 +13,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 { indian } from './utils/scale.js'
 
 // ============================================================================
 // Vocabulary
@@ -55,20 +57,29 @@ const BELOW_HUNDRED = [
   'ساٹھ', 'اکسٹھ', 'باسٹھ', 'ترسٹھ', 'چونسٹھ', 'پینسٹھ', 'چھیاسٹھ', 'سڑسٹھ', 'اڑسٹھ', 'انہتر',
   'ستر', 'اکہتر', 'بہتر', 'تہتر', 'چوہتر', 'پچھتر', 'چھہتر', 'ستتر', 'اٹھہتر', 'اناسی',
   'اسی', 'اکیاسی', 'بیاسی', 'تریاسی', 'چوراسی', 'پچاسی', 'چھیاسی', 'ستاسی', 'اٹھاسی', 'نواسی',
-  'نوے', 'اکانوے', 'بانوے', 'ترانوے', 'چورانوے', 'پچانوے', 'چھیانوے', 'ستانوے', 'اٹھانوے', 'ننانوے'
+  'نوے', 'اکانوے', 'بانوے', 'ترانوے', 'چورانوے', 'پچانوے', 'چھیانوے', 'ستانوے', 'اٹھانوے', 'ننانوے',
 ]
 
 // Scale words: index 0 = units (empty), 1 = thousand, 2 = lakh, 3 = crore, etc.
 const SCALE_WORDS = ['', 'ہزار', 'لاکھ', 'کروڑ', 'ارب', 'کھرب', 'نیل', 'پدم', 'شنکھ']
 
+// 3-2-2 Indian grouping: a 3-digit base segment, then 2 digits per scale word
+// (SCALE_WORDS[0] = '' is the units slot). Past the table the scale word is
+// dropped, which collapses the magnitude — so cap there.
+export const cardinalMax = indian(SCALE_WORDS.length)
+export const ordinalMax = indian(SCALE_WORDS.length)
+export const currencyMax = indian(SCALE_WORDS.length)
+
 // ============================================================================
 // Segment Building
 // ============================================================================
 
 /**
  * Builds words for a 0-999 segment.
+ * @param {number} n - Segment value (0-999)
+ * @returns {string} Urdu words for the segment
  */
-function buildSegment (n) {
+function buildSegment(n) {
   if (n === 0) return ''
   if (n < 100) return BELOW_HUNDRED[n]
 
@@ -90,11 +101,10 @@ function buildSegment (n) {
  *
  * Uses BigInt modulo for segment extraction (faster than string slicing).
  * South Asian 3-2-2 grouping: first 3 digits, then groups of 2.
- *
  * @param {bigint} n - Non-negative integer to convert
  * @returns {string} Urdu words
  */
-function integerToWords (n) {
+function integerToWords(n) {
   if (n === 0n) return ZERO
 
   // Fast path: numbers < 1000 (direct lookup)
@@ -120,7 +130,8 @@ function integerToWords (n) {
 
     if (i === 0) {
       words.push(buildSegment(segment))
-    } else {
+    }
+    else {
       words.push(BELOW_HUNDRED[segment])
     }
 
@@ -132,7 +143,12 @@ function integerToWords (n) {
   return words.join(' ')
 }
 
-function decimalPartToWords (decimalPart) {
+/**
+ * Converts the fractional digit string to Urdu words.
+ * @param {string} decimalPart - Digits after the decimal separator
+ * @returns {string} Urdu words for the decimal part
+ */
+function decimalPartToWords(decimalPart) {
   let result = ''
   let i = 0
 
@@ -153,12 +169,14 @@ function decimalPartToWords (decimalPart) {
 
 /**
  * Converts a numeric value to Urdu words.
- *
  * @param {number | string | bigint} value - The numeric value to convert
  * @returns {string} The number in Urdu words
  */
-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 = ''
 
@@ -183,11 +201,10 @@ function toCardinal (value) {
  * Converts a positive integer to Urdu ordinal words.
  *
  * Urdu ordinals: First 6 are irregular, then add -واں suffix.
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Urdu ordinal words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   // Special ordinals for 1-6
   if (n >= 1n && n <= 6n) {
     return ORDINAL_SPECIAL[Number(n)]
@@ -200,20 +217,20 @@ function integerToOrdinal (n) {
 
 /**
  * Converts a numeric value to Urdu 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)    // 'پہلا'
  * toOrdinal(2)    // 'دوسرا'
  * toOrdinal(3)    // 'تیسرا'
  * toOrdinal(10)   // 'دسواں'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
+  // Ordinals build on the cardinal speller, so they share its ceiling.
+  checkMax(integerPart, ordinalMax)
   return integerToOrdinal(integerPart)
 }
 
@@ -223,19 +240,18 @@ function toOrdinal (value) {
 
 /**
  * Converts a numeric value to Urdu currency words (Pakistani Rupee).
- *
  * @param {number | string | bigint} value - The currency amount to convert
  * @returns {string} The amount in Urdu 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)  // 'بیالیس روپے پچاس پیسے'
  * toCurrency(1)      // 'ایک روپیہ'
  * toCurrency(0.01)   // 'ایک پیسہ'
  */
-function toCurrency (value) {
+function toCurrency(value) {
   const { isNegative, dollars: rupees, cents: paise } = parseCurrencyValue(value)
+  checkMax(rupees, currencyMax)
 
   // Build result
   let result = ''

package/src/utils/check-max.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Range guard — the throwing counterpart of the scale-range producers.
+ *
+ * A precondition validator in the same family as `parseCardinalValue` /
+ * `resolveOptions`: the language calls it and it throws on a value past the
+ * form's ceiling, e.g. `checkMax(integerPart, cardinalMax, decimalPart)`. The
+ * `*Max` it consumes is produced by the pure helpers in `scale.js`.
+ * @module check-max
+ */
+/**
+ * Throws a `RangeError` when `value` — or its integer-spelled fraction —
+ * reaches a form's ceiling (`max`, the smallest value the form refuses).
+ *
+ * Runs at the entry point: an O(1) short-circuit before any spelling is built —
+ * the in-range path is just the bigint comparison, plus a single
+ * `BigInt(fraction)` parse when an integer-spelled fraction is supplied. The
+ * message renders `10^N - 1` when the ceiling is an exact power of ten,
+ * otherwise the raw maximum.
+ * @param {bigint} value The integer magnitude to test (integer part, dollars, …)
+ * @param {bigint | null} max The form's ceiling, or `null` for no limit (never throws)
+ * @param {string} [fraction] The decimal digit string — pass it **only** when the
+ *   fraction is spelled via the scale builder; digit-by-digit and ordinal /
+ *   currency forms omit it so long fractions stay valid.
+ * @throws {RangeError} when the value is out of range
+ */
+export function checkMax(value: bigint, max: bigint | null, fraction?: string): void;

package/src/utils/check-max.js

@@ -0,0 +1,33 @@
+/**
+ * Range guard — the throwing counterpart of the scale-range producers.
+ *
+ * A precondition validator in the same family as `parseCardinalValue` /
+ * `resolveOptions`: the language calls it and it throws on a value past the
+ * form's ceiling, e.g. `checkMax(integerPart, cardinalMax, decimalPart)`. The
+ * `*Max` it consumes is produced by the pure helpers in `scale.js`.
+ * @module check-max
+ */
+
+/**
+ * Throws a `RangeError` when `value` — or its integer-spelled fraction —
+ * reaches a form's ceiling (`max`, the smallest value the form refuses).
+ *
+ * Runs at the entry point: an O(1) short-circuit before any spelling is built —
+ * the in-range path is just the bigint comparison, plus a single
+ * `BigInt(fraction)` parse when an integer-spelled fraction is supplied. The
+ * message renders `10^N - 1` when the ceiling is an exact power of ten,
+ * otherwise the raw maximum.
+ * @param {bigint} value The integer magnitude to test (integer part, dollars, …)
+ * @param {bigint | null} max The form's ceiling, or `null` for no limit (never throws)
+ * @param {string} [fraction] The decimal digit string — pass it **only** when the
+ *   fraction is spelled via the scale builder; digit-by-digit and ordinal /
+ *   currency forms omit it so long fractions stay valid.
+ * @throws {RangeError} when the value is out of range
+ */
+export function checkMax(value, max, fraction) {
+  if (max === null) return
+  if (value < max && !(fraction && BigInt(fraction) >= max)) return
+  const exponent = max.toString().length - 1
+  const largest = max === 10n ** BigInt(exponent) ? `10^${exponent} - 1` : `${max - 1n}`
+  throw new RangeError(`Number too large to convert: the largest supported value is ${largest}`)
+}

package/src/utils/expand-scientific.d.ts

@@ -6,10 +6,8 @@
 /**
  * Expands scientific notation to full decimal form.
  * Handles arbitrarily large exponents without precision loss.
- *
  * @param {string} str - String in scientific notation (e.g., "1e21", "1.5e-3")
  * @returns {string} Full decimal representation (e.g., "1000000000000000000000", "0.0015")
- *
  * @example
  * expandScientificNotation("1e21")    // "1000000000000000000000"
  * expandScientificNotation("1.5e3")   // "1500"
@@ -18,14 +16,12 @@
 export function expandScientificNotation(str: string): string;
 /**
  * Converts a number to decimal string, expanding scientific notation if needed.
- *
  * @param {number} value - The number to convert
  * @returns {string} Decimal string representation
  */
 export function numberToString(value: number): string;
 /**
  * Checks if a string contains scientific notation.
- *
  * @param {string} str - String to check
  * @returns {boolean} True if string contains 'e' or 'E'
  */

package/src/utils/expand-scientific.js

@@ -7,16 +7,14 @@
 /**
  * Expands scientific notation to full decimal form.
  * Handles arbitrarily large exponents without precision loss.
- *
  * @param {string} str - String in scientific notation (e.g., "1e21", "1.5e-3")
  * @returns {string} Full decimal representation (e.g., "1000000000000000000000", "0.0015")
- *
  * @example
  * expandScientificNotation("1e21")    // "1000000000000000000000"
  * expandScientificNotation("1.5e3")   // "1500"
  * expandScientificNotation("1e-3")    // "0.001"
  */
-export function expandScientificNotation (str) {
+export function expandScientificNotation(str) {
   let [mantissa, expStr] = str.toLowerCase().split('e')
   const exp = parseInt(expStr, 10)
 
@@ -36,30 +34,30 @@ export function expandScientificNotation (str) {
 
   if (newDotPosition >= digits.length) {
     return sign + digits + '0'.repeat(newDotPosition - digits.length)
-  } else if (newDotPosition <= 0) {
+  }
+  else if (newDotPosition <= 0) {
     return sign + '0.' + '0'.repeat(-newDotPosition) + digits
-  } else {
+  }
+  else {
     return sign + digits.slice(0, newDotPosition) + '.' + digits.slice(newDotPosition)
   }
 }
 
 /**
  * Converts a number to decimal string, expanding scientific notation if needed.
- *
  * @param {number} value - The number to convert
  * @returns {string} Decimal string representation
  */
-export function numberToString (value) {
+export function numberToString(value) {
   const str = value.toString()
   return hasScientificNotation(str) ? expandScientificNotation(str) : str
 }
 
 /**
  * Checks if a string contains scientific notation.
- *
  * @param {string} str - String to check
  * @returns {boolean} True if string contains 'e' or 'E'
  */
-export function hasScientificNotation (str) {
+export function hasScientificNotation(str) {
   return str.includes('e') || str.includes('E')
 }

package/src/utils/is-plain-object.d.ts

@@ -6,8 +6,7 @@
  * - Object.create(null): null-prototype object
  *
  * This excludes arrays, class instances, Map, Set, and other object types.
- *
- * @param {*} value Value to check
- * @returns {boolean} True if value is a plain object
+ * @param {unknown} value Value to check
+ * @returns {value is object} True if value is a plain object
  */
-export function isPlainObject(value: any): boolean;
+export function isPlainObject(value: unknown): value is object;

package/src/utils/is-plain-object.js

@@ -6,11 +6,10 @@
  * - Object.create(null): null-prototype object
  *
  * This excludes arrays, class instances, Map, Set, and other object types.
- *
- * @param {*} value Value to check
- * @returns {boolean} True if value is a plain object
+ * @param {unknown} value Value to check
+ * @returns {value is object} True if value is a plain object
  */
-export function isPlainObject (value) {
+export function isPlainObject(value) {
   if (value === null || typeof value !== 'object') return false
   const proto = Object.getPrototypeOf(value)
   return proto === null || proto === Object.prototype

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

@@ -1,9 +1,8 @@
 /**
  * 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
  */