n2words 1.23.1 → 2.0.0

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

@@ -1,54 +1,178 @@
-export default AbstractLanguage;
 /**
- * Creates new common language class that processes decimals separately.
- * Requires implementing `toCardinal`.
+ * 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
  */
-declare class AbstractLanguage {
+export class AbstractLanguage {
     /**
-     * @param {object} options Options for class.
-     * @param {string} [options.negativeWord] Word that precedes a negative number (if any).
-     * @param {string} options.separatorWord Word that separates cardinal numbers (i.e. "and").
-     * @param {string} options.zero Word for 0 (i.e. "zero").
-     * @param {string} [options.spaceSeparator] Character that separates words.
+     * Word that precedes negative numbers (e.g., "minus", "negative", "moins").
+     * @type {string}
      */
-    constructor(options: {
-        negativeWord?: string;
-        separatorWord: string;
-        zero: string;
-        spaceSeparator?: string;
-    });
+    negativeWord: string;
     /**
-     * @returns {string} Word that precedes a negative number (if any).
+     * Word that separates integer and decimal parts (e.g., "point", "virgule", "comma").
+     * @type {string}
      */
-    get negativeWord(): string;
+    decimalSeparatorWord: string;
     /**
-     * @returns {string} Word that separates cardinal numbers (i.e. "and").
+     * Word representation for the digit 0 (e.g., "zero", "zéro", "null").
+     * Used for zero values and leading zeros in decimals.
+     * @type {string}
      */
-    get separatorWord(): string;
+    zeroWord: string;
     /**
-     * @returns {string} Word for 0 (i.e. "zero").
+     * 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}
      */
-    get zero(): string;
+    wordSeparator: string;
     /**
-     * @returns {string} Character that separates words.
+     * 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}
      */
-    get spaceSeparator(): string;
+    usePerDigitDecimals: boolean;
     /**
-     * @returns {number} Input value without decimal.
+     * Read-only access to options set via `setOptions()`.
+     * @type {Object}
      */
-    get wholeNumber(): number;
+    get options(): Object;
     /**
-     * Convert ONLY decimal portion of number (processing leading zeros) to a string array of cardinal numbers.
-     * @param {string} decimal Decimal string to convert.
-     * @returns {string} Value in written format.
+     * 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
      */
-    decimalToCardinal(decimal: string): string;
+    public toWords(isNegative: boolean, integerPart: bigint, decimalPart?: string): string;
     /**
-     * Convert a number to cardinal form.
-     * @param {number|string|bigint} value Number to be convert.
-     * @returns {string} Value in written format.
-     * @throws {Error} Value must be a valid number.
+     * 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
      */
-    floatToCardinal(value: number | string | bigint): string;
+    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,160 +1,268 @@
 /**
- * Creates new common language class that processes decimals separately.
- * Requires implementing `toCardinal`.
+ * 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
  */
-class AbstractLanguage {
-  #negativeWord;
-  #separatorWord;
-  #zero;
-  #spaceSeparator;
-  #wholeNumber;
+export class AbstractLanguage {
+  // ============================================================================
+  // Private Fields
+  // ============================================================================
 
   /**
-   * @param {object} options Options for class.
-   * @param {string} [options.negativeWord] Word that precedes a negative number (if any).
-   * @param {string} options.separatorWord Word that separates cardinal numbers (i.e. "and").
-   * @param {string} options.zero Word for 0 (i.e. "zero").
-   * @param {string} [options.spaceSeparator] Character that separates words.
+   * Private storage for options.
+   * @type {Object}
    */
-  constructor(options) {
-    // Merge supplied options with defaults
-    options = Object.assign({
-      negativeWord: '',
-      separatorWord: '',
-      zero: '',
-      spaceSeparator: ' '
-    }, options);
-
-    // Make options available to class
-    this.#negativeWord = options.negativeWord;
-    this.#separatorWord = options.separatorWord;
-    this.#zero = options.zero;
-    this.#spaceSeparator = options.spaceSeparator;
-  }
+  #options = {}
+
+  // ============================================================================
+  // Required Properties (subclasses must define)
+  // ============================================================================
 
   /**
-   * @returns {string} Word that precedes a negative number (if any).
+   * Word that precedes negative numbers (e.g., "minus", "negative", "moins").
+   * @type {string}
    */
-  get negativeWord() {
-    return this.#negativeWord;
-  }
+  negativeWord = ''
 
   /**
-   * @returns {string} Word that separates cardinal numbers (i.e. "and").
+   * Word that separates integer and decimal parts (e.g., "point", "virgule", "comma").
+   * @type {string}
    */
-  get separatorWord() {
-    return this.#separatorWord;
-  }
+  decimalSeparatorWord = ''
 
   /**
-   * @returns {string} Word for 0 (i.e. "zero").
+   * Word representation for the digit 0 (e.g., "zero", "zéro", "null").
+   * Used for zero values and leading zeros in decimals.
+   * @type {string}
    */
-  get zero() {
-    return this.#zero;
-  }
+  zeroWord = ''
+
+  // ============================================================================
+  // Optional Properties (subclasses may override)
+  // ============================================================================
 
   /**
-   * @returns {string} Character that separates words.
+   * 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}
    */
-  get spaceSeparator() {
-    return this.#spaceSeparator;
-  }
+  wordSeparator = ' '
 
   /**
-   * @returns {number} Input value without decimal.
+   * 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}
    */
-  get wholeNumber() {
-    return this.#wholeNumber;
+  usePerDigitDecimals = false
+
+  // ============================================================================
+  // Public Accessors
+  // ============================================================================
+
+  /**
+   * Read-only access to options set via `setOptions()`.
+   * @type {Object}
+   */
+  get options () {
+    return this.#options
   }
 
+  // ============================================================================
+  // Public Methods
+  // ============================================================================
+
   /**
-   * Convert ONLY decimal portion of number (processing leading zeros) to a string array of cardinal numbers.
-   * @param {string} decimal Decimal string to convert.
-   * @returns {string} Value in written format.
+   * 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
    */
-  decimalToCardinal(decimal) {
-    const words = [];
+  toWords (isNegative, integerPart, decimalPart) {
+    const words = []
 
-    // Split decimal string into an array of characters
-    const chars = [...decimal];
+    if (isNegative) words.push(this.negativeWord)
 
-    // Loop through characters adding leading zeros to words array
-    let index = 0;
-    while (index < chars.length && chars[index] === '0') {
-      words.push(this.zero);
-      index++;
-    }
+    words.push(this.integerToWords(integerPart))
 
-    // Prevent further processing if entire string was zeros
-    if (index === chars.length) {
-      return words;
+    if (decimalPart) {
+      words.push(this.decimalSeparatorWord)
+      words.push(...this.decimalDigitsToWords(decimalPart))
     }
 
-    // Convert and add remaining then return words array
-    return [...words, this.toCardinal(BigInt(decimal))];
+    return words.join(this.wordSeparator)
   }
 
+  // ============================================================================
+  // Abstract Methods (subclasses must implement)
+  // ============================================================================
+
   /**
-   * Convert a number to cardinal form.
-   * @param {number|string|bigint} value Number to be convert.
-   * @returns {string} Value in written format.
-   * @throws {Error} Value must be a valid number.
+   * 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
    */
-  floatToCardinal(value) {
-    // Validate user input value and convert to string (excluding BigInt)
-    if (typeof value == 'number') {
-      if (Number.isNaN(value)) {
-        throw new TypeError('NaN is not an accepted number.');
-      }
-      value = value.toString();
-    } else if (typeof value == 'string') {
-      value = value.trim();
-      if (value.length === 0 || Number.isNaN(Number(value))) {
-        throw new Error('"' + value + '" is not a valid number.');
-      }
-    } else if (typeof value != 'bigint') {
-      throw new TypeError('Invalid variable type: ' + typeof value);
-    }
-
-    let words = [];
-    let wholeNumber;
-    let decimalNumber;
+  integerToWords (integerPart) {
+    throw new Error('integerToWords() must be implemented by subclass')
+  }
 
-    // If negative number add negative word
-    if (value < 0) {
-      words.push(this.negativeWord);
-    }
+  // ============================================================================
+  // Protected Methods (subclasses may override or call)
+  // ============================================================================
 
-    // Split value decimal (if any) then convert to BigInt
-    if (typeof value == 'bigint') {
-      wholeNumber = value;
-    } else {
-      const splitValue = value.split('.');
-      wholeNumber = BigInt(splitValue[0]);
-      decimalNumber = splitValue[1];
+  /**
+   * 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
     }
+  }
 
-    // Convert whole number to positive (if negative)
-    if (wholeNumber < 0) {
-      wholeNumber = -wholeNumber;
-    }
+  /**
+   * 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)
+  }
 
-    // NOTE: Only needed for CZ
-    this.#wholeNumber = wholeNumber;
+  /**
+   * 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 = []
 
-    // Add whole number in written form
-    words = [...words, this.toCardinal(wholeNumber)];
+    // Always preserve leading zeros individually
+    let i = 0
+    while (i < decimalPart.length && decimalPart[i] === '0') {
+      words.push(this.zeroWord)
+      i++
+    }
 
-    // Add decimal number in written form (if any)
-    if (decimalNumber) {
-      words.push(this.separatorWord);
+    const remainder = decimalPart.slice(i)
+    if (!remainder) return words
 
-      words = [...words, ...this.decimalToCardinal(decimalNumber)];
+    // 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)))
     }
 
-    // Join words with spaces
-    return words.join(this.spaceSeparator);
+    return words
   }
 }
-
-export default AbstractLanguage;