@rinxun/numeric-calculator 1.0.0

package/.gitignore

@@ -0,0 +1,15 @@
+node_modules
+package-lock.json
+yarn.lock
+.vscode
+.DS_Store
+/coverage
+/.pnp
+.pnp.js
+/build
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+*.js
+*.d.ts
+dist

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Symply Software Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+<h1 align="center">Numeric Calculator</h1>
+
+<p align="center">Calculate addition, subtaction, multiplication, division precisely, for tackling the precision issue</p>
+
+---
+
+<h2>Installation</h2>
+
+It is available as an [npm package](https://www.npmjs.com/package/@rinxun/numeric-calculator).
+
+```sh
+// with npm
+npm install @rinxun/numeric-calculator
+
+// with yarn
+yarn add @rinxun/numeric-calculator
+```
+
+
+
+<h2>License</h2>
+
+This project is licensed under the terms of the [MIT license](https://github.com/rinxun/numeric-calculator/blob/master/LICENSE).
+
+
+
+<h2>Why do we need this</h2>
+
+```typescript
+0.1 + 0.2 = 0.30000000000000004; 
+0.1 + 0.2 - 0.3 = 5.551115123125783e-17;
+```
+
+
+
+<h2>Constructor</h2>
+
+- `new NC(number: number, config: object)`
+
+  - number: Initial numeric
+
+    - optional
+
+  - config: Configurations 
+
+    - optional
+
+    - ```js
+      config = {
+        enableCheckBoundary?: boolean // if true, it will check if the value is out of the safe boundary
+      }
+      ```
+
+
+
+<h2>Methods</h2>
+
+The instance supports chain operations.
+
+- `plus(operands: number[]) => instance `
+- `minus(operands: number[]) => instance`
+- `times(operands: number[]) => instance`
+- `divide(operands: number[]) => instance`
+- `toPrecision(precision?: number) => number`
+
+
+
+<h2>Usage</h2>
+
+<h4>Import</h4>
+
+```typescript
+// CommonJS
+const NC = require('@rinxun/numeric-calculator');
+
+// ES6 
+import NC from '@rinxun/numeric-calculator';
+```
+
+
+
+<h4>Instantiate</h4>
+
+```typescript
+const inst1 = new NC(); 
+// or with initial numeric
+const inst2 = new NC(10); 
+// or with config
+const inst3 = new NC(10, { enableCheckBoundary: true }); 
+```
+
+
+
+<h4>inst.plus</h4>
+
+```typescript
+const result = new NC().plus(2.134).toPrecision(); // 2.134
+const result = new NC().plus(2.1341, 3.09, 0.65).toPrecision(); // 5.8741
+const result = new NC(10).plus(2.134).toPrecision(); // 12.134
+const result = new NC(10).plus(2.1341, 3.09, 0.65).toPrecision(); // 15.8741
+```
+
+
+
+<h4>inst.minus</h4>
+
+```typescript
+const result = new NC().minus(0.4).toPrecision(); // -0.6
+const result = new NC().minus(0.25, 1.5, 3.498).toPrecision(); // -4.748
+const result = new NC(2).minus(0.4).toPrecision(); // 1.6
+const result = new NC(-2).minus(0.25, 1.5, 3.498).toPrecision(); // -7.248
+```
+
+
+
+<h4>inst.times</h4>
+
+```typescript
+const result = new NC().times(0.12).toPrecision(); // 0.12
+const result = new NC().times(0.12, 100, 5).toPrecision(); // 60
+const result = new NC(-4).times(0.12).toPrecision(); // -0.48
+const result = new NC(3.2).times(0.12, 100, 5).toPrecision(); // 192
+```
+
+
+
+<h4>inst.divide</h4>
+
+```typescript
+const result = new NC().divide(3).toPrecision(); // 3
+const result = new NC().divide(100, 20, 2).toPrecision(); // 2.5
+const result = new NC(36.12).divide(3).toPrecision(); // 12.04
+const result = new NC(-1000).divide(100, 20, 2).toPrecision(); // -0.25
+```
+
+
+
+<h4>inst.toPrecision</h4>
+
+```typescript
+const result = new NC(1.2345).toPrecision(); // 1.2345
+const result = new NC(1.2345).toPrecision(4); // 1.234
+const result = new NC(1.2e-2).toPrecision(); // 0.012
+```
+
+
+
+<h4>chain operations</h4>
+
+```typescript
+const result = new NC(10).plus(2).minus(4).times(2).divide(8).toPrecision(); // 2
+```
+
+
+

package/index.d.ts

@@ -0,0 +1,99 @@
+declare type IConfig = {
+    enableCheckBoundary?: boolean;
+};
+/**
+ * @description Calculate addition, subtaction, multiplication, division precisely, for tackling the precision issue
+ * @author Janden Ma
+ * @copyright Symply Software Inc
+ */
+declare class Calculator {
+    /**
+     * @private
+     * @description global register for temporary results, core for chaining operations
+     */
+    private _VALUE;
+    /**
+     * @private
+     * @description for debugging, if true, it will check if the value is out of the safe boundary
+     */
+    private _enableCheckBoundary;
+    /**
+     * @description check if the value is out of the safe boundary
+     * @param {number} value
+     */
+    private checkBoundary;
+    /**
+     * get the length of the mantissa of the numeric
+     * @param {number} num numeric
+     */
+    private getMantissaLen;
+    /**
+     * get the precise value
+     * @param {number} num numeric
+     * @param {number} precision default 15
+     */
+    private processPrecision;
+    /**
+     * core processor for times
+     * @param {number} num1 operand 1
+     * @param {number} num2 operand 2
+     */
+    private processTimes;
+    /**
+     * core processor for divide
+     * @param {number} num1 operand 1
+     * @param {number} num2 operand 2
+     */
+    private processDivide;
+    /**
+     * core processor for minus
+     * @param {number} num1 operand 1
+     * @param {number} num2 operand 2
+     */
+    private processMinus;
+    /**
+     * core processor for plus
+     * @param {number} num1 operand 1
+     * @param {number} num2 operand 2
+     */
+    private processPlus;
+    /**
+     * core processor for times
+     * @param {number[]} nums operands
+     * @param {"plus" | "minus" | "times" | "divide"} op operator
+     */
+    private calculate;
+    /**
+     * @constructor
+     * @param {number|undefined} num initial operand
+     * @param {Config} config Configurations
+     */
+    constructor(num?: number, config?: IConfig);
+    /**
+     * @description parse the result to precise numeric
+     * @param precision default to 15
+     * @returns {number} precise result
+     */
+    toPrecision(precision?: number): number;
+    /**
+     * @description plus operator
+     * @param {number[]} nums operands
+     */
+    plus(...nums: Array<number>): this;
+    /**
+     * @description minus operator
+     * @param {number[]} nums operands
+     */
+    minus(...nums: Array<number>): this;
+    /**
+     * @description times operator
+     * @param {number[]} nums operands
+     */
+    times(...nums: Array<number>): this;
+    /**
+     * @description divide operator
+     * @param {number[]} nums operands
+     */
+    divide(...nums: Array<number>): this;
+}
+export default Calculator;

package/index.js

@@ -0,0 +1,236 @@
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+/**
+ * @description Calculate addition, subtaction, multiplication, division precisely, for tackling the precision issue
+ * @author Janden Ma
+ * @copyright Symply Software Inc
+ */
+var Calculator = /** @class */ (function () {
+    // #endregion
+    // #region Constructor
+    /**
+     * @constructor
+     * @param {number|undefined} num initial operand
+     * @param {Config} config Configurations
+     */
+    function Calculator(num, config) {
+        // #region Private Variables
+        /**
+         * @private
+         * @description global register for temporary results, core for chaining operations
+         */
+        this._VALUE = undefined;
+        /**
+         * @private
+         * @description for debugging, if true, it will check if the value is out of the safe boundary
+         */
+        this._enableCheckBoundary = false;
+        if (num !== undefined && num !== null) {
+            this._VALUE = num;
+        }
+        if (config) {
+            if (config.enableCheckBoundary) {
+                this._enableCheckBoundary = config.enableCheckBoundary;
+            }
+        }
+    }
+    // #endregion
+    // #region Private Functions
+    /**
+     * @description check if the value is out of the safe boundary
+     * @param {number} value
+     */
+    Calculator.prototype.checkBoundary = function (value) {
+        if (this._enableCheckBoundary) {
+            var val = value || this._VALUE || 0;
+            if (val > Number.MAX_SAFE_INTEGER || val < Number.MIN_SAFE_INTEGER) {
+                console.warn("".concat(val, " is out of the safe boundary, the result may be not accurate!"));
+            }
+        }
+    };
+    /**
+     * get the length of the mantissa of the numeric
+     * @param {number} num numeric
+     */
+    Calculator.prototype.getMantissaLen = function (num) {
+        var arrBySplittingExponent = num.toString().split(/[Ee]/); // eg: 2.1337983389e-12
+        var exponentPrefix = arrBySplittingExponent[0]; // value before e (eg: 2.1337983389)
+        var exponentSuffix = arrBySplittingExponent[1] || 0; // exponent length (eg: -12)
+        var decimals = exponentPrefix.split(".")[1] || ""; // decimals before e (eg: 1337983389)
+        var len = decimals.length - +exponentSuffix;
+        return len > 0 ? len : 0;
+    };
+    /**
+     * get the precise value
+     * @param {number} num numeric
+     * @param {number} precision default 15
+     */
+    Calculator.prototype.processPrecision = function (num, precision) {
+        return +parseFloat(num.toPrecision(precision || 15));
+    };
+    /**
+     * core processor for times
+     * @param {number} num1 operand 1
+     * @param {number} num2 operand 2
+     */
+    Calculator.prototype.processTimes = function (num1, num2) {
+        var num1MatissaLen = this.getMantissaLen(num1);
+        var num2MatissaLen = this.getMantissaLen(num2);
+        var amplifyingNum1 = num1 * Math.pow(10, num1MatissaLen);
+        var amplifyingNum2 = num2 * Math.pow(10, num2MatissaLen);
+        var magnification = Math.pow(10, num1MatissaLen + num2MatissaLen);
+        this.checkBoundary(amplifyingNum1);
+        this.checkBoundary(amplifyingNum2);
+        var amplifyingResult = amplifyingNum1 * amplifyingNum2;
+        this.checkBoundary(amplifyingResult);
+        return amplifyingResult / magnification;
+    };
+    /**
+     * core processor for divide
+     * @param {number} num1 operand 1
+     * @param {number} num2 operand 2
+     */
+    Calculator.prototype.processDivide = function (num1, num2) {
+        var num1MatissaLen = this.getMantissaLen(num1);
+        var num2MatissaLen = this.getMantissaLen(num2);
+        var amplifyingNum1 = num1 * Math.pow(10, num1MatissaLen);
+        var amplifyingNum2 = num2 * Math.pow(10, num2MatissaLen);
+        var magnification = Math.pow(10, num2MatissaLen - num1MatissaLen);
+        this.checkBoundary(amplifyingNum1);
+        this.checkBoundary(amplifyingNum2);
+        var amplifyingResult = amplifyingNum1 / amplifyingNum2;
+        return this.processTimes(this.processPrecision(amplifyingResult), magnification);
+    };
+    /**
+     * core processor for minus
+     * @param {number} num1 operand 1
+     * @param {number} num2 operand 2
+     */
+    Calculator.prototype.processMinus = function (num1, num2) {
+        var num1MatissaLen = this.getMantissaLen(num1);
+        var num2MatissaLen = this.getMantissaLen(num2);
+        var maxMatissaLen = Math.max(num1MatissaLen, num2MatissaLen);
+        var magnification = Math.pow(10, maxMatissaLen);
+        var amplifyingNum1 = this.processTimes(num1, magnification);
+        var amplifyingNum2 = this.processTimes(num2, magnification);
+        this.checkBoundary(amplifyingNum1);
+        this.checkBoundary(amplifyingNum2);
+        var amplifyingResult = amplifyingNum1 - amplifyingNum2;
+        this.checkBoundary(amplifyingResult);
+        return amplifyingResult / magnification;
+    };
+    /**
+     * core processor for plus
+     * @param {number} num1 operand 1
+     * @param {number} num2 operand 2
+     */
+    Calculator.prototype.processPlus = function (num1, num2) {
+        var num1MatissaLen = this.getMantissaLen(num1);
+        var num2MatissaLen = this.getMantissaLen(num2);
+        var maxMatissaLen = Math.max(num1MatissaLen, num2MatissaLen);
+        var magnification = Math.pow(10, maxMatissaLen);
+        var amplifyingNum1 = this.processTimes(num1, magnification);
+        var amplifyingNum2 = this.processTimes(num2, magnification);
+        this.checkBoundary(amplifyingNum1);
+        this.checkBoundary(amplifyingNum2);
+        var amplifyingResult = amplifyingNum1 + amplifyingNum2;
+        this.checkBoundary(amplifyingResult);
+        return amplifyingResult / magnification;
+    };
+    /**
+     * core processor for times
+     * @param {number[]} nums operands
+     * @param {"plus" | "minus" | "times" | "divide"} op operator
+     */
+    Calculator.prototype.calculate = function (nums, op) {
+        var _this = this;
+        var operands = __spreadArray([], nums, true);
+        var firstOperand = this._VALUE;
+        if (firstOperand === undefined) {
+            firstOperand = operands[0];
+            operands.shift();
+        }
+        var result = operands.reduce(function (prev, operand) {
+            switch (op) {
+                case "plus":
+                    return _this.processPlus(prev, operand);
+                case "minus":
+                    return _this.processMinus(prev, operand);
+                case "times":
+                    return _this.processTimes(prev, operand);
+                case "divide":
+                    return _this.processDivide(prev, operand);
+                default:
+                    return prev;
+            }
+        }, firstOperand);
+        this._VALUE = result;
+    };
+    // #endregion
+    // #region Public Functions
+    /**
+     * @description parse the result to precise numeric
+     * @param precision default to 15
+     * @returns {number} precise result
+     */
+    Calculator.prototype.toPrecision = function (precision) {
+        return this.processPrecision(this._VALUE || 0, precision);
+    };
+    /**
+     * @description plus operator
+     * @param {number[]} nums operands
+     */
+    Calculator.prototype.plus = function () {
+        var nums = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            nums[_i] = arguments[_i];
+        }
+        this.calculate(nums, "plus");
+        return this;
+    };
+    /**
+     * @description minus operator
+     * @param {number[]} nums operands
+     */
+    Calculator.prototype.minus = function () {
+        var nums = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            nums[_i] = arguments[_i];
+        }
+        this.calculate(nums, "minus");
+        return this;
+    };
+    /**
+     * @description times operator
+     * @param {number[]} nums operands
+     */
+    Calculator.prototype.times = function () {
+        var nums = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            nums[_i] = arguments[_i];
+        }
+        this.calculate(nums, "times");
+        return this;
+    };
+    /**
+     * @description divide operator
+     * @param {number[]} nums operands
+     */
+    Calculator.prototype.divide = function () {
+        var nums = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            nums[_i] = arguments[_i];
+        }
+        this.calculate(nums, "divide");
+        return this;
+    };
+    return Calculator;
+}());
+export default Calculator;

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@rinxun/numeric-calculator",
+  "version": "1.0.0",
+  "description": "Calculate addition, subtaction, multiplication, division precisely, for tackling the precision issue",
+  "keywords": [
+    "long",
+    "numeric",
+    "percision",
+    "calculator"
+  ],
+  "main": "index.js",
+  "type": "module",
+  "types": "**/*.d.ts",
+  "license": "MIT",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rinxun/numeric-calculator"
+  },
+  "bugs": {
+    "url": "https://github.com/rinxun/numeric-calculator/issues",
+    "email": "janden_ma@qq.com"
+  },
+  "homepage": "https://github.com/rinxun/numeric-calculator",
+  "author": {
+    "name": "Janden Ma",
+    "email": "janden_ma@qq.com",
+    "url": "https://github.com/JandneMa"
+  },
+  "scripts": {
+    "build": "./node_modules/.bin/tsc"
+  },
+  "files": [
+    "*.js",
+    "*.d.ts",
+    ".gitignore",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@types/node": "^17.0.23",
+    "typescript": "^4.6.3"
+  }
+}