n2words 1.23.1 → 1.24.0

package/lib/languages/da.js

@@ -0,0 +1,167 @@
+import GreedyScaleLanguage from '../classes/greedy-scale-language.js'
+
+/**
+ * @typedef {Object} DanishOptions
+ * @property {boolean} [ordFlag=false] Enable ordinal number conversion.
+ */
+
+/**
+ * Danish language converter.
+ *
+ * GreedyScaleLanguage with Danish-specific extensions:
+ * - Unique vigesimal (base-20) number system for 50-90
+ * - Special composition rules ("og" for "and" between units and tens)
+ * - Reverse digit order (e.g., "fem-og-tyve" = five-and-twenty = 25)
+ * - Support for ordinal numbers via ordFlag option
+ *
+ * Key Features:
+ * - Vigesimal tens: halvtreds (50), treds (60), halvfjerds (70), firs (80), halvfems (90)
+ * - Units-before-tens pattern (e.g., "tre-og-tyve" = 23)
+ * - "et" prefix for hundreds/thousands (not "en")
+ * - Optional ordinal number conversion via ordFlag option
+ * - Inline merge logic tailored for Danish ordering
+ */
+export class Danish extends GreedyScaleLanguage {
+  negativeWord = 'minus'
+  decimalSeparatorWord = 'komma'
+  zeroWord = 'nul'
+  scaleWordPairs = [
+    [1_000_000_000_000_000_000_000_000_000n, 'quadrillarder'],
+    [1_000_000_000_000_000_000_000_000n, 'quadrillioner'],
+    [1_000_000_000_000_000_000_000n, 'trillarder'],
+    [1_000_000_000_000_000_000n, 'trillioner'],
+    [1_000_000_000_000_000n, 'billarder'],
+    [1_000_000_000_000n, 'billioner'],
+    [1_000_000_000n, 'millarder'],
+    [1_000_000n, 'millioner'],
+    [1000n, 'tusind'],
+    [100n, 'hundrede'],
+    [90n, 'halvfems'],
+    [80n, 'firs'],
+    [70n, 'halvfjerds'],
+    [60n, 'treds'],
+    [50n, 'halvtreds'],
+    [40n, 'fyrre'],
+    [30n, 'tredive'],
+    [20n, 'tyve'],
+    [19n, 'nitten'],
+    [18n, 'atten'],
+    [17n, 'sytten'],
+    [16n, 'seksten'],
+    [15n, 'femten'],
+    [14n, 'fjorten'],
+    [13n, 'tretten'],
+    [12n, 'tolv'],
+    [11n, 'elleve'],
+    [10n, 'ti'],
+    [9n, 'ni'],
+    [8n, 'otte'],
+    [7n, 'syv'],
+    [6n, 'seks'],
+    [5n, 'fem'],
+    [4n, 'fire'],
+    [3n, 'tre'],
+    [2n, 'to'],
+    [1n, 'et'],
+    [0n, 'nul']
+  ]
+
+  /**
+   * Initializes the Danish converter with language-specific options.
+   *
+   * @param {DanishOptions} [options={}] Configuration options.
+   */
+  constructor ({ ordFlag = false } = {}) {
+    super()
+
+    this.ordFlag = ordFlag
+  }
+
+  /**
+   * Merges two adjacent word-number pairs according to Danish grammar rules.
+   * Danish uses complex vigesimal (base-20) patterns and reverse digit ordering.
+   *
+   * Key Danish patterns:
+   * - Vigesimal tens: halvtreds(50), treds(60), halvfjerds(70), firs(80), halvfems(90)
+   * - Units-before-tens order with "og" (and): "tre-og-tyve" (3 and 20 = 25)
+   * - "et" prefix for hundreds/thousands (not "en")
+   * - Space separators for large magnitudes (≥ millions)
+   * - Ordinal support via this.ordFlag
+   *
+   * @param {Object} current The left operand as `{ word: bigint }`.
+   * @param {Object} next The right operand as `{ word: bigint }`.
+   * @returns {Object} Merged pair with combined word and resulting number (bigint).
+   */
+  mergeScales (current, next) {
+    let cText = Object.keys(current)[0]
+    let nText = Object.keys(next)[0]
+    const cNumber = Object.values(current)[0] // BigInt (e.g., 1n, 100n, 1000n)
+    const nNumber = Object.values(next)[0] // BigInt (e.g., magnitude level like 100n, 1000n)
+
+    // Prepend "et" to hundreds and thousands (not "en") for proper Danish form
+    if (nNumber === 100n || nNumber === 1000n) {
+      next = { [`et${nText}`]: nNumber }
+    }
+
+    // Implicit '1' handling: omit '1' before most magnitudes (except millions/ordinals)
+    if (cNumber === 1n) {
+      if (nNumber < 1_000_000n || this.ordFlag) {
+        return next // Just the magnitude word (e.g., "hundrede" not "en hundrede")
+      }
+      cText = 'en' // Explicit "en" (one) for millions and above
+    }
+
+    // Multiplication across magnitude boundaries
+    if (nNumber > cNumber) {
+      // Space for million+ (e.g., "en million", "to millioner")
+      if (nNumber >= 1_000_000n) {
+        cText += ' '
+      }
+      return { [`${cText}${nText}`]: cNumber * nNumber }
+    }
+
+    // Addition with separator rules:
+    // "og" (and) for hundreds + smaller numbers
+    if (cNumber >= 100n && cNumber < 1000n) {
+      cText += ' og '
+    } else if (cNumber >= 1000n && cNumber <= 100_000n) {
+      // Special "e og" for thousands (e.g., "tusinde og tyve")
+      cText += 'e og '
+    }
+
+    // Units-before-tens reversal (Danish vigesimal pattern):
+    // For small units (< 10) with tens (10-99), swap order: "tre og tyve" (25)
+    if (nNumber < 10n && cNumber > 10n && cNumber < 100n) {
+      if (nNumber === 1n) {
+        nText = 'en' // Convert 1 to "en" for vigesimal context
+      }
+      // Swap positions: units go after "og", tens go before
+      const temporary = nText
+      nText = cText
+      cText = temporary + 'og'
+    } else if (cNumber >= 1_000_000n) {
+      // Space for large magnitudes (millions+)
+      cText += ' '
+    }
+
+    return { [`${cText}${nText}`]: cNumber + nNumber }
+  }
+}
+
+/**
+ * Converts a number to Danish cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {Object} [options] Conversion options (see Danish class options).
+ * @param {boolean} [options.ordFlag=false] Enable ordinal number conversion.
+ * @returns {string} The number expressed in Danish words.
+ * @throws {TypeError} If value is NaN or invalid type.
+ * @throws {Error} If value is an invalid number string.
+ *
+ * @example
+ * convertToWords(25); // 'femogtyve' (five-and-twenty)
+ * convertToWords(50); // 'halvtreds' (half-third-times-twenty)
+ */
+export default function convertToWords (value, options = {}) {
+  return new Danish(options).convertToWords(value)
+}

package/lib/languages/de.js

@@ -0,0 +1,135 @@
+import GreedyScaleLanguage from '../classes/greedy-scale-language.js'
+
+/**
+ * German language converter.
+ *
+ * Handles German grammatical features:
+ * - "eins" vs "ein" and "eine" forms for 1
+ * - Compound words without separators (e.g., "einundzwanzig" = 21)
+ * - Million/Billion pluralization
+ * - Special characters (e.g., "ü", "ö", "ß")
+ */
+export class German extends GreedyScaleLanguage {
+  negativeWord = 'minus'
+  decimalSeparatorWord = 'komma'
+  zeroWord = 'null'
+  scaleWordPairs = [
+    [1_000_000_000_000_000_000_000_000_000n, 'Quadrilliarde'],
+    [1_000_000_000_000_000_000_000_000n, 'Quadrillion'],
+    [1_000_000_000_000_000_000_000n, 'Trilliarde'],
+    [1_000_000_000_000_000_000n, 'Trillion'],
+    [1_000_000_000_000_000n, 'Billiarde'],
+    [1_000_000_000_000n, 'Billion'],
+    [1_000_000_000n, 'Milliarde'],
+    [1_000_000n, 'Million'],
+    [1000n, 'tausend'],
+    [100n, 'hundert'],
+    [90n, 'neunzig'],
+    [80n, 'achtzig'],
+    [70n, 'siebzig'],
+    [60n, 'sechzig'],
+    [50n, 'fünfzig'],
+    [40n, 'vierzig'],
+    [30n, 'dreißig'],
+    [20n, 'zwanzig'],
+    [19n, 'neunzehn'],
+    [18n, 'achtzehn'],
+    [17n, 'siebzehn'],
+    [16n, 'sechzehn'],
+    [15n, 'fünfzehn'],
+    [14n, 'vierzehn'],
+    [13n, 'dreizehn'],
+    [12n, 'zwölf'],
+    [11n, 'elf'],
+    [10n, 'zehn'],
+    [9n, 'neun'],
+    [8n, 'acht'],
+    [7n, 'sieben'],
+    [6n, 'sechs'],
+    [5n, 'fünf'],
+    [4n, 'vier'],
+    [3n, 'drei'],
+    [2n, 'zwei'],
+    [1n, 'eins'],
+    [0n, 'null']
+  ]
+
+  /**
+   * Merges two adjacent word-number pairs according to German grammar rules.
+   *
+   * German-specific rules:
+   * - Implicit "eins": `mergeScales({ 'eins': 1n }, { 'hundert': 100n })` → `{ 'einhundert': 100n }`
+   * - Compound words without separators (e.g., "einundzwanzig" = 21)
+   * - Special handling for forms of 1 (eins/ein/eine) depending on context
+   * - Pluralization of millions and higher: "Millionen", "Milliarden"
+   * - Reordering of tens and units: `mergeScales({ 'zwanzig': 20n }, { 'eins': 1n })` → `{ 'einundzwanzig': 21n }`
+   *
+   * @param {Object} currentPair The left operand as `{ word: BigInt }`.
+   * @param {Object} nextPair The right operand as `{ word: BigInt }`.
+   * @returns {Object} Merged pair with combined word and resulting numeric value.
+   *
+   * @example
+   * mergeScales({ 'eins': 1n }, { 'hundert': 100n }); // { 'einhundert': 100n }
+   * mergeScales({ 'zwanzig': 20n }, { 'drei': 3n }); // { 'dreiundzwanzig': 23n }
+   */
+  mergeScales (currentPair, nextPair) {
+    let currentWord = Object.keys(currentPair)[0]
+    let nextWord = Object.keys(nextPair)[0]
+    const currentNumber = Object.values(currentPair)[0]
+    const nextNumber = Object.values(nextPair)[0]
+
+    // Handle form of 1: "eins" → "ein(e)" in certain contexts
+    if (currentNumber === 1n) {
+      if (nextNumber === 100n || nextNumber === 1000n) {
+        return { [`ein${nextWord}`]: nextNumber }
+      }
+      if (nextNumber < 1_000_000n) {
+        return nextPair
+      }
+      currentWord = 'eine'
+    }
+
+    if (nextNumber > currentNumber) {
+      // Multiply: apply pluralization rules for millions
+      if (nextNumber >= 1_000_000n) {
+        if (currentNumber > 1n) {
+          nextWord += nextWord.at(-1) === 'e' ? 'n' : 'en'
+        }
+        currentWord += ' '
+      }
+      return { [`${currentWord}${nextWord}`]: currentNumber * nextNumber }
+    }
+
+    // Add: handle special case of tens + units
+    if (nextNumber < 10n && currentNumber > 10n && currentNumber < 100n) {
+      // German reverses tens and units (einundzwanzig = one and twenty)
+      if (nextNumber === 1n) {
+        nextWord = 'ein'
+      }
+      const temp = nextWord
+      nextWord = currentWord
+      currentWord = `${temp}und`
+    } else if (currentNumber >= 1_000_000n) {
+      currentWord += ' '
+    }
+
+    return { [`${currentWord}${nextWord}`]: currentNumber + nextNumber }
+  }
+}
+
+/**
+ * Converts a number to German cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {Object} [options] Conversion options (see German class options).
+ * @returns {string} The number expressed in German words.
+ * @throws {TypeError} If value is NaN or invalid type.
+ * @throws {Error} If value is an invalid number string.
+ *
+ * @example
+ * convertToWords(42); // 'zweiundvierzig'
+ * convertToWords('1.5'); // 'eins komma fünf'
+ */
+export default function convertToWords (value, options = {}) {
+  return new German(options).convertToWords(value)
+}

package/lib/languages/el.js

@@ -0,0 +1,116 @@
+/**
+ * Converts numbers to their word representation in Greek (Ελληνικά).
+ * @module languages/el
+ */
+
+import GreedyScaleLanguage from '../classes/greedy-scale-language.js'
+
+/**
+ * Greek language implementation using scale-based number conversion.
+ * @extends GreedyScaleLanguage
+ */
+class GreekLanguage extends GreedyScaleLanguage {
+  negativeWord = 'μείον'
+  decimalSeparatorWord = 'κόμμα'
+  zeroWord = 'μηδέν'
+  convertDecimalsPerDigit = true
+
+  scaleWordPairs = [
+    // Large numbers (limited set for now)
+    [1_000_000_000n, 'δισεκατομμύριο'],
+    [1_000_000n, 'εκατομμύριο'],
+    [1000n, 'χίλια'],
+
+    // Hundreds
+    [900n, 'εννιακόσια'],
+    [800n, 'οκτακόσια'],
+    [700n, 'επτακόσια'],
+    [600n, 'εξακόσια'],
+    [500n, 'πεντακόσια'],
+    [400n, 'τετρακόσια'],
+    [300n, 'τριακόσια'],
+    [200n, 'διακόσια'],
+    [100n, 'εκατό'],
+
+    // Tens
+    [90n, 'ενενήντα'],
+    [80n, 'ογδόντα'],
+    [70n, 'εβδομήντα'],
+    [60n, 'εξήντα'],
+    [50n, 'πενήντα'],
+    [40n, 'σαράντα'],
+    [30n, 'τριάντα'],
+    [20n, 'είκοσι'],
+    [19n, 'δεκαεννέα'],
+    [18n, 'δεκαοκτώ'],
+    [17n, 'δεκαεπτά'],
+    [16n, 'δεκαέξι'],
+    [15n, 'δεκαπέντε'],
+    [14n, 'δεκατέσσερα'],
+    [13n, 'δεκατρία'],
+    [12n, 'δώδεκα'],
+    [11n, 'έντεκα'],
+    [10n, 'δέκα'],
+
+    // Singles
+    [9n, 'εννέα'],
+    [8n, 'οκτώ'],
+    [7n, 'επτά'],
+    [6n, 'έξι'],
+    [5n, 'πέντε'],
+    [4n, 'τέσσερα'],
+    [3n, 'τρία'],
+    [2n, 'δύο'],
+    [1n, 'ένα'],
+    [0n, 'μηδέν']
+  ]
+
+  /**
+   * Merges two adjacent word-number pairs according to Greek grammar rules.
+   *
+   * Greek-specific rules:
+   * - Implicit "one": χίλια (thousand), not ένα χίλια
+   * - Space-separated composites
+   * - Multiplication for scales (e.g., δύο χίλια = two thousand)
+   *
+   * @param {Object} leftPair - Left word-number pair (e.g., { 'δύο': 2n })
+   * @param {Object} rightPair - Right word-number pair (e.g., { 'χίλια': 1000n })
+   * @returns {Object} Merged word-number pair
+   */
+  mergeScales (leftPair, rightPair) {
+    const leftWord = Object.keys(leftPair)[0]
+    const leftNumber = Object.values(leftPair)[0]
+    const rightWord = Object.keys(rightPair)[0]
+    const rightNumber = Object.values(rightPair)[0]
+
+    // Implicit one: omit "ένα" before any following value (> 0)
+    if (leftNumber === 1n) {
+      return rightPair
+    }
+
+    // No special handling needed for trailing 'ένα';
+    // nested merge will first collapse {1, 'ένα'} -> 'ένα'.
+
+    // Multiplication: larger right scale multiplied by left number
+    if (rightNumber > leftNumber) {
+      return { [`${leftWord} ${rightWord}`]: leftNumber * rightNumber }
+    }
+
+    // Addition: smaller numbers added together
+    return { [`${leftWord} ${rightWord}`]: leftNumber + rightNumber }
+  }
+}
+
+/**
+ * Converts a number to its word representation in Greek.
+ * @param {number|string|bigint} value - The number to convert
+ * @param {Object} [options={}] - Conversion options
+ * @returns {string} The word representation of the number
+ * @example
+ * convertToWords(42) // 'σαράντα δύο'
+ * convertToWords(1000) // 'χίλια'
+ * convertToWords(2000) // 'δύο χίλια'
+ */
+export default function convertToWords (value, options = {}) {
+  return new GreekLanguage(options).convertToWords(value)
+}

package/lib/languages/en.js

@@ -0,0 +1,123 @@
+import GreedyScaleLanguage from '../classes/greedy-scale-language.js'
+
+/**
+ * English language converter.
+ *
+ * Converts numbers to English words, supporting:
+ * - Negative numbers (prepended with "minus")
+ * - Decimal numbers (word "point" between whole and fractional parts)
+ * - Numbers up to octillions
+ *
+ * Merge rules:
+ * - Hyphenated for compound tens (e.g., "twenty-three")
+ * - "and" after hundreds (e.g., "one hundred and one")
+ * - Space-separated for larger composites (e.g., "one thousand twenty-three")
+ */
+export class English extends GreedyScaleLanguage {
+  negativeWord = 'minus'
+  decimalSeparatorWord = 'point'
+  zeroWord = 'zero'
+  scaleWordPairs = [
+    [1_000_000_000_000_000_000_000_000_000n, 'octillion'],
+    [1_000_000_000_000_000_000_000_000n, 'septillion'],
+    [1_000_000_000_000_000_000_000n, 'sextillion'],
+    [1_000_000_000_000_000_000n, 'quintillion'],
+    [1_000_000_000_000_000n, 'quadrillion'],
+    [1_000_000_000_000n, 'trillion'],
+    [1_000_000_000n, 'billion'],
+    [1_000_000n, 'million'],
+    [1000n, 'thousand'],
+    [100n, 'hundred'],
+    [90n, 'ninety'],
+    [80n, 'eighty'],
+    [70n, 'seventy'],
+    [60n, 'sixty'],
+    [50n, 'fifty'],
+    [40n, 'forty'],
+    [30n, 'thirty'],
+    [20n, 'twenty'],
+    [19n, 'nineteen'],
+    [18n, 'eighteen'],
+    [17n, 'seventeen'],
+    [16n, 'sixteen'],
+    [15n, 'fifteen'],
+    [14n, 'fourteen'],
+    [13n, 'thirteen'],
+    [12n, 'twelve'],
+    [11n, 'eleven'],
+    [10n, 'ten'],
+    [9n, 'nine'],
+    [8n, 'eight'],
+    [7n, 'seven'],
+    [6n, 'six'],
+    [5n, 'five'],
+    [4n, 'four'],
+    [3n, 'three'],
+    [2n, 'two'],
+    [1n, 'one'],
+    [0n, 'zero']
+  ]
+
+  /**
+   * Merges two adjacent word-number pairs according to English grammar rules.
+   *
+   * English-specific rules:
+   * - Implicit "one": `mergeScales({ 'one': 1n }, { 'hundred': 100n })` → `{ 'one hundred': 100n }`
+   * - Hyphenated compounds: `mergeScales({ 'twenty': 20n }, { 'three': 3n })` → `{ 'twenty-three': 23n }`
+   * - "and" after hundreds: `mergeScales({ 'one hundred': 100n }, { 'one': 1n })` → `{ 'one hundred and one': 101n }`
+   * - Multiplication: `mergeScales({ 'one': 1n }, { 'thousand': 1000n })` → `{ 'one thousand': 1000n }`
+   *
+   * @param {Object} leftPair Left word-set as `{ word: BigInt }`.
+   * @param {Object} rightPair Right word-set as `{ word: BigInt }`.
+   * @returns {Object} Merged pair with combined word and resulting numeric value.
+   *
+   * @example
+   * mergeScales({ 'one': 1n }, { 'hundred': 100n }); // { 'one hundred': 100n }
+   * mergeScales({ 'twenty': 20n }, { 'three': 3n }); // { 'twenty-three': 23n }
+   */
+  mergeScales (leftPair, rightPair) {
+    const leftWord = Object.keys(leftPair)[0]
+    const leftNumber = Object.values(leftPair)[0]
+    const rightWord = Object.keys(rightPair)[0]
+    const rightNumber = Object.values(rightPair)[0]
+
+    // Rule 1: Implicit "one" - omit when multiplying ("one hundred" → "hundred")
+    if (leftNumber === 1n && rightNumber < 100n) {
+      return { [rightWord]: rightNumber }
+    }
+
+    // Rule 2: Hyphenate compounds under 100 ("twenty-three")
+    if (leftNumber < 100n && leftNumber > rightNumber) {
+      return { [`${leftWord}-${rightWord}`]: leftNumber + rightNumber }
+    }
+
+    // Rule 3: Add "and" before units after hundreds ("one hundred and one")
+    if (leftNumber >= 100n && rightNumber < 100n) {
+      return { [`${leftWord} and ${rightWord}`]: leftNumber + rightNumber }
+    }
+
+    // Rule 4: Multiply when right > left ("one thousand")
+    if (rightNumber > leftNumber) {
+      return { [`${leftWord} ${rightWord}`]: leftNumber * rightNumber }
+    }
+
+    return { [`${leftWord} ${rightWord}`]: leftNumber + rightNumber }
+  }
+}
+
+/**
+ * Converts a number to English cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {Object} [options] Conversion options (see English class options).
+ * @returns {string} The number expressed in English words.
+ * @throws {TypeError} If value is NaN or invalid type.
+ * @throws {Error} If value is an invalid number string.
+ *
+ * @example
+ * convertToWords(42); // 'forty-two'
+ * convertToWords('1.5'); // 'one point five'
+ */
+export default function convertToWords (value, options = {}) {
+  return new English(options).convertToWords(value)
+}

package/lib/languages/es.js

@@ -0,0 +1,153 @@
+import GreedyScaleLanguage from '../classes/greedy-scale-language.js'
+
+/**
+ * @typedef {Object} SpanishOptions
+ * @property {string} [genderStem='o'] Masculine 'o' or feminine 'a' ending.
+ */
+
+/**
+ * Spanish language converter.
+ *
+ * Handles Spanish grammatical features:
+ * - Gender agreement for numbers (masculine by default, feminine via `genderStem`)
+ * - "y" (and) between tens and units (e.g., "veinte y uno")
+ * - Special forms for hundreds (e.g., "cien", "ciento", "doscientos")
+ * - Million pluralization
+ */
+export class Spanish extends GreedyScaleLanguage {
+  negativeWord = 'menos'
+  decimalSeparatorWord = 'punto'
+  zeroWord = 'cero'
+  scaleWordPairs = [
+    [1_000_000_000_000_000_000_000_000n, 'cuatrillón'],
+    [1_000_000_000_000_000_000n, 'trillón'],
+    [1_000_000_000_000n, 'billón'],
+    [1_000_000n, 'millón'],
+    [1000n, 'mil'],
+    [100n, 'cien'],
+    [90n, 'noventa'],
+    [80n, 'ochenta'],
+    [70n, 'setenta'],
+    [60n, 'sesenta'],
+    [50n, 'cincuenta'],
+    [40n, 'cuarenta'],
+    [30n, 'treinta'],
+    [29n, 'veintinueve'],
+    [28n, 'veintiocho'],
+    [27n, 'veintisiete'],
+    [26n, 'veintiséis'],
+    [25n, 'veinticinco'],
+    [24n, 'veinticuatro'],
+    [23n, 'veintitrés'],
+    [22n, 'veintidós'],
+    [21n, 'veintiuno'],
+    [20n, 'veinte'],
+    [19n, 'diecinueve'],
+    [18n, 'dieciocho'],
+    [17n, 'diecisiete'],
+    [16n, 'dieciseis'],
+    [15n, 'quince'],
+    [14n, 'catorce'],
+    [13n, 'trece'],
+    [12n, 'doce'],
+    [11n, 'once'],
+    [10n, 'diez'],
+    [9n, 'nueve'],
+    [8n, 'ocho'],
+    [7n, 'siete'],
+    [6n, 'seis'],
+    [5n, 'cinco'],
+    [4n, 'cuatro'],
+    [3n, 'tres'],
+    [2n, 'dos'],
+    [1n, 'uno'],
+    [0n, 'cero']
+  ]
+
+  /**
+   * Initializes the Spanish converter.
+   *
+   * @param {SpanishOptions} [options={}] Configuration options.
+   */
+  constructor ({ genderStem = 'o' } = {}) {
+    super()
+
+    this.genderStem = genderStem
+  }
+
+  /**
+   * Merges two adjacent word-number pairs according to Spanish grammar rules.
+   *
+   * Spanish-specific rules:
+   * - Implicit "uno": `mergeScales({ 'uno': 1n }, { 'mil': 1000n })` → `{ 'mil': 1000n }`
+   * - "y" (and) between tens and units: `mergeScales({ 'veinte': 20n }, { 'uno': 1n })` → `{ 'veinte y uno': 21n }`
+   * - Gender agreement for hundreds: "cien" + suffix based on genderStem
+   * - Special forms for hundreds (cien/ciento/quinientos/setecientos/novecientos)
+   * - Million pluralization when coefficient > 1: "millones" instead of "millón"
+   *
+   * @param {Object} currentPair The left operand as `{ word: BigInt }`.
+   * @param {Object} nextPair The right operand as `{ word: BigInt }`.
+   * @returns {Object} Merged pair with combined word and resulting numeric value.
+   *
+   * @example
+   * mergeScales({ 'uno': 1n }, { 'mil': 1000n }); // { 'mil': 1000n }
+   * mergeScales({ 'veinte': 20n }, { 'tres': 3n }); // { 'veinte y tres': 23n }
+   */
+  mergeScales (currentPair, nextPair) {
+    let currentWord = Object.keys(currentPair)[0]
+    let nextWord = Object.keys(nextPair)[0]
+    const currentNumber = Object.values(currentPair)[0]
+    const nextNumber = Object.values(nextPair)[0]
+
+    if (currentNumber === 1n) {
+      if (nextNumber < 1_000_000n) return nextPair
+      currentWord = 'un'
+    } else if (currentNumber === 100n && nextNumber % 1000n !== 0n) {
+      currentWord += 't' + this.genderStem
+    }
+
+    if (nextNumber < currentNumber) {
+      if (currentNumber < 100n) {
+        return { [`${currentWord} y ${nextWord}`]: currentNumber + nextNumber }
+      }
+      return { [`${currentWord} ${nextWord}`]: currentNumber + nextNumber }
+    }
+
+    if (nextNumber % 1_000_000n === 0n && currentNumber > 1n) {
+      nextWord = nextWord.slice(0, -3) + 'lones'
+    }
+
+    if (nextNumber === 100n) {
+      if (currentNumber === 5n) {
+        currentWord = 'quinien'
+        nextWord = ''
+      } else if (currentNumber === 7n) {
+        currentWord = 'sete'
+      } else if (currentNumber === 9n) {
+        currentWord = 'nove'
+      }
+      nextWord += 't' + this.genderStem + 's'
+    } else {
+      nextWord = ' ' + nextWord
+    }
+
+    return { [`${currentWord}${nextWord}`]: currentNumber * nextNumber }
+  }
+}
+
+/**
+ * Converts a number to Spanish cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {Object} [options] Conversion options (see ES class).
+ * @returns {string} The number expressed in Spanish words.
+ * @throws {TypeError} If value is NaN or invalid type.
+ * @throws {Error} If value is an invalid number string.
+ *
+ * @example
+ * convertToWords(42, { lang: 'es' }); // 'cuarenta y dos'
+ * convertToWords(100, { lang: 'es' }); // 'cien'
+ */
+export default function convertToWords (value, options = {}) {
+  return new Spanish(options).convertToWords(value)
+}