n2words 5.0.0 → 5.1.1

package/src/sr-Cyrl-RS.js

@@ -5,7 +5,8 @@
  *
  * Key features:
  * - Three-form pluralization (one/few/many)
- * - Gender: thousands are feminine, millions+ are masculine
+ * - Gender by scale word: the -arda forms (hiljada, milijarda, bilijarda, ...)
+ *   are feminine; the -ion forms (milion, bilion, ...) are masculine
  * - Irregular hundreds
  * - Long scale naming with -ard forms
  * - Cyrillic script
@@ -14,7 +15,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
@@ -56,7 +59,7 @@ const ORDINAL_SCALES = [
   'трилионити',
   'трилијардити',
   'квадрилионити',
-  'квадрилијардити'
+  'квадрилијардити',
 ]
 
 // ============================================================================
@@ -79,14 +82,27 @@ const SCALE_FORMS = [
   ['трилион', 'трилиона', 'трилиона'],
   ['трилијарда', 'трилијарде', 'трилијарда'],
   ['квадрилион', 'квадрилиона', 'квадрилиона'],
-  ['квадрилијарда', 'квадрилијарде', 'квадрилијарда']
+  ['квадрилијарда', 'квадрилијарде', 'квадрилијарда'],
 ]
 
+// Supported magnitude ceilings (checked at the public entry points). Both the
+// cardinal SCALE_FORMS and the ORDINAL_SCALES tables cover units + N scale
+// groups, so values must stay below 10^((length + 1) * 3) = 10^30.
+export const cardinalMax = western(SCALE_FORMS.length)
+export const ordinalMax = western(ORDINAL_SCALES.length)
+export const currencyMax = western(SCALE_FORMS.length)
+
 // ============================================================================
 // 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
@@ -100,7 +116,12 @@ function pluralize (n, forms) {
   return forms[2]
 }
 
-function buildSegmentMasc (n) {
+/**
+ * Builds the masculine word form for a 0-999 segment.
+ * @param {number} n - Number 0-999
+ * @returns {string} The segment words
+ */
+function buildSegmentMasc(n) {
   if (n === 0) return ''
 
   const onesDigit = n % 10
@@ -119,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 the feminine word form for a 0-999 segment.
+ * @param {number} n - Number 0-999
+ * @returns {string} The segment words
+ */
+function buildSegmentFem(n) {
   if (n === 0) return ''
 
   const onesDigit = n % 10
@@ -145,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])
   }
 
@@ -156,7 +184,13 @@ function buildSegmentFem (n) {
 // Conversion Functions
 // ============================================================================
 
-function integerToWords (n, gender) {
+/**
+ * Converts a non-negative integer to Serbian words.
+ * @param {bigint} n - The integer to convert
+ * @param {('masculine'|'feminine')} gender - Grammatical gender
+ * @returns {string} The integer in words
+ */
+function integerToWords(n, gender) {
   if (n === 0n) return ZERO
 
   if (n < 1000n) {
@@ -166,7 +200,13 @@ function integerToWords (n, gender) {
   return buildLargeNumberWords(n, gender)
 }
 
-function buildLargeNumberWords (n, gender) {
+/**
+ * Builds words for integers >= 1000 using scale decomposition.
+ * @param {bigint} n - The integer to convert (>= 1000)
+ * @param {('masculine'|'feminine')} gender - Grammatical gender
+ * @returns {string} The integer in words
+ */
+function buildLargeNumberWords(n, gender) {
   const numStr = n.toString()
   const len = numStr.length
 
@@ -193,11 +233,12 @@ 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
-        const isFeminine = scaleIndex === 1
+        // -arda scale words (hiljada, milijarda, ...) are feminine; -ion words masculine
+        const isFeminine = scaleIndex % 2 === 1
         const segmentWord = isFeminine ? buildSegmentFem(segment) : buildSegmentMasc(segment)
         parts.push(segmentWord + ' ' + scaleWord)
       }
@@ -209,7 +250,13 @@ function buildLargeNumberWords (n, gender) {
   return parts.join(' ')
 }
 
-function decimalPartToWords (decimalPart, gender) {
+/**
+ * Converts the decimal-part digit string to Serbian words.
+ * @param {string} decimalPart - The decimal digits as a string
+ * @param {('masculine'|'feminine')} gender - Grammatical gender
+ * @returns {string} The decimal part in words
+ */
+function decimalPartToWords(decimalPart, gender) {
   let result = ''
   let i = 0
 
@@ -228,20 +275,31 @@ function decimalPartToWords (decimalPart, gender) {
   return result
 }
 
+/**
+ * @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 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
  */
-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 = ''
 
@@ -265,11 +323,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
@@ -300,11 +357,10 @@ function buildOrdinalTensOnes (n) {
  *
  * In Serbian ordinals, only the LAST component becomes ordinal.
  * E.g., 121 = "сто двадесет први" (one hundred twenty first)
- *
  * @param {bigint} n - Positive integer to convert
  * @returns {string} Ordinal Serbian words
  */
-function integerToOrdinal (n) {
+function integerToOrdinal(n) {
   // Fast path: numbers < 100
   if (n < 100n) {
     return buildOrdinalTensOnes(Number(n))
@@ -352,11 +408,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 Serbian words
  */
-function buildLargeOrdinal (n) {
+function buildLargeOrdinal(n) {
   const numStr = n.toString()
   const len = numStr.length
 
@@ -394,26 +449,30 @@ 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 isFeminine = scaleIndex % 2 === 1 // feminine at -arda scales (hiljada, milijarda, ...)
             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)
-          const isFeminine = scaleIndex === 1
+          const isFeminine = scaleIndex % 2 === 1
           const segmentWord = isFeminine ? buildSegmentFem(segment) : buildSegmentMasc(segment)
           parts.push(segmentWord + ' ' + scaleWord)
         }
@@ -428,12 +487,10 @@ function buildLargeOrdinal (n) {
 
 /**
  * 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)    // 'други'
@@ -443,8 +500,9 @@ function buildLargeOrdinal (n) {
  * toOrdinal(100)  // 'стоти'
  * toOrdinal(1000) // 'хиљадити'
  */
-function toOrdinal (value) {
+function toOrdinal(value) {
   const integerPart = parseOrdinalValue(value)
+  checkMax(integerPart, ordinalMax)
   return integerToOrdinal(integerPart)
 }
 
@@ -452,16 +510,21 @@ function toOrdinal (value) {
 // CURRENCY: toCurrency(value, options?)
 // ============================================================================
 
+/**
+ * @typedef {object} CurrencyOptions
+ * @property {boolean} [and] - Use "и" between dinars and para
+ */
+
+/** @type {Required<CurrencyOptions>} */
+export const currencyDefaults = { and: true }
+
 /**
  * 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)                        // 'један динар'
@@ -469,10 +532,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: dinars, cents: para } = parseCurrencyValue(value)
-  const { and: useAnd = true } = options
+  checkMax(dinars, currencyMax)
+  const { and: useAnd } = resolveOptions(options, currencyDefaults)
 
   // Build result
   let result = ''

package/src/sr-Latn-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 "i" 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 "i" between dinars and para
+     */
+    and?: boolean | undefined;
+};
 /**
  * Converts a numeric value to Serbian (Latin) 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 Latin 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., "prvi", "četrdeset drugi")
  * @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)    // 'prvi'
  * toOrdinal(2)    // 'drugi'
@@ -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 "i" 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)                    // 'četrdeset dva dinara i pedeset para'
  * toCurrency(1)                        // 'jedan dinar'
@@ -44,6 +66,4 @@ export function toOrdinal(value: number | string | bigint): string;
  * toCurrency(0.01)                     // 'jedna para'
  * toCurrency(42.50, { and: false })    // 'četrdeset dva dinara pedeset para'
  */
-export function toCurrency(value: number | string | bigint, options?: {
-    and?: boolean | undefined;
-}): string;
+export function toCurrency(value: number | string | bigint, options?: CurrencyOptions): string;