big.esm 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,18 @@
1
+ ## [1.0.1](https://github.com/dschewchenko/big.esm/compare/v1.0.0...v1.0.1) (2023-05-13)
2
+
3
+
4
+ ### Bug Fixes
5
+
6
+ * rename due to npm 403 ([d54d499](https://github.com/dschewchenko/big.esm/commit/d54d499e1757530a3563fe859c2cffcb8c4fe4de))
7
+
8
+ # 1.0.0 (2023-05-13)
9
+
10
+
11
+ ### Bug Fixes
12
+
13
+ * readme, description, workflows ([b3f6c22](https://github.com/dschewchenko/big.es/commit/b3f6c22119c37a11d4b805479c4916c4eb480b92))
14
+
15
+
16
+ ### Features
17
+
18
+ * Initial release ([b8433ca](https://github.com/dschewchenko/big.es/commit/b8433ca2f5a1193da7d4ae93041449d803ccf7b1))
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2023 Dmytro Shevchenko
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,135 @@
1
+ # big.esm
2
+
3
+ Library for working with large numbers and fractions using `BigInt`.
4
+ It provides advanced functionality for performing arithmetic operations with precision and decimal handling.
5
+
6
+ 100% test coverage.
7
+
8
+ No dependencies.
9
+
10
+ No limitations on the size of the numbers, except for the limitations of `BigInt`, so limited by system memory =).
11
+
12
+ Fully written in TypeScript, so it provides type definitions out of the box.
13
+
14
+ Tree-shaking is supported.
15
+
16
+ Full bundle size(ES) — 5.48 kB minified and 1.98 kB gzipped.
17
+ `sqrtBig` and `powBig` are half of this size.
18
+
19
+ Full bundle size(UMD) — 3.52 kB minified and 1.58 kB gzipped.
20
+
21
+ ## Installation
22
+
23
+ Install `big.esm` using npm:
24
+
25
+ ```bash
26
+ npm install big.esm
27
+ ```
28
+
29
+ ## Usage
30
+
31
+ ```js
32
+ import { createBig, addBig } from 'big.esm';
33
+
34
+ const a = createBig("12345678910.12345678910"); // or new Big("12345678910.12345678910")
35
+ const b = createBig("9876543210.9876543210");
36
+ const result = addBig(a, b);
37
+ console.log(result.toString()); // 22222222121.1111111101
38
+ ```
39
+
40
+ ## Compatibility
41
+
42
+ `big.esm` is compatible with all modern browsers and Node.js 10+. It uses `BigInt` internally, so it is not compatible with older browsers and Node.js versions. On info from [caniuse.com](https://caniuse.com/#feat=bigint) `BigInt` is supported by 95.25% of all browsers(as of 2023-05-12).
43
+
44
+ ## Notes
45
+
46
+ - `big.esm` is not a drop-in replacement for `big.js`. It does not support the same API and does not have the same functionality. It is a completely different library.
47
+ - `powBig()` and `sqrtBig()` are heavy and slow operations. They are implemented using the Newton's method and exponentiation by squaring algorithms. Use them with caution, especially with large numbers. In most cases, there will be no problems.
48
+
49
+ ## API
50
+
51
+ More information in the [documentation](https://dschewchenko.github.io/big.esm/).
52
+
53
+ ### Core
54
+
55
+ #### `new Big(value: BigValue, scale?: number | string): Big`
56
+
57
+ Creates a new `Big` instance from a string, number or `BigInt`. Optionally, you can specify the scale of the number. The scale is the number of digits to the right of the decimal point. If the scale is not specified, it will be calculated automatically, otherwise the number will be rounded to integer.
58
+
59
+ ### Utilities
60
+
61
+ #### `createBig(value: string | number | bigint): Big`
62
+
63
+ Alias for `new Big(value)`.
64
+ But it does not support the scale parameter and if the value is instance of `Big` it will be returned without changes.
65
+
66
+ ```js
67
+ const a = createBig("12345678910.12345678910"); // value = 1234567891012345678910 ,scale = 11
68
+ const b = createBig(12345678910.12345678910); // value = 1234567891012345678910 ,scale = 11
69
+ const c = createBig(1234567891012345678910n); // value = 1234567891012345678910 ,scale = 0
70
+ ```
71
+
72
+ ### `cloneBig(a: Big): Big`
73
+
74
+ Creates a new `Big` instance from another `Big` instance.
75
+
76
+ ```js
77
+ const a = createBig("12345678910.12345678910");
78
+ const b = cloneBig(a);
79
+ ```
80
+
81
+ ### `alignScale(a: Big, b: Big): [Big, Big]`
82
+
83
+ Aligns the scale of two `Big` instances. The scale of the result will be equal to the maximum scale of the two numbers.
84
+
85
+ ### `isNumericValue(value: any): boolean`
86
+
87
+ Checks if the value is a valid numeric value for creating a `Big` instance.
88
+
89
+ ### Mathematical operations
90
+
91
+ #### `addBig(a: Big, b: Big): Big`
92
+
93
+ Adds two `Big` instances.
94
+
95
+ #### `subBig(a: Big, b: Big): Big`
96
+
97
+ Subtracts two `Big` instances.
98
+
99
+ #### `mulBig(a: Big, b: Big): Big`
100
+
101
+ Multiplies two `Big` instances.
102
+
103
+ #### `divBig(a: Big, b: Big): Big`
104
+
105
+ Divides two `Big` instances.
106
+
107
+ #### `modBig(a: Big, b: Big): Big`
108
+
109
+ Calculates the remainder of dividing two `Big` instances.
110
+
111
+ #### `powBig(a: Big, b: Big): Big`
112
+
113
+ Raises `a` to the power of `b`.
114
+
115
+ #### `sqrtBig(a: Big): Big`
116
+
117
+ Calculates the square root of `a`.
118
+
119
+ #### `absBig(a: Big): Big`
120
+
121
+ Returns the absolute value of `a`.
122
+
123
+ ## Roadmap
124
+
125
+ - [x] Generate documentation from JSDoc
126
+ - [ ] Add formatting options and remove trailing zeros from toString method
127
+ - [ ] Add more mathematical functions
128
+
129
+ ## License
130
+
131
+ MIT
132
+
133
+ ## Copyright
134
+
135
+ © 2023 dschewchenko
package/dist/big.d.ts ADDED
@@ -0,0 +1,69 @@
1
+ import type { PossibleNumber } from "./types";
2
+ /**
3
+ * The Big class for working with large numbers and fractions using BigInt.
4
+ *
5
+ * @category Core
6
+ *
7
+ * @example
8
+ * const big1 = new Big(123.456);
9
+ * console.log(big1.toString()); // 123.456
10
+ * const big2 = new Big("123.456");
11
+ * console.log(big2.toString()); // 123.456
12
+ * const big3 = new Big(123456n, 2);
13
+ * console.log(big3.toString()); // 1234.56
14
+ * const big4 = new Big(123.456, 2);
15
+ * console.log(big4.toString()); // 1.23, because the scale is 2 and it removes the fractional part
16
+ */
17
+ export declare class Big {
18
+ /**
19
+ * The value of the Big instance.
20
+ */
21
+ readonly value: bigint;
22
+ /**
23
+ * The scale of the Big instance, representing the number of decimal places.
24
+ */
25
+ readonly scale: number;
26
+ /**
27
+ * Creates a new Big instance.
28
+ *
29
+ * @param {Big} value - The value to create the Big instance from.
30
+ * @throws {TypeError} - If the value is not a number, string, BigInt, or Big instance.
31
+ * @return {Big} - A new Big instance.
32
+ */
33
+ constructor(value: Big);
34
+ /**
35
+ * Creates a new Big instance.
36
+ *
37
+ * @param {PossibleNumber} value - The value to create the Big instance from. It Can be a number, string, or BigInt.
38
+ * @throws {TypeError} - If the value is not a number, string, BigInt, or Big instance.
39
+ * @return {Big} - A new Big instance.
40
+ */
41
+ constructor(value: PossibleNumber);
42
+ /**
43
+ * Creates a new Big instance.
44
+ *
45
+ * @param {PossibleNumber} value - The value to create the Big instance from. Can be a number, string, or BigInt.
46
+ * @param {number | string | undefined} [scale] - The scale for the value (optional), representing the number of decimal places. If scale provided and value has a fractional part, the fractional part will be removed.
47
+ * @throws {TypeError} - If the value is not a number, string, BigInt, or Big instance.
48
+ * @return {Big} - A new Big instance.
49
+ */
50
+ constructor(value: PossibleNumber, scale: number | string | undefined);
51
+ /**
52
+ * Returns the primitive value of the Big instance.
53
+ *
54
+ * @returns {bigint} The primitive value of the Big instance.
55
+ */
56
+ valueOf(): bigint;
57
+ /**
58
+ * Returns a string representation of the Big instance.
59
+ *
60
+ * @return {string} - A string representation of the Big instance.
61
+ */
62
+ toString(): string;
63
+ /**
64
+ * Returns the JSON representation of the Big instance.
65
+ *
66
+ * @returns {string} The JSON representation of the Big instance. It is the same as the string representation, because JSON does not support BigInt.
67
+ */
68
+ toJSON(): string;
69
+ }
@@ -0,0 +1,175 @@
1
+ var y = Object.defineProperty;
2
+ var T = (e, t, n) => t in e ? y(e, t, { enumerable: !0, configurable: !0, writable: !0, value: n }) : e[t] = n;
3
+ var v = (e, t, n) => (T(e, typeof t != "symbol" ? t + "" : t, n), n);
4
+ function D(e) {
5
+ return typeof e == "bigint" || typeof e == "number" || typeof e == "string" && !isNaN(Number(e));
6
+ }
7
+ const p = 20, g = BigInt(0);
8
+ class f {
9
+ /**
10
+ * Implements the overloaded constructors for the Big class.
11
+ * @param {BigValue} value - The value to create the Big instance from. Can be a number, string, BigInt, or another Big instance.
12
+ * @param {number | string | undefined} [scale] - The scale for the value (optional), representing the number of decimal places. If scale provided and value has a fractional part, the fractional part will be removed.
13
+ * @throws {TypeError} - If the value is not a number, string, BigInt, or Big instance.
14
+ * @return {Big} - A new Big instance.
15
+ */
16
+ constructor(t, n) {
17
+ /**
18
+ * The value of the Big instance.
19
+ */
20
+ v(this, "value");
21
+ /**
22
+ * The scale of the Big instance, representing the number of decimal places.
23
+ */
24
+ v(this, "scale");
25
+ if (t instanceof f)
26
+ this.value = t.value, this.scale = t.scale;
27
+ else if (D(t)) {
28
+ let [r, i = ""] = t.toString().split(".");
29
+ n !== void 0 && (typeof n != "number" && (n = Number(n)), n = Math.floor(n), i && (i = ""), r.length < n && (r = r.padEnd(n, "0"))), this.value = BigInt(r + i), this.scale = i ? i.length : n ?? 0;
30
+ } else
31
+ throw new TypeError("Invalid type provided to Big constructor.");
32
+ return this;
33
+ }
34
+ /**
35
+ * Returns the primitive value of the Big instance.
36
+ *
37
+ * @returns {bigint} The primitive value of the Big instance.
38
+ */
39
+ valueOf() {
40
+ return this.value;
41
+ }
42
+ /**
43
+ * Returns a string representation of the Big instance.
44
+ *
45
+ * @return {string} - A string representation of the Big instance.
46
+ */
47
+ toString() {
48
+ let t = this.value.toString();
49
+ const n = t.startsWith("-") ? "-" : "";
50
+ n && (t = t.substring(1));
51
+ let r = "";
52
+ if (this.scale > g) {
53
+ const i = t.length > this.scale ? t.length - Number(this.scale) : 0;
54
+ r = t.slice(i).padStart(Number(this.scale), "0"), r.length > 0 && (r = `.${r}`), t = t.slice(0, i);
55
+ }
56
+ return `${n}${t || "0"}${r}`;
57
+ }
58
+ /**
59
+ * Returns the JSON representation of the Big instance.
60
+ *
61
+ * @returns {string} The JSON representation of the Big instance. It is the same as the string representation, because JSON does not support BigInt.
62
+ */
63
+ toJSON() {
64
+ return this.toString();
65
+ }
66
+ }
67
+ function o(e, t) {
68
+ return e instanceof f ? e : new f(e, t);
69
+ }
70
+ function m(e, t) {
71
+ const n = e.scale - t.scale;
72
+ if (n > 0) {
73
+ const r = t.value * BigInt(10 ** n);
74
+ return [e, o(r, e.scale)];
75
+ }
76
+ if (n < 0) {
77
+ const r = e.value * BigInt(10 ** -n);
78
+ return [o(r, t.scale), t];
79
+ }
80
+ return [e, t];
81
+ }
82
+ function S(e, t) {
83
+ const [n, r] = m(e, t), i = n.value + r.value;
84
+ return o(i, n.scale);
85
+ }
86
+ function N(e, t) {
87
+ const [n, r] = m(e, t), i = n.value - r.value;
88
+ return o(i, n.scale);
89
+ }
90
+ function w(e, t) {
91
+ const n = e.value * t.value, r = e.scale + t.scale;
92
+ return o(n, r);
93
+ }
94
+ function d(e) {
95
+ return e.value === g;
96
+ }
97
+ function c(e, t, n = p, r = "half-up") {
98
+ if (d(t))
99
+ throw new Error("Division by zero is not allowed.");
100
+ const i = Math.max(e.scale, t.scale), h = Math.max(0, n), B = e.value * BigInt(10) ** BigInt(i + h - e.scale), u = t.value * BigInt(10) ** BigInt(i - t.scale), a = B / u, l = B % u;
101
+ let s;
102
+ switch (r) {
103
+ case "down":
104
+ s = a;
105
+ break;
106
+ case "up":
107
+ s = l !== g ? a + BigInt(1) : a + g;
108
+ break;
109
+ case "half-up":
110
+ default:
111
+ s = l * BigInt(2) >= u ? a + BigInt(1) : a;
112
+ break;
113
+ }
114
+ return o(s.toString(), h);
115
+ }
116
+ function V(e, t) {
117
+ if (d(t))
118
+ throw new Error("Division by zero is not allowed.");
119
+ const n = c(e, t, 0, "down"), r = w(n, t);
120
+ return N(e, r);
121
+ }
122
+ function M(e, t) {
123
+ if (!Number.isInteger(t) || t < 0)
124
+ throw new Error("The exponent must be a non-negative integer.");
125
+ let n = o(1), r = o(e);
126
+ for (t = Math.abs(t); t > 0; )
127
+ t % 2 === 1 && (n = w(n, r)), r = w(r, r), t = Math.floor(t / 2);
128
+ return n;
129
+ }
130
+ const O = (e, t) => {
131
+ const [n, r] = m(e, t);
132
+ return n.value > r.value ? 1 : n.value < r.value ? -1 : 0;
133
+ };
134
+ function A(e) {
135
+ const t = e.value < BigInt(0) ? -e.value : e.value;
136
+ return o(t, e.scale);
137
+ }
138
+ function $(e, t = 2, n = p) {
139
+ if (d(e))
140
+ return o(0);
141
+ if (e.valueOf() === BigInt(1))
142
+ return o(1);
143
+ if (e.value < g && t % 2 === 0)
144
+ throw new Error("The root must be an odd integer when the number is negative.");
145
+ if (!Number.isInteger(t) || t < 2)
146
+ throw new Error("The root must be an integer and greater than 1");
147
+ if (n < 0)
148
+ throw new Error("The precision must be a non-negative integer.");
149
+ const r = n === 0 ? "1" : "0." + "0".repeat(n - 1) + "1", i = o(r), h = o(t), B = o(t - 1), u = o(2);
150
+ let a = c(S(e, c(e, u, n)), u, n), l;
151
+ do {
152
+ l = a;
153
+ const b = S(w(B, a), c(e, M(a, t - 1), n));
154
+ a = c(b, h, n);
155
+ } while (O(A(N(l, a)), i) === 1);
156
+ const s = a.toString(), I = s.indexOf("."), E = I !== -1 ? s.slice(0, I + n + 1) : s;
157
+ return o(E);
158
+ }
159
+ const k = (e) => new f(e.value, e.scale);
160
+ export {
161
+ f as Big,
162
+ A as absBig,
163
+ S as addBig,
164
+ m as alignScale,
165
+ k as cloneBig,
166
+ O as compareBig,
167
+ o as createBig,
168
+ c as divBig,
169
+ D as isNumericValue,
170
+ V as modBig,
171
+ w as mulBig,
172
+ M as powBig,
173
+ $ as sqrtBig,
174
+ N as subBig
175
+ };
@@ -0,0 +1 @@
1
+ (function(r,a){typeof exports=="object"&&typeof module<"u"?a(exports):typeof define=="function"&&define.amd?define(["exports"],a):(r=typeof globalThis<"u"?globalThis:r||self,a((r.big=r.big||{},r.big.esm={})))})(this,function(r){"use strict";var j=Object.defineProperty;var q=(r,a,l)=>a in r?j(r,a,{enumerable:!0,configurable:!0,writable:!0,value:l}):r[a]=l;var y=(r,a,l)=>(q(r,typeof a!="symbol"?a+"":a,l),l);function a(e){return typeof e=="bigint"||typeof e=="number"||typeof e=="string"&&!isNaN(Number(e))}const l=20,B=BigInt(0);class g{constructor(t,n){y(this,"value");y(this,"scale");if(t instanceof g)this.value=t.value,this.scale=t.scale;else if(a(t)){let[i,u=""]=t.toString().split(".");n!==void 0&&(typeof n!="number"&&(n=Number(n)),n=Math.floor(n),u&&(u=""),i.length<n&&(i=i.padEnd(n,"0"))),this.value=BigInt(i+u),this.scale=u?u.length:n??0}else throw new TypeError("Invalid type provided to Big constructor.");return this}valueOf(){return this.value}toString(){let t=this.value.toString();const n=t.startsWith("-")?"-":"";n&&(t=t.substring(1));let i="";if(this.scale>B){const u=t.length>this.scale?t.length-Number(this.scale):0;i=t.slice(u).padStart(Number(this.scale),"0"),i.length>0&&(i=`.${i}`),t=t.slice(0,u)}return`${n}${t||"0"}${i}`}toJSON(){return this.toString()}}function o(e,t){return e instanceof g?e:new g(e,t)}function v(e,t){const n=e.scale-t.scale;if(n>0){const i=t.value*BigInt(10**n);return[e,o(i,e.scale)]}if(n<0){const i=e.value*BigInt(10**-n);return[o(i,t.scale),t]}return[e,t]}function S(e,t){const[n,i]=v(e,t),u=n.value+i.value;return o(u,n.scale)}function b(e,t){const[n,i]=v(e,t),u=n.value-i.value;return o(u,n.scale)}function d(e,t){const n=e.value*t.value,i=e.scale+t.scale;return o(n,i)}function N(e){return e.value===B}function f(e,t,n=l,i="half-up"){if(N(t))throw new Error("Division by zero is not allowed.");const u=Math.max(e.scale,t.scale),w=Math.max(0,n),I=e.value*BigInt(10)**BigInt(u+w-e.scale),h=t.value*BigInt(10)**BigInt(u-t.scale),s=I/h,m=I%h;let c;switch(i){case"down":c=s;break;case"up":c=m!==B?s+BigInt(1):s+B;break;case"half-up":default:c=m*BigInt(2)>=h?s+BigInt(1):s;break}return o(c.toString(),w)}function O(e,t){if(N(t))throw new Error("Division by zero is not allowed.");const n=f(e,t,0,"down"),i=d(n,t);return b(e,i)}function E(e,t){if(!Number.isInteger(t)||t<0)throw new Error("The exponent must be a non-negative integer.");let n=o(1),i=o(e);for(t=Math.abs(t);t>0;)t%2===1&&(n=d(n,i)),i=d(i,i),t=Math.floor(t/2);return n}const T=(e,t)=>{const[n,i]=v(e,t);return n.value>i.value?1:n.value<i.value?-1:0};function p(e){const t=e.value<BigInt(0)?-e.value:e.value;return o(t,e.scale)}function D(e,t=2,n=l){if(N(e))return o(0);if(e.valueOf()===BigInt(1))return o(1);if(e.value<B&&t%2===0)throw new Error("The root must be an odd integer when the number is negative.");if(!Number.isInteger(t)||t<2)throw new Error("The root must be an integer and greater than 1");if(n<0)throw new Error("The precision must be a non-negative integer.");const i=n===0?"1":"0."+"0".repeat(n-1)+"1",u=o(i),w=o(t),I=o(t-1),h=o(2);let s=f(S(e,f(e,h,n)),h,n),m;do{m=s;const V=S(d(I,s),f(e,E(s,t-1),n));s=f(V,w,n)}while(T(p(b(m,s)),u)===1);const c=s.toString(),M=c.indexOf("."),A=M!==-1?c.slice(0,M+n+1):c;return o(A)}const P=e=>new g(e.value,e.scale);r.Big=g,r.absBig=p,r.addBig=S,r.alignScale=v,r.cloneBig=P,r.compareBig=T,r.createBig=o,r.divBig=f,r.isNumericValue=a,r.modBig=O,r.mulBig=d,r.powBig=E,r.sqrtBig=D,r.subBig=b,Object.defineProperty(r,Symbol.toStringTag,{value:"Module"})});
@@ -0,0 +1,15 @@
1
+ export { Big } from "./big";
2
+ export type { BigValue, PossibleNumber, RoundingMode, CompareResult } from "./types";
3
+ export { addBig } from "./operations/add";
4
+ export { subBig } from "./operations/sub";
5
+ export { mulBig } from "./operations/mul";
6
+ export { divBig } from "./operations/div";
7
+ export { modBig } from "./operations/mod";
8
+ export { powBig } from "./operations/pow";
9
+ export { sqrtBig } from "./operations/sqrt";
10
+ export { absBig } from "./operations/abs";
11
+ export { compareBig } from "./operations/compare";
12
+ export { isNumericValue } from "./utils/numeric";
13
+ export { alignScale } from "./utils/align-scale";
14
+ export { createBig } from "./utils/create.ts";
15
+ export { cloneBig } from "./utils/clone.ts";
@@ -0,0 +1,15 @@
1
+ import type { Big } from "../big";
2
+ /**
3
+ * Returns the absolute value of a Big instance.
4
+ *
5
+ * @param {Big} big - The Big instance.
6
+ * @returns {Big} The absolute value of the Big instance.
7
+ *
8
+ * @category Operations
9
+ *
10
+ * @example
11
+ * absBig(new Big(-1)); // new Big instance with value 1
12
+ * absBig(new Big(-1.1)); // new Big instance with value 1.1
13
+ * absBig(new Big(1)); // new Big instance with value 1
14
+ */
15
+ export declare function absBig(big: Big): Big;
@@ -0,0 +1,16 @@
1
+ import type { Big } from "../big";
2
+ /**
3
+ * Adds two big values.
4
+ *
5
+ * @param {Big} a - The first value to add.
6
+ * @param {Big} b - The second value to add.
7
+ * @returns {Big} The sum of the two values.
8
+ *
9
+ * @category Operations
10
+ *
11
+ * @example
12
+ * addBig(new Big(1), new Big(2)); // new Big instance with value 3
13
+ * addBig(new Big(1.1), new Big(2.2)); // new Big instance with value 3.3
14
+ * addBig(new Big(1.1), new Big(2)); // new Big instance with value 3.1
15
+ */
16
+ export declare function addBig(a: Big, b: Big): Big;
@@ -0,0 +1,17 @@
1
+ import type { Big } from "../big";
2
+ import type { CompareResult } from "../types.ts";
3
+ /**
4
+ * Compares two Big numbers and returns a CompareResult indicating the relation between them.
5
+ *
6
+ * @param {Big} a - The first Big number to compare.
7
+ * @param {Big} b - The second Big number to compare.
8
+ * @returns {CompareResult} - 1 if a > b, -1 if a < b, or 0 if a == b.
9
+ *
10
+ * @category Operations
11
+ *
12
+ * @example
13
+ * compareBig(new Big(1), new Big(2)); // -1
14
+ * compareBig(new Big(2), new Big(1)); // 1
15
+ * compareBig(new Big(1), new Big(1)); // 0
16
+ */
17
+ export declare const compareBig: (a: Big, b: Big) => CompareResult;
@@ -0,0 +1,24 @@
1
+ import type { RoundingMode } from "../types";
2
+ import type { Big } from "../big";
3
+ /**
4
+ * Divides two Big instances and returns the result as a new Big instance.
5
+ *
6
+ * @param {Big} dividend - The dividend Big instance.
7
+ * @param {Big} divisor - The divisor Big instance.
8
+ * @param {number} [precision] - The number of decimal places to keep in the result (optional). Defaults to the maximum scale of both Big instances. If the precision is lower than the scale of the result, the result will be rounded. If input numbers are without scale, the precision will be 0, so the result will be rounded to an integer.
9
+ * @param {string} [roundingMode="half-up"] - The rounding mode to apply ("half-up", "down" or "up"). Defaults to "half-up".
10
+ * @returns {Big} - A new Big instance representing the result of the division.
11
+ * @throws {Error} Division by zero is not allowed.
12
+ *
13
+ * @category Operations
14
+ *
15
+ * @example
16
+ * const big1 = new Big(10);
17
+ * const big2 = new Big(3);
18
+ * console.log(divBig(big1, big2).toString()); // "3.33333333333333333333"
19
+ * console.log(divBig(big1, big2, 0).toString()); // "3"
20
+ * console.log(divBig(big1, big2, 2).toString()); // "3.33"
21
+ * console.log(divBig(big1, big2, 2, "down").toString()); // "3.33"
22
+ * console.log(divBig(big1, big2, 2, "up").toString()); // "3.34"
23
+ */
24
+ export declare function divBig(dividend: Big, divisor: Big, precision?: number, roundingMode?: RoundingMode): Big;
@@ -0,0 +1,19 @@
1
+ import type { Big } from "../big";
2
+ /**
3
+ * Performs the modulo operation (remainder of division) for two Big instances.
4
+ *
5
+ * @param dividend The Big instance representing the dividend.
6
+ * @param divisor The Big instance representing the divisor.
7
+ * @returns A new Big instance representing the remainder of the division.
8
+ * @throws {Error} Division by zero is not allowed.
9
+ *
10
+ * @category Operations
11
+ *
12
+ * @example
13
+ * const big1 = new Big(10);
14
+ * const big2 = new Big(3);
15
+ * console.log(modBig(big1, big2).toString()); // "1"
16
+ * console.log(modBig(big2, big1).toString()); // "3"
17
+ * console.log(modBig(big1, big1).toString()); // "0"
18
+ */
19
+ export declare function modBig(dividend: Big, divisor: Big): Big;
@@ -0,0 +1,16 @@
1
+ import type { Big } from "../big";
2
+ /**
3
+ * Multiplies two Big instances and returns the result as a new Big instance.
4
+ *
5
+ * @param {Big} a - The first Big instance.
6
+ * @param {Big} b - The second Big instance.
7
+ * @returns {Big} The result of the multiplication.
8
+ *
9
+ * @category Operations
10
+ *
11
+ * @example
12
+ * mulBig(new Big(1), new Big(2)); // new Big instance with value 2
13
+ * mulBig(new Big(1.1), new Big(2.2)); // new Big instance with value 2.42
14
+ * mulBig(new Big(1.1), new Big(2)); // new Big instance with value 2.2
15
+ */
16
+ export declare function mulBig(a: Big, b: Big): Big;
@@ -0,0 +1,19 @@
1
+ import type { Big } from "../big";
2
+ /**
3
+ * Raises a Big number to the power of another Big number.
4
+ *
5
+ * @param {Big} big - The base Big number.
6
+ * @param {number} exp - The exponent (non-negative integer).
7
+ * @returns {Big} - The result of a raised to the power of b.
8
+ * @throws {Error} - If the exponent is not a non-negative integer.
9
+ *
10
+ * @category Operations
11
+ *
12
+ * @example
13
+ * powBig(new Big(2), 0); // new Big instance with value 1
14
+ * powBig(new Big(2), 1); // new Big instance with value 2
15
+ * powBig(new Big(2), 3); // new Big instance with value 8
16
+ * powBig(new Big(2), 3.3); // throws Error
17
+ * powBig(new Big(2), -3); // throws Error
18
+ */
19
+ export declare function powBig(big: Big, exp: number): Big;
@@ -0,0 +1,27 @@
1
+ import type { Big } from "../big";
2
+ /**
3
+ * Calculates the nth root of a Big instance with custom precision and rounding mode.
4
+ *
5
+ * Note: it's the most weighted function in the library. It's reusing a lot of other functions, and it's not perfect in performance, recommended to use it only when you need it and with default precision and rounding mode. It uses the Newton's method to calculate the root.
6
+ *
7
+ * @param {Big} big - The Big instance.
8
+ * @param {number} root - The root to calculate. Must be an integer. Defaults to 2.
9
+ * @param {number} precision - The number of decimal places to keep in the result (optional). Defaults to 20.
10
+ * @returns {Big} The nth root of the Big instance with the specified precision and rounding mode.
11
+ * @throws {Error} - If the root is not an integer.
12
+ *
13
+ * @category Operations
14
+ *
15
+ * @example
16
+ * const big1 = new Big(16);
17
+ * console.log(sqrtBig(big1).toString()); // 4.00000000000000000000
18
+ * console.log(sqrtBig(big1, 4, 0).toString()); // 2
19
+ * console.log(sqrtBig(big1, 4, 1).toString()); // 2.0
20
+ * console.log(sqrtBig(Big(0), 4).toString()); // 0
21
+ * console.log(sqrtBig(Big(1), 4).toString()); // 1
22
+ * console.log(sqrtBig(Big(-1), 4).toString()); // throws Error
23
+ * console.log(sqrtBig(Big(16), 0.5).toString()); // throws Error
24
+ * console.log(sqrtBig(Big(16), -2).toString()); // throws Error
25
+ * console.log(sqrtBig(Big(16), 4, -1).toString()); // throws Error
26
+ */
27
+ export declare function sqrtBig(big: Big, root?: number, precision?: number): Big;
@@ -0,0 +1,15 @@
1
+ import type { Big } from "../big";
2
+ /**
3
+ * Subtracts two big values and returns the result as a new Big instance.
4
+ *
5
+ * @param {Big} a - The first Big instance.
6
+ * @param {Big} b - The second Big instance.
7
+ * @returns {Big} The result of the subtraction.
8
+ *
9
+ * @category Operations
10
+ *
11
+ * @example
12
+ * subBig(new Big(1), new Big(2)); // new Big instance with value -1
13
+ * subBig(new Big(1.1), new Big(2.2)); // new Big instance with value -1.1
14
+ */
15
+ export declare function subBig(a: Big, b: Big): Big;
@@ -0,0 +1,25 @@
1
+ import type { Big } from "./big";
2
+ /**
3
+ * Possible number types for processing.
4
+ *
5
+ * @category Types
6
+ */
7
+ export type PossibleNumber = number | string | bigint;
8
+ /**
9
+ * Possible value types for the Big class.
10
+ *
11
+ * @category Types
12
+ */
13
+ export type BigValue = PossibleNumber | Big;
14
+ /**
15
+ * The rounding mode for division operations.
16
+ *
17
+ * @category Types
18
+ */
19
+ export type RoundingMode = "half-up" | "down" | "up";
20
+ /**
21
+ * The comparison result for two Big instances.
22
+ *
23
+ * @category Types
24
+ */
25
+ export type CompareResult = -1 | 0 | 1;
@@ -0,0 +1,23 @@
1
+ import type { Big } from "../big";
2
+ /**
3
+ * Aligns the scale(decimal places) of two Big instances before performing arithmetic operations.
4
+ * It takes two Big instances as input and returns a tuple (array) of two new Big instances with the same scale.
5
+ *
6
+ * When the scales of the two input instances are different, the function adjusts the value and scale of one of the instances so that their scales are equal, allowing the arithmetic operations to be performed correctly.
7
+ *
8
+ * Note: This function does not modify the input instances. It creates new instances with the aligned scales.
9
+ *
10
+ * @param {Big} a - The first Big instance.
11
+ * @param {Big} b - The second Big instance.
12
+ * @returns {[Big, Big]} A tuple of two Big instances with the same scale.
13
+ *
14
+ * @category Utilities
15
+ *
16
+ * @example
17
+ * const a = new Big(123.456);
18
+ * const b = new Big(123.456789);
19
+ * const [x, y] = alignScale(a, b);
20
+ * console.log(x.toString()); // "123.456000"
21
+ * console.log(y.toString()); // "123.456789"
22
+ */
23
+ export declare function alignScale(a: Big, b: Big): [Big, Big];
@@ -0,0 +1,12 @@
1
+ import { Big } from "../big.ts";
2
+ /**
3
+ * Clone a Big instance
4
+ * @param {Big} big - The Big instance to clone.
5
+ * @returns {Big} - The cloned Big instance.
6
+ *
7
+ * @category Utilities
8
+ *
9
+ * @example
10
+ * cloneBig(new Big(123.456)); // new Big instance with the same value and scale as the original
11
+ */
12
+ export declare const cloneBig: (big: Big) => Big;
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Default precision for operations, such as division, square root, etc.
3
+ *
4
+ * @category Constants
5
+ */
6
+ export declare const DEFAULT_PRECISION = 20;
7
+ /**
8
+ * Zero as a BigInt.
9
+ *
10
+ * @category Constants
11
+ */
12
+ export declare const ZERO_BIGINT: bigint;
@@ -0,0 +1,35 @@
1
+ import { Big } from "../big.ts";
2
+ import type { PossibleNumber } from "../types.ts";
3
+ /**
4
+ * Creates a new Big instance from the given value.
5
+ * If the value is already a Big instance, it returns the value itself.
6
+ * Use this function instead of the Big constructor to create a Big instance from a value.
7
+ *
8
+ * @param {Big} value - The value to create the Big instance from.
9
+ * @return {Big} - A new Big instance.
10
+ */
11
+ export declare function createBig(value: Big): Big;
12
+ /**
13
+ * Creates a new Big instance from the given value.
14
+ * If the value is already a Big instance, it returns the value itself.
15
+ * Use this function instead of the Big constructor to create a Big instance from a value.
16
+ *
17
+ * @param {PossibleNumber} value - The value to create the Big instance from. It Can be a number, string, or BigInt.
18
+ * @return {Big} - A new Big instance.
19
+ */
20
+ export declare function createBig(value: PossibleNumber): Big;
21
+ /**
22
+ * Creates a new Big instance from the given value.
23
+ * If the value is already a Big instance, it returns the value itself.
24
+ * Use this function instead of the Big constructor to create a Big instance from a value.
25
+ *
26
+ * @param {PossibleNumber} value - The value to create the Big instance from. Can be a number, string, or BigInt.
27
+ * @param {number | string | undefined} [scale] - The scale for the value (optional), representing the number of decimal places. If scale provided and value has a fractional part, the fractional part will be removed.
28
+ * @return {Big} - A new Big instance.
29
+ *
30
+ * @example
31
+ * const big1 = createBig(123.456); // 123.456
32
+ * const big2 = createBig("123.456"); // 123.456
33
+ * const big3 = createBig(123.456, 2); // 1.23, because the scale is 2 and it removes the fractional part
34
+ */
35
+ export declare function createBig(value: PossibleNumber, scale: number | string | undefined): Big;
@@ -0,0 +1,14 @@
1
+ import type { Big } from "../big";
2
+ /**
3
+ * Checks if a Big instance is zero.
4
+ *
5
+ * @param {Big} big - The Big instance to check.
6
+ * @returns {boolean} - Whether the Big instance is zero.
7
+ *
8
+ * @category Utilities
9
+ *
10
+ * @example
11
+ * isZero(new Big(0)); // true
12
+ * isZero(new Big(1)); // false
13
+ */
14
+ export declare function isZero(big: Big): boolean;
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Checks if a value is a numeric value (bigint, number, or string representation of a number).
3
+ * @param {any} value - The value to check.
4
+ * @returns {boolean} Returns true if the value is a numeric value, false otherwise.
5
+ *
6
+ * @category Utilities
7
+ *
8
+ * @example
9
+ * isNumericValue("12345678910.12345678910"); // true
10
+ * isNumericValue(12345678910.12345678910); // true
11
+ * isNumericValue(1234567891012345678910n); // true
12
+ * isNumericValue("123abc"); // false
13
+ */
14
+ export declare function isNumericValue(value: unknown): boolean;
package/package.json ADDED
@@ -0,0 +1,78 @@
1
+ {
2
+ "name": "big.esm",
3
+ "version": "1.0.1",
4
+ "description": "A small, fast JavaScript library for arbitrary-precision decimal arithmetic.",
5
+ "type": "module",
6
+ "scripts": {
7
+ "dev": "vite",
8
+ "build": "tsc && vite build",
9
+ "preview": "vite preview",
10
+ "test": "vitest",
11
+ "test:ui": "vitest --ui",
12
+ "test:run": "vitest run",
13
+ "coverage": "vitest run --coverage",
14
+ "docs": "typedoc --out docs src/index.ts",
15
+ "lint": "eslint --ext .ts,.js,.json ./src",
16
+ "lint:fix": "eslint --fix --ext .ts,.js,.json ./src",
17
+ "semantic-release": "semantic-release",
18
+ "prepare": "is-ci || husky install"
19
+ },
20
+ "main": "dist/big.esm.umd.cjs",
21
+ "module": "dist/big.esm.js",
22
+ "types": "dist/big.esm.ts",
23
+ "files": [
24
+ "dist/*",
25
+ "package.json",
26
+ "README.md",
27
+ "LICENSE",
28
+ "CHANGELOG.md"
29
+ ],
30
+ "repository": {
31
+ "type": "git",
32
+ "url": "https://github.com/dschewchenko/big.esm.git"
33
+ },
34
+ "keywords": [
35
+ "big",
36
+ "number",
37
+ "bigint",
38
+ "decimal",
39
+ "math",
40
+ "operations"
41
+ ],
42
+ "author": "dschewchenko",
43
+ "license": "MIT",
44
+ "bugs": {
45
+ "url": "https://github.com/dschewchenko/big.esm/issues"
46
+ },
47
+ "homepage": "https://github.com/dschewchenko/big.esm#readme",
48
+ "engines": {
49
+ "node": ">=16"
50
+ },
51
+ "devDependencies": {
52
+ "@commitlint/cli": "^17.6.3",
53
+ "@commitlint/config-conventional": "^17.6.3",
54
+ "@semantic-release/changelog": "^6.0.3",
55
+ "@semantic-release/git": "^10.0.1",
56
+ "@types/jest": "^29.5.1",
57
+ "@types/node": "^18.15.3",
58
+ "@typescript-eslint/eslint-plugin": "^5.59.5",
59
+ "@typescript-eslint/parser": "^5.59.5",
60
+ "@vitest/coverage-c8": "^0.31.0",
61
+ "@vitest/ui": "^0.31.0",
62
+ "eslint": "^8.40.0",
63
+ "eslint-config-prettier": "^8.8.0",
64
+ "eslint-plugin-prettier": "^4.2.1",
65
+ "husky": "^8.0.3",
66
+ "is-ci": "^3.0.1",
67
+ "prettier": "^2.8.8",
68
+ "rollup-plugin-visualizer": "^5.9.0",
69
+ "semantic-release": "^21.0.2",
70
+ "ts-jest": "^29.1.0",
71
+ "typedoc": "^0.24.7",
72
+ "typedoc-plugin-mdn-links": "^3.0.3",
73
+ "typescript": "^5.0.4",
74
+ "vite": "^4.3.5",
75
+ "vite-plugin-dts": "^2.3.0",
76
+ "vitest": "^0.31.0"
77
+ }
78
+ }