n2words 1.13.0 → 1.15.0

package/examples/node.mjs

@@ -0,0 +1,10 @@
+/* eslint-disable import/no-nodejs-modules */
+import n2words from '../lib/i18n/EN.mjs';
+import * as readline from 'node:readline/promises';
+import {stdin as input, stdout as output} from 'node:process';
+
+const rl = readline.createInterface({input, output});
+
+console.log(n2words(await rl.question('Value to convert? ')));
+
+rl.close();

package/lib/classes/AbstractLanguage.mjs

@@ -0,0 +1,151 @@
+/**
+ * Creates new language class that processes decimals separately.
+ * Requires implementing `toCardinal`.
+ */
+export default class {
+  #negativeWord;
+  #separatorWord;
+  #zero;
+  #spaceSeparator;
+  #wholeNumber;
+
+  /**
+   * @param {object} options Options for class.
+   * @param {string} [options.negativeWord = ''] Word that precedes a negative number (if any).
+   * @param {string} options.separatorWord Word that separates cardinal numbers (i.e. "and").
+   * @param {string} options.zero Word for 0 (i.e. "zero").
+   * @param {string} [options.spaceSeparator = ' '] Character that separates words.
+   */
+  constructor(options) {
+    // Merge supplied options with defaults
+    options = Object.assign({
+      negativeWord: '',
+      separatorWord: undefined,
+      zeroWord: undefined,
+      spaceSeparator: ' '
+    }, options);
+
+    // Make options available to class
+    this.#negativeWord = options.negativeWord;
+    this.#separatorWord = options.separatorWord;
+    this.#zero = options.zero;
+    this.#spaceSeparator = options.spaceSeparator;
+  }
+
+  /**
+   * @returns {string} Word that precedes a negative number (if any).
+   */
+  get negativeWord() {
+    return this.#negativeWord;
+  }
+
+  /**
+   * @returns {string} Word that separates cardinal numbers (i.e. "and").
+   */
+  get separatorWord() {
+    return this.#separatorWord;
+  }
+
+  /**
+   * @returns {string} Word for 0 (i.e. "zero").
+   */
+  get zero() {
+    return this.#zero;
+  }
+
+  /**
+   * @returns {string} Character that separates words.
+   */
+  get spaceSeparator() {
+    return this.#spaceSeparator;
+  }
+
+  /**
+   * @returns {number} Input value without decimal.
+   */
+  get wholeNumber() {
+    return this.#wholeNumber;
+  }
+
+  /**
+   * Convert decimal number to a string array of cardinal numbers.
+   * @param {number} decimal Decimal number to convert.
+   * @returns {string} Value in written format.
+   */
+  decimalToCardinal(decimal) {
+    const words = [];
+
+    // Split decimal portion into an array of characters in reverse
+    const chars = decimal.split('').reverse();
+
+    // Loop through array (from the end) adding words to output array
+    while (chars.pop() == '0') {
+      words.push(this.zero);
+    }
+
+    // Add decimal number to word array
+    return words.concat(this.toCardinal(BigInt(decimal)));
+  }
+
+  /**
+   * Converts a number to written form.
+   * @param {number|string} value Number to be convert.
+   * @throws {Error} Value must be a valid number.
+   * @returns {string} Value in written format.
+   */
+  floatToCardinal(value) {
+    // Validate user input value
+    if (typeof value == 'number') {
+      if (Number.isNaN(value)) {
+        throw new Error('NaN is not an accepted number.');
+      }
+      value = value.toString();
+    } else if (typeof value == 'string') {
+      value = value.trim();
+      if (value.length == 0 || Number.isNaN(Number(value))) {
+        throw new Error('"' + value + '" is not a valid number.');
+      }
+    } else if (typeof value != 'bigint') {
+      throw new TypeError('Invalid variable type: ' + typeof value);
+    }
+
+    let words = [];
+    let wholeNumber;
+    let decimalNumber;
+
+    // If negative number add negative word
+    if (value < 0) {
+      words.push(this.negativeWord);
+    }
+
+    // Split value decimal (if any) (excluding BigInt)
+    if (typeof value == 'bigint') {
+      wholeNumber = value;
+    } else {
+      const splitValue = value.split('.');
+      wholeNumber = BigInt(splitValue[0]);
+      decimalNumber = splitValue[1];
+    }
+
+    // Convert whole number to positive (if negative)
+    if (wholeNumber < 0) {
+      wholeNumber = -wholeNumber;
+    }
+
+    // NOTE: Only needed for CZ
+    this.#wholeNumber = wholeNumber;
+
+    // Add whole number in written form
+    words = words.concat(this.toCardinal(wholeNumber));
+
+    // Add decimal number in written form (if any)
+    if (decimalNumber) {
+      words.push(this.separatorWord);
+
+      words = words.concat(this.decimalToCardinal(decimalNumber));
+    }
+
+    // Join words with spaces
+    return words.join(this.spaceSeparator);
+  }
+}

package/lib/classes/BaseLanguage.mjs

@@ -0,0 +1,174 @@
+import AbstractLanguage from './AbstractLanguage.mjs';
+
+/**
+ * Creates new common language class that uses a highest matching word value algorithm.
+ * Number matching word {@link cards} must be provided for this to work.
+ * See {@link AbstractLanguage} for further requirements.
+ * @classdesc Common class for (mostly european) languages.
+ */
+export default class extends AbstractLanguage {
+  #cards;
+
+  /**
+   * @param {object} options Options for class.
+   * @param {string} [options.negativeWord = ''] Word that precedes a negative number (if any).
+   * @param {string} options.separatorWord Word that separates cardinal numbers (i.e. "and").
+   * @param {string} options.zero Word for 0 (i.e. "zero").
+   * @param {string} [options.spaceSeparator = ' '] Character that separates words.
+   * @param {Array} cards Array of number matching "cards" from highest-to-lowest.
+   */
+  constructor(options, cards) {
+    super(options);
+
+    this.#cards = cards;
+  }
+
+  /**
+   * Get array of number matching "cards" from highest-to-lowest.
+   * First element in card array is the number to match while the second is the word to use.
+   * @example
+   * [
+   *   ...
+   *   [100, 'hundred'],
+   *   ...
+   *   [1, 'one'],
+   * ]
+   * @returns {Array} Array of number matching "cards" from highest-to-lowest.
+   */
+  get cards() {
+    return this.#cards;
+  }
+
+  /**
+   * Get word for number if it matches a language card.
+   * @param {number} number Card number value.
+   * @returns {string|undefined} Return card word or undefined if no card.
+   */
+  getCardWord(number) {
+    // Get matching card from number
+    const card = this.cards.find(_card => _card[0] == number);
+
+    // Return card word or undefined if no card found
+    return (Array.isArray(card) ? card[1] : undefined);
+  }
+
+  /**
+   * Get array of card matches.
+   * @param {number} value The number value to convert to cardinal form.
+   * @returns {object} Word sets (and pairs) from value.
+   * @todo Simplify return object.
+   */
+  toCardMatches(value) {
+    const out = [];
+    let remaining = value;
+
+    do {
+      // Find card with highest matching number
+      const card = this.cards.find(card => {
+        return remaining >= card[0];
+      });
+
+      let quantity; // Quantity of card set values
+
+      // Calculate quantity and remaining value
+      // Override variables for 0 as math will fail
+      if (remaining == 0) {
+        quantity = 1;
+        remaining = 0;
+      } else {
+        quantity = remaining / card[0];
+        remaining = remaining % card[0];
+      }
+
+      // Is value perfect match of card number?
+      if (quantity == 1) {
+        /** @todo Merge word set pairs together (if possible) to simplify return object */
+        out.push({
+          [this.getCardWord(1)]: 1,
+        });
+      } else {
+        /** @todo Understand the logic for this */
+        /*if (quantity == remaining) {
+          return [(quantity * this.getCardWord(card[0]), quantity * card[0])];
+        }*/
+
+        /**
+         * @todo Remove reciprocating calls.
+         */
+        out.push(this.toCardMatches(quantity));
+      }
+
+      // Add matching word set to output list
+      out.push({
+        [card[1]]: card[0],
+      });
+    }
+    while (remaining > 0);
+
+    return out;
+  }
+
+  scanNum(value) {
+    return value.split('').map(v => this.getCardWord(Number(v)));
+  }
+
+  clean(words) {
+    let out = words;
+
+    // Loop through word sets while array size is greater or less than 1
+    /** @todo Change logic to work in for loop to better understand loop intentions */
+    while (words.length != 1) {
+      out = [];
+      const left = words[0];
+      const right = words[1];
+
+      // Are the first & second word sets arrays?
+      if (!Array.isArray(left) && !Array.isArray(right)) {
+        // Merge word set pair and add to output array
+        out.push(this.merge(left, right));
+
+        /** @todo Understand */
+        if (words.slice(2).length > 0) {
+          out.push(words.slice(2));
+        }
+      } else {
+        // Loop through
+        for (let i = 0; i < words.length; i++) {
+          const elem = words[i];
+
+          if (Array.isArray(elem)) {
+            if (elem.length == 1) out.push(elem[0]);
+            else out.push(this.clean(elem));
+          } else {
+            out.push(elem);
+          }
+        }
+      }
+
+      words = out;
+    }
+
+    return out[0];
+  }
+
+  postClean(out0) {
+    return out0.trimRight();
+  }
+
+  /**
+   * Convert a whole number to written format.
+   * @param {number} value The number value to convert to cardinal form.
+   * @returns {string} Value in written format.
+   */
+  toCardinal(value) {
+    // Convert value to word sets
+    const words = this.toCardMatches(value);
+
+    // Process word sets
+    const preWords = Object.keys(this.clean(words))[0];
+
+    // Process word sets some more and return result
+    /** @todo Look into language functions/events */
+    return this.postClean(preWords);
+  }
+}

package/lib/i18n/AR.mjs

@@ -1,38 +1,52 @@
-import N2WordsAbs from '../classes/N2WordsAbs.mjs';
-
-export class N2WordsAR extends N2WordsAbs {
-  constructor() {
-    super();
-
-    this.integerValue = 0;
-    this.decimalValue = 0;
-    this.negativeWord = 'ناقص';
-    this.separatorWord = 'فاصلة';
-    this.number = 0;
-    this.zero = 'صفر';
-    // this.isCurrencyPartNameFeminine = true
-    // this.isCurrencyNameFeminine = false
-    this.arabicOnes = [
-      '', 'واحد', 'اثنان', 'ثلاثة', 'أربعة', 'خمسة', 'ستة', 'سبعة', 'ثمانية',
-      'تسعة',
-      'عشرة', 'أحد عشر', 'اثنا عشر', 'ثلاثة عشر', 'أربعة عشر', 'خمسة عشر',
-      'ستة عشر', 'سبعة عشر', 'ثمانية عشر',
-      'تسعة عشر',
-    ];
-    this.arabicFeminineOnes = [
-      '', 'إحدى', 'اثنتان', 'ثلاث', 'أربع', 'خمس', 'ست', 'سبع', 'ثمان',
-      'تسع',
-      'عشر', 'إحدى عشرة', 'اثنتا عشرة', 'ثلاث عشرة', 'أربع عشرة',
-      'خمس عشرة', 'ست عشرة', 'سبع عشرة', 'ثماني عشرة',
-      'تسع عشرة',
-    ];
-    this.arabicTens = ['عشرون', 'ثلاثون', 'أربعون', 'خمسون', 'ستون', 'سبعون', 'ثمانون', 'تسعون'];
-    this.arabicHundreds = ['', 'مائة', 'مئتان', 'ثلاثمائة', 'أربعمائة', 'خمسمائة', 'ستمائة', 'سبعمائة', 'ثمانمائة', 'تسعمائة'];
-    this.arabicAppendedTwos = ['مئتا', 'ألفا', 'مليونا', 'مليارا', 'تريليونا', 'كوادريليونا', 'كوينتليونا', 'سكستيليونا'];
-    this.arabicTwos = ['مئتان', 'ألفان', 'مليونان', 'ملياران', 'تريليونان', 'كوادريليونان', 'كوينتليونان', 'سكستيليونان'];
-    this.arabicGroup = ['مائة', 'ألف', 'مليون', 'مليار', 'تريليون', 'كوادريليون', 'كوينتليون', 'سكستيليون'];
-    this.arabicAppendedGroup = ['', 'ألفاً', 'مليوناً', 'ملياراً', 'تريليوناً', 'كوادريليوناً', 'كوينتليوناً', 'سكستيليوناً'];
-    this.arabicPluralGroups = ['', 'آلاف', 'ملايين', 'مليارات', 'تريليونات', 'كوادريليونات', 'كوينتليونات', 'سكستيليونات'];
+import AbstractLanguage from '../classes/AbstractLanguage.mjs';
+
+export class Arabic extends AbstractLanguage {
+  integerValue = 0;
+
+  decimalValue = 0;
+
+  number = 0;
+
+  arabicOnes = [
+    '', 'واحد', 'اثنان', 'ثلاثة', 'أربعة', 'خمسة', 'ستة', 'سبعة', 'ثمانية',
+    'تسعة',
+    'عشرة', 'أحد عشر', 'اثنا عشر', 'ثلاثة عشر', 'أربعة عشر', 'خمسة عشر',
+    'ستة عشر', 'سبعة عشر', 'ثمانية عشر',
+    'تسعة عشر',
+  ];
+
+  arabicFeminineOnes = [
+    '', 'إحدى', 'اثنتان', 'ثلاث', 'أربع', 'خمس', 'ست', 'سبع', 'ثمان',
+    'تسع',
+    'عشر', 'إحدى عشرة', 'اثنتا عشرة', 'ثلاث عشرة', 'أربع عشرة',
+    'خمس عشرة', 'ست عشرة', 'سبع عشرة', 'ثماني عشرة',
+    'تسع عشرة',
+  ];
+
+  arabicTens = ['عشرون', 'ثلاثون', 'أربعون', 'خمسون', 'ستون', 'سبعون', 'ثمانون', 'تسعون'];
+
+  arabicHundreds = ['', 'مائة', 'مئتان', 'ثلاثمائة', 'أربعمائة', 'خمسمائة', 'ستمائة', 'سبعمائة', 'ثمانمائة', 'تسعمائة'];
+
+  arabicAppendedTwos = ['مئتا', 'ألفا', 'مليونا', 'مليارا', 'تريليونا', 'كوادريليونا', 'كوينتليونا', 'سكستيليونا'];
+
+  arabicTwos = ['مئتان', 'ألفان', 'مليونان', 'ملياران', 'تريليونان', 'كوادريليونان', 'كوينتليونان', 'سكستيليونان'];
+
+  arabicGroup = ['مائة', 'ألف', 'مليون', 'مليار', 'تريليون', 'كوادريليون', 'كوينتليون', 'سكستيليون'];
+
+  arabicAppendedGroup = ['', 'ألفاً', 'مليوناً', 'ملياراً', 'تريليوناً', 'كوادريليوناً', 'كوينتليوناً', 'سكستيليوناً'];
+
+  arabicPluralGroups = ['', 'آلاف', 'ملايين', 'مليارات', 'تريليونات', 'كوادريليونات', 'كوينتليونات', 'سكستيليونات'];
+
+  // isCurrencyPartNameFeminine = true
+
+  // isCurrencyNameFeminine = false
+
+  constructor(options) {
+    super(Object.assign({
+      negativeWord: 'ناقص',
+      separatorWord: 'فاصلة',
+      zero: 'صفر'
+    }, options));
   }
 
   digitFeminineStatus(digit/* , groupLevel */) {
@@ -93,7 +107,10 @@ export class N2WordsAR extends N2WordsAbs {
   }
 
   toCardinal(number) {
-    if (parseInt(number) == 0) {
+    /** @todo Convert class to work with BigInt */
+    number = Number(number);
+
+    if (number == 0) {
       return this.zero;
     }
     let tempNumber = number;
@@ -133,6 +150,13 @@ export class N2WordsAR extends N2WordsAbs {
   }
 }
 
-export default function(n) {
-  return new N2WordsAR().floatToCardinal(n);
+/**
+ * Converts a value to cardinal (written) form.
+ * @param {number|string} value Number to be convert.
+ * @param {object} options Options for class.
+ * @throws {Error} Value cannot be invalid.
+ * @returns {string} Value in cardinal (written) format.
+ */
+export default function(value, options) {
+  return new Arabic(options).floatToCardinal(value);
 }

package/lib/i18n/AZ.mjs

@@ -1,40 +1,39 @@
-import N2WordsBase from '../classes/N2WordsBase.mjs';
+import BaseLanguage from '../classes/BaseLanguage.mjs';
 
-export class N2WordsAZ extends N2WordsBase {
-  constructor() {
-    super();
-
-    this.negativeWord = 'mənfi';
-    this.separatorWord = 'nöqtə';
-    this.zero = 'sıfır';
-    this.cards = [
-      { '1000000000000000000': 'kentilyon' },
-      { '1000000000000000': 'katrilyon' },
-      { '1000000000000': 'trilyon' },
-      { '1000000000': 'milyar' },
-      { '1000000': 'milyon' },
-      { '1000': 'min' },
-      { '100': 'yüz' },
-      { '90': 'doxsan' },
-      { '80': 'səksən' },
-      { '70': 'yetmiş' },
-      { '60': 'altmış' },
-      { '50': 'əlli' },
-      { '40': 'qırx' },
-      { '30': 'otuz' },
-      { '20': 'iyirmi' },
-      { '10': 'on' },
-      { '9': 'doqquz' },
-      { '8': 'səkkiz' },
-      { '7': 'yeddi' },
-      { '6': 'altı' },
-      { '5': 'beş' },
-      { '4': 'dörd' },
-      { '3': 'üç' },
-      { '2': 'iki' },
-      { '1': 'bir' },
-      { '0': 'sıfır' }
-    ];
+export class N2WordsAZ extends BaseLanguage {
+  constructor(options) {
+    super(Object.assign({
+      negativeWord: 'mənfi',
+      separatorWord: 'nöqtə',
+      zero: 'sıfır'
+    }, options), [
+      [1000000000000000000n, 'kentilyon'],
+      [1000000000000000n, 'katrilyon'],
+      [1000000000000n, 'trilyon'],
+      [1000000000n, 'milyar'],
+      [1000000n, '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']
+    ]);
   }
 
   merge(lPair, rPair) {
@@ -52,6 +51,13 @@ export class N2WordsAZ extends N2WordsBase {
   }
 }
 
-export default function(n) {
-  return new N2WordsAZ().floatToCardinal(n);
+/**
+ * Converts a value to cardinal (written) form.
+ * @param {number|string} value Number to be convert.
+ * @param {object} options Options for class.
+ * @throws {Error} Value cannot be invalid.
+ * @returns {string} Value in cardinal (written) format.
+ */
+export default function(value, options) {
+  return new N2WordsAZ(options).floatToCardinal(value);
 }