bigmathutils 1.0.0

package/README.md

@@ -0,0 +1,161 @@
+# bigmathutils
+
+A lightweight, high-precision **big number** utility for JavaScript and Node.js.
+Designed for financial calculations, blockchain integrations, and any environment where native JavaScript numbers are not enough.
+
+## ✨ Features
+
+- 🔢 Arbitrary-precision math using BigInt
+- ⚡ Zero dependencies — fast & secure
+- 🧮 Easy-to-use math functions (`add`, `sub`, `mul`, `div`, `pow`, etc.)
+- 🧱 Type-safe and stable
+- 🔒 Suitable for cryptography, blockchain, finance, token math
+- 📦 Works in Node.js and bundlers (Vite, Webpack, etc.)
+
+## 📦 Installation
+
+The library is the single JavaScript file *big.js* or the ES module *big.mjs*.
+
+### [Node.js](http://nodejs.org)
+
+```bash
+$ npm install bigmathutils
+```
+
+CommonJS:
+
+```javascript
+const Big = require('bigmathutils');
+```
+
+ES module:
+
+```javascript
+import Big from 'bigmathutils';
+```
+
+## 🚀 Usage
+
+*In the code examples below, semicolons and `toString` calls are not shown.*
+
+The library exports a single constructor function, `Big`.
+
+A Big number is created from a primitive number, string, or other Big number.
+
+```javascript
+x = new Big(123.4567)
+y = Big('123456.7e-3')                 // 'new' is optional
+z = new Big(x)
+x.eq(y) && x.eq(z) && y.eq(z)          // true
+```
+
+In Big strict mode, creating a Big number from a primitive number is disallowed.
+
+```javascript
+Big.strict = true
+x = new Big(1)                         // TypeError: [bigmathutils] Invalid number
+y = new Big('1.0000000000000001')
+y.toNumber()                           // Error: [bigmathutils] Imprecise conversion
+```
+
+A Big number is immutable in the sense that it is not changed by its methods.
+
+```javascript
+0.3 - 0.1                              // 0.19999999999999998
+x = new Big(0.3)
+x.minus(0.1)                           // "0.2"
+x                                      // "0.3"
+```
+
+The methods that return a Big number can be chained.
+
+```javascript
+x.div(y).plus(z).times(9).minus('1.234567801234567e+8').plus(976.54321).div('2598.11772')
+x.sqrt().div(y).pow(3).gt(y.mod(z))    // true
+```
+
+Like JavaScript's Number type, there are `toExponential`, `toFixed` and `toPrecision` methods.
+
+```javascript
+x = new Big(255.5)
+x.toExponential(5)                     // "2.55500e+2"
+x.toFixed(5)                           // "255.50000"
+x.toPrecision(5)                       // "255.50"
+```
+
+The arithmetic methods always return the exact result except `div`, `sqrt` and `pow`
+(with negative exponent), as these methods involve division.
+
+The maximum number of decimal places and the rounding mode used to round the results of these methods is determined by the value of the `DP` and `RM` properties of the `Big` number constructor.
+
+```javascript
+Big.DP = 10
+Big.RM = Big.roundHalfUp
+
+x = new Big(2);
+y = new Big(3);
+z = x.div(y)                           // "0.6666666667"
+z.sqrt()                               // "0.8164965809"
+z.pow(-3)                              // "3.3749999995"
+z.times(z)                             // "0.44444444448888888889"
+z.times(z).round(10)                   // "0.4444444445"
+```
+
+The value of a Big number is stored in a decimal floating point format in terms of a coefficient, exponent and sign.
+
+```javascript
+x = new Big(-123.456);
+x.c                                    // [1,2,3,4,5,6]    coefficient (i.e. significand)
+x.e                                    // 2                exponent
+x.s                                    // -1               sign
+```
+
+For advanced usage, multiple Big number constructors can be created, each with an independent configuration.
+
+## 🧠 Minify
+
+To minify using, for example, npm and [terser](https://github.com/terser/terser)
+
+```bash
+$ npm install -g terser
+```
+
+```bash
+$ terser big.js -c -m -o big.min.js
+```
+
+## 🧪 Test 
+
+The *test* directory contains the test scripts for each Big number method.
+
+The tests can be run with Node.js or a browser.
+
+Run all the tests:
+
+```bash
+$ npm test
+```
+
+Test a single method:
+
+```bash
+$ node test/toFixed
+```
+
+For the browser, see *runner.html* and *test.html* in the *test/browser* directory.
+
+*big-vs-number.html* is a old application that enables some of the methods of bigmathutils to be compared with those of JavaScript's Number type.
+
+## 📝 TypeScript
+
+The [DefinitelyTyped](https://github.com/borisyankov/DefinitelyTyped) project has a Typescript type definitions file for bigmathutils.
+
+```bash
+$ npm install --save-dev @types/bigmathutils
+```
+
+Any questions about the TypeScript type definitions file should be addressed to the DefinitelyTyped project.
+
+## 📄 Licence
+
+[MIT](LICENCE.md)