n2words 5.0.0 → 5.1.0

package/src/ru-RU.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
@@ -44,7 +46,7 @@ const SCALE_FORMS = [
   ['секстиллион', 'секстиллиона', 'секстиллионов'],
   ['септиллион', 'септиллиона', 'септиллионов'],
   ['октиллион', 'октиллиона', 'октиллионов'],
-  ['нониллион', 'нониллиона', 'нониллионов']
+  ['нониллион', 'нониллиона', 'нониллионов'],
 ]
 
 // ============================================================================
@@ -74,7 +76,7 @@ const ORDINAL_SCALES = [
   'секстиллионный',
   'септиллионный',
   'октиллионный',
-  'нониллионный'
+  'нониллионный',
 ]
 
 // Prefixes for compound ordinal thousands (двух-, трёх-, etc. + тысячный)
@@ -94,7 +96,13 @@ const KOPECK_FORMS = ['копейка', 'копейки', 'копеек']
 // Segment Building
 // ============================================================================
 
-function pluralize (n, forms) {
+/**
+ * Selects the correct plural form based on Russian pluralization rules.
+ * @param {number | bigint} n - The count
+ * @param {string[]} forms - [one, few, many] forms
+ * @returns {string} The matching plural form
+ */
+function pluralize(n, forms) {
   const num = typeof n === 'bigint' ? Number(n) : n
   const lastDigit = num % 10
   const lastTwoDigits = num % 100
@@ -108,7 +116,12 @@ function pluralize (n, forms) {
   return forms[2]
 }
 
-function buildSegmentMasc (n) {
+/**
+ * Builds masculine cardinal words for a 0-999 segment.
+ * @param {number} n - Number 0-999
+ * @returns {string} Masculine cardinal words
+ */
+function buildSegmentMasc(n) {
   if (n === 0) return ''
 
   const onesDigit = n % 10
@@ -127,14 +140,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 feminine cardinal words for a 0-999 segment.
+ * @param {number} n - Number 0-999
+ * @returns {string} Feminine cardinal words
+ */
+function buildSegmentFem(n) {
   if (n === 0) return ''
 
   const onesDigit = n % 10
@@ -153,7 +172,8 @@ function buildSegmentFem (n) {
 
   if (tensDigit === 1) {
     parts.push(TEENS[onesDigit])
-  } else if (onesDigit > 0) {
+  }
+  else if (onesDigit > 0) {
     parts.push(ONES_FEM[onesDigit])
   }
 
@@ -164,7 +184,13 @@ function buildSegmentFem (n) {
 // Conversion Functions
 // ============================================================================
 
-function integerToWords (n, gender) {
+/**
+ * Converts a non-negative integer to Russian cardinal words.
+ * @param {bigint} n - Non-negative integer to convert
+ * @param {('masculine'|'feminine')} gender - Grammatical gender
+ * @returns {string} Cardinal Russian words
+ */
+function integerToWords(n, gender) {
   if (n === 0n) return ZERO
 
   const feminine = gender === 'feminine'
@@ -193,7 +219,13 @@ function integerToWords (n, gender) {
   return buildLargeNumberWords(n, gender)
 }
 
-function buildLargeNumberWords (n, gender) {
+/**
+ * Builds cardinal words for numbers >= 1,000,000 via scale decomposition.
+ * @param {bigint} n - Number >= 1,000,000
+ * @param {('masculine'|'feminine')} gender - Grammatical gender
+ * @returns {string} Cardinal Russian words
+ */
+function buildLargeNumberWords(n, gender) {
   const feminine = gender === 'feminine'
   const numStr = n.toString()
   const len = numStr.length
@@ -221,7 +253,8 @@ function buildLargeNumberWords (n, gender) {
     if (segment !== 0) {
       if (scaleIndex === 0) {
         parts.push(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
@@ -237,7 +270,13 @@ function buildLargeNumberWords (n, gender) {
   return parts.join(' ')
 }
 
-function decimalPartToWords (decimalPart, gender) {
+/**
+ * Converts the fractional digit string to Russian words.
+ * @param {string} decimalPart - The fractional digits
+ * @param {('masculine'|'feminine')} gender - Grammatical gender
+ * @returns {string} Cardinal Russian words for the decimal part
+ */
+function decimalPartToWords(decimalPart, gender) {
   let result = ''
   let i = 0
 
@@ -256,20 +295,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^33, ordinal 10^33.
+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 Russian 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 Russian 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 = ''
 
@@ -293,11 +350,10 @@ function toCardinal (value, options) {
 /**
  * Builds ordinal for a 0-99 segment when it's the final (ordinal) part.
  * Returns ordinal form: "первый", "двадцать первый", etc.
- *
  * @param {number} n - Number 0-99
  * @returns {string} Ordinal words
  */
-function buildOrdinalTensOnes (n) {
+function buildOrdinalTensOnes(n) {
   if (n === 0) return ''
 
   const onesDigit = n % 10
@@ -328,11 +384,10 @@ function buildOrdinalTensOnes (n) {
  *
  * In Russian ordinals, only the LAST component becomes ordinal.
  * E.g., 121 = "сто двадцать первый" (one hundred twenty first)
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Ordinal Russian words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   // Fast path: numbers < 100
   if (n < 100n) {
     return buildOrdinalTensOnes(Number(n))
@@ -383,11 +438,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 Russian words
  */
-function buildLargeOrdinal (n) {
+function buildLargeOrdinal(n) {
   const numStr = n.toString()
   const len = numStr.length
 
@@ -425,22 +479,26 @@ function buildLargeOrdinal (n) {
         // Units position (no scale)
         if (isLastNonZero) {
           parts.push(integerToOrdinal(BigInt(segment)))
-        } else {
+        }
+        else {
           parts.push(buildSegmentMasc(segment))
         }
-      } else {
+      }
+      else {
         // Has scale word
         if (isLastNonZero) {
           // This scale position is the final ordinal
           if (segment === 1) {
             parts.push(ORDINAL_SCALES[scaleIndex - 1])
-          } else {
+          }
+          else {
             // Use cardinal segment + ordinal scale
             const isFeminine = scaleIndex === 1 // thousands are feminine
             const segmentWord = isFeminine ? buildSegmentFem(segment) : buildSegmentMasc(segment)
             parts.push(segmentWord + ' ' + ORDINAL_SCALES[scaleIndex - 1])
           }
-        } else {
+        }
+        else {
           // Not the final segment: use cardinal
           const scaleForms = SCALE_FORMS[scaleIndex - 1]
           const scaleWord = pluralize(segment, scaleForms)
@@ -459,12 +517,10 @@ function buildLargeOrdinal (n) {
 
 /**
  * Converts a numeric value to Russian 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 (e.g., "первый", "сорок второй")
  * @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)    // 'второй'
@@ -475,8 +531,9 @@ function buildLargeOrdinal (n) {
  * toOrdinal(101)  // 'сто первый'
  * toOrdinal(1000) // 'тысячный'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
+  checkMax(integerPart, ordinalMax)
   return integerToOrdinal(integerPart)
 }
 
@@ -484,16 +541,21 @@ function toOrdinal (value) {
 // CURRENCY: toCurrency(value, options?)
 // ============================================================================
 
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [and] - Use "и" between rubles and kopecks
+ */
+
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults = { and: true }
+
 /**
  * Converts a numeric value to Russian currency words (Russian Ruble).
- *
  * @param {number | string | bigint} value - The currency amount to convert
- * @param {Object} [options] - Optional configuration
- * @param {boolean} [options.and=true] - Use "и" between rubles and kopecks
+ * @param {CurrencyOptions} [options] - Optional configuration
  * @returns {string} The amount in Russian 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)                        // 'один рубль'
@@ -501,10 +563,10 @@ function toOrdinal (value) {
  * toCurrency(0.01)                     // 'одна копейка'
  * toCurrency(42.50, { and: false })    // 'сорок два рубля пятьдесят копеек'
  */
-function toCurrency (value, options) {
-  options = validateOptions(options)
+function toCurrency(value, options) {
   const { isNegative, dollars: rubles, cents: kopecks } = parseCurrencyValue(value)
-  const { and: useAnd = true } = options
+  checkMax(rubles, currencyMax)
+  const { and: useAnd } = resolveOptions(options, currencyDefaults)
 
   // Build result
   let result = ''

package/src/sr-Cyrl-RS.d.ts

@@ -1,22 +1,47 @@
+export const cardinalMax: bigint;
+export const ordinalMax: bigint;
+export const currencyMax: bigint;
+/**
+ * @typedef {object} CardinalOptions
+ * @property {('masculine'|'feminine')} [gender] - Grammatical gender
+ */
+/** @type {Required<CardinalOptions>} */
+export const cardinalDefaults: Required<CardinalOptions>;
+/** @type {{ gender: ReadonlyArray<Required<CardinalOptions>['gender']> }} */
+export const cardinalValues: {
+    gender: ReadonlyArray<Required<CardinalOptions>["gender"]>;
+};
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [and] - Use "и" between dinars and para
+ */
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults: Required<CurrencyOptions>;
+export type CardinalOptions = {
+    /**
+     * - Grammatical gender
+     */
+    gender?: "feminine" | "masculine" | undefined;
+};
+export type CurrencyOptions = {
+    /**
+     * - Use "и" between dinars and para
+     */
+    and?: boolean | undefined;
+};
 /**
  * Converts a numeric value to Serbian (Cyrillic) 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 Serbian Cyrillic words
  */
-export function toCardinal(value: number | string | bigint, options?: {
-    gender?: "masculine" | "feminine" | undefined;
-}): string;
+export function toCardinal(value: number | string | bigint, options?: CardinalOptions): string;
 /**
  * Converts a numeric value to Serbian 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 (e.g., "први", "четрдесет други")
  * @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)    // 'други'
@@ -29,14 +54,11 @@ export function toCardinal(value: number | string | bigint, options?: {
 export function toOrdinal(value: number | string | bigint): string;
 /**
  * Converts a numeric value to Serbian currency words (Serbian Dinar).
- *
  * @param {number | string | bigint} value - The currency amount to convert
- * @param {Object} [options] - Optional configuration
- * @param {boolean} [options.and=true] - Use "и" between dinars and para
+ * @param {CurrencyOptions} [options] - Optional configuration
  * @returns {string} The amount in Serbian 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)                        // 'један динар'
@@ -44,6 +66,4 @@ export function toOrdinal(value: number | string | bigint): string;
  * toCurrency(0.01)                     // 'једна пара'
  * toCurrency(42.50, { and: false })    // 'четрдесет два динара педесет пара'
  */
-export function toCurrency(value: number | string | bigint, options?: {
-    and?: boolean | undefined;
-}): string;
+export function toCurrency(value: number | string | bigint, options?: CurrencyOptions): string;