n2words 1.23.1 → 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

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

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';