n2words 1.24.0 → 3.0.0

package/lib/languages/uk.js

@@ -1,122 +1,218 @@
-import SlavicLanguage from '../classes/slavic-language.js'
-
-/**
- * @typedef {Object} SlavicOptions
- * @property {boolean} [feminine=false] Use feminine forms for numbers.
- */
-
 /**
- * Ukrainian language converter.
+ * Ukrainian language converter - Functional Implementation
  *
- * Implements Ukrainian number words using the Slavic language pattern:
- * - Ukrainian number words (один/одна, два/дві, три, чотири...)
- * - Gender-aware forms (masculine/feminine)
- * - Slavic three-form pluralization (тисяча/тисячі/тисяч)
- * - Ukrainian orthography and phonology
+ * Self-contained converter using shared Slavic utilities.
  *
- * Key Features:
- * - Three-form pluralization system shared across Slavic languages
- *   * Form 1 (singular): 1 (e.g., "тисяча")
- *   * Form 2 (few): 2-4, 22-24, 32-34... excluding teens (e.g., "тисячі")
- *   * Form 3 (many): all other numbers (e.g., "тисяч")
- * - Chunk-based decomposition (splits into groups of 3 digits: ones, thousands, millions, etc.)
- * - Large number handling via thousands[] array with indexed [singular, few, many] forms
- *
- * Features:
- * - Ukrainian-specific letters (і, ї, ґ, є)
- * - Apostrophe usage (п'ять, дев'ять)
- * - Close structural similarity to Russian with distinct vocabulary
- *
- * Inherits from SlavicLanguage for complex pluralization algorithms.
+ * Key features:
+ * - Three-form pluralization (one/few/many)
+ * - Gender: thousands are feminine, millions+ are masculine
+ * - Irregular hundreds
+ * - Long scale naming
  */
-export class Ukrainian extends SlavicLanguage {
-  negativeWord = 'мiнус'
-  decimalSeparatorWord = 'кома'
-  zeroWord = 'нуль'
-  ones = {
-    1: 'один',
-    2: 'два',
-    3: 'три',
-    4: 'чотири',
-    5: 'п\'ять',
-    6: 'шiсть',
-    7: 'сiм',
-    8: 'вiсiм',
-    9: 'дев\'ять'
+
+import { parseNumericValue } from '../utils/parse-numeric.js'
+import { validateOptions } from '../utils/validate-options.js'
+
+// ============================================================================
+// Slavic Utilities (inlined for performance)
+// ============================================================================
+
+function pluralize (n, forms) {
+  const num = typeof n === 'bigint' ? Number(n) : n
+  const lastDigit = num % 10
+  const lastTwoDigits = num % 100
+
+  if (lastTwoDigits >= 11 && lastTwoDigits <= 19) {
+    return forms[2]
   }
 
-  onesFeminine = {
-    1: 'одна',
-    2: 'двi',
-    3: 'три',
-    4: 'чотири',
-    5: 'п\'ять',
-    6: 'шiсть',
-    7: 'сiм',
-    8: 'вiсiм',
-    9: 'дев\'ять'
+  if (lastDigit === 1) return forms[0]
+  if (lastDigit >= 2 && lastDigit <= 4) return forms[1]
+  return forms[2]
+}
+
+function buildAllSegments (onesMasc, onesFem, teens, tens, hundreds) {
+  const masc = new Array(1000)
+  const fem = new Array(1000)
+
+  for (let i = 0; i < 1000; i++) {
+    masc[i] = buildSegment(i, onesMasc, teens, tens, hundreds)
+    fem[i] = buildSegment(i, onesFem, teens, tens, hundreds)
   }
 
-  tens = {
-    0: 'десять',
-    1: 'одинадцять',
-    2: 'дванадцять',
-    3: 'тринадцять',
-    4: 'чотирнадцять',
-    5: 'п\'ятнадцять',
-    6: 'шiстнадцять',
-    7: 'сiмнадцять',
-    8: 'вiсiмнадцять',
-    9: 'дев\'ятнадцять'
+  return { masc, fem }
+}
+
+function buildSegment (n, ones, teens, tens, hundreds) {
+  if (n === 0) return ''
+
+  const onesDigit = n % 10
+  const tensDigit = Math.floor(n / 10) % 10
+  const hundredsDigit = Math.floor(n / 100)
+
+  const parts = []
+
+  if (hundredsDigit > 0) {
+    parts.push(hundreds[hundredsDigit])
   }
 
-  twenties = {
-    2: 'двадцять',
-    3: 'тридцять',
-    4: 'сорок',
-    5: 'п\'ятдесят',
-    6: 'шiстдесят',
-    7: 'сiмдесят',
-    8: 'вiсiмдесят',
-    9: 'дев\'яносто'
+  if (tensDigit > 1) {
+    parts.push(tens[tensDigit])
   }
 
-  hundreds = {
-    1: 'сто',
-    2: 'двiстi',
-    3: 'триста',
-    4: 'чотириста',
-    5: 'п\'ятсот',
-    6: 'шiстсот',
-    7: 'сiмсот',
-    8: 'вiсiмсот',
-    9: 'дев\'ятсот'
+  if (tensDigit === 1) {
+    parts.push(teens[onesDigit])
+  } else if (onesDigit > 0) {
+    parts.push(ones[onesDigit])
   }
 
-  thousands = {
-    1: ['тисяча', 'тисячi', 'тисяч'], // 10^ 3
-    2: ['мiльйон', 'мiльйони', 'мiльйонiв'], // 10^ 6
-    3: ['мiльярд', 'мiльярди', 'мiльярдiв'], // 10^ 9
-    4: ['трильйон', 'трильйони', 'трильйонiв'], // 10^ 12
-    5: ['квадрильйон', 'квадрильйони', 'квадрильйонiв'], // 10^ 15
-    6: ['квiнтильйон', 'квiнтильйони', 'квiнтильйонiв'], // 10^ 18
-    7: ['секстильйон', 'секстильйони', 'секстильйонiв'], // 10^ 21
-    8: ['септильйон', 'септильйони', 'септильйонiв'], // 10^ 24
-    9: ['октильйон', 'октильйони', 'октильйонiв'], // 10^ 27
-    10: ['нонiльйон', 'нонiльйони', 'нонiльйонiв'] // 10^ 30
+  return parts.join(' ')
+}
+
+// ============================================================================
+// Vocabulary
+// ============================================================================
+
+const ONES_MASC = ['', 'один', 'два', 'три', 'чотири', 'п\'ять', 'шiсть', 'сiм', 'вiсiм', 'дев\'ять']
+const ONES_FEM = ['', 'одна', 'двi', 'три', 'чотири', 'п\'ять', 'шiсть', 'сiм', 'вiсiм', 'дев\'ять']
+
+const TEENS = ['десять', 'одинадцять', 'дванадцять', 'тринадцять', 'чотирнадцять', 'п\'ятнадцять', 'шiстнадцять', 'сiмнадцять', 'вiсiмнадцять', 'дев\'ятнадцять']
+const TENS = ['', '', 'двадцять', 'тридцять', 'сорок', 'п\'ятдесят', 'шiстдесят', 'сiмдесят', 'вiсiмдесят', 'дев\'яносто']
+
+// Irregular hundreds
+const HUNDREDS = ['', 'сто', 'двiстi', 'триста', 'чотириста', 'п\'ятсот', 'шiстсот', 'сiмсот', 'вiсiмсот', 'дев\'ятсот']
+
+const ZERO = 'нуль'
+const NEGATIVE = 'мiнус'
+const DECIMAL_SEP = 'кома'
+
+// Scale words: [singular, few, many]
+// Thousands (index 0) are feminine, rest are masculine
+const SCALE_FORMS = [
+  ['тисяча', 'тисячi', 'тисяч'],
+  ['мiльйон', 'мiльйони', 'мiльйонiв'],
+  ['мiльярд', 'мiльярди', 'мiльярдiв'],
+  ['трильйон', 'трильйони', 'трильйонiв'],
+  ['квадрильйон', 'квадрильйони', 'квадрильйонiв'],
+  ['квiнтильйон', 'квiнтильйони', 'квiнтильйонiв'],
+  ['секстильйон', 'секстильйони', 'секстильйонiв'],
+  ['септильйон', 'септильйони', 'септильйонiв'],
+  ['октильйон', 'октильйони', 'октильйонiв']
+]
+
+// ============================================================================
+// Precomputed Lookup Tables
+// ============================================================================
+
+const { masc: SEGMENTS_MASC, fem: SEGMENTS_FEM } = buildAllSegments(ONES_MASC, ONES_FEM, TEENS, TENS, HUNDREDS)
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+function integerToWords (n, options = {}) {
+  if (n === 0n) return ZERO
+
+  if (n < 1000n) {
+    const segments = options.gender === 'feminine' ? SEGMENTS_FEM : SEGMENTS_MASC
+    return segments[Number(n)]
   }
+
+  return buildLargeNumberWords(n, options)
+}
+
+function buildLargeNumberWords (n, options) {
+  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) {
+      if (scaleIndex === 0) {
+        const segmentWords = options.gender === 'feminine' ? SEGMENTS_FEM : SEGMENTS_MASC
+        parts.push(segmentWords[segment])
+      } else {
+        const scaleForms = SCALE_FORMS[scaleIndex - 1]
+        const scaleWord = pluralize(segment, scaleForms)
+        // Thousands (scaleIndex=1) are feminine, others masculine
+        const isFeminine = scaleIndex === 1
+        const segmentWords = isFeminine ? SEGMENTS_FEM : SEGMENTS_MASC
+        parts.push(segmentWords[segment] + ' ' + scaleWord)
+      }
+    }
+
+    scaleIndex--
+  }
+
+  return parts.join(' ')
+}
+
+function decimalPartToWords (decimalPart, options) {
+  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), options)
+  }
+
+  return result
 }
 
 /**
- * Converts a number to Ukrainian cardinal (written) form.
+ * Converts a numeric value to Ukrainian words.
  *
- * @param {number|string|bigint} value The number to convert.
- * @param {Object} [options={}] Configuration options.
- * @param {boolean} [options.feminine=false] Use feminine forms for numbers.
- * @returns {string} The number expressed in Ukrainian 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
+ * @returns {string} The number in Ukrainian words
  */
-export default function convertToWords (value, options = {}) {
-  return new Ukrainian(options).convertToWords(value)
+function toWords (value, options) {
+  options = validateOptions(options)
+  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+
+  let result = ''
+
+  if (isNegative) {
+    result = NEGATIVE + ' '
+  }
+
+  result += integerToWords(integerPart, options)
+
+  if (decimalPart) {
+    result += ' ' + DECIMAL_SEP + ' ' + decimalPartToWords(decimalPart, options)
+  }
+
+  return result
 }
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export { toWords }

package/lib/languages/ur.d.ts

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

package/lib/languages/ur.js

@@ -1,126 +1,163 @@
-import SouthAsianLanguage from '../classes/south-asian-language.js'
-
-class Urdu extends SouthAsianLanguage {
-  negativeWord = 'منفی'
-  decimalSeparatorWord = 'اعشاریہ'
-  zeroWord = 'صفر'
-  hundredWord = 'سو'
-  belowHundred = [
-    'صفر',
-    'ایک',
-    'دو',
-    'تین',
-    'چار',
-    'پانچ',
-    'چھ',
-    'سات',
-    'آٹھ',
-    'نو',
-    'دس',
-    'گیارہ',
-    'بارہ',
-    'تیرہ',
-    'چودہ',
-    'پندرہ',
-    'سولہ',
-    'سترہ',
-    'اٹھارہ',
-    'انیس',
-    'بیس',
-    'اکیس',
-    'بائیس',
-    'تیئیس',
-    'چوبیس',
-    'پچیس',
-    'چھبیس',
-    'ستائیس',
-    'اٹھائیس',
-    'انتیس',
-    'تیس',
-    'اکتیس',
-    'بتیس',
-    'تینتیس',
-    'چونتیس',
-    'پینتیس',
-    'چھتیس',
-    'سینتیس',
-    'اڑتیس',
-    'انتالیس',
-    'چالیس',
-    'اکتالیس',
-    'بیالیس',
-    'تینتالیس',
-    'چوالیس',
-    'پینتالیس',
-    'چھالیس',
-    'سینتالیس',
-    'اڑتالیس',
-    'انچاس',
-    'پچاس',
-    'اکاون',
-    'باون',
-    'ترپن',
-    'چون',
-    'پچپن',
-    'چھپن',
-    'ستاون',
-    'اٹھاون',
-    'انسٹھ',
-    'ساٹھ',
-    'اکسٹھ',
-    'باسٹھ',
-    'ترسٹھ',
-    'چونسٹھ',
-    'پینسٹھ',
-    'چھیاسٹھ',
-    'سڑسٹھ',
-    'اڑسٹھ',
-    'انہتر',
-    'ستر',
-    'اکہتر',
-    'بہتر',
-    'تہتر',
-    'چوہتر',
-    'پچھتر',
-    'چھہتر',
-    'ستتر',
-    'اٹھہتر',
-    'اناسی',
-    'اسی',
-    'اکیاسی',
-    'بیاسی',
-    'تریاسی',
-    'چوراسی',
-    'پچاسی',
-    'چھیاسی',
-    'ستاسی',
-    'اٹھاسی',
-    'نواسی',
-    'نوے',
-    'اکانوے',
-    'بانوے',
-    'ترانوے',
-    'چورانوے',
-    'پچانوے',
-    'چھیانوے',
-    'ستانوے',
-    'اٹھانوے',
-    'ننانوے'
-  ]
-
-  scaleWords = [
-    '',
-    'ہزار',
-    'لاکھ',
-    'کروڑ',
-    'ارب',
-    'کھرب',
-    'نیل',
-    'پدم',
-    'شنکھ'
-  ]
+/**
+ * Urdu language converter - Functional Implementation
+ *
+ * Self-contained converter for South Asian numbering.
+ *
+ * Key features:
+ * - Indian numbering system (ہزار, لاکھ, کروڑ)
+ * - Urdu script (right-to-left)
+ * - 3-2-2 grouping pattern (last 3 digits, then groups of 2)
+ * - Complete word forms for 0-99
+ */
+
+import { parseNumericValue } from '../utils/parse-numeric.js'
+
+// ============================================================================
+// Vocabulary
+// ============================================================================
+
+const ZERO = 'صفر'
+const NEGATIVE = 'منفی'
+const DECIMAL_SEP = 'اعشاریہ'
+const HUNDRED = 'سو'
+
+const BELOW_HUNDRED = [
+  'صفر', 'ایک', 'دو', 'تین', 'چار', 'پانچ', 'چھ', 'سات', 'آٹھ', 'نو',
+  'دس', 'گیارہ', 'بارہ', 'تیرہ', 'چودہ', 'پندرہ', 'سولہ', 'سترہ', 'اٹھارہ', 'انیس',
+  'بیس', 'اکیس', 'بائیس', 'تیئیس', 'چوبیس', 'پچیس', 'چھبیس', 'ستائیس', 'اٹھائیس', 'انتیس',
+  'تیس', 'اکتیس', 'بتیس', 'تینتیس', 'چونتیس', 'پینتیس', 'چھتیس', 'سینتیس', 'اڑتیس', 'انتالیس',
+  'چالیس', 'اکتالیس', 'بیالیس', 'تینتالیس', 'چوالیس', 'پینتالیس', 'چھالیس', 'سینتالیس', 'اڑتالیس', 'انچاس',
+  'پچاس', 'اکاون', 'باون', 'ترپن', 'چون', 'پچپن', 'چھپن', 'ستاون', 'اٹھاون', 'انسٹھ',
+  'ساٹھ', 'اکسٹھ', 'باسٹھ', 'ترسٹھ', 'چونسٹھ', 'پینسٹھ', 'چھیاسٹھ', 'سڑسٹھ', 'اڑسٹھ', 'انہتر',
+  'ستر', 'اکہتر', 'بہتر', 'تہتر', 'چوہتر', 'پچھتر', 'چھہتر', 'ستتر', 'اٹھہتر', 'اناسی',
+  'اسی', 'اکیاسی', 'بیاسی', 'تریاسی', 'چوراسی', 'پچاسی', 'چھیاسی', 'ستاسی', 'اٹھاسی', 'نواسی',
+  'نوے', 'اکانوے', 'بانوے', 'ترانوے', 'چورانوے', 'پچانوے', 'چھیانوے', 'ستانوے', 'اٹھانوے', 'ننانوے'
+]
+
+// Scale words: index 0 = units (empty), 1 = thousand, 2 = lakh, 3 = crore, etc.
+const SCALE_WORDS = ['', 'ہزار', 'لاکھ', 'کروڑ', 'ارب', 'کھرب', 'نیل', 'پدم', 'شنکھ']
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+/**
+ * Converts 0-999 to Urdu words.
+ */
+function segmentToWords (n) {
+  if (n === 0) return ''
+  if (n < 100) return BELOW_HUNDRED[n]
+
+  const hundreds = Math.trunc(n / 100)
+  const remainder = n % 100
+
+  if (remainder === 0) {
+    return BELOW_HUNDRED[hundreds] + ' ' + HUNDRED
+  }
+  return BELOW_HUNDRED[hundreds] + ' ' + HUNDRED + ' ' + BELOW_HUNDRED[remainder]
+}
+
+/**
+ * Converts a non-negative integer to Urdu words.
+ * Uses recursive approach for Indian 3-2-2 grouping pattern.
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} Urdu words
+ */
+function integerToWords (n) {
+  if (n === 0n) return ZERO
+
+  // Fast path: numbers < 1000 (direct lookup)
+  if (n < 1000n) {
+    return segmentToWords(Number(n))
+  }
+
+  return buildLargeNumberWords(n, 0)
+}
+
+/**
+ * Recursively builds words for numbers >= 1000.
+ * Indian grouping: first 3 digits, then 2-digit groups.
+ *
+ * @param {bigint} n - Number to convert
+ * @param {number} scale - Current scale index (0=units, 1=thousands, etc.)
+ * @returns {string} Urdu words
+ */
+function buildLargeNumberWords (n, scale) {
+  if (n === 0n) return ''
+
+  // Determine divisor: 1000 for first split, 100 for rest
+  const divisor = scale === 0 ? 1000n : 100n
+  const segment = Number(n % divisor)
+  const rest = n / divisor
+
+  // Build higher segments first (recursive)
+  let result = ''
+  if (rest > 0n) {
+    result = buildLargeNumberWords(rest, scale + 1)
+  }
+
+  // Add current segment
+  if (segment > 0) {
+    if (result) result += ' '
+
+    if (scale === 0) {
+      // Units segment (0-999)
+      result += segmentToWords(segment)
+    } else {
+      // Scale segments (0-99)
+      result += BELOW_HUNDRED[segment] + ' ' + SCALE_WORDS[scale]
+    }
+  }
+
+  return result
+}
+
+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
 }
 
-export default function convertToWords (value, options = {}) {
-  return new Urdu(options).convertToWords(value)
+/**
+ * Converts a numeric value to Urdu words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Urdu words
+ */
+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/vi.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Converts a numeric value to Vietnamese words.
+ *
+ * This is the main public API. It accepts any valid numeric input
+ * (number, string, or bigint) and handles parsing internally.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Vietnamese words
+ * @throws {TypeError} If value is not a valid numeric type
+ * @throws {Error} If value is not a valid number format
+ *
+ * @example
+ * toWords(42)           // 'bốn mươi hai'
+ * toWords(101)          // 'một trăm lẻ một'
+ * toWords(1000000)      // 'một triệu'
+ */
+export function toWords(value: number | string | bigint): string;