n2words 2.0.0 → 3.1.0

package/lib/languages/yo.js

@@ -0,0 +1,303 @@
+/**
+ * Yoruba language converter - Functional Implementation
+ *
+ * A number-to-words converter for Yoruba (yo), a Niger-Congo language
+ * spoken by ~45 million people in Nigeria, Benin, and Togo.
+ *
+ * Yoruba uses a complex vigesimal (base-20) system with:
+ * - Additive patterns: 1-4 added to decade (lé = "plus")
+ * - Subtractive patterns: 5-9 subtracted from next decade (dín = "minus")
+ * - Odd decades (30,50,70,90) formed by subtracting 10 from next even decade
+ * - Even decades (20,40,60,80,100) are multiples of 20
+ *
+ * Examples:
+ * - 21 = ọ̀kan lé lógún (1 + 20)
+ * - 15 = àrùndínlógún (20 - 5)
+ * - 50 = àádọ́ta (60 - 10)
+ * - 45 = àrùndínláàádọ́ta (50 - 5)
+ */
+
+import { parseNumericValue } from '../utils/parse-numeric.js'
+
+// ============================================================================
+// Vocabulary (module-level constants)
+// ============================================================================
+
+// Basic numbers 1-10
+const ONES = [
+  '',
+  'ọ̀kan', // 1
+  'èjì', // 2
+  'ẹ̀ta', // 3
+  'ẹ̀rin', // 4
+  'àrùn', // 5
+  'ẹ̀fà', // 6
+  'èje', // 7
+  'ẹ̀jọ', // 8
+  'ẹ̀sán', // 9
+  'ẹ̀wá' // 10
+]
+
+// Numbers 11-14 (additive: X + 10, using "lá")
+const TEENS_ADD = [
+  '',
+  'ọ̀kànlá', // 11 = 1 + 10
+  'èjìlá', // 12 = 2 + 10
+  'ẹ̀talá', // 13 = 3 + 10
+  'ẹ̀rinlá' // 14 = 4 + 10
+]
+
+// Numbers 15-19 (subtractive: 20 - X, using "dín")
+const TEENS_SUB = [
+  'àrùndínlógún', // 15 = 20 - 5
+  'ẹ̀rìndínlógún', // 16 = 20 - 4
+  'ẹ̀tadínlógún', // 17 = 20 - 3
+  'èjìdínlógún', // 18 = 20 - 2
+  'ọ̀kàndínlógún' // 19 = 20 - 1
+]
+
+// Decades (base-20 structure)
+// Even decades are multiples of 20
+// Odd decades subtract 10 from next even decade
+const DECADES = {
+  20: 'ogún', // 20 = 20 × 1
+  30: 'ọgbọ̀n', // 30 = 20 + 10 (special word)
+  40: 'ogójì', // 40 = 20 × 2
+  50: 'àádọ́ta', // 50 = 60 - 10
+  60: 'ogóta', // 60 = 20 × 3
+  70: 'àádọ́rin', // 70 = 80 - 10
+  80: 'ogórin', // 80 = 20 × 4
+  90: 'àádọ́rùn', // 90 = 100 - 10
+  100: 'ọgọ́rùn' // 100 = 20 × 5
+}
+
+// Prefixes for adding to decades (lé lógún, lé lọgbọ̀n, etc.)
+const DECADE_ADD_SUFFIX = {
+  20: 'lógún',
+  30: 'lọgbọ̀n',
+  40: 'lógójì',
+  50: 'láàádọ́ta',
+  60: 'lógóta',
+  70: 'láàádọ́rin',
+  80: 'lógórin',
+  90: 'láàádọ́rùn',
+  100: 'lọ́gọ́rùn'
+}
+
+// Prefixes for subtracting from decades (dín lógójì, etc.)
+const DECADE_SUB_SUFFIX = {
+  20: 'dínlógún',
+  30: 'dínlọgbọ̀n',
+  40: 'dínlógójì',
+  50: 'dínláàádọ́ta',
+  60: 'dínlógóta',
+  70: 'dínláàádọ́rin',
+  80: 'dínlógórin',
+  90: 'dínláàádọ́rùn',
+  100: 'dínlọ́gọ́rùn'
+}
+
+// Scale words
+const HUNDRED = 'ọgọ́rùn'
+const TWO_HUNDRED = 'igba' // 200 (special word, historically 200 cowries)
+const FOUR_HUNDRED = 'irinwó' // 400 (20 × 20)
+const THOUSAND = 'ẹgbẹ̀rún' // 1000
+const TEN_THOUSAND = 'ẹgbàárùn' // 10,000 (special)
+const TWENTY_THOUSAND = 'ọ̀kẹ́' // 20,000 (bag of cowries)
+const MILLION = 'mílíọ̀nù' // million (loanword)
+
+const ZERO = 'òdo'
+const NEGATIVE = 'àìní'
+const DECIMAL_SEP = 'àmì'
+const AND = 'ó lé' // "and" / "plus" connector
+
+// ============================================================================
+// Segment Building
+// ============================================================================
+
+/**
+ * Builds word for numbers 0-99
+ */
+function buildUnder100 (n) {
+  if (n === 0) return ''
+  if (n <= 10) return ONES[n]
+
+  // 11-14: additive from 10
+  if (n <= 14) return TEENS_ADD[n - 10]
+
+  // 15-19: subtractive from 20
+  if (n <= 19) return TEENS_SUB[n - 15]
+
+  // Exact decades
+  if (n % 10 === 0) return DECADES[n]
+
+  const decade = Math.floor(n / 10) * 10
+  const unit = n % 10
+
+  // 1-4 are added to current decade (21 = 1 + 20, not 1 + 30)
+  if (unit <= 4) {
+    return ONES[unit] + ' lé ' + DECADE_ADD_SUFFIX[decade]
+  }
+
+  // 5-9 are subtracted from next decade
+  const nextDecade = decade + 10
+  const subtractAmount = 10 - unit
+  return ONES[subtractAmount] + DECADE_SUB_SUFFIX[nextDecade]
+}
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+/**
+ * Converts hundreds (100-999)
+ */
+function convertHundreds (n) {
+  if (n < 100) return buildUnder100(n)
+
+  const hundreds = Math.floor(n / 100)
+  const remainder = n % 100
+
+  let result
+
+  // Special cases for 200 and 400
+  if (hundreds === 2 && remainder === 0) {
+    return TWO_HUNDRED
+  }
+  if (hundreds === 4 && remainder === 0) {
+    return FOUR_HUNDRED
+  }
+
+  // Build hundreds
+  if (hundreds === 1) {
+    result = HUNDRED
+  } else if (hundreds === 2) {
+    result = TWO_HUNDRED
+  } else if (hundreds === 4) {
+    result = FOUR_HUNDRED
+  } else {
+    // Other hundreds: X ọgọ́rùn
+    result = ONES[hundreds] + ' ' + HUNDRED
+  }
+
+  if (remainder > 0) {
+    result += ' ' + AND + ' ' + buildUnder100(remainder)
+  }
+
+  return result
+}
+
+/**
+ * Converts a non-negative integer to Yoruba words.
+ *
+ * @param {bigint} n - Non-negative integer to convert
+ * @returns {string} Yoruba words
+ */
+function integerToWords (n) {
+  if (n === 0n) return ZERO
+
+  // Fast path: numbers < 100
+  if (n < 100n) {
+    return buildUnder100(Number(n))
+  }
+
+  // Numbers < 1000
+  if (n < 1000n) {
+    return convertHundreds(Number(n))
+  }
+
+  // Build from segments
+  const parts = []
+  let remaining = n
+
+  // Millions
+  if (remaining >= 1_000_000n) {
+    const millions = remaining / 1_000_000n
+    remaining = remaining % 1_000_000n
+    if (millions === 1n) {
+      parts.push(MILLION + ' kan')
+    } else {
+      parts.push(MILLION + ' ' + integerToWords(millions))
+    }
+  }
+
+  // Thousands
+  if (remaining >= 1000n) {
+    const thousands = remaining / 1000n
+    remaining = remaining % 1000n
+
+    if (thousands === 1n) {
+      parts.push(THOUSAND + ' kan')
+    } else if (thousands === 10n) {
+      parts.push(TEN_THOUSAND)
+    } else if (thousands === 20n) {
+      parts.push(TWENTY_THOUSAND)
+    } else if (thousands < 100n) {
+      parts.push(THOUSAND + ' ' + buildUnder100(Number(thousands)))
+    } else {
+      parts.push(THOUSAND + ' ' + convertHundreds(Number(thousands)))
+    }
+  }
+
+  // Hundreds and below
+  if (remaining > 0n) {
+    if (remaining < 100n) {
+      if (parts.length > 0) {
+        parts.push(AND + ' ' + buildUnder100(Number(remaining)))
+      } else {
+        parts.push(buildUnder100(Number(remaining)))
+      }
+    } else {
+      if (parts.length > 0) {
+        parts.push(AND + ' ' + convertHundreds(Number(remaining)))
+      } else {
+        parts.push(convertHundreds(Number(remaining)))
+      }
+    }
+  }
+
+  return parts.join(', ')
+}
+
+/**
+ * Converts decimal digits to Yoruba words.
+ *
+ * @param {string} decimalPart - Decimal digits
+ * @returns {string} Yoruba words for decimal
+ */
+function decimalPartToWords (decimalPart) {
+  const parts = []
+
+  for (const digit of decimalPart) {
+    const d = parseInt(digit, 10)
+    parts.push(d === 0 ? ZERO : ONES[d])
+  }
+
+  return parts.join(' ')
+}
+
+/**
+ * Converts a numeric value to Yoruba words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @returns {string} The number in Yoruba 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
+}
+
+export { toWords }

package/lib/languages/zh-Hans.d.ts

@@ -1,21 +1,11 @@
 /**
- * Simplified Chinese language converter.
+ * Converts a numeric value to Simplified Chinese words.
  *
- * Supports:
- * - Simplified Chinese characters (简体中文)
- * - No word separators (concatenated format)
- * - Optional formal (financial) vs common numerals
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @param {Object} [options] - Optional configuration
+ * @param {boolean} [options.formal=true] - Use formal/financial numerals
+ * @returns {string} The number in Simplified Chinese words
  */
-export class SimplifiedChinese extends GreedyScaleLanguage {
-    constructor(options?: {});
-    scaleWords: (string | bigint)[][];
-    /** Combines two word-sets according to Chinese grammar rules. */
-    combineWordSets(preceding: any, following: any): any;
-    /** Returns the number of digits in a number. */
-    digit(number_: any): any;
-    /** Counts the number of zero digits in a number. */
-    zeroDigit(number_: any): number;
-    /** Converts decimal digits to words by reading each digit individually. */
-    decimalDigitsToWords(decimalString: any): string[];
-}
-import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js';
+export function toWords(value: number | string | bigint, options?: {
+    formal?: boolean | undefined;
+}): string;

package/lib/languages/zh-Hans.js

@@ -1,111 +1,182 @@
-import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js'
-
 /**
- * Simplified Chinese language converter.
+ * Simplified Chinese language converter - Functional Implementation
+ *
+ * Self-contained converter for Simplified Chinese.
  *
- * Supports:
- * - Simplified Chinese characters (简体中文)
+ * Key features:
+ * - Myriad-based (万, 亿) grouping - 4 digits
+ * - Formal (financial) vs common numerals
+ * - Zero insertion for skipped positions
  * - No word separators (concatenated format)
- * - Optional formal (financial) vs common numerals
  */
-export class SimplifiedChinese extends GreedyScaleLanguage {
-  negativeWord = '负'
-  decimalSeparatorWord = '点'
-  zeroWord = '零'
-  wordSeparator = ''
-
-  constructor (options = {}) {
-    super()
-
-    this.setOptions({
-      formal: true
-    }, options)
-
-    if (this.options.formal) {
-      this.scaleWords = [
-        [1_000_000_000_000n, '万'],
-        [100_000_000n, '亿'],
-        [10_000n, '万'],
-        [1000n, '仟'],
-        [100n, '佰'],
-        [10n, '拾'],
-        [9n, '玖'],
-        [8n, '捌'],
-        [7n, '柒'],
-        [6n, '陆'],
-        [5n, '伍'],
-        [4n, '肆'],
-        [3n, '叁'],
-        [2n, '贰'],
-        [1n, '壹'],
-        [0n, '零']
-      ]
-    } else {
-      this.scaleWords = [
-        [1_000_000_000_000n, '万'],
-        [100_000_000n, '亿'],
-        [10_000n, '万'],
-        [1000n, '千'],
-        [100n, '百'],
-        [10n, '十'],
-        [9n, '九'],
-        [8n, '八'],
-        [7n, '七'],
-        [6n, '六'],
-        [5n, '五'],
-        [4n, '四'],
-        [3n, '三'],
-        [2n, '二'],
-        [1n, '一'],
-        [0n, '零']
-      ]
-    }
+
+import { parseNumericValue } from '../utils/parse-numeric.js'
+import { validateOptions } from '../utils/validate-options.js'
+
+// ============================================================================
+// Vocabulary
+// ============================================================================
+
+// Common (everyday) numerals
+const ONES_COMMON = ['零', '一', '二', '三', '四', '五', '六', '七', '八', '九']
+const TEN_COMMON = '十'
+const HUNDRED_COMMON = '百'
+const THOUSAND_COMMON = '千'
+
+// Formal (financial) numerals - harder to alter/forge
+const ONES_FORMAL = ['零', '壹', '贰', '叁', '肆', '伍', '陆', '柒', '捌', '玖']
+const TEN_FORMAL = '拾'
+const HUNDRED_FORMAL = '佰'
+const THOUSAND_FORMAL = '仟'
+
+// Scale words
+const WAN_WORD = '万' // 10,000
+const YI_WORD = '亿' // 100,000,000
+
+const ZERO = '零'
+const NEGATIVE = '负'
+const DECIMAL_SEP = '点'
+
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+
+/**
+ * Convert number below 万 (10,000) to words using direct string concatenation.
+ */
+function convertBelowWan (value, ones, ten, hundred, thousand) {
+  if (value === 0n) return ''
+
+  let result = ''
+  let needsZero = false
+
+  // Thousands (千)
+  const thousandsVal = value / 1000n
+  const thousandsRemainder = value % 1000n
+  if (thousandsVal > 0n) {
+    result = ones[Number(thousandsVal)] + thousand
+    needsZero = thousandsRemainder > 0n && thousandsRemainder < 100n
   }
 
-  /** Combines two word-sets according to Chinese grammar rules. */
-  combineWordSets (preceding, following) {
-    const precedingWord = Object.keys(preceding)[0]
-    const precedingValue = Object.values(preceding)[0]
-    const followingWord = Object.keys(following)[0]
-    const followingValue = Object.values(following)[0]
+  // Hundreds (百)
+  const hundredsVal = thousandsRemainder / 100n
+  const hundredsRemainder = thousandsRemainder % 100n
+  if (hundredsVal > 0n) {
+    if (needsZero) result += ZERO
+    result += ones[Number(hundredsVal)] + hundred
+    needsZero = hundredsRemainder > 0n && hundredsRemainder < 10n
+  } else if (thousandsVal > 0n && hundredsRemainder > 0n) {
+    needsZero = true
+  }
 
-    // Implicit one: omit 1 before single digits (< 10)
-    if (precedingValue === 1n && followingValue < 10n) {
-      return following
-    }
+  // Tens (十)
+  const tensVal = hundredsRemainder / 10n
+  const onesVal = hundredsRemainder % 10n
+  if (tensVal > 0n) {
+    if (needsZero) result += ZERO
+    result += ones[Number(tensVal)] + ten
+    needsZero = false
+  } else if ((hundredsVal > 0n || thousandsVal > 0n) && onesVal > 0n) {
+    needsZero = true
+  }
 
-    // Multiply when following > preceding (scale words like 仁, 万, 亿)
-    if (followingValue > precedingValue) {
-      return { [`${precedingWord}${followingWord}`]: precedingValue * followingValue }
-    }
+  // Ones
+  if (onesVal > 0n) {
+    if (needsZero) result += ZERO
+    result += ones[Number(onesVal)]
+  }
+
+  return result
+}
+
+/**
+ * Convert number below 亿 (100 million) to words.
+ */
+function convertBelowYi (value, ones, ten, hundred, thousand) {
+  if (value === 0n) return ''
 
-    // Insert "零" (zero) when position skip levels (e.g., 1003 = 千零三)
-    // zeroDigit() checks if gap exists between preceding and following magnitude
-    if (this.zeroDigit(precedingValue) > this.digit(followingValue)) {
-      return { [`${precedingWord}${this.zeroWord}${followingWord}`]: precedingValue + followingValue }
+  if (value >= 10_000n) {
+    const wanValue = value / 10_000n
+    const wanRemainder = value % 10_000n
+
+    let result = convertBelowWan(wanValue, ones, ten, hundred, thousand) + WAN_WORD
+
+    if (wanRemainder > 0n) {
+      const needsZero = (wanValue % 10n === 0n) || (wanRemainder < 1000n)
+      if (needsZero) result += ZERO
+      result += convertBelowWan(wanRemainder, ones, ten, hundred, thousand)
     }
 
-    // Default: concatenate without zero insertion
-    return { [`${precedingWord}${followingWord}`]: precedingValue + followingValue }
+    return result
   }
 
-  /** Returns the number of digits in a number. */
-  digit (number_) {
-    return number_.toString().length
+  return convertBelowWan(value, ones, ten, hundred, thousand)
+}
+
+function integerToWords (n, formal = true) {
+  if (n === 0n) return ZERO
+
+  const ones = formal ? ONES_FORMAL : ONES_COMMON
+  const ten = formal ? TEN_FORMAL : TEN_COMMON
+  const hundred = formal ? HUNDRED_FORMAL : HUNDRED_COMMON
+  const thousand = formal ? THOUSAND_FORMAL : THOUSAND_COMMON
+
+  // Handle numbers >= 亿 (100 million)
+  if (n >= 100_000_000n) {
+    const yiValue = n / 100_000_000n
+    const yiRemainder = n % 100_000_000n
+
+    let result = convertBelowYi(yiValue, ones, ten, hundred, thousand) + YI_WORD
+
+    if (yiRemainder > 0n) {
+      if (yiRemainder < 10_000_000n) result += ZERO
+      result += convertBelowYi(yiRemainder, ones, ten, hundred, thousand)
+    }
+
+    return result
   }
 
-  /** Counts the number of zero digits in a number. */
-  zeroDigit (number_) {
-    return [...number_.toString()].filter(c => c === '0').length
+  return convertBelowYi(n, ones, ten, hundred, thousand)
+}
+
+/**
+ * Convert decimal digits to words using direct concatenation.
+ */
+function decimalDigitsToWords (decimalString, ones) {
+  let result = ''
+  for (let i = 0; i < decimalString.length; i++) {
+    result += ones[Number(decimalString[i])]
   }
+  return result
+}
 
-  /** Converts decimal digits to words by reading each digit individually. */
-  decimalDigitsToWords (decimalString) {
-    const words = []
-    for (let i = 0; i < decimalString.length; i++) {
-      const digitValue = BigInt(decimalString[i])
-      words.push(this.integerToWords(digitValue))
-    }
-    return words
+/**
+ * Converts a numeric value to Simplified Chinese words.
+ *
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @param {Object} [options] - Optional configuration
+ * @param {boolean} [options.formal=true] - Use formal/financial numerals
+ * @returns {string} The number in Simplified Chinese words
+ */
+function toWords (value, options) {
+  options = validateOptions(options)
+  const { isNegative, integerPart, decimalPart } = parseNumericValue(value)
+  const formal = options.formal !== false // Default to true
+
+  let result = isNegative ? NEGATIVE : ''
+
+  result += integerToWords(integerPart, formal)
+
+  if (decimalPart) {
+    const ones = formal ? ONES_FORMAL : ONES_COMMON
+    result += DECIMAL_SEP + decimalDigitsToWords(decimalPart, ones)
   }
+
+  return result
 }
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export { toWords }

package/lib/languages/zh-Hant.d.ts

@@ -1,21 +1,11 @@
 /**
- * Traditional Chinese language converter.
+ * Converts a numeric value to Traditional Chinese words.
  *
- * Supports:
- * - Traditional Chinese characters (繁體中文)
- * - No word separators (concatenated format)
- * - Optional formal (financial) vs common numerals
+ * @param {number | string | bigint} value - The numeric value to convert
+ * @param {Object} [options] - Optional configuration
+ * @param {boolean} [options.formal=true] - Use formal/financial numerals
+ * @returns {string} The number in Traditional Chinese words
  */
-export class TraditionalChinese extends GreedyScaleLanguage {
-    constructor(options?: {});
-    scaleWords: (string | bigint)[][];
-    /** Combines two word-sets with Traditional Chinese grammar rules and zero insertion. */
-    combineWordSets(preceding: any, following: any): any;
-    /** Returns the number of digits in a number. */
-    digit(number_: any): any;
-    /** Counts the number of zero digits in a number. */
-    zeroDigit(number_: any): number;
-    /** Converts decimal digits to words by reading each digit individually. */
-    decimalDigitsToWords(decimalString: any): string[];
-}
-import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js';
+export function toWords(value: number | string | bigint, options?: {
+    formal?: boolean | undefined;
+}): string;