n2words 1.23.0 → 1.24.0

package/lib/classes/abstract-language.js

@@ -1,160 +1,261 @@
 /**
- * Creates new common language class that processes decimals separately.
- * Requires implementing `toCardinal`.
+ * 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.
+ *
+ * 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.
+ *
+ * This class stays minimal; language grammar lives in subclasses.
+ *
+ * @abstract
  */
 class AbstractLanguage {
-  #negativeWord;
-  #separatorWord;
-  #zero;
-  #spaceSeparator;
-  #wholeNumber;
-
   /**
-   * @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) {
-    // 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;
-  }
+  negativeWord = ''
 
   /**
-   * @returns {string} Word that precedes a negative number (if any).
+   * Word that separates whole and decimal parts (e.g., "point", "virgule", "comma").
+   * @type {string}
    */
-  get negativeWord() {
-    return this.#negativeWord;
-  }
+  decimalSeparatorWord = ''
 
   /**
-   * @returns {string} Word that separates cardinal numbers (i.e. "and").
+   * Word representation for the digit 0 (e.g., "zero", "zéro", "null").
+   * @type {string}
    */
-  get separatorWord() {
-    return this.#separatorWord;
-  }
+  zeroWord = ''
 
   /**
-   * @returns {string} Word for 0 (i.e. "zero").
+   * Character(s) used to separate words in the output (typically a space).
+   * @type {string}
    */
-  get zero() {
-    return this.#zero;
-  }
+  wordSeparator = ' '
 
   /**
-   * @returns {string} Character that separates words.
+   * 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}
    */
-  get spaceSeparator() {
-    return this.#spaceSeparator;
-  }
+  cachedWholeNumber = 0n
 
   /**
-   * @returns {number} Input value without decimal.
+   * 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.
+   * @type {boolean}
    */
-  get wholeNumber() {
-    return this.#wholeNumber;
-  }
+  convertDecimalsPerDigit = false
 
   /**
-   * 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.
+   * 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}
    */
-  decimalToCardinal(decimal) {
-    const words = [];
-
-    // Split decimal string into an array of characters
-    const chars = [...decimal];
+  digits = null
 
-    // Loop through characters adding leading zeros to words array
-    let index = 0;
-    while (index < chars.length && chars[index] === '0') {
-      words.push(this.zero);
-      index++;
-    }
+  /**
+   * Convert a single decimal digit (0-9) to its word representation.
+   *
+   * 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)`
+   *
+   * Subclasses may override this for custom logic.
+   *
+   * @protected
+   * @param {bigint} digit A single digit value (0-9) as BigInt
+   * @returns {string} The word representation of the digit
+   */
+  convertDigitToWord (digit) {
+    const idx = Number(digit)
+    if (idx === 0) return this.zeroWord
 
-    // Prevent further processing if entire string was zeros
-    if (index === chars.length) {
-      return 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
+      }
     }
 
-    // Convert and add remaining then return words array
-    return [...words, this.toCardinal(BigInt(decimal))];
+    return this.convertWholePart(digit)
   }
 
   /**
-   * 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.
+   * Convert the decimal fractional digits into words.
+   *
+  * Behavior depends on the `convertDecimalsPerDigit` class property:
+   *
+   * **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
+   *
+   * **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.)
+   *
+   * @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.
+   *
+   * @example
+   * // Per-digit mode
+   * decimalDigitsToWords('05'); // -> [this.zeroWord, 'five']
+   * decimalDigitsToWords('14'); // -> ['one', 'four']
+   *
+   * // Grouped mode
+   * decimalDigitsToWords('05'); // -> [this.zeroWord, 'five']
+   * decimalDigitsToWords('14'); // -> ['fourteen']
    */
-  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.');
+  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))
       }
-    } else if (typeof value != 'bigint') {
-      throw new TypeError('Invalid variable type: ' + typeof value);
+      return words
+    }
+
+    // Default grouped-decimal behavior with leading zero preservation
+    let i = 0
+    while (i < len && decimalString[i] === '0') {
+      words.push(this.zeroWord)
+      i++
     }
 
-    let words = [];
-    let wholeNumber;
-    let decimalNumber;
+    if (i === len) return words
+
+    const remainingDigits = decimalString.slice(i)
+    words.push(this.convertWholePart(BigInt(remainingDigits)))
+
+    return words
+  }
+
+  /**
+   * Convert a numeric input into its language cardinal representation.
+   *
+   * 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()`.
+   *
+   * Errors and validation:
+   * - Passing `NaN` (as `number`) throws `TypeError`.
+   * - Passing a non-numeric `string` throws `Error`.
+   * - Passing an unsupported type throws `TypeError`.
+   *
+   * @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.
+   */
+  convertToWords (value) {
+    // Normalize and validate input
+    const inputType = typeof value
 
-    // If negative number add negative word
-    if (value < 0) {
-      words.push(this.negativeWord);
+    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
+      )
     }
 
-    // Split value decimal (if any) then convert to BigInt
-    if (typeof value == 'bigint') {
-      wholeNumber = value;
+    const 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 {
-      const splitValue = value.split('.');
-      wholeNumber = BigInt(splitValue[0]);
-      decimalNumber = splitValue[1];
+      // For strings, check first character before normalization
+      if (value[0] === '-') {
+        isNegative = true
+        value = value.slice(1)
+      }
     }
 
-    // Convert whole number to positive (if negative)
-    if (wholeNumber < 0) {
-      wholeNumber = -wholeNumber;
+    // 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)
+      }
     }
 
-    // NOTE: Only needed for CZ
-    this.#wholeNumber = wholeNumber;
+    this.cachedWholeNumber = wholeNumber
 
-    // Add whole number in written form
-    words = [...words, this.toCardinal(wholeNumber)];
+    if (isNegative) words.push(this.negativeWord)
 
-    // Add decimal number in written form (if any)
-    if (decimalNumber) {
-      words.push(this.separatorWord);
+    words.push(this.convertWholePart(wholeNumber))
 
-      words = [...words, ...this.decimalToCardinal(decimalNumber)];
+    // Append decimal portion if present (separator + fractional digits)
+    if (decimalPart) {
+      words.push(this.decimalSeparatorWord)
+      words.push(...this.decimalDigitsToWords(decimalPart))
     }
 
-    // Join words with spaces
-    return words.join(this.spaceSeparator);
+    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')
   }
 }
 
-export default AbstractLanguage;
+export default AbstractLanguage

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

@@ -0,0 +1,195 @@
+import AbstractLanguage from './abstract-language.js'
+
+/**
+ * @typedef {Object} WordSet
+ * @property {string} word - The language word or phrase
+ * @property {bigint} value - The numeric value represented by the word
+ */
+
+/**
+ * @typedef {Array.<Array.<(bigint|string)>>} ScaleWordPairs
+ * Array of scale word pairs in descending order. Each pair contains:
+ * - [0]: BigInt numeric value
+ * - [1]: String word representation
+ * Must be ordered largest to smallest for the greedy algorithm.
+ */
+
+/**
+ * Greedy scale language converter implementing the "highest-matching scale word" algorithm.
+ *
+ * Responsibilities:
+ * - Decompose a whole-number value into a sequence of scale word-sets.
+ * - Provide helpers to merge and post-process matched word-sets.
+ * - Inherits decimal handling from AbstractLanguage (supports grouped and per-digit
+ *   modes via the `convertDecimalsPerDigit` class property).
+ *
+ * Subclass requirements:
+ * - Define `scaleWordPairs` (ordered descending) as `[BigInt, string]` tuples.
+ * - Implement `mergeScales(leftWordSet, rightWordSet)` to combine adjacent word-sets
+ *   per language grammar.
+ *
+ * Scale words specification:
+ * - `scaleWordPairs` is an Array of 2-tuples: `[BigInt, string]` where the first element
+ *   is the numeric value (BigInt) and the second is the word used for that value.
+ * - Scale words MUST be ordered from largest to smallest (descending) for the algorithm
+ *   to function correctly.
+ *
+ * @abstract
+ * @extends AbstractLanguage
+ * @example
+ * // Example `scaleWordPairs` for English (descending order):
+ * // [[1000000000n, 'billion'], [1000000n, 'million'], [1000n, 'thousand'], [100n, 'hundred'], ..., [1n, 'one']]
+ */
+
+class GreedyScaleLanguage extends AbstractLanguage {
+  /**
+   * Array of scale word pairs mapping numeric values to their word representations.
+   *
+   * Each element is a 2-tuple: `[BigInt, string]` where the first element is the
+   * numeric 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.<Array.<(bigint|string)>>}
+   * @example
+   * // English scale words (descending order):
+   * // [[1000000000n, 'billion'], [1000000n, 'million'], [1000n, 'thousand'], [100n, 'hundred'], ..., [1n, 'one']]
+   */
+  scaleWordPairs
+
+  /**
+   * Return the word associated with an exact scale word-set numeric value.
+   *
+   * @param {bigint|number} scaleValue Numeric word-set object key (prefer BigInt for exact matching).
+   * @returns {string|undefined} The word for the provided scale value, or `undefined`.
+   */
+  getScaleWord (scaleValue) {
+    const matchingPair = this.scaleWordPairs.find((pair) => pair[0] === scaleValue)
+    return matchingPair?.[1]
+  }
+
+  /**
+   * Decompose a whole-number into a sequence of scale 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 `mergeWordSets()` using language-specific `mergeScales()`.
+   *
+   * For quantities > 1, the multiplier is recursively decomposed. For quantity = 1,
+   * the implicit "one" is represented with `{ 'one': 1n }` and typically omitted during mergeScales().
+   *
+   * @protected
+   * @param {bigint} wholeNumber The integer value to decompose (BigInt preferred).
+   * @returns {Array<Object|Array>} An array of word-set objects and possibly nested arrays.
+   */
+  decomposeToScales (wholeNumber) {
+    const decomposeWordSets = []
+    let remainingValue = wholeNumber
+
+    do {
+      const matchingScaleWordPair = this.scaleWordPairs.find((scaleWordPair) => remainingValue >= scaleWordPair[0])
+      if (!matchingScaleWordPair) break
+
+      const multiplier = remainingValue === 0n ? 1n : remainingValue / matchingScaleWordPair[0]
+
+      if (multiplier === 1n) {
+        decomposeWordSets.push({ [this.getScaleWord(1n)]: 1n })
+      } else {
+        decomposeWordSets.push(this.decomposeToScales(multiplier))
+      }
+
+      decomposeWordSets.push({ [matchingScaleWordPair[1]]: matchingScaleWordPair[0] })
+
+      remainingValue = remainingValue === 0n ? 0n : remainingValue % matchingScaleWordPair[0]
+    } while (remainingValue > 0n)
+
+    return decomposeWordSets
+  }
+
+  /**
+   * Reduce a nested array of word-sets into a single merged word-set object.
+   *
+   * This method repeatedly applies the subclass `mergeScales()` operation until a single
+   * object remains. It normalizes nested arrays by recursively merging them.
+   *
+   * @protected
+   * @param {Array<Object|Array>} mergeWordSetsList Array of word-set objects and nested arrays.
+   * @returns {Object} Merged word-set where the single object key is the language string
+   *   and its value is the numeric BigInt result for that string.
+   */
+  mergeWordSets (mergeWordSetsList) {
+    while (mergeWordSetsList.length > 1) {
+      const [firstWordSet, secondWordSet, ...remainingWordSets] = mergeWordSetsList
+
+      if (!Array.isArray(firstWordSet) && !Array.isArray(secondWordSet)) {
+        const merged = this.mergeScales(firstWordSet, secondWordSet)
+        mergeWordSetsList = remainingWordSets.length > 0 ? [merged, remainingWordSets] : [merged]
+        continue
+      }
+
+      const normalizedWordSets = mergeWordSetsList.map((wordSetElement) => {
+        if (!Array.isArray(wordSetElement)) return wordSetElement
+        return wordSetElement.length === 1 ? wordSetElement[0] : this.mergeWordSets(wordSetElement)
+      })
+
+      mergeWordSetsList = normalizedWordSets
+    }
+
+    return mergeWordSetsList[0]
+  }
+
+  /**
+   * Combine two adjacent word-sets into a single merged 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} leftWordSet Left operand as `{ word: bigint }` pair.
+   * @param {Object} rightWordSet Right operand as `{ word: bigint }` pair.
+   * @returns {Object} Single merged word-set object with combined text and numeric value.
+   *
+   * @example
+   * // English implementation might handle:
+   * // mergeScales({ 'twenty': 20n }, { 'three': 3n }) → { 'twenty-three': 23n }
+   * // mergeScales({ 'one': 1n }, { 'hundred': 100n }) → { 'one hundred': 100n }
+   */
+  mergeScales (leftWordSet, rightWordSet) {
+    throw new Error('mergeScales() must be implemented by subclass')
+  }
+
+  /**
+   * Final string post-processing hook.
+   *
+   * Subclasses may override to apply language-specific whitespace, punctuation or
+   * orthographic corrections.
+   *
+   * @protected
+   * @param {string} output Merged language string produced by `convertWholePart` flow.
+   * @returns {string} Final formatted string.
+   */
+  finalizeWords (output) {
+    return output.trimEnd()
+  }
+
+  /**
+   * Convert an integer value to its language-specific cardinal words.
+   *
+   * This method orchestrates decomposition, merging and final formatting. It does
+   * not handle decimals or sign; those concerns are implemented in
+   * `AbstractLanguage.convertToWords` which calls this helper for the whole-number part.
+   *
+   * @param {bigint|number} wholeNumber Whole-number value to convert (BigInt is preferred).
+   * @returns {string} The cardinal representation for `value` in the language.
+   */
+  convertWholePart (wholeNumber) {
+    const decomposeWordSets = this.decomposeToScales(wholeNumber)
+    const mergedWordSet = this.mergeWordSets(decomposeWordSets)
+    const resultString = Object.keys(mergedWordSet)[0]
+    return this.finalizeWords(resultString)
+  }
+}
+
+export default GreedyScaleLanguage