n2words 1.19.0 → 1.20.0

package/lib/classes/AbstractLanguage.d.ts

@@ -37,17 +37,17 @@ export default class _default {
      */
     get wholeNumber(): number;
     /**
-     * Convert decimal number to a string array of cardinal numbers.
+     * Convert ONLY decimal portion of number (processing leading zeros) to a string array of cardinal numbers.
      * @param {string} decimal Decimal string to convert.
      * @returns {string} Value in written format.
      */
     decimalToCardinal(decimal: string): string;
     /**
-     * Converts a number to written form.
-     * @param {number|string} value Number to be convert.
+     * Convert a number to cardinal form.
+     * @param {number|string|bigint} value Number to be convert.
      * @throws {Error} Value must be a valid number.
      * @returns {string} Value in written format.
      */
-    floatToCardinal(value: number | string): string;
+    floatToCardinal(value: number | string | bigint): string;
     #private;
 }

package/lib/classes/AbstractLanguage.js

@@ -20,8 +20,8 @@ export default class {
     // Merge supplied options with defaults
     options = Object.assign({
       negativeWord: '',
-      separatorWord: undefined,
-      zero: undefined,
+      separatorWord: '',
+      zero: '',
       spaceSeparator: ' '
     }, options);
 
@@ -68,41 +68,40 @@ export default class {
   }
 
   /**
-   * Convert decimal number to a string array of cardinal numbers.
+   * Convert ONLY decimal portion of number (processing leading zeros) to a string array of cardinal numbers.
    * @param {string} decimal Decimal string to convert.
    * @returns {string} Value in written format.
    */
   decimalToCardinal(decimal) {
     const words = [];
-    let allZero = true;
 
-    // Split decimal portion into an array of characters
+    // Split decimal string into an array of characters
     const chars = decimal.split('');
 
-    // Loop through characters adding zeros to output array
-    chars.forEach(char => {
-      if (char === '0') {
-        words.push(this.zero);
-      } else {
-        allZero = false;
-      }
-    });
+    // Loop through characters adding leading zeros to words array
+    let i = 0;
+    while (i < chars.length && chars[i] === '0') {
+      words.push(this.zero);
+      i++;
+    }
 
-    if (allZero) {
+    // Prevent further processing if entire string was zeros
+    if (i === chars.length) {
       return words;
     }
 
+    // Convert and add remaining then return words array
     return words.concat(this.toCardinal(BigInt(decimal)));
   }
 
   /**
-   * Converts a number to written form.
-   * @param {number|string} value Number to be convert.
+   * Convert a number to cardinal form.
+   * @param {number|string|bigint} 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
+    // Validate user input value and convert to string (excluding BigInt)
     if (typeof value == 'number') {
       if (Number.isNaN(value)) {
         throw new Error('NaN is not an accepted number.');
@@ -110,7 +109,7 @@ export default class {
       value = value.toString();
     } else if (typeof value == 'string') {
       value = value.trim();
-      if (value.length == 0 || Number.isNaN(Number(value))) {
+      if (value.length === 0 || Number.isNaN(Number(value))) {
         throw new Error('"' + value + '" is not a valid number.');
       }
     } else if (typeof value != 'bigint') {
@@ -126,7 +125,7 @@ export default class {
       words.push(this.negativeWord);
     }
 
-    // Split value decimal (if any) (excluding BigInt)
+    // Split value decimal (if any) then convert to BigInt
     if (typeof value == 'bigint') {
       wholeNumber = value;
     } else {

package/lib/classes/BaseLanguage.d.ts

@@ -20,7 +20,7 @@ export default class _default extends AbstractLanguage {
         spaceSeparator?: string;
     }, cards: any[]);
     /**
-     * Get array of number matching "cards" from highest-to-lowest.
+     * Set 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
      * [
@@ -29,30 +29,34 @@ export default class _default extends AbstractLanguage {
      *   ...
      *   [1, 'one'],
      * ]
+     */
+    set cards(value: any[]);
+    /**
+     * Get array of number matching "cards" from highest-to-lowest.
      * @returns {Array} Array of number matching "cards" from highest-to-lowest.
      */
     get cards(): any[];
     /**
      * Get word for number if it matches a language card.
-     * @param {number} number Card number value.
+     * @param {number|bigint} number Card number value.
      * @returns {string|undefined} Return card word or undefined if no card.
      */
-    getCardWord(number: number): string | undefined;
+    getCardWord(number: number | bigint): string | undefined;
     /**
      * Get array of card matches.
-     * @param {number} value The number value to convert to cardinal form.
+     * @param {number|bigint} value The number value to convert to cardinal form.
      * @returns {object} Word sets (and pairs) from value.
      * @todo Simplify return object.
      */
-    toCardMatches(value: number): object;
+    toCardMatches(value: number | bigint): object;
     clean(words: any): any;
     postClean(out0: any): any;
     /**
      * Convert a whole number to written format.
-     * @param {number} value The number value to convert to cardinal form.
+     * @param {number|bigint} value The number value to convert to cardinal form.
      * @returns {string} Value in written format.
      */
-    toCardinal(value: number): string;
+    toCardinal(value: number | bigint): string;
     #private;
 }
 import AbstractLanguage from './AbstractLanguage.js';

package/lib/classes/BaseLanguage.js

@@ -25,6 +25,14 @@ export default class extends AbstractLanguage {
 
   /**
    * Get array of number matching "cards" from highest-to-lowest.
+   * @returns {Array} Array of number matching "cards" from highest-to-lowest.
+   */
+  get cards() {
+    return this.#cards;
+  }
+
+  /**
+   * Set 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
    * [
@@ -33,15 +41,14 @@ export default class extends AbstractLanguage {
    *   ...
    *   [1, 'one'],
    * ]
-   * @returns {Array} Array of number matching "cards" from highest-to-lowest.
    */
-  get cards() {
-    return this.#cards;
+  set cards(value) {
+    this.#cards = value;
   }
 
   /**
    * Get word for number if it matches a language card.
-   * @param {number} number Card number value.
+   * @param {number|bigint} number Card number value.
    * @returns {string|undefined} Return card word or undefined if no card.
    */
   getCardWord(number) {
@@ -54,7 +61,7 @@ export default class extends AbstractLanguage {
 
   /**
    * Get array of card matches.
-   * @param {number} value The number value to convert to cardinal form.
+   * @param {number|bigint} value The number value to convert to cardinal form.
    * @returns {object} Word sets (and pairs) from value.
    * @todo Simplify return object.
    */
@@ -153,7 +160,7 @@ export default class extends AbstractLanguage {
 
   /**
    * Convert a whole number to written format.
-   * @param {number} value The number value to convert to cardinal form.
+   * @param {number|bigint} value The number value to convert to cardinal form.
    * @returns {string} Value in written format.
    */
   toCardinal(value) {

package/lib/i18n/ar.d.ts

@@ -1,11 +1,11 @@
 /**
  * Converts a value to cardinal (written) form.
- * @param {number|string} value Number to be convert.
+ * @param {number|string|bigint} 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 _default(value: number | string, options?: object): string;
+export default function _default(value: number | string | bigint, options?: object): string;
 export class Arabic extends AbstractLanguage {
     constructor(options: any);
     number: any;
@@ -22,7 +22,20 @@ export class Arabic extends AbstractLanguage {
     arabicAppendedGroup: string[];
     arabicPluralGroups: string[];
     digitFeminineStatus(digit: any): string;
-    processArabicGroup(groupNumber: any, groupLevel: any, remainingNumber: any): string;
-    toCardinal(number: any): string;
+    /**
+     * Processes the Arabic group number and returns the corresponding Arabic representation.
+     * @param {number} groupNumber - The number to process. From 1 to 999.
+     * @param {number} groupLevel - The level of the group.
+     *     Example: 12345678 is processed in blocks: '678' (group 0), '345' (group 1), '12' (group 2)
+     * @returns {string} The Arabic representation of the group number.
+     */
+    processArabicGroup(groupNumber: number, groupLevel: number): string;
+    /**
+     * Converts a number to its cardinal representation in Arabic.
+     * It process by blocks of 3 digits.
+     * @param {number} number - The number to convert.
+     * @returns {string} The cardinal representation of the number in Arabic.
+     */
+    toCardinal(number: number): string;
 }
 import AbstractLanguage from '../classes/AbstractLanguage.js';

package/lib/i18n/ar.js

@@ -28,7 +28,7 @@ export class Arabic extends AbstractLanguage {
       'تسعة عشر',
     ],
     feminine: [
-      'إحدى',
+      'واحدة',
       'اثنتان',
       'ثلاث',
       'أربع',
@@ -64,10 +64,6 @@ export class Arabic extends AbstractLanguage {
 
   arabicPluralGroups = ['', 'آلاف', 'ملايين', 'مليارات', 'تريليونات', 'كوادريليونات', 'كوينتليونات', 'سكستيليونات'];
 
-  // isCurrencyPartNameFeminine = true
-
-  // isCurrencyNameFeminine = false
-
   constructor(options) {
     options = Object.assign({
       negativeWord: 'ناقص',
@@ -82,67 +78,70 @@ export class Arabic extends AbstractLanguage {
   }
 
   digitFeminineStatus(digit) {
-    // if ((groupLevel == -1 && this.isCurrencyPartNameFeminine) || (groupLevel == 0 && this.isCurrencyNameFeminine)) {
-    //   return this.arabicFeminineOnes[digit]
-    // }
     return this.ones[this.feminine ? 'feminine' : 'masculine'][digit - 1];
   }
 
-  processArabicGroup(groupNumber, groupLevel, remainingNumber) {
+  /**
+   * Processes the Arabic group number and returns the corresponding Arabic representation.
+   * @param {number} groupNumber - The number to process. From 1 to 999.
+   * @param {number} groupLevel - The level of the group.
+   *     Example: 12345678 is processed in blocks: '678' (group 0), '345' (group 1), '12' (group 2)
+   * @returns {string} The Arabic representation of the group number.
+   */
+  processArabicGroup(groupNumber, groupLevel) {
     let tens = groupNumber % 100;
     const hundreds = groupNumber / 100;
     let retVal = '';
 
-    if (hundreds > 0) {
-      retVal = (tens == 0 && Math.trunc(hundreds) == 2 ? this.arabicAppendedTwos[0] : this.arabicHundreds[Math.trunc(hundreds)]);
+    if (Math.trunc(hundreds) > 0) {
+      if (tens == 0 && Math.trunc(hundreds) == 2) {
+        retVal = this.arabicTwos[0];
+      } else {
+        retVal = this.arabicHundreds[Math.trunc(hundreds)];
+        if (retVal != '' && tens != 0) {
+          retVal += ' و';
+        }
+      }
     }
 
-    if (tens > 0) {
-      if (tens < 20) {
-        if (tens == 2 && Math.trunc(hundreds) == 0 && groupLevel > 0) {
-          retVal = ([
-            2000, 2000000, 2000000000, 2000000000000, 2000000000000000, 2000000000000000000
-          ].indexOf(this.number) != -1) ? this.arabicAppendedTwos[groupLevel] : this.arabicTwos[groupLevel];
-        } else {
-          // Add divider
-          if (retVal != '') {
-            retVal += ' و ';
-          }
-
-          if (tens == 1 && groupLevel > 0 && hundreds == 0) {
-            retVal += '';
-          } else if (
-            (tens == 1 || tens == 2) &&
-            (groupLevel == 0 || groupLevel == -1) &&
-            (hundreds == 0 && remainingNumber == 0)
-          ) {
-            retVal += '';
+    if (tens > 0 && tens < 20) { // 1 -> 19
+      if (tens === 2 && Math.trunc(hundreds) === 0 && groupLevel > 0) {
+        const pow = Math.trunc(Math.log10(Number(this.number)));
+        if (pow % 3 === 0 && this.number === 2 * Math.pow(10, pow)) {
+          if (groupNumber === 2) {
+            retVal = this.arabicTwos[Math.trunc(groupLevel)];
           } else {
-            retVal += this.digitFeminineStatus(Math.trunc(tens), groupLevel);
+            retVal = this.arabicAppendedTwos[Math.trunc(groupLevel)];
           }
+        } else {
+          retVal = this.arabicTwos[Math.trunc(groupLevel)];
         }
+      } else if (tens === 1 && groupLevel > 0) {
+        retVal += this.arabicGroup[Math.trunc(groupLevel)];
       } else {
-        const ones = tens % 10;
-        tens = (tens / 10) - 2;
-
-        if (ones > 0) {
-          if (retVal != '' && tens < 4) {
-            retVal += ' و ';
-          }
-
-          retVal += this.digitFeminineStatus(ones, groupLevel);
-        }
-        if (retVal != '' && ones != 0) {
-          retVal += ' و ';
-        }
-
-        retVal += this.arabicTens[Math.trunc(tens)];
+        retVal += this.digitFeminineStatus(Math.trunc(tens), groupLevel);
+      }
+    } else if (tens >= 20) { // 20 -> 99
+      const ones = tens % 10;
+      const tensIndex = (tens / 10) - 2;
+      if (ones > 0) {
+        retVal += this.digitFeminineStatus(ones, groupLevel);
       }
+      if (retVal != '' && ones != 0) {
+        retVal += ' و';
+      }
+      retVal += this.arabicTens[Math.trunc(tensIndex)];
     }
 
     return retVal;
   }
 
+  /**
+   * Converts a number to its cardinal representation in Arabic.
+   * It process by blocks of 3 digits.
+   * @param {number} number - The number to convert.
+   * @returns {string} The cardinal representation of the number in Arabic.
+   */
   toCardinal(number) {
     if (number == 0) {
       return this.zero;
@@ -150,30 +149,30 @@ export class Arabic extends AbstractLanguage {
 
     this.number = number;
     let tempNumber = number;
+    let tempNumberDec;
     let group = 0;
     let retVal = '';
 
     // Loop until number has been reduced to zero or less
     while (tempNumber > 0) {
+      tempNumberDec = tempNumber;
       // Get the remaining value after dividing by 1000
-      const numberToProcess = Number(tempNumber % 1000n); // Maximum: 999
-      // Divide number by 1000
-      tempNumber = tempNumber / 1000n;
+      const numberToProcess = Number(tempNumberDec % 1000n); // Maximum: 999
+      tempNumber = tempNumberDec / 1000n;
 
       // Process "group"
-      const groupDescription = this.processArabicGroup(numberToProcess, group, tempNumber);
+      const groupDescription = this.processArabicGroup(numberToProcess, group);
 
       // Did the group return anything?
       if (groupDescription != '') {
-        // Is this after the first "group"?
-        if (group > 0) {
-          // Is the return value still empty?
+        // Is this after the first "group" ? Because nothing is appeded after group 0.
+        if (group > 0) { // hundreds, thousands, etc...
+          // Is the return value still empty ?
           if (retVal != '') {
-            retVal = ' و ' + retVal;
+            retVal = ' و' + retVal;
           }
 
-          // Process every number other than 2
-          if (numberToProcess != 2) {
+          if (numberToProcess > 2) {
             if (numberToProcess % 100 != 1) {
               if (numberToProcess >= 3 && numberToProcess <= 10) {
                 retVal = this.arabicPluralGroups[group] + ' ' + retVal;
@@ -199,13 +198,16 @@ export class Arabic extends AbstractLanguage {
       group++;
     }
 
+    // Replace multiple spaces with one space
+    retVal = retVal.replace(/ +/g, ' ');
+
     return retVal.trim();
   }
 }
 
 /**
  * Converts a value to cardinal (written) form.
- * @param {number|string} value Number to be convert.
+ * @param {number|string|bigint} value Number to be convert.
  * @param {object} [options] Options for class.
  * @throws {Error} Value cannot be invalid.
  * @returns {string} Value in cardinal (written) format.

package/lib/i18n/az.d.ts

@@ -1,11 +1,11 @@
 /**
  * Converts a value to cardinal (written) form.
- * @param {number|string} value Number to be convert.
+ * @param {number|string|bigint} 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 _default(value: number | string, options?: object): string;
+export default function _default(value: number | string | bigint, options?: object): string;
 export class N2WordsAZ extends BaseLanguage {
     constructor(options: any);
     merge(lPair: any, rPair: any): {

package/lib/i18n/az.js

@@ -56,7 +56,7 @@ export class N2WordsAZ extends BaseLanguage {
 
 /**
  * Converts a value to cardinal (written) form.
- * @param {number|string} value Number to be convert.
+ * @param {number|string|bigint} value Number to be convert.
  * @param {object} [options] Options for class.
  * @throws {Error} Value cannot be invalid.
  * @returns {string} Value in cardinal (written) format.

package/lib/i18n/cz.d.ts

@@ -1,11 +1,11 @@
 /**
  * Converts a value to cardinal (written) form.
- * @param {number|string} value Number to be convert.
+ * @param {number|string|bigint} 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 _default(value: number | string, options?: object): string;
+export default function _default(value: number | string | bigint, options?: object): string;
 export class N2WordsCZ extends N2WordsRU {
     ones: {
         1: string;

package/lib/i18n/cz.js

@@ -126,7 +126,7 @@ export class N2WordsCZ extends N2WordsRU {
 
 /**
  * Converts a value to cardinal (written) form.
- * @param {number|string} value Number to be convert.
+ * @param {number|string|bigint} value Number to be convert.
  * @param {object} [options] Options for class.
  * @throws {Error} Value cannot be invalid.
  * @returns {string} Value in cardinal (written) format.

package/lib/i18n/de.d.ts

@@ -1,11 +1,11 @@
 /**
  * Converts a value to cardinal (written) form.
- * @param {number|string} value Number to be convert.
+ * @param {number|string|bigint} 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 _default(value: number | string, options?: object): string;
+export default function _default(value: number | string | bigint, options?: object): string;
 export class N2WordsDE extends BaseLanguage {
     constructor(options: any);
     merge(curr: any, next: any): {

package/lib/i18n/de.js

@@ -97,7 +97,7 @@ export class N2WordsDE extends BaseLanguage {
 
 /**
  * Converts a value to cardinal (written) form.
- * @param {number|string} value Number to be convert.
+ * @param {number|string|bigint} value Number to be convert.
  * @param {object} [options] Options for class.
  * @throws {Error} Value cannot be invalid.
  * @returns {string} Value in cardinal (written) format.

package/lib/i18n/dk.d.ts

@@ -1,11 +1,11 @@
 /**
  * Converts a value to cardinal (written) form.
- * @param {number|string} value Number to be convert.
+ * @param {number|string|bigint} 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 _default(value: number | string, options?: object): string;
+export default function _default(value: number | string | bigint, options?: object): string;
 export class N2WordsDK extends BaseLanguage {
     constructor(options: any);
     ordFlag: any;

package/lib/i18n/dk.js

@@ -100,7 +100,7 @@ export class N2WordsDK extends BaseLanguage {
 
 /**
  * Converts a value to cardinal (written) form.
- * @param {number|string} value Number to be convert.
+ * @param {number|string|bigint} value Number to be convert.
  * @param {object} [options] Options for class.
  * @throws {Error} Value cannot be invalid.
  * @returns {string} Value in cardinal (written) format.

package/lib/i18n/en.d.ts

@@ -1,11 +1,11 @@
 /**
  * Converts a value to cardinal (written) form.
- * @param {number|string} value Number to be convert.
+ * @param {number|string|bigint} 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 _default(value: number | string, options?: object): string;
+export default function _default(value: number | string | bigint, options?: object): string;
 /**
  * This class is for converting numbers to english words.
  */

package/lib/i18n/en.js

@@ -76,7 +76,7 @@ export class English extends BaseLanguage {
 
 /**
  * Converts a value to cardinal (written) form.
- * @param {number|string} value Number to be convert.
+ * @param {number|string|bigint} value Number to be convert.
  * @param {object} [options] Options for class.
  * @throws {Error} Value cannot be invalid.
  * @returns {string} Value in cardinal (written) format.

package/lib/i18n/es.d.ts

@@ -1,11 +1,11 @@
 /**
  * Converts a value to cardinal (written) form.
- * @param {number|string} value Number to be convert.
+ * @param {number|string|bigint} 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 _default(value: number | string, options?: object): string;
+export default function _default(value: number | string | bigint, options?: object): string;
 export class N2WordsES extends BaseLanguage {
     constructor(options: any);
     genderStem: any;

package/lib/i18n/es.js

@@ -100,7 +100,7 @@ export class N2WordsES extends BaseLanguage {
 
 /**
  * Converts a value to cardinal (written) form.
- * @param {number|string} value Number to be convert.
+ * @param {number|string|bigint} value Number to be convert.
  * @param {object} [options] Options for class.
  * @throws {Error} Value cannot be invalid.
  * @returns {string} Value in cardinal (written) format.

package/lib/i18n/fa.d.ts

@@ -1,11 +1,11 @@
 /**
  * Converts a value to cardinal (written) form.
- * @param {number|string} value Number to be convert.
+ * @param {number|string|bigint} 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 _default(value: number | string, options?: object): string;
+export default function _default(value: number | string | bigint, options?: object): string;
 export class N2WordsFA extends AbstractLanguage {
     constructor(options: any);
     namedNumbers: {

package/lib/i18n/fa.js

@@ -96,7 +96,7 @@ export class N2WordsFA extends AbstractLanguage {
 
 /**
  * Converts a value to cardinal (written) form.
- * @param {number|string} value Number to be convert.
+ * @param {number|string|bigint} value Number to be convert.
  * @param {object} [options] Options for class.
  * @throws {Error} Value cannot be invalid.
  * @returns {string} Value in cardinal (written) format.

package/lib/i18n/fr-BE.d.ts

@@ -1,11 +1,11 @@
 /**
  * Converts a value to cardinal (written) form.
- * @param {number|string} value Number to be convert.
+ * @param {number|string|bigint} 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 _default(value: number | string, options?: object): string;
+export default function _default(value: number | string | bigint, options?: object): string;
 export class N2WordsFRBE extends N2WordsFR {
 }
 import { N2WordsFR } from './fr.js';

package/lib/i18n/fr-BE.js

@@ -10,7 +10,7 @@ export class N2WordsFRBE extends N2WordsFR {
 
 /**
  * Converts a value to cardinal (written) form.
- * @param {number|string} value Number to be convert.
+ * @param {number|string|bigint} value Number to be convert.
  * @param {object} [options] Options for class.
  * @throws {Error} Value cannot be invalid.
  * @returns {string} Value in cardinal (written) format.

package/lib/i18n/fr.d.ts

@@ -1,11 +1,11 @@
 /**
  * Converts a value to cardinal (written) form.
- * @param {number|string} value Number to be convert.
+ * @param {number|string|bigint} 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 _default(value: number | string, options?: object): string;
+export default function _default(value: number | string | bigint, options?: object): string;
 export class N2WordsFR extends BaseLanguage {
     constructor(options: any);
     merge(curr: any, next: any): {