n2words 2.0.0 → 3.1.0

package/lib/classes/abstract-language.js

@@ -1,268 +0,0 @@
-/**
- * Abstract base class for language converters.
- *
- * This class provides the framework for converting numbers to words in any language.
- * It handles the common conversion flow while delegating language-specific logic to subclasses.
- *
- * ## Responsibilities
- *
- * - Receives pre-validated and normalized input from the public API (n2words.js)
- * - Handles negative number prefixing via `negativeWord`
- * - Converts decimals via `decimalDigitsToWords()`, preserving leading zeros
- * - Delegates integer conversion to `integerToWords()` (implemented by subclasses)
- *
- * ## Required Subclass Implementation
- *
- * Subclasses MUST provide:
- * - `integerToWords(integerPart)` - Core conversion logic (abstract method)
- * - `negativeWord` - Word preceding negative numbers (e.g., "minus"))
- * - `zeroWord` - Word for the digit 0 (e.g., "zero")
- * - `decimalSeparatorWord` - Word between whole and decimal parts (e.g., "point")
- *
- * ## Optional Overrides
- *
- * Subclasses MAY override:
- * - `wordSeparator` - Character(s) between words (default: space, empty for CJK languages)
- * - `usePerDigitDecimals` - Enable per-digit decimal mode (default: false)
- * - `decimalIntegerToWords()` - Custom decimal conversion (e.g., Romanian masculine forms)
- * - `decimalDigitsToWords()` - Complete decimal conversion override
- * - `toWords()` - Override to capture integerPart for context-dependent rules (e.g., Czech)
- *
- * ## Input Contract
- *
- * Input validation and normalization happen at the public API boundary (n2words.js).
- * This class assumes it receives clean, pre-processed data via `toWords()`.
- *
- * @abstract
- */
-export class AbstractLanguage {
-  // ============================================================================
-  // Private Fields
-  // ============================================================================
-
-  /**
-   * Private storage for options.
-   * @type {Object}
-   */
-  #options = {}
-
-  // ============================================================================
-  // Required Properties (subclasses must define)
-  // ============================================================================
-
-  /**
-   * Word that precedes negative numbers (e.g., "minus", "negative", "moins").
-   * @type {string}
-   */
-  negativeWord = ''
-
-  /**
-   * Word that separates integer and decimal parts (e.g., "point", "virgule", "comma").
-   * @type {string}
-   */
-  decimalSeparatorWord = ''
-
-  /**
-   * Word representation for the digit 0 (e.g., "zero", "zéro", "null").
-   * Used for zero values and leading zeros in decimals.
-   * @type {string}
-   */
-  zeroWord = ''
-
-  // ============================================================================
-  // Optional Properties (subclasses may override)
-  // ============================================================================
-
-  /**
-   * Character(s) used to separate words in the output.
-   *
-   * Defaults to a single space. Set to empty string for languages without
-   * word separators (e.g., Japanese, Thai, Chinese).
-   *
-   * @type {string}
-   */
-  wordSeparator = ' '
-
-  /**
-   * Whether to convert decimal digits individually rather than grouped.
-   *
-   * - `false` (default): Leading zeros preserved, remaining digits grouped as a number
-   *   - Example: "05" → ["zero", "five"], "14" → ["fourteen"]
-   *   - Used by: English, Spanish, French, German, etc.
-   *
-   * - `true`: Each digit converted separately
-   *   - Example: "05" → ["zero", "five"], "14" → ["one", "four"]
-   *   - Used by: Japanese, Thai, Tamil, Telugu, Greek, Hebrew, Filipino
-   *
-   * @type {boolean}
-   */
-  usePerDigitDecimals = false
-
-  // ============================================================================
-  // Public Accessors
-  // ============================================================================
-
-  /**
-   * Read-only access to options set via `setOptions()`.
-   * @type {Object}
-   */
-  get options () {
-    return this.#options
-  }
-
-  // ============================================================================
-  // Public Methods
-  // ============================================================================
-
-  /**
-   * Converts pre-normalized numeric components to words.
-   *
-   * This is the main entry point called by the public API (makeConverter in n2words.js).
-   * It assembles the final word representation from the provided components.
-   *
-   * **Caller contract (enforced by makeConverter):**
-   * - `integerPart` is a non-negative BigInt (>= 0n)
-   * - `decimalPart` is a string of digits only (no sign, no decimal point)
-   * - `isNegative` reflects the original input sign
-   *
-   * **Conversion flow:**
-   * 1. Prepend negative word if applicable
-   * 2. Convert integer part via `integerToWords()`
-   * 3. If decimals present: append separator and decimal words
-   * 4. Join all parts with `wordSeparator`
-   *
-   * Subclasses needing access to the integer part during decimal conversion
-   * (e.g., for context-dependent separator words) should override this
-   * method to cache the value before calling super.toWords().
-   *
-   * @public
-   * @param {boolean} isNegative Whether the original number was negative
-   * @param {bigint} integerPart The integer part (always non-negative)
-   * @param {string} [decimalPart] - Decimal digits if present (e.g., "14" for 3.14)
-   * @returns {string} The localized cardinal string
-   */
-  toWords (isNegative, integerPart, decimalPart) {
-    const words = []
-
-    if (isNegative) words.push(this.negativeWord)
-
-    words.push(this.integerToWords(integerPart))
-
-    if (decimalPart) {
-      words.push(this.decimalSeparatorWord)
-      words.push(...this.decimalDigitsToWords(decimalPart))
-    }
-
-    return words.join(this.wordSeparator)
-  }
-
-  // ============================================================================
-  // Abstract Methods (subclasses must implement)
-  // ============================================================================
-
-  /**
-   * Converts a BigInt integer part to its cardinal word representation.
-   *
-   * This is the core template method that subclasses MUST implement to provide
-   * language-specific number conversion logic.
-   *
-   * @abstract
-   * @param {bigint} integerPart The integer part to convert (always >= 0n)
-   * @returns {string} The cardinal representation in the target language
-   * @throws {Error} If not implemented by subclass
-   */
-  integerToWords (integerPart) {
-    throw new Error('integerToWords() must be implemented by subclass')
-  }
-
-  // ============================================================================
-  // Protected Methods (subclasses may override or call)
-  // ============================================================================
-
-  /**
-   * Sets options by merging language defaults with user-provided options.
-   *
-   * Merges defaults first, then user options (later keys override earlier ones).
-   * Stores the result in the private `#options` field, accessible via the
-   * read-only `options` getter.
-   *
-   * @protected
-   * @param {Object} [defaults={}] - Default option values for the language
-   * @param {Object} [userOptions={}] - Runtime options supplied by the caller
-   *
-   * @example
-   * constructor(options = {}) {
-   *   super()
-   *   this.setOptions({ gender: 'masculine' }, options)
-   * }
-   */
-  setOptions (defaults = {}, userOptions = {}) {
-    this.#options = {
-      ...defaults,
-      ...userOptions
-    }
-  }
-
-  /**
-   * Converts an integer to words in decimal context.
-   *
-   * By default, delegates to `integerToWords()`. Override this method
-   * when decimal conversion requires different behavior than integer conversion.
-   *
-   * Called with:
-   * - Single digits (0-9) when `usePerDigitDecimals = true`
-   * - Grouped numbers when `usePerDigitDecimals = false`
-   *
-   * **Use cases for overriding:**
-   * - Romanian: Decimals always use masculine forms regardless of gender option
-   * - Languages with different plural/gender rules for decimal vs integer parts
-   *
-   * @protected
-   * @param {bigint} integerPart The integer to convert (single digit or grouped)
-   * @returns {string} The word representation for use in decimal context
-   */
-  decimalIntegerToWords (integerPart) {
-    return this.integerToWords(integerPart)
-  }
-
-  /**
-   * Converts decimal fractional digits into an array of words.
-   *
-   * Leading zeros are always preserved individually. The remaining digits
-   * are converted based on `usePerDigitDecimals`:
-   *
-   * - `false` (default): Remaining digits grouped as a single number
-   *   - "05" → ["zero", "five"], "14" → ["fourteen"]
-   *
-   * - `true`: Each remaining digit converted separately
-   *   - "05" → ["zero", "five"], "14" → ["one", "four"]
-   *
-   * @protected
-   * @param {string} decimalPart Decimal digits as string (e.g., "05" for 3.05)
-   * @returns {string[]} Array of word tokens for the fractional part
-   */
-  decimalDigitsToWords (decimalPart) {
-    const words = []
-
-    // Always preserve leading zeros individually
-    let i = 0
-    while (i < decimalPart.length && decimalPart[i] === '0') {
-      words.push(this.zeroWord)
-      i++
-    }
-
-    const remainder = decimalPart.slice(i)
-    if (!remainder) return words
-
-    // Convert remainder: per-digit or as single number
-    if (this.usePerDigitDecimals) {
-      for (const char of remainder) {
-        words.push(this.decimalIntegerToWords(BigInt(char)))
-      }
-    } else {
-      words.push(this.decimalIntegerToWords(BigInt(remainder)))
-    }
-
-    return words
-  }
-}

package/lib/classes/greedy-scale-language.d.ts

@@ -1,109 +0,0 @@
-/**
- * Greedy scale language converter implementing the "highest-matching scale word" algorithm.
- *
- * Responsibilities:
- * - Decompose an integer into a sequence of word-sets using greedy matching.
- * - Provide helpers to reduce and post-process matched word-sets.
- * - Inherits decimal handling from AbstractLanguage (supports grouped and per-digit
- *   modes via the `usePerDigitDecimals` class property).
- *
- * Subclass requirements:
- * - Define `scaleWords` (ordered descending) as `[bigint, string]` tuples.
- * - Implement 'combineWordSets(preceding, following)' to combine adjacent word-sets
- *   per language grammar.
- *
- * Scale words specification:
- * - `scaleWords` is an Array of 2-tuples: `[bigint, string]` where the first element
- *   is the numeric scale value and the second is the word for that value.
- * - Scale words MUST be ordered from largest to smallest (descending) for the algorithm
- *   to function correctly.
- *
- * Terminology:
- * - **Scale**: A magnitude value (100n, 1000n, 1000000n)
- * - **Word-set**: An object `{ word: bigint }` representing a partial result
- * - **Scale word**: The word for a scale value ("hundred", "thousand")
- *
- * @abstract
- * @extends AbstractLanguage
- */
-export class GreedyScaleLanguage extends AbstractLanguage {
-    /**
-     * Array of scale words mapping numeric values to their word representations.
-     *
-     * Each element is a 2-tuple: `[bigint, string]` where the first element is the
-     * numeric scale value and the second is the word for that value. The array MUST be
-     * ordered from largest to smallest (descending) for the greedy algorithm to work correctly.
-     *
-     * @type {Array<[bigint, string]>}
-     * @example
-     * // English scale words (descending order):
-     * // [[1000000000n, 'billion'], [1000000n, 'million'], [1000n, 'thousand'], [100n, 'hundred'], ..., [1n, 'one']]
-     */
-    scaleWords: Array<[bigint, string]>;
-    /**
-     * Returns the word for an exact scale value.
-     *
-     * @param {bigint} scale The scale value to look up (prefer BigInt for exact matching).
-     * @returns {string|undefined} The word for the provided scale, or `undefined`.
-     */
-    wordForScale(scale: bigint): string | undefined;
-    /**
-     * Decomposes an integer into a sequence of word-sets.
-     *
-     * This internal helper returns a nested structure that represents quantities and
-     * their matching scale words (e.g. `[{ 'one': 1n }, { 'hundred': 100n }, ...]`).
-     * The result is designed to be reduced by `reduceWordSets()` using language-specific `combineWordSets()`.
-     *
-     * For quantities > 1, the multiplier is recursively decomposed. For quantity = 1,
-     * the implicit "one" is represented with `{ 'one': 1n }` and typically omitted during combineWordSets().
-     *
-     * @protected
-     * @param {bigint} integerPart The integer to decompose.
-     * @returns {Array<Object|Array>} An array of word-set objects and possibly nested arrays.
-     */
-    protected decomposeInteger(integerPart: bigint): Array<Object | any[]>;
-    /**
-     * Reduces a nested array of word-sets into a single word-set object.
-     *
-     * This method repeatedly applies the subclass `combineWordSets()` operation until a single
-     * object remains. It normalizes nested arrays by recursively reducing them.
-     *
-     * @protected
-     * @param {Array<Object|Array>} wordSets Array of word-set objects and nested arrays.
-     * @returns {Object} Reduced word-set where the single object key is the language string
-     *   and its value is the numeric BigInt result for that string.
-     */
-    protected reduceWordSets(wordSets: Array<Object | any[]>): Object;
-    /**
-     * Combines two adjacent word-sets into a single word-set.
-     *
-     * This is the core language-specific method that must be implemented by subclasses
-     * to define how adjacent word-sets are combined according to the language's grammar.
-     * For example, English combines "twenty" + "three" → "twenty-three", while
-     * French might combine "quatre-vingts" + "dix" → "quatre-vingt-dix".
-     *
-     * @abstract
-     * @protected
-     * @param {Object} preceding Preceding word-set as `{ word: bigint }`.
-     * @param {Object} following Following word-set as `{ word: bigint }`.
-     * @returns {Object} Combined word-set with merged text and resulting numeric value.
-     *
-     * @example
-     * // English implementation might handle:
-     * // combineWordSets({ 'twenty': 20n }, { 'three': 3n }) → { 'twenty-three': 23n }
-     * // combineWordSets({ 'one': 1n }, { 'hundred': 100n }) → { 'one hundred': 100n }
-     */
-    protected combineWordSets(preceding: Object, following: Object): Object;
-    /**
-     * Final string post-processing hook.
-     *
-     * Subclasses may override to apply language-specific whitespace, punctuation or
-     * orthographic corrections.
-     *
-     * @protected
-     * @param {string} output Language string produced by the conversion flow.
-     * @returns {string} Final formatted string.
-     */
-    protected finalizeWords(output: string): string;
-}
-import { AbstractLanguage } from './abstract-language.js';

package/lib/classes/greedy-scale-language.js

@@ -1,201 +0,0 @@
-import { AbstractLanguage } from './abstract-language.js'
-
-/**
- * Greedy scale language converter implementing the "highest-matching scale word" algorithm.
- *
- * Responsibilities:
- * - Decompose an integer into a sequence of word-sets using greedy matching.
- * - Provide helpers to reduce and post-process matched word-sets.
- * - Inherits decimal handling from AbstractLanguage (supports grouped and per-digit
- *   modes via the `usePerDigitDecimals` class property).
- *
- * Subclass requirements:
- * - Define `scaleWords` (ordered descending) as `[bigint, string]` tuples.
- * - Implement 'combineWordSets(preceding, following)' to combine adjacent word-sets
- *   per language grammar.
- *
- * Scale words specification:
- * - `scaleWords` is an Array of 2-tuples: `[bigint, string]` where the first element
- *   is the numeric scale value and the second is the word for that value.
- * - Scale words MUST be ordered from largest to smallest (descending) for the algorithm
- *   to function correctly.
- *
- * Terminology:
- * - **Scale**: A magnitude value (100n, 1000n, 1000000n)
- * - **Word-set**: An object `{ word: bigint }` representing a partial result
- * - **Scale word**: The word for a scale value ("hundred", "thousand")
- *
- * @abstract
- * @extends AbstractLanguage
- */
-
-export class GreedyScaleLanguage extends AbstractLanguage {
-  // ============================================================================
-  // Required Properties (subclasses must define)
-  // ============================================================================
-
-  /**
-   * Array of scale words mapping numeric values to their word representations.
-   *
-   * Each element is a 2-tuple: `[bigint, string]` where the first element is the
-   * numeric scale value and the second is the word for that value. The array MUST be
-   * ordered from largest to smallest (descending) for the greedy algorithm to work correctly.
-   *
-   * @type {Array<[bigint, string]>}
-   * @example
-   * // English scale words (descending order):
-   * // [[1000000000n, 'billion'], [1000000n, 'million'], [1000n, 'thousand'], [100n, 'hundred'], ..., [1n, 'one']]
-   */
-  scaleWords
-
-  // ============================================================================
-  // Public Methods
-  // ============================================================================
-
-  /**
-   * Returns the word for an exact scale value.
-   *
-   * @param {bigint} scale The scale value to look up (prefer BigInt for exact matching).
-   * @returns {string|undefined} The word for the provided scale, or `undefined`.
-   */
-  wordForScale (scale) {
-    const match = this.scaleWords.find((pair) => pair[0] === scale)
-    return match?.[1]
-  }
-
-  // ============================================================================
-  // Protected Methods (subclasses may call or override)
-  // ============================================================================
-
-  /**
-   * Decomposes an integer into a sequence of word-sets.
-   *
-   * This internal helper returns a nested structure that represents quantities and
-   * their matching scale words (e.g. `[{ 'one': 1n }, { 'hundred': 100n }, ...]`).
-   * The result is designed to be reduced by `reduceWordSets()` using language-specific `combineWordSets()`.
-   *
-   * For quantities > 1, the multiplier is recursively decomposed. For quantity = 1,
-   * the implicit "one" is represented with `{ 'one': 1n }` and typically omitted during combineWordSets().
-   *
-   * @protected
-   * @param {bigint} integerPart The integer to decompose.
-   * @returns {Array<Object|Array>} An array of word-set objects and possibly nested arrays.
-   */
-  decomposeInteger (integerPart) {
-    const wordSets = []
-    let remaining = integerPart
-
-    do {
-      const match = this.scaleWords.find((pair) => remaining >= pair[0])
-      if (!match) break
-
-      const multiplier = remaining === 0n ? 1n : remaining / match[0]
-
-      if (multiplier === 1n) {
-        wordSets.push({ [this.wordForScale(1n)]: 1n })
-      } else {
-        wordSets.push(this.decomposeInteger(multiplier))
-      }
-
-      wordSets.push({ [match[1]]: match[0] })
-
-      remaining = remaining === 0n ? 0n : remaining % match[0]
-    } while (remaining > 0n)
-
-    return wordSets
-  }
-
-  /**
-   * Reduces a nested array of word-sets into a single word-set object.
-   *
-   * This method repeatedly applies the subclass `combineWordSets()` operation until a single
-   * object remains. It normalizes nested arrays by recursively reducing them.
-   *
-   * @protected
-   * @param {Array<Object|Array>} wordSets Array of word-set objects and nested arrays.
-   * @returns {Object} Reduced word-set where the single object key is the language string
-   *   and its value is the numeric BigInt result for that string.
-   */
-  reduceWordSets (wordSets) {
-    while (wordSets.length > 1) {
-      const [first, second, ...rest] = wordSets
-
-      if (!Array.isArray(first) && !Array.isArray(second)) {
-        const combined = this.combineWordSets(first, second)
-        wordSets = rest.length > 0 ? [combined, rest] : [combined]
-        continue
-      }
-
-      const normalized = wordSets.map((element) => {
-        if (!Array.isArray(element)) return element
-        return element.length === 1 ? element[0] : this.reduceWordSets(element)
-      })
-
-      wordSets = normalized
-    }
-
-    return wordSets[0]
-  }
-
-  // ============================================================================
-  // Abstract Methods (subclasses must implement)
-  // ============================================================================
-
-  /**
-   * Combines two adjacent word-sets into a single word-set.
-   *
-   * This is the core language-specific method that must be implemented by subclasses
-   * to define how adjacent word-sets are combined according to the language's grammar.
-   * For example, English combines "twenty" + "three" → "twenty-three", while
-   * French might combine "quatre-vingts" + "dix" → "quatre-vingt-dix".
-   *
-   * @abstract
-   * @protected
-   * @param {Object} preceding Preceding word-set as `{ word: bigint }`.
-   * @param {Object} following Following word-set as `{ word: bigint }`.
-   * @returns {Object} Combined word-set with merged text and resulting numeric value.
-   *
-   * @example
-   * // English implementation might handle:
-   * // combineWordSets({ 'twenty': 20n }, { 'three': 3n }) → { 'twenty-three': 23n }
-   * // combineWordSets({ 'one': 1n }, { 'hundred': 100n }) → { 'one hundred': 100n }
-   */
-  combineWordSets (preceding, following) {
-    throw new Error('combineWordSets() must be implemented by subclass')
-  }
-
-  // ============================================================================
-  // Optional Methods (subclasses may override)
-  // ============================================================================
-
-  /**
-   * Final string post-processing hook.
-   *
-   * Subclasses may override to apply language-specific whitespace, punctuation or
-   * orthographic corrections.
-   *
-   * @protected
-   * @param {string} output Language string produced by the conversion flow.
-   * @returns {string} Final formatted string.
-   */
-  finalizeWords (output) {
-    return output.trimEnd()
-  }
-
-  /**
-   * Converts an integer to its language-specific cardinal words.
-   *
-   * This method orchestrates decomposition, reduction, and final formatting. It does
-   * not handle decimals or sign; those concerns are implemented in
-   * `AbstractLanguage.toWords` which calls this method for the integer part.
-   *
-   * @param {bigint} integerPart The integer to convert.
-   * @returns {string} The cardinal representation for the integer in the language.
-   */
-  integerToWords (integerPart) {
-    const wordSets = this.decomposeInteger(integerPart)
-    const reduced = this.reduceWordSets(wordSets)
-    const result = Object.keys(reduced)[0]
-    return this.finalizeWords(result)
-  }
-}