n2words 1.24.0 → 2.0.0

package/lib/classes/abstract-language.d.ts

@@ -0,0 +1,178 @@
+/**
+ * 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 {
+    /**
+     * Word that precedes negative numbers (e.g., "minus", "negative", "moins").
+     * @type {string}
+     */
+    negativeWord: string;
+    /**
+     * Word that separates integer and decimal parts (e.g., "point", "virgule", "comma").
+     * @type {string}
+     */
+    decimalSeparatorWord: string;
+    /**
+     * Word representation for the digit 0 (e.g., "zero", "zéro", "null").
+     * Used for zero values and leading zeros in decimals.
+     * @type {string}
+     */
+    zeroWord: string;
+    /**
+     * 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: string;
+    /**
+     * 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: boolean;
+    /**
+     * Read-only access to options set via `setOptions()`.
+     * @type {Object}
+     */
+    get options(): Object;
+    /**
+     * 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
+     */
+    public toWords(isNegative: boolean, integerPart: bigint, decimalPart?: string): string;
+    /**
+     * 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: bigint): string;
+    /**
+     * 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)
+     * }
+     */
+    protected setOptions(defaults?: Object, userOptions?: Object): void;
+    /**
+     * 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
+     */
+    protected decimalIntegerToWords(integerPart: bigint): string;
+    /**
+     * 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
+     */
+    protected decimalDigitsToWords(decimalPart: string): string[];
+    #private;
+}

package/lib/classes/abstract-language.js

@@ -1,25 +1,55 @@
 /**
  * Abstract base class for language converters.
  *
- * What this class handles:
- * - Validates and normalizes caller input (`number | string | bigint`), rejecting NaN/invalid strings.
- * - Splits sign, whole, and decimal parts, caching the whole part for languages that need it.
- * - Delegates whole-number wording to `convertWholePart(wholeNumber)` implemented by subclasses.
- * - Converts decimals via `decimalDigitsToWords()`, preserving leading zeros and supporting per-digit mode when `convertDecimalsPerDigit` is true.
+ * 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.
  *
- * What subclasses must provide:
- * - `convertWholePart(wholeNumber)` method implementation (required; abstract).
- * - `negativeWord` class property (word preceding negative numbers, e.g., "minus").
- * - `zeroWord` class property (word for digit 0, e.g., "zero").
- * - `decimalSeparatorWord` class property (word between whole and decimal, e.g., "point").
- * - `wordSeparator` class property (word separator in output, typically a space).
- * Optional: override `convertDecimalsPerDigit`, `digits`, or `convertDigitToWord()` for custom behavior.
+ * ## Responsibilities
  *
- * This class stays minimal; language grammar lives in subclasses.
+ * - 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
  */
-class AbstractLanguage {
+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}
@@ -27,235 +57,212 @@ class AbstractLanguage {
   negativeWord = ''
 
   /**
-   * Word that separates whole and decimal parts (e.g., "point", "virgule", "comma").
+   * 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 (typically a space).
+   * 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 = ' '
 
-  /**
-   * Cached whole number portion from the most recent conversion.
-   * Some languages need access to this value during conversion for
-   * pluralization rules or special cases (e.g., Czech, Hebrew).
-   * @type {bigint}
-   */
-  cachedWholeNumber = 0n
-
   /**
    * Whether to convert decimal digits individually rather than grouped.
-   * - `true`: Each digit converted separately (e.g., "05" → "zero five")
-   * - `false`: Leading zeros preserved, remaining grouped (e.g., "14" → "fourteen")
-   * Used by languages like Japanese, Thai, Tamil, Telugu.
+   *
+   * - `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}
    */
-  convertDecimalsPerDigit = false
+  usePerDigitDecimals = false
+
+  // ============================================================================
+  // Public Accessors
+  // ============================================================================
 
   /**
-   * Optional array of digit words for direct lookup in `convertDigitToWord()`.
-   * - Length 10: indices 0–9 map directly to digit words
-   * - Length 9: indices 0–8 map to words for digits 1–9
-   * - `null`: Falls back to `convertWholePart()` for digit conversion
-   * @type {string[]|null}
+   * Read-only access to options set via `setOptions()`.
+   * @type {Object}
    */
-  digits = null
+  get options () {
+    return this.#options
+  }
+
+  // ============================================================================
+  // Public Methods
+  // ============================================================================
 
   /**
-   * Convert a single decimal digit (0-9) to its word representation.
+   * Converts pre-normalized numeric components to words.
    *
-   * Default behavior:
-   * - 0 returns the language's `zeroWord`
-   * - If a `digits` array is present, use it for direct lookup
-   *   - Length 10: indices 0–9 map directly
-   *   - Length 9: indices 1–9 map via `idx - 1`
-   * - Otherwise delegate to `convertWholePart(digit)`
+   * 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.
    *
-   * Subclasses may override this for custom logic.
+   * **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
    *
-   * @protected
-   * @param {bigint} digit A single digit value (0-9) as BigInt
-   * @returns {string} The word representation of the digit
+   * **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
    */
-  convertDigitToWord (digit) {
-    const idx = Number(digit)
-    if (idx === 0) return this.zeroWord
+  toWords (isNegative, integerPart, decimalPart) {
+    const words = []
 
-    if (Array.isArray(this.digits)) {
-      if (this.digits.length === 10) {
-        return this.digits[idx] ?? this.zeroWord
-      }
-      if (this.digits.length === 9) {
-        return this.digits[idx - 1] ?? this.zeroWord
-      }
+    if (isNegative) words.push(this.negativeWord)
+
+    words.push(this.integerToWords(integerPart))
+
+    if (decimalPart) {
+      words.push(this.decimalSeparatorWord)
+      words.push(...this.decimalDigitsToWords(decimalPart))
     }
 
-    return this.convertWholePart(digit)
+    return words.join(this.wordSeparator)
   }
 
+  // ============================================================================
+  // Abstract Methods (subclasses must implement)
+  // ============================================================================
+
   /**
-   * Convert the decimal fractional digits into words.
+   * Converts a BigInt integer part to its cardinal word representation.
    *
-  * Behavior depends on the `convertDecimalsPerDigit` class property:
+   * This is the core template method that subclasses MUST implement to provide
+   * language-specific number conversion logic.
    *
-   * **Per-digit mode** (`convertDecimalsPerDigit: true`):
-   * - Each decimal digit is converted individually using `convertDigitToWord()`
-   * - Example: "05" -> [zero, 'five'], "14" -> ['one', 'four']
-   * - Used by: Japanese, Thai, Tamil, Telugu
+   * @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.
    *
-   * **Grouped mode** (default, `convertDecimalsPerDigit: false`):
-   * - Leading zeros are preserved as individual `zeroWord` entries
-   * - Remaining digits are grouped and converted as a number
-   * - Example: "05" -> [zero, 'five'], "14" -> ['fourteen']
-   * - Used by: Most languages (English, Spanish, French, etc.)
+   * 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 {string} decimalString The decimal digits as a string (e.g. `'05'` for 3.05).
-   * @returns {Array<string>} Array of word tokens representing the fractional part.
+   * @param {Object} [defaults={}] - Default option values for the language
+   * @param {Object} [userOptions={}] - Runtime options supplied by the caller
    *
    * @example
-   * // Per-digit mode
-   * decimalDigitsToWords('05'); // -> [this.zeroWord, 'five']
-   * decimalDigitsToWords('14'); // -> ['one', 'four']
-   *
-   * // Grouped mode
-   * decimalDigitsToWords('05'); // -> [this.zeroWord, 'five']
-   * decimalDigitsToWords('14'); // -> ['fourteen']
+   * constructor(options = {}) {
+   *   super()
+   *   this.setOptions({ gender: 'masculine' }, options)
+   * }
    */
-  decimalDigitsToWords (decimalString) {
-    const words = []
-    const len = decimalString.length
-
-    if (this.convertDecimalsPerDigit) {
-      for (let i = 0; i < len; i++) {
-        const decimalDigit = BigInt(decimalString[i])
-        words.push(this.convertDigitToWord(decimalDigit))
-      }
-      return words
+  setOptions (defaults = {}, userOptions = {}) {
+    this.#options = {
+      ...defaults,
+      ...userOptions
     }
+  }
 
-    // Default grouped-decimal behavior with leading zero preservation
-    let i = 0
-    while (i < len && decimalString[i] === '0') {
-      words.push(this.zeroWord)
-      i++
-    }
-
-    if (i === len) return words
-
-    const remainingDigits = decimalString.slice(i)
-    words.push(this.convertWholePart(BigInt(remainingDigits)))
-
-    return words
+  /**
+   * 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)
   }
 
   /**
-   * Convert a numeric input into its language cardinal representation.
+   * Converts decimal fractional digits into an array of words.
    *
-   * This is the public entry point used by consumers. It normalizes the input
-   * (accepting `number | string | bigint`), validates it, splits sign and
-   * fractional parts, and delegates whole-number conversion to
-   * `convertWholePart(BigInt)` and fractional conversion to `decimalDigitsToWords()`.
+   * Leading zeros are always preserved individually. The remaining digits
+   * are converted based on `usePerDigitDecimals`:
    *
-   * Errors and validation:
-   * - Passing `NaN` (as `number`) throws `TypeError`.
-   * - Passing a non-numeric `string` throws `Error`.
-   * - Passing an unsupported type throws `TypeError`.
+   * - `false` (default): Remaining digits grouped as a single number
+   *   - "05" → ["zero", "five"], "14" → ["fourteen"]
    *
-   * @public
-   * @param {number|string|bigint} value Numeric input to convert. Strings may include a single `.` decimal marker.
-   * @returns {string} The localized cardinal string.
-   * @throws {TypeError|Error} For invalid input as described above.
+   * - `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
    */
-  convertToWords (value) {
-    // Normalize and validate input
-    const inputType = typeof value
+  decimalDigitsToWords (decimalPart) {
+    const words = []
 
-    if (inputType === 'number') {
-      if (Number.isNaN(value)) throw new TypeError('NaN is not an accepted number.')
-      value = value.toString()
-    } else if (inputType === 'string') {
-      value = value.trim()
-      if (value.length === 0 || Number.isNaN(Number(value))) { throw new Error('Invalid number format: "' + value + '"') }
-    } else if (inputType !== 'bigint') {
-      throw new TypeError(
-        'Invalid variable type, expected number|string|bigint, received: ' + inputType
-      )
+    // Always preserve leading zeros individually
+    let i = 0
+    while (i < decimalPart.length && decimalPart[i] === '0') {
+      words.push(this.zeroWord)
+      i++
     }
 
-    const words = []
+    const remainder = decimalPart.slice(i)
+    if (!remainder) return words
 
-    // Detect negativity and strip sign for further processing.
-    // Must check before type coercion for BigInt (comparison works but slice does not).
-    let isNegative = false
-    if (inputType === 'bigint') {
-      if (value < 0n) {
-        isNegative = true
-        value = -value
-      }
-    } else {
-      // For strings, check first character before normalization
-      if (value[0] === '-') {
-        isNegative = true
-        value = value.slice(1)
+    // Convert remainder: per-digit or as single number
+    if (this.usePerDigitDecimals) {
+      for (const char of remainder) {
+        words.push(this.decimalIntegerToWords(BigInt(char)))
       }
-    }
-
-    // Extract whole and decimal parts based on type.
-    // BigInt has no decimal point; strings may contain a single '.'.
-    // Default whole part to '0' if empty (e.g., '.5' -> '0' + '.5')
-    let wholeNumber
-    let decimalPart
-    if (inputType === 'bigint') {
-      wholeNumber = value
     } else {
-      const decimalPointIndex = value.indexOf('.')
-      if (decimalPointIndex === -1) {
-        wholeNumber = BigInt(value)
-      } else {
-        const wholePartString = value.slice(0, decimalPointIndex) || '0'
-        wholeNumber = BigInt(wholePartString)
-        decimalPart = value.slice(decimalPointIndex + 1)
-      }
-    }
-
-    this.cachedWholeNumber = wholeNumber
-
-    if (isNegative) words.push(this.negativeWord)
-
-    words.push(this.convertWholePart(wholeNumber))
-
-    // Append decimal portion if present (separator + fractional digits)
-    if (decimalPart) {
-      words.push(this.decimalSeparatorWord)
-      words.push(...this.decimalDigitsToWords(decimalPart))
+      words.push(this.decimalIntegerToWords(BigInt(remainder)))
     }
 
-    return words.join(this.wordSeparator)
-  }
-
-  /**
-   * Convert a BigInt whole number to its cardinal word representation.
-   *
-   * This is a template method that subclasses MUST implement to provide
-   * language-specific number conversion logic.
-   *
-   * @abstract
-   * @param {bigint} wholeNumber The whole number part to convert
-   * @returns {string} The cardinal representation in the target language
-   */
-  convertWholePart (wholeNumber) {
-    throw new Error('convertWholePart() must be implemented by subclass')
+    return words
   }
 }
-
-export default AbstractLanguage