n2words 1.24.0 → 3.0.0

package/lib/languages/ar.js

@@ -1,243 +1,205 @@
-import AbstractLanguage from '../classes/abstract-language.js'
-
-/**
- * @typedef {Object} ArabicOptions
- * @property {string} [negativeWord='ناقص'] Word for negative numbers (minus).
- * @property {boolean} [feminine=false] Use feminine forms for numbers.
- */
-
 /**
- * Arabic language converter.
- *
- * Converts numbers to Arabic words with full grammatical support:
- * - Gender agreement (masculine/feminine forms)
- * - Complex pluralization rules (singular, dual, plural forms)
- * - Special handling for hundreds, thousands, millions, etc.
- * - Right-to-left text orientation
- * - Traditional Arabic number naming conventions
- *
- * Key Features:
- * - Gender-aware number forms (واحد masculine vs واحدة feminine)
- * - Dual forms: اثنان/اثنتان (two masculine/feminine)
- * - Complex rule system for numbers 3-10 (requiring feminine when referring to countables)
- * - Group-based algorithm: splits number by powers of 1000 (ones, thousands, millions, billions)
- * - Tanween (nunation) for indefinite numbers
- * - Sophisticated pluralization with singular, dual, and plural forms
+ * Arabic language converter - Functional Implementation
  *
- * Algorithm:
- * 1. Break number into groups of 3 digits (right to left)
- * 2. For each non-zero group, convert to words using gender and plural rules
- * 3. Append the appropriate magnitude word (ألف/مليون/مليار) with proper plural form
- * 4. Join all groups with spaces
+ * Self-contained converter with gender agreement and complex pluralization.
  *
- * Features:
- * - Support for gender-aware number forms
- * - Proper handling of Arabic dual forms (اثنان/اثنتان)
- * - Complex group processing for large numbers
- * - Right-to-left text orientation
+ * Key features:
+ * - Gender agreement (masculine/feminine forms)
+ * - Complex pluralization (singular/dual/plural)
  * - Traditional Arabic number naming conventions
+ * - "و" (and) conjunction between segments
  */
-export class Arabic extends AbstractLanguage {
-  decimalSeparatorWord = 'فاصلة'
-  zeroWord = 'صفر'
-  arabicTens = ['عشرون', 'ثلاثون', 'أربعون', 'خمسون', 'ستون', 'سبعون', 'ثمانون', 'تسعون']
-  arabicHundreds = ['', 'مائة', 'مئتان', 'ثلاثمائة', 'أربعمائة', 'خمسمائة', 'ستمائة', 'سبعمائة', 'ثمانمائة', 'تسعمائة']
-  arabicAppendedTwos = ['مئتا', 'ألفا', 'مليونا', 'مليارا', 'تريليونا', 'كوادريليونا', 'كوينتليونا', 'سكستيليونا']
-  arabicTwos = ['مئتان', 'ألفان', 'مليونان', 'ملياران', 'تريليونان', 'كوادريليونان', 'كوينتليونان', 'سكستيليونان']
-  arabicGroup = ['مائة', 'ألف', 'مليون', 'مليار', 'تريليون', 'كوادريليون', 'كوينتليون', 'سكستيليون']
-  arabicAppendedGroup = ['', 'ألفاً', 'مليوناً', 'ملياراً', 'تريليوناً', 'كوادريليوناً', 'كوينتليوناً', 'سكستيليوناً']
-  arabicPluralGroups = ['', 'آلاف', 'ملايين', 'مليارات', 'تريليونات', 'كوادريليونات', 'كوينتليونات', 'سكستيليونات']
-  ones = {
-    masculine: [
-      'واحد',
-      'اثنان',
-      'ثلاثة',
-      'أربعة',
-      'خمسة',
-      'ستة',
-      'سبعة',
-      'ثمانية',
-      'تسعة',
-      'عشرة',
-      'أحد عشر',
-      'اثنا عشر',
-      'ثلاثة عشر',
-      'أربعة عشر',
-      'خمسة عشر',
-      'ستة عشر',
-      'سبعة عشر',
-      'ثمانية عشر',
-      'تسعة عشر'
-    ],
-    feminine: [
-      'واحدة',
-      'اثنتان',
-      'ثلاث',
-      'أربع',
-      'خمس',
-      'ست',
-      'سبع',
-      'ثمان',
-      'تسع',
-      'عشر',
-      'إحدى عشرة',
-      'اثنتا عشرة',
-      'ثلاث عشرة',
-      'أربع عشرة',
-      'خمس عشرة',
-      'ست عشرة',
-      'سبع عشرة',
-      'ثماني عشرة',
-      'تسع عشرة'
-    ]
-  }
 
-  /**
-   * Initializes the Arabic converter with language-specific options.
-   *
-   * @param {ArabicOptions} [options={}] Configuration options.
-   */
-  constructor ({ negativeWord = 'ناقص', feminine = false } = {}) {
-    super()
+import { parseNumericValue } from '../utils/parse-numeric.js'
+import { validateOptions } from '../utils/validate-options.js'
 
-    this.feminine = feminine
-    this.negativeWord = negativeWord
+// ============================================================================
+// Vocabulary
+// ============================================================================
 
-    this.selectedOnes = this.ones[this.feminine ? 'feminine' : 'masculine']
-  }
+const TENS = ['عشرون', 'ثلاثون', 'أربعون', 'خمسون', 'ستون', 'سبعون', 'ثمانون', 'تسعون']
+const HUNDREDS = ['', 'مائة', 'مئتان', 'ثلاثمائة', 'أربعمائة', 'خمسمائة', 'ستمائة', 'سبعمائة', 'ثمانمائة', 'تسعمائة']
+
+// Magnitude words with three forms: singular, appended (tanween), plural
+const SCALE_WORDS = ['مائة', 'ألف', 'مليون', 'مليار', 'تريليون', 'كوادريليون', 'كوينتليون', 'سكستيليون']
+const SCALE_APPENDED = ['', 'ألفاً', 'مليوناً', 'ملياراً', 'تريليوناً', 'كوادريليوناً', 'كوينتليوناً', 'سكستيليوناً']
+const SCALE_PLURAL = ['', 'آلاف', 'ملايين', 'مليارات', 'تريليونات', 'كوادريليونات', 'كوينتليونات', 'سكستيليونات']
+
+// Dual forms
+const DUAL = ['مئتان', 'ألفان', 'مليونان', 'ملياران', 'تريليونان', 'كوادريليونان', 'كوينتليونان', 'سكستيليونان']
+const DUAL_APPENDED = ['مئتا', 'ألفا', 'مليونا', 'مليارا', 'تريليونا', 'كوادريليونا', 'كوينتليونا', 'سكستيليونا']
+
+// Gender-specific forms (1-19)
+const ONES_MASC = ['واحد', 'اثنان', 'ثلاثة', 'أربعة', 'خمسة', 'ستة', 'سبعة', 'ثمانية', 'تسعة', 'عشرة', 'أحد عشر', 'اثنا عشر', 'ثلاثة عشر', 'أربعة عشر', 'خمسة عشر', 'ستة عشر', 'سبعة عشر', 'ثمانية عشر', 'تسعة عشر']
+const ONES_FEM = ['واحدة', 'اثنتان', 'ثلاث', 'أربع', 'خمس', 'ست', 'سبع', 'ثمان', 'تسع', 'عشر', 'إحدى عشرة', 'اثنتا عشرة', 'ثلاث عشرة', 'أربع عشرة', 'خمس عشرة', 'ست عشرة', 'سبع عشرة', 'ثماني عشرة', 'تسع عشرة']
+
+const ZERO = 'صفر'
+const NEGATIVE = 'ناقص'
+const DECIMAL_SEP = 'فاصلة'
+const AND = 'و'
 
-  /**
-   * Returns the feminine status of a given digit (1-9).
-   *
-   * @param {number} digit - The digit to check (1-9).
-   * @returns {string} The word form of the digit based on feminine status.
-   */
-  digitFeminineStatus (digit) {
-    return this.selectedOnes[digit - 1]
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+/**
+ * Convert a 3-digit group to words.
+ * Returns a clean string with no leading/trailing spaces.
+ * Arabic "و" (and) is attached to following word: "مائة وخمسة" not "مائة و خمسة"
+ */
+function segmentToWords (groupNumber, groupLevel, fullNumber, ones) {
+  const tensValue = groupNumber % 100
+  const hundredsDigit = Math.trunc(groupNumber / 100)
+  let result = ''
+
+  // Process hundreds
+  if (hundredsDigit > 0) {
+    if (tensValue === 0 && hundredsDigit === 2) {
+      result = DUAL[0]
+    } else {
+      const hundredsWord = HUNDREDS[hundredsDigit]
+      if (hundredsWord) {
+        result = hundredsWord
+        if (tensValue !== 0) {
+          result += ' ' + AND // "مائة و" - و attaches to next word
+        }
+      }
+    }
   }
 
-  /**
-   * Processes the Arabic group number and returns the corresponding Arabic representation.
-   * @param {number} groupNumber - The number to process. (Range: 1-999)
-   * @param {number} groupLevel - Group level to process. (See example)
-   * @returns {string} The Arabic representation of the group number.
-   * @example 12345678 is processed in blocks of 3: '678' (group 0), '345' (group 1), '12' (group 2).
-   */
-  processArabicGroup (groupNumber, groupLevel, fullNumber) {
-    const tens = groupNumber % 100
-    const hundredsRaw = groupNumber / 100
-    const hundreds = Math.trunc(hundredsRaw)
-    let returnValue = ''
-
-    // Process hundreds
-    if (hundreds > 0) {
-      if (tens === 0 && hundreds === 2) {
-        returnValue = this.arabicTwos[0]
-      } else {
-        const hundredsWord = this.arabicHundreds[hundreds]
-        if (hundredsWord) {
-          returnValue = hundredsWord
-          if (tens !== 0) {
-            returnValue += ' و'
-          }
+  // Process tens and ones
+  if (tensValue > 0) {
+    if (tensValue < 20) {
+      if (tensValue === 2 && hundredsDigit === 0 && groupLevel > 0) {
+        const numValue = Number(fullNumber)
+        const pow = Math.trunc(Math.log10(numValue))
+        if (pow % 3 === 0 && fullNumber === BigInt(2 * Math.pow(10, pow))) {
+          result += (groupNumber === 2 ? DUAL[groupLevel] : DUAL_APPENDED[groupLevel])
+        } else {
+          result += DUAL[groupLevel]
         }
+      } else if (tensValue === 1 && groupLevel > 0) {
+        result += SCALE_WORDS[groupLevel]
+      } else {
+        result += ones[tensValue - 1]
       }
+    } else {
+      const onesDigit = tensValue % 10
+      const tensIndex = Math.trunc(tensValue / 10) - 2
+
+      if (onesDigit > 0) {
+        result += ones[onesDigit - 1] + ' ' + AND // "ستة و" attaches to tens
+      }
+      result += TENS[tensIndex]
     }
+  }
+
+  return result
+}
+
+function integerToWords (n, options) {
+  if (n === 0n) return ZERO
+
+  const gender = options.gender || 'masculine'
+  const ones = gender === 'feminine' ? ONES_FEM : ONES_MASC
+
+  let temp = n
+  let group = 0
+  const groups = []
 
-    // Process tens and ones
-    if (tens > 0) {
-      if (tens < 20) { // 1 -> 19
-        if (tens === 2 && hundreds === 0 && groupLevel > 0) {
-          // Cache expensive log10 calculation
-          const numValue = Number(fullNumber)
-          const pow = Math.trunc(Math.log10(numValue))
-          if (pow % 3 === 0 && fullNumber === BigInt(2 * Math.pow(10, pow))) {
-            returnValue = groupNumber === 2 ? this.arabicTwos[groupLevel] : this.arabicAppendedTwos[groupLevel]
+  while (temp > 0n) {
+    const numberToProcess = Number(temp % 1000n)
+    temp = temp / 1000n
+
+    if (numberToProcess > 0) {
+      const groupDescription = segmentToWords(numberToProcess, group, n, ones)
+
+      if (groupDescription) {
+        let groupText = groupDescription
+
+        // Add scale word for groups > 0
+        if (group > 0 && numberToProcess > 2) {
+          const remainder = numberToProcess % 100
+          if (remainder === 1) {
+            groupText += ' ' + SCALE_WORDS[group]
+          } else if (numberToProcess >= 3 && numberToProcess <= 10) {
+            groupText += ' ' + SCALE_PLURAL[group]
           } else {
-            returnValue = this.arabicTwos[groupLevel]
+            groupText += ' ' + (groups.length > 0 ? SCALE_APPENDED[group] : SCALE_WORDS[group])
           }
-        } else if (tens === 1 && groupLevel > 0) {
-          returnValue += this.arabicGroup[groupLevel]
-        } else {
-          returnValue += this.selectedOnes[tens - 1]
         }
-      } else { // 20 -> 99
-        const ones = tens % 10
-        const tensIndex = Math.trunc(tens / 10) - 2
 
-        if (ones > 0) {
-          returnValue += this.selectedOnes[ones - 1]
-          returnValue += ' و'
-        }
-        returnValue += this.arabicTens[tensIndex]
+        groups.unshift(groupText)
       }
     }
 
-    return returnValue
+    group++
   }
 
-  /**
-   * Converts a number to its cardinal representation in Arabic.
-   * It process by blocks of 3 digits.
-   * @param {bigint} number - The number to convert.
-   * @returns {string} The cardinal representation of the number in Arabic.
-   */
-  convertWholePart (number) {
-    if (number === 0n) {
-      return this.zeroWord
-    }
-    let temp = number
-    let group = 0
-    let result = ''
-
-    // Process each group of 3 digits (right to left)
-    while (temp > 0n) {
-      const numberToProcess = Number(temp % 1000n)
-      temp = temp / 1000n
-
-      if (numberToProcess > 0) {
-        const groupDescription = this.processArabicGroup(numberToProcess, group, number)
-
-        if (groupDescription) {
-          // Add group name for thousands, millions, etc.
-          if (group > 0) {
-            if (result) {
-              result = ' و' + result
-            }
-
-            if (numberToProcess > 2) {
-              const remainder = numberToProcess % 100
-              if (remainder === 1) {
-                result = this.arabicGroup[group] + ' ' + result
-              } else if (numberToProcess >= 3 && numberToProcess <= 10) {
-                result = this.arabicPluralGroups[group] + ' ' + result
-              } else {
-                result = (result ? this.arabicAppendedGroup[group] : this.arabicGroup[group]) + ' ' + result
-              }
-            }
-          }
+  // Join groups with و (and) - space before و, attaches to next word
+  // Use simple join since segmentToWords returns clean strings
+  if (groups.length === 1) return groups[0]
 
-          // Add group description (prepend for RTL)
-          result = groupDescription + ' ' + result
-        }
-      }
+  // Build result: "group1 وgroup2 وgroup3"
+  let result = groups[0]
+  for (let i = 1; i < groups.length; i++) {
+    result += ' ' + AND + groups[i]
+  }
+  return result
+}
 
-      group++
-    }
+function decimalPartToWords (decimalPart, options) {
+  const parts = []
+  let i = 0
+
+  while (i < decimalPart.length && decimalPart[i] === '0') {
+    parts.push(ZERO)
+    i++
+  }
 
-    return result.replace(/\s+/g, ' ').trim()
+  const remainder = decimalPart.slice(i)
+  if (remainder) {
+    parts.push(integerToWords(BigInt(remainder), options))
   }
+
+  return parts.join(' ')
 }
 
 /**
- * Converts a number to Arabic cardinal (written) form.
+ * Converts a numeric value to Arabic words.
  *
- * @param {number|string|bigint} value The number to convert.
- * @param {ArabicOptions} [options={}] Configuration options.
- * @returns {string} The number expressed in Arabic words.
- * @throws {TypeError} If value is NaN or invalid type.
- * @throws {Error} If value is an invalid number string.
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @param {Object} [options] - Optional configuration
+ * @param {('masculine'|'feminine')} [options.gender='masculine'] - Grammatical gender
+ * @param {string} [options.negativeWord] - Custom word for negative numbers
+ * @returns {string} The number in Arabic words
+ *
+ * @example
+ * toWords(1)                        // 'واحد'
+ * toWords(1, {gender: 'feminine'})  // 'واحدة'
  */
-export default function convertToWords (value, options = {}) {
-  return new Arabic(options).convertToWords(value)
+function toWords (value, options) {
+  options = validateOptions(options)
+  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+
+  const parts = []
+
+  if (isNegative) {
+    parts.push(options.negativeWord || NEGATIVE)
+  }
+
+  parts.push(integerToWords(integerPart, options))
+
+  if (decimalPart) {
+    parts.push(DECIMAL_SEP)
+    parts.push(decimalPartToWords(decimalPart, options))
+  }
+
+  return parts.join(' ')
 }
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export { toWords }

package/lib/languages/az.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Converts a numeric value to Azerbaijani words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Azerbaijani words
+ */
+export function toWords(value: number | string | bigint): string;

package/lib/languages/az.js

@@ -1,58 +1,176 @@
-import TurkicLanguage from '../classes/turkic-language.js'
-
 /**
- * Azerbaijani language converter.
+ * Azerbaijani language converter - Functional Implementation
+ *
+ * Self-contained converter with precomputed lookup tables.
  *
- * Inherits from TurkicLanguage shared patterns:
- * - Space-separated number combinations
- * - Omits '1' before hundreds and thousands
- * - Supports flexible word spacing configuration
+ * Key features:
+ * - Turkic language patterns
+ * - Implicit "bir" (one) omission before hundreds and thousands
+ * - Short scale naming
  */
-export class Azerbaijani extends TurkicLanguage {
-  negativeWord = 'mənfi'
-  decimalSeparatorWord = 'nöqtə'
-  zeroWord = 'sıfır'
-  scaleWordPairs = [[1_000_000_000_000_000_000n, 'kentilyon'],
-    [1_000_000_000_000_000n, 'katrilyon'],
-    [1_000_000_000_000n, 'trilyon'],
-    [1_000_000_000n, 'milyar'],
-    [1_000_000n, 'milyon'],
-    [1000n, 'min'],
-    [100n, 'yüz'],
-    [90n, 'doxsan'],
-    [80n, 'səksən'],
-    [70n, 'yetmiş'],
-    [60n, 'altmış'],
-    [50n, 'əlli'],
-    [40n, 'qırx'],
-    [30n, 'otuz'],
-    [20n, 'iyirmi'],
-    [10n, 'on'],
-    [9n, 'doqquz'],
-    [8n, 'səkkiz'],
-    [7n, 'yeddi'],
-    [6n, 'altı'],
-    [5n, 'beş'],
-    [4n, 'dörd'],
-    [3n, 'üç'],
-    [2n, 'iki'],
-    [1n, 'bir'],
-    [0n, 'sıfır']]
+
+import { parseNumericValue } from '../utils/parse-numeric.js'
+
+// ============================================================================
+// Vocabulary
+// ============================================================================
+
+const ONES = ['', 'bir', 'iki', 'üç', 'dörd', 'beş', 'altı', 'yeddi', 'səkkiz', 'doqquz']
+const TEENS = ['on', 'on bir', 'on iki', 'on üç', 'on dörd', 'on beş', 'on altı', 'on yeddi', 'on səkkiz', 'on doqquz']
+const TENS = ['', '', 'iyirmi', 'otuz', 'qırx', 'əlli', 'altmış', 'yetmiş', 'səksən', 'doxsan']
+
+const HUNDRED = 'yüz'
+const THOUSAND = 'min'
+
+const ZERO = 'sıfır'
+const NEGATIVE = 'mənfi'
+const DECIMAL_SEP = 'nöqtə'
+
+// Short scale
+const SCALE_WORDS = ['', THOUSAND, 'milyon', 'milyar', 'trilyon', 'katrilyon', 'kentilyon']
+
+// ============================================================================
+// Precomputed Lookup Table
+// ============================================================================
+
+function buildSegment (n) {
+  if (n === 0) return ''
+
+  const ones = n % 10
+  const tensDigit = Math.floor(n / 10) % 10
+  const hundredsDigit = Math.floor(n / 100)
+
+  const parts = []
+
+  if (hundredsDigit > 0) {
+    if (hundredsDigit === 1) {
+      parts.push(HUNDRED)
+    } else {
+      parts.push(ONES[hundredsDigit] + ' ' + HUNDRED)
+    }
+  }
+
+  if (tensDigit === 1) {
+    parts.push(TEENS[ones])
+  } else {
+    if (tensDigit > 1) {
+      parts.push(TENS[tensDigit])
+    }
+    if (ones > 0) {
+      parts.push(ONES[ones])
+    }
+  }
+
+  return parts.join(' ')
+}
+
+const SEGMENTS = new Array(1000)
+for (let i = 0; i < 1000; i++) {
+  SEGMENTS[i] = buildSegment(i)
+}
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+function integerToWords (n) {
+  if (n === 0n) return ZERO
+
+  if (n < 1000n) {
+    return SEGMENTS[Number(n)]
+  }
+
+  return buildLargeNumberWords(n)
+}
+
+function buildLargeNumberWords (n) {
+  const numStr = n.toString()
+  const len = numStr.length
+
+  const segments = []
+  const segmentSize = 3
+
+  const remainderLen = len % segmentSize
+  let pos = 0
+  if (remainderLen > 0) {
+    segments.push(Number(numStr.slice(0, remainderLen)))
+    pos = remainderLen
+  }
+  while (pos < len) {
+    segments.push(Number(numStr.slice(pos, pos + segmentSize)))
+    pos += segmentSize
+  }
+
+  const parts = []
+  let scaleIndex = segments.length - 1
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i]
+
+    if (segment !== 0) {
+      const scaleWord = SCALE_WORDS[scaleIndex] || ''
+
+      if (scaleIndex === 0) {
+        parts.push(SEGMENTS[segment])
+      } else if (scaleIndex === 1 && segment === 1) {
+        // Omit "bir" before thousand
+        parts.push(scaleWord)
+      } else {
+        parts.push(SEGMENTS[segment] + ' ' + scaleWord)
+      }
+    }
+
+    scaleIndex--
+  }
+
+  return parts.join(' ')
+}
+
+function decimalPartToWords (decimalPart) {
+  let result = ''
+  let i = 0
+
+  while (i < decimalPart.length && decimalPart[i] === '0') {
+    if (result) result += ' '
+    result += ZERO
+    i++
+  }
+
+  const remainder = decimalPart.slice(i)
+  if (remainder) {
+    if (result) result += ' '
+    result += integerToWords(BigInt(remainder))
+  }
+
+  return result
 }
 
 /**
- * Converts a number to Azerbaijani cardinal (written) form.
+ * Converts a numeric value to Azerbaijani words.
  *
- * @param {number|string|bigint} value The number to convert.
- * @param {Object} [options] Conversion options (see AZ class).
- * @returns {string} The number expressed in Azerbaijani words.
- * @throws {TypeError} If value is NaN or invalid type.
- * @throws {Error} If value is an invalid number string.
- *
- * @example
- * convertToWords(42, { lang: 'az' }); // 'qırx iki'
- * convertToWords(1000, { lang: 'az' }); // 'min'
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Azerbaijani words
  */
-export default function convertToWords (value, options = {}) {
-  return new Azerbaijani(options).convertToWords(value)
+function toWords (value) {
+  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+
+  let result = ''
+
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  result += integerToWords(integerPart)
+
+  if (decimalPart) {
+    result += ' ' + DECIMAL_SEP + ' ' + decimalPartToWords(decimalPart)
+  }
+
+  return result
 }
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export { toWords }

package/lib/languages/bn.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Converts a numeric value to Bengali words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Bengali words
+ */
+export function toWords(value: number | string | bigint): string;