n2words 1.23.1 → 2.0.0

package/lib/classes/slavic-language.js

@@ -0,0 +1,281 @@
+import { AbstractLanguage } from './abstract-language.js'
+
+/**
+ * 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 {
+  // ============================================================================
+  // Required Properties (subclasses must define)
+  // ============================================================================
+
+  /**
+   * Masculine forms for digits 1-9 (or default forms if no gender distinction).
+   *
+   * @type {Object.<number, string>}
+   */
+  onesWords = {}
+
+  /**
+   * Feminine forms for digits 1-9 (if language has gender distinction).
+   *
+   * @type {Object.<number, string>}
+   */
+  onesFeminineWords = {}
+
+  /**
+   * Words for teen numbers (10-19).
+   *
+   * @type {Object.<number, string>}
+   */
+  teensWords = {}
+
+  /**
+   * Words for multiples of ten (20, 30, 40, etc.).
+   *
+   * @type {Object.<number, string>}
+   */
+  twentiesWords = {}
+
+  /**
+   * Words for hundreds (100, 200, 300, etc.) or special hundreds handling.
+   *
+   * @type {Object.<number, string>}
+   */
+  hundredsWords = {}
+
+  /**
+   * Plural forms for scale words (thousands, millions, billions, etc.).
+   * Maps segment indices to [singular, few, many] forms.
+   *
+   * @type {Object.<number, string[]>}
+   */
+  pluralForms = {}
+
+  // ============================================================================
+  // Optional Properties (subclasses may override)
+  // ============================================================================
+
+  /**
+   * 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 = {}
+
+  /**
+   * 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 = false
+
+  // ============================================================================
+  // Constructor
+  // ============================================================================
+
+  /**
+   * 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 = {}) {
+    super()
+
+    this.setOptions({
+      gender: 'masculine'
+    }, options)
+  }
+
+  // ============================================================================
+  // Public Methods
+  // ============================================================================
+
+  /**
+   * Converts an integer to its word representation.
+   *
+   * This method implements the Slavic number construction algorithm:
+   * 1. Split number into 3-digit segments from right to left (567, 234, 1 for 1,234,567)
+   * 2. For each segment (processing left to right): convert hundreds, tens, ones
+   * 3. Apply gender rules: feminine forms for thousands segment or when feminine=true
+   * 4. Add appropriate pluralized scale word (thousand/million/billion/etc.)
+   * 5. Join all parts with spaces
+   *
+   * @param {bigint} integerPart The integer to convert (non-negative).
+   * @returns {string} The number in words.
+   */
+  integerToWords (integerPart) {
+    if (integerPart === 0n) {
+      return this.zeroWord
+    }
+
+    const words = []
+    const segments = this.splitToSegments(integerPart.toString(), 3)
+    let segmentIndex = segments.length
+
+    for (const segmentValue of segments) {
+      segmentIndex = segmentIndex - 1
+
+      if (segmentValue === 0n) {
+        continue
+      }
+
+      const [onesDigit, tensDigit, hundredsDigit] = this.extractDigits(segmentValue)
+
+      if (hundredsDigit > 0n) {
+        words.push(this.hundredsWords[hundredsDigit])
+      }
+
+      if (tensDigit > 1n) {
+        words.push(this.twentiesWords[tensDigit])
+      }
+
+      // Handle teens (10-19) or ones (1-9)
+      if (tensDigit === 1n) {
+        // Teens: use teensWords array directly
+        words.push(this.teensWords[onesDigit])
+      } else if (onesDigit > 0n) {
+        // Skip "one" before scale words if omitOneBeforeScale is set
+        // e.g., Polish says "tysiąc" not "jeden tysiąc" for 1000
+        const shouldOmitOne = this.omitOneBeforeScale && segmentIndex > 0 && segmentValue === 1n
+
+        if (!shouldOmitOne) {
+          // Determine if feminine forms should be used:
+          // 1. Check scaleGenders for this segment index (e.g., thousands = index 1)
+          // 2. Also use feminine if user requested gender='feminine' for the ones segment
+          const isScaleFeminine = this.scaleGenders[segmentIndex] === true
+          const isFeminine = isScaleFeminine || (this.options.gender === 'feminine' && segmentIndex === 0)
+          const onesArray = isFeminine ? this.onesFeminineWords : this.onesWords
+          words.push(onesArray[onesDigit])
+        }
+      }
+
+      // Add power word (thousand, million, etc.) with proper pluralization
+      if (segmentIndex > 0) {
+        words.push(this.pluralize(segmentValue, this.pluralForms[segmentIndex]))
+      }
+    }
+
+    return words.join(' ')
+  }
+
+  // ============================================================================
+  // Protected Methods (subclasses may call or override)
+  // ============================================================================
+
+  /**
+   * 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, segmentSize) {
+    const segments = []
+    const stringLength = numberString.length
+
+    if (stringLength > segmentSize) {
+      const remainderLength = stringLength % segmentSize
+
+      if (remainderLength > 0) {
+        segments.push(BigInt(numberString.slice(0, remainderLength)))
+      }
+
+      for (let i = remainderLength; i < stringLength; i += segmentSize) {
+        segments.push(BigInt(numberString.slice(i, i + segmentSize)))
+      }
+    } else {
+      segments.push(BigInt(numberString))
+    }
+
+    return segments
+  }
+
+  /**
+   * 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) {
+    // Direct BigInt arithmetic is faster than string manipulation
+    const onesPlace = value % 10n
+    const tensPlace = (value / 10n) % 10n
+    const hundredsPlace = value / 100n
+    return [onesPlace, tensPlace, hundredsPlace]
+  }
+
+  /**
+   * 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, pluralForms) {
+    const remainder100 = number % 100n
+    const remainder10 = number % 10n
+
+    // Check if in 11-19 range (special case)
+    if (remainder100 >= 10n && remainder100 <= 20n) {
+      return pluralForms[2] // Always use "many" form for 11-20
+    }
+
+    if (remainder10 === 1n) {
+      return pluralForms[0] // Singular
+    }
+
+    if (remainder10 >= 2n && remainder10 <= 4n) {
+      return pluralForms[1] // Few (2-4)
+    }
+
+    return pluralForms[2] // Many
+  }
+}

package/lib/classes/south-asian-language.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Base class for South Asian languages with shared grouping patterns.
+ *
+ * This class provides a reusable implementation for South Asian languages that share:
+ * - Indian-style number grouping: last 3 digits, then 2-2 (1,23,45,67,89)
+ * - Lakh (100,000), Crore (10,000,000), Arab (1,000,000,000) scale words
+ * - Standard negative and decimal handling (inherits AbstractLanguage decimal logic,
+ *   including `usePerDigitDecimals` support when set by subclasses)
+ *
+ * Used by: Hindi (hi), Bengali (bn), Urdu (ur), Punjabi (pa), Marathi (mr), Gujarati (gu), Kannada (kn)
+ *
+ * Subclasses MUST define language-specific vocabulary via class properties:
+ * - `belowHundredWords` array with digit and teen words (0-99)
+ * - `hundredWord` string used inside `segmentToWords`
+ * - `scaleWords` array with grouping words (hazaar, lakh, crore, etc.) indexed by grouping level
+ * - `negativeWord`, `decimalSeparatorWord`, `zeroWord`, `wordSeparator`
+ *
+ * @abstract
+ * @extends AbstractLanguage
+ */
+export class SouthAsianLanguage extends AbstractLanguage {
+    /**
+     * Array of words for numbers 0-99 (digits and teens).
+     * Index directly: belowHundredWords[0] through belowHundredWords[99].
+     * @type {Array<string>}
+     */
+    belowHundredWords: Array<string>;
+    /**
+     * Word for "hundred" in the language (e.g., 'सौ' in Hindi, 'শত' in Bengali).
+     * Used to construct hundreds (e.g., "1 hundred", "2 hundred").
+     * @type {string}
+     */
+    hundredWord: string;
+    /**
+     * Array of scale words for Indian-style grouping (hazaar, lakh, crore, arab, etc.).
+     * Index 0 contains empty string (ones place has no scale word).
+     * Index 1 is for thousands, Index 2 for lakhs, Index 3 for crores, etc.
+     * @type {Array<string>}
+     */
+    scaleWords: Array<string>;
+    /**
+     * Splits a number into Indian numbering system segments.
+     *
+     * The Indian system segments differently than Western (3-3-3) systems:
+     * - First segment (rightmost): Up to 3 digits (ones, tens, hundreds)
+     * - Subsequent segments: Exactly 2 digits each (thousands, lakhs, crores, etc.)
+     *
+     * This creates the familiar Indian comma pattern: 1,23,45,67,890
+     *
+     * @protected
+     * @param {bigint} integerPart The integer to split into segments.
+     * @returns {Array<number>} Array of segments from most significant to least significant.
+     *
+     * @example
+     * // splitToSegments(1234567n) → [12, 34, 567]
+     * // Reads as: 12 lakhs, 34 thousands, 567 units
+     * // splitToSegments(98765432n) → [9, 87, 65, 432]
+     * // Reads as: 9 crores, 87 lakhs, 65 thousands, 432 units
+     */
+    protected splitToSegments(integerPart: bigint): Array<number>;
+    /**
+     * Converts a segment (0-999) to words.
+     *
+     * @protected
+     * @param {number} segmentValue Value between 0 and 999.
+     * @returns {string} Language-specific word representation.
+     */
+    protected segmentToWords(segmentValue: number): string;
+}
+import { AbstractLanguage } from './abstract-language.js';

package/lib/classes/south-asian-language.js

@@ -0,0 +1,154 @@
+import { AbstractLanguage } from './abstract-language.js'
+
+/**
+ * Base class for South Asian languages with shared grouping patterns.
+ *
+ * This class provides a reusable implementation for South Asian languages that share:
+ * - Indian-style number grouping: last 3 digits, then 2-2 (1,23,45,67,89)
+ * - Lakh (100,000), Crore (10,000,000), Arab (1,000,000,000) scale words
+ * - Standard negative and decimal handling (inherits AbstractLanguage decimal logic,
+ *   including `usePerDigitDecimals` support when set by subclasses)
+ *
+ * Used by: Hindi (hi), Bengali (bn), Urdu (ur), Punjabi (pa), Marathi (mr), Gujarati (gu), Kannada (kn)
+ *
+ * Subclasses MUST define language-specific vocabulary via class properties:
+ * - `belowHundredWords` array with digit and teen words (0-99)
+ * - `hundredWord` string used inside `segmentToWords`
+ * - `scaleWords` array with grouping words (hazaar, lakh, crore, etc.) indexed by grouping level
+ * - `negativeWord`, `decimalSeparatorWord`, `zeroWord`, `wordSeparator`
+ *
+ * @abstract
+ * @extends AbstractLanguage
+ */
+export class SouthAsianLanguage extends AbstractLanguage {
+  // ============================================================================
+  // Required Properties (subclasses must define)
+  // ============================================================================
+
+  /**
+   * Array of words for numbers 0-99 (digits and teens).
+   * Index directly: belowHundredWords[0] through belowHundredWords[99].
+   * @type {Array<string>}
+   */
+  belowHundredWords
+
+  /**
+   * Word for "hundred" in the language (e.g., 'सौ' in Hindi, 'শত' in Bengali).
+   * Used to construct hundreds (e.g., "1 hundred", "2 hundred").
+   * @type {string}
+   */
+  hundredWord
+
+  /**
+   * Array of scale words for Indian-style grouping (hazaar, lakh, crore, arab, etc.).
+   * Index 0 contains empty string (ones place has no scale word).
+   * Index 1 is for thousands, Index 2 for lakhs, Index 3 for crores, etc.
+   * @type {Array<string>}
+   */
+  scaleWords
+
+  // ============================================================================
+  // Protected Methods (subclasses may call or override)
+  // ============================================================================
+
+  /**
+   * Splits a number into Indian numbering system segments.
+   *
+   * The Indian system segments differently than Western (3-3-3) systems:
+   * - First segment (rightmost): Up to 3 digits (ones, tens, hundreds)
+   * - Subsequent segments: Exactly 2 digits each (thousands, lakhs, crores, etc.)
+   *
+   * This creates the familiar Indian comma pattern: 1,23,45,67,890
+   *
+   * @protected
+   * @param {bigint} integerPart The integer to split into segments.
+   * @returns {Array<number>} Array of segments from most significant to least significant.
+   *
+   * @example
+   * // splitToSegments(1234567n) → [12, 34, 567]
+   * // Reads as: 12 lakhs, 34 thousands, 567 units
+   * // splitToSegments(98765432n) → [9, 87, 65, 432]
+   * // Reads as: 9 crores, 87 lakhs, 65 thousands, 432 units
+   */
+  splitToSegments (integerPart) {
+    const numStr = integerPart.toString()
+
+    if (numStr.length <= 3) {
+      return [Number(numStr)]
+    }
+
+    const segments = []
+    const last3 = numStr.slice(-3)
+    segments.unshift(Number(last3))
+
+    let remaining = numStr.slice(0, -3)
+    while (remaining.length > 0) {
+      const segment = remaining.slice(-2)
+      segments.unshift(Number(segment))
+      remaining = remaining.slice(0, -2)
+    }
+
+    return segments
+  }
+
+  /**
+   * Converts a segment (0-999) to words.
+   *
+   * @protected
+   * @param {number} segmentValue Value between 0 and 999.
+   * @returns {string} Language-specific word representation.
+   */
+  segmentToWords (segmentValue) {
+    if (segmentValue === 0) return ''
+    if (segmentValue < 100) return this.belowHundredWords[segmentValue]
+
+    const hundreds = Math.trunc(segmentValue / 100)
+    const remainder = segmentValue % 100
+    const parts = []
+
+    if (hundreds === 1) {
+      parts.push(this.belowHundredWords[1] + ' ' + this.hundredWord)
+    } else {
+      parts.push(this.belowHundredWords[hundreds] + ' ' + this.hundredWord)
+    }
+
+    if (remainder > 0) {
+      parts.push(this.belowHundredWords[remainder])
+    }
+
+    return parts.join(' ')
+  }
+
+  // ============================================================================
+  // Public Methods
+  // ============================================================================
+
+  /**
+   * Converts integer to cardinal words using South Asian grouping.
+   *
+   * @param {bigint} integerPart Number to convert.
+   * @returns {string} Cardinal representation.
+   */
+  integerToWords (integerPart) {
+    if (integerPart === 0n) {
+      return this.zeroWord
+    }
+
+    const segments = this.splitToSegments(integerPart)
+    const segmentCount = segments.length
+    const words = []
+
+    for (let i = 0; i < segmentCount; i++) {
+      const segmentValue = segments[i]
+      if (segmentValue === 0) continue
+
+      const scaleIndex = segmentCount - i - 1
+      words.push(this.segmentToWords(segmentValue))
+      if (scaleIndex > 0 && this.scaleWords[scaleIndex]) {
+        words.push(this.scaleWords[scaleIndex])
+      }
+    }
+
+    return words.join(' ').trim()
+  }
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Base class for Turkic languages with shared grammar patterns.
+ *
+ * This class provides a reusable implementation for Turkic languages that share:
+ * - Space-separated number combinations
+ * - Implicit 'bir' (one) before hundreds and thousands
+ * - Simple multiplication/addition logic
+ * - Consistent magnitude handling
+ * - Inherits decimal handling from AbstractLanguage via GreedyScaleLanguage
+ *   (supports both grouped and per-digit modes via the `usePerDigitDecimals` class property).
+ *
+ * Used by: Turkish (TR), Azerbaijani (AZ)
+ *
+ * Subclasses MUST define (from GreedyScaleLanguage requirements):
+ * - `scaleWords` array of [value, word] tuples as a class property (ordered descending by value).
+ * Optionally, language-specific class properties (e.g., `negativeWord`, `zeroWord`, `decimalSeparatorWord`, `wordSeparator`).
+ *
+ * TurkicLanguage provides a default `combineWordSets()` implementation; subclasses may override
+ * if specialized combine logic is needed (unlikely for Turkic languages).
+ *
+ * @abstract
+ * @extends GreedyScaleLanguage
+ */
+export class TurkicLanguage extends GreedyScaleLanguage {
+}
+import { GreedyScaleLanguage } from './greedy-scale-language.js';

package/lib/classes/turkic-language.js

@@ -0,0 +1,59 @@
+import { GreedyScaleLanguage } from './greedy-scale-language.js'
+
+/**
+ * Base class for Turkic languages with shared grammar patterns.
+ *
+ * This class provides a reusable implementation for Turkic languages that share:
+ * - Space-separated number combinations
+ * - Implicit 'bir' (one) before hundreds and thousands
+ * - Simple multiplication/addition logic
+ * - Consistent magnitude handling
+ * - Inherits decimal handling from AbstractLanguage via GreedyScaleLanguage
+ *   (supports both grouped and per-digit modes via the `usePerDigitDecimals` class property).
+ *
+ * Used by: Turkish (TR), Azerbaijani (AZ)
+ *
+ * Subclasses MUST define (from GreedyScaleLanguage requirements):
+ * - `scaleWords` array of [value, word] tuples as a class property (ordered descending by value).
+ * Optionally, language-specific class properties (e.g., `negativeWord`, `zeroWord`, `decimalSeparatorWord`, `wordSeparator`).
+ *
+ * TurkicLanguage provides a default `combineWordSets()` implementation; subclasses may override
+ * if specialized combine logic is needed (unlikely for Turkic languages).
+ *
+ * @abstract
+ * @extends GreedyScaleLanguage
+ */
+export class TurkicLanguage extends GreedyScaleLanguage {
+  // ============================================================================
+  // Inherited Implementation (overrides GreedyScaleLanguage)
+  // ============================================================================
+
+  /**
+   * Combines two adjacent word-sets according to Turkic grammar rules.
+   *
+   * Shared Turkic patterns:
+   * - Implicit 'bir' (one) before hundreds and thousands
+   * - Space separator (wordSeparator property) for all combinations
+   * - Multiplies when following > preceding (crossing magnitude boundary)
+   * - Adds otherwise (combining same-magnitude components)
+   *
+   * @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 word and resulting number.
+   */
+  combineWordSets (preceding, following) {
+    const [[precedingWord, precedingValue]] = Object.entries(preceding)
+    const [[followingWord, followingValue]] = Object.entries(following)
+
+    // Implicit 'bir' (one) before certain magnitudes:
+    // Omit '1' before hundreds (100n) and thousands (1000n) to form natural combinations
+    if (precedingValue === 1n && (followingValue <= 100n || followingValue === 1000n)) {
+      return following // Return just the magnitude word (e.g., "yüz", not "bir yüz")
+    }
+
+    // Combine numbers with space separator (wordSeparator from GreedyScaleLanguage):
+    // Multiply when crossing magnitude boundary, add otherwise
+    const resultNumber = followingValue > precedingValue ? precedingValue * followingValue : precedingValue + followingValue
+    return { [`${precedingWord}${this.wordSeparator}${followingWord}`]: resultNumber }
+  }
+}

package/lib/languages/ar.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Arabic language converter.
+ *
+ * Supports:
+ * - Gender agreement (masculine/feminine forms)
+ * - Complex pluralization (singular/dual/plural)
+ * - Traditional Arabic number naming conventions
+ * - Right-to-left text orientation
+ */
+export class Arabic extends AbstractLanguage {
+    constructor(options?: {});
+    tensWords: string[];
+    hundredsWords: string[];
+    scaleWords: string[];
+    scaleAppendedWords: string[];
+    scalePluralWords: string[];
+    dualWords: string[];
+    dualAppendedWords: string[];
+    ones: {
+        masculine: string[];
+        feminine: string[];
+    };
+    /** Selects masculine or feminine number forms based on options. */
+    get selectedOnes(): string[];
+    /** Converts a 3-digit segment (0-999) to Arabic words with gender/plural rules. */
+    segmentToWords(groupNumber: any, groupLevel: any, fullNumber: any): string;
+    /** Converts integer part to Arabic words by processing 3-digit groups. */
+    integerToWords(integerPart: any): string;
+}
+import { AbstractLanguage } from '../classes/abstract-language.js';