n2words 1.24.0 → 2.0.0

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

@@ -0,0 +1,109 @@
+/**
+ * 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,144 +1,148 @@
-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.
- */
+import { AbstractLanguage } from './abstract-language.js'
 
 /**
  * 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.
+ * - 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 `convertDecimalsPerDigit` class property).
+ *   modes via the `usePerDigitDecimals` class property).
  *
  * Subclass requirements:
- * - Define `scaleWordPairs` (ordered descending) as `[BigInt, string]` tuples.
- * - Implement `mergeScales(leftWordSet, rightWordSet)` to combine adjacent word-sets
+ * - Define `scaleWords` (ordered descending) as `[bigint, string]` tuples.
+ * - Implement 'combineWordSets(preceding, following)' 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.
+ * - `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
- * @example
- * // Example `scaleWordPairs` for English (descending order):
- * // [[1000000000n, 'billion'], [1000000n, 'million'], [1000n, 'thousand'], [100n, 'hundred'], ..., [1n, 'one']]
  */
 
-class GreedyScaleLanguage extends AbstractLanguage {
+export class GreedyScaleLanguage extends AbstractLanguage {
+  // ============================================================================
+  // Required Properties (subclasses must define)
+  // ============================================================================
+
   /**
-   * Array of scale word pairs mapping numeric values to their word representations.
+   * 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 value and the second is the word for that value. The array MUST be
+   * 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.<Array.<(bigint|string)>>}
+   * @type {Array<[bigint, string]>}
    * @example
    * // English scale words (descending order):
    * // [[1000000000n, 'billion'], [1000000n, 'million'], [1000n, 'thousand'], [100n, 'hundred'], ..., [1n, 'one']]
    */
-  scaleWordPairs
+  scaleWords
+
+  // ============================================================================
+  // Public Methods
+  // ============================================================================
 
   /**
-   * Return the word associated with an exact scale word-set numeric value.
+   * Returns the word for an exact scale 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`.
+   * @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`.
    */
-  getScaleWord (scaleValue) {
-    const matchingPair = this.scaleWordPairs.find((pair) => pair[0] === scaleValue)
-    return matchingPair?.[1]
+  wordForScale (scale) {
+    const match = this.scaleWords.find((pair) => pair[0] === scale)
+    return match?.[1]
   }
 
+  // ============================================================================
+  // Protected Methods (subclasses may call or override)
+  // ============================================================================
+
   /**
-   * Decompose a whole-number into a sequence of scale word-sets.
+   * 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 `mergeWordSets()` using language-specific `mergeScales()`.
+   * 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 mergeScales().
+   * the implicit "one" is represented with `{ 'one': 1n }` and typically omitted during combineWordSets().
    *
    * @protected
-   * @param {bigint} wholeNumber The integer value to decompose (BigInt preferred).
+   * @param {bigint} integerPart The integer to decompose.
    * @returns {Array<Object|Array>} An array of word-set objects and possibly nested arrays.
    */
-  decomposeToScales (wholeNumber) {
-    const decomposeWordSets = []
-    let remainingValue = wholeNumber
+  decomposeInteger (integerPart) {
+    const wordSets = []
+    let remaining = integerPart
 
     do {
-      const matchingScaleWordPair = this.scaleWordPairs.find((scaleWordPair) => remainingValue >= scaleWordPair[0])
-      if (!matchingScaleWordPair) break
+      const match = this.scaleWords.find((pair) => remaining >= pair[0])
+      if (!match) break
 
-      const multiplier = remainingValue === 0n ? 1n : remainingValue / matchingScaleWordPair[0]
+      const multiplier = remaining === 0n ? 1n : remaining / match[0]
 
       if (multiplier === 1n) {
-        decomposeWordSets.push({ [this.getScaleWord(1n)]: 1n })
+        wordSets.push({ [this.wordForScale(1n)]: 1n })
       } else {
-        decomposeWordSets.push(this.decomposeToScales(multiplier))
+        wordSets.push(this.decomposeInteger(multiplier))
       }
 
-      decomposeWordSets.push({ [matchingScaleWordPair[1]]: matchingScaleWordPair[0] })
+      wordSets.push({ [match[1]]: match[0] })
 
-      remainingValue = remainingValue === 0n ? 0n : remainingValue % matchingScaleWordPair[0]
-    } while (remainingValue > 0n)
+      remaining = remaining === 0n ? 0n : remaining % match[0]
+    } while (remaining > 0n)
 
-    return decomposeWordSets
+    return wordSets
   }
 
   /**
-   * Reduce a nested array of word-sets into a single merged word-set object.
+   * Reduces a nested array of word-sets into a single word-set object.
    *
-   * This method repeatedly applies the subclass `mergeScales()` operation until a single
-   * object remains. It normalizes nested arrays by recursively merging them.
+   * 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>} mergeWordSetsList Array of word-set objects and nested arrays.
-   * @returns {Object} Merged word-set where the single object key is the language string
+   * @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.
    */
-  mergeWordSets (mergeWordSetsList) {
-    while (mergeWordSetsList.length > 1) {
-      const [firstWordSet, secondWordSet, ...remainingWordSets] = mergeWordSetsList
+  reduceWordSets (wordSets) {
+    while (wordSets.length > 1) {
+      const [first, second, ...rest] = wordSets
 
-      if (!Array.isArray(firstWordSet) && !Array.isArray(secondWordSet)) {
-        const merged = this.mergeScales(firstWordSet, secondWordSet)
-        mergeWordSetsList = remainingWordSets.length > 0 ? [merged, remainingWordSets] : [merged]
+      if (!Array.isArray(first) && !Array.isArray(second)) {
+        const combined = this.combineWordSets(first, second)
+        wordSets = rest.length > 0 ? [combined, rest] : [combined]
         continue
       }
 
-      const normalizedWordSets = mergeWordSetsList.map((wordSetElement) => {
-        if (!Array.isArray(wordSetElement)) return wordSetElement
-        return wordSetElement.length === 1 ? wordSetElement[0] : this.mergeWordSets(wordSetElement)
+      const normalized = wordSets.map((element) => {
+        if (!Array.isArray(element)) return element
+        return element.length === 1 ? element[0] : this.reduceWordSets(element)
       })
 
-      mergeWordSetsList = normalizedWordSets
+      wordSets = normalized
     }
 
-    return mergeWordSetsList[0]
+    return wordSets[0]
   }
 
+  // ============================================================================
+  // Abstract Methods (subclasses must implement)
+  // ============================================================================
+
   /**
-   * Combine two adjacent word-sets into a single merged word-set.
+   * 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.
@@ -147,19 +151,23 @@ class GreedyScaleLanguage extends AbstractLanguage {
    *
    * @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.
+   * @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:
-   * // mergeScales({ 'twenty': 20n }, { 'three': 3n }) → { 'twenty-three': 23n }
-   * // mergeScales({ 'one': 1n }, { 'hundred': 100n }) → { 'one hundred': 100n }
+   * // combineWordSets({ 'twenty': 20n }, { 'three': 3n }) → { 'twenty-three': 23n }
+   * // combineWordSets({ 'one': 1n }, { 'hundred': 100n }) → { 'one hundred': 100n }
    */
-  mergeScales (leftWordSet, rightWordSet) {
-    throw new Error('mergeScales() must be implemented by subclass')
+  combineWordSets (preceding, following) {
+    throw new Error('combineWordSets() must be implemented by subclass')
   }
 
+  // ============================================================================
+  // Optional Methods (subclasses may override)
+  // ============================================================================
+
   /**
    * Final string post-processing hook.
    *
@@ -167,7 +175,7 @@ class GreedyScaleLanguage extends AbstractLanguage {
    * orthographic corrections.
    *
    * @protected
-   * @param {string} output Merged language string produced by `convertWholePart` flow.
+   * @param {string} output Language string produced by the conversion flow.
    * @returns {string} Final formatted string.
    */
   finalizeWords (output) {
@@ -175,21 +183,19 @@ class GreedyScaleLanguage extends AbstractLanguage {
   }
 
   /**
-   * Convert an integer value to its language-specific cardinal words.
+   * Converts an integer to its language-specific cardinal words.
    *
-   * This method orchestrates decomposition, merging and final formatting. It does
+   * This method orchestrates decomposition, reduction, 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.
+   * `AbstractLanguage.toWords` which calls this method for the integer part.
    *
-   * @param {bigint|number} wholeNumber Whole-number value to convert (BigInt is preferred).
-   * @returns {string} The cardinal representation for `value` in the language.
+   * @param {bigint} integerPart The integer to convert.
+   * @returns {string} The cardinal representation for the integer 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)
+  integerToWords (integerPart) {
+    const wordSets = this.decomposeInteger(integerPart)
+    const reduced = this.reduceWordSets(wordSets)
+    const result = Object.keys(reduced)[0]
+    return this.finalizeWords(result)
   }
 }
-
-export default GreedyScaleLanguage

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

@@ -0,0 +1,148 @@
+/**
+ * Base class for Slavic and related languages with complex pluralization.
+ *
+ * This class provides a reusable implementation for languages that share:
+ * - Three-form pluralization (singular/few/many)
+ * - Gender-aware number forms (masculine/feminine for 1-9)
+ * - Hundreds, tens, ones decomposition pattern
+ * - Segment-based large number handling (thousands, millions, etc.)
+ * - Inherits decimal handling from AbstractLanguage (supports both grouped and
+ *   per-digit modes via the `usePerDigitDecimals` class property).
+ *
+ * Used by: Russian (ru), Czech (cs), Polish (pl), Ukrainian (uk), Serbian (sr-Latn),
+ * Croatian (hr), Lithuanian (lt), Latvian (lv), Hebrew (he), and Biblical Hebrew (hbo).
+ *
+ * Subclasses MUST define these properties with language-specific vocabulary:
+ * - `onesWords` - Object mapping 1-9 to masculine forms (or default forms)
+ * - `onesFeminineWords` - Object mapping 1-9 to feminine forms (if gender distinction exists)
+ * - `teensWords` - Object mapping 0-9 to teen numbers (10-19)
+ * - `twentiesWords` - Object mapping 2-9 to tens (20-90)
+ * - `hundredsWords` - Object mapping 1-9 to hundreds (100-900) or special hundreds handling
+ * - `pluralForms` - Object mapping segment indices to [singular, few, many] plural forms
+ *
+ * Optional properties:
+ * - `scaleGenders` - Object mapping segment indices to boolean (true = feminine scale word)
+ *   If not defined, defaults to thousands (index 1) being feminine, others masculine.
+ *
+ * @abstract
+ * @extends AbstractLanguage
+ */
+export class SlavicLanguage extends AbstractLanguage {
+    /**
+     * Constructs a SlavicLanguage instance with optional configuration.
+     *
+     * @param {Object} [options] Configuration options.
+     * @param {('masculine'|'feminine')} [options.gender='masculine'] Grammatical gender for number forms.
+     */
+    constructor(options?: {
+        gender?: "feminine" | "masculine" | undefined;
+    });
+    /**
+     * Masculine forms for digits 1-9 (or default forms if no gender distinction).
+     *
+     * @type {Object.<number, string>}
+     */
+    onesWords: {
+        [x: number]: string;
+    };
+    /**
+     * Feminine forms for digits 1-9 (if language has gender distinction).
+     *
+     * @type {Object.<number, string>}
+     */
+    onesFeminineWords: {
+        [x: number]: string;
+    };
+    /**
+     * Words for teen numbers (10-19).
+     *
+     * @type {Object.<number, string>}
+     */
+    teensWords: {
+        [x: number]: string;
+    };
+    /**
+     * Words for multiples of ten (20, 30, 40, etc.).
+     *
+     * @type {Object.<number, string>}
+     */
+    twentiesWords: {
+        [x: number]: string;
+    };
+    /**
+     * Words for hundreds (100, 200, 300, etc.) or special hundreds handling.
+     *
+     * @type {Object.<number, string>}
+     */
+    hundredsWords: {
+        [x: number]: string;
+    };
+    /**
+     * Plural forms for scale words (thousands, millions, billions, etc.).
+     * Maps segment indices to [singular, few, many] forms.
+     *
+     * @type {Object.<number, string[]>}
+     */
+    pluralForms: {
+        [x: number]: string[];
+    };
+    /**
+     * Gender of each scale word.
+     * Maps segment indices to boolean: true = feminine, false = masculine.
+     * Default is empty (all masculine). Languages with feminine thousands
+     * (Russian, Ukrainian, Serbian, Croatian) should set `{ 1: true }`.
+     *
+     * @type {Object.<number, boolean>}
+     */
+    scaleGenders: {
+        [x: number]: boolean;
+    };
+    /**
+     * Whether to omit "one" before scale words (e.g., "thousand" instead of "one thousand").
+     * When true, 1000 becomes "tysiąc" (Polish) instead of "jeden tysiąc".
+     * Used by Polish, Czech, and similar languages.
+     *
+     * @type {boolean}
+     */
+    omitOneBeforeScale: boolean;
+    /**
+     * Splits a number string into segments of specified size from right to left.
+     *
+     * Example: splitToSegments('1234567', 3) => [1n, 234n, 567n]
+     * This represents: 1 million + 234 thousand + 567 ones
+     *
+     * @param {string} numberString The number as a string.
+     * @param {number} segmentSize Segment size (typically 3 for thousands grouping).
+     * @returns {bigint[]} Array of BigInt segments from highest to lowest scale.
+     */
+    splitToSegments(numberString: string, segmentSize: number): bigint[];
+    /**
+     * Extracts individual digits from a number (units, tens, hundreds).
+     *
+     * Returns digits in reverse order: [ones, tens, hundreds]
+     * Example: 456 => [6n, 5n, 4n]
+     *
+     * @param {bigint} value The number to extract digits from (0-999).
+     * @returns {bigint[]} Array of [ones, tens, hundreds] as BigInts.
+     */
+    extractDigits(value: bigint): bigint[];
+    /**
+     * Selects the correct plural form based on Slavic pluralization rules.
+     *
+     * Slavic languages typically use three forms:
+     * - Form 0 (singular): numbers ending in 1, except 11 (1, 21, 31, 101...)
+     * - Form 1 (few): numbers ending in 2-4, except 12-14 (2-4, 22-24, 32-34...)
+     * - Form 2 (many): all other numbers (0, 5-20, 25-30, 100, 111-119...)
+     *
+     * Examples using Russian тысяча (thousand):
+     * - 1, 21, 31... ⇒ тысяча (form 0, singular)
+     * - 2-4, 22-24, 32-34... ⇒ тысячи (form 1, few)
+     * - 0, 5-20, 25-30, 100... ⇒ тысяч (form 2, many)
+     *
+     * @param {bigint} number The number to check.
+     * @param {string[]} pluralForms Array of [singular, few, many] forms.
+     * @returns {string} The appropriate form for the number.
+     */
+    pluralize(number: bigint, pluralForms: string[]): string;
+}
+import { AbstractLanguage } from './abstract-language.js';