big.esm 1.3.1 → 2.0.0
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 +17 -0
- package/README.md +83 -43
- package/dist/big.d.ts +1 -1
- package/dist/big.esm.js +240 -151
- package/dist/big.esm.umd.cjs +1 -1
- package/dist/index.d.ts +22 -19
- package/dist/operations/abs.d.ts +3 -14
- package/dist/operations/add.d.ts +3 -15
- package/dist/operations/compare.d.ts +2 -2
- package/dist/operations/div.d.ts +5 -6
- package/dist/operations/max.d.ts +6 -8
- package/dist/operations/min.d.ts +6 -8
- package/dist/operations/mod.d.ts +3 -4
- package/dist/operations/mul.d.ts +3 -15
- package/dist/operations/pow.d.ts +3 -18
- package/dist/operations/sqrt.d.ts +3 -24
- package/dist/operations/sub.d.ts +3 -14
- package/dist/pipeline.d.ts +42 -0
- package/dist/types.d.ts +1 -1
- package/dist/utils/align-scale.d.ts +3 -6
- package/dist/utils/clone.d.ts +1 -1
- package/dist/utils/constants.d.ts +3 -3
- package/dist/utils/create.d.ts +6 -2
- package/dist/utils/from-string.d.ts +3 -3
- package/dist/utils/is-big-object.d.ts +2 -3
- package/dist/utils/is-zero.d.ts +1 -1
- package/dist/utils/pow10.d.ts +1 -0
- package/package.json +35 -39
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,20 @@
|
|
|
1
|
+
# [2.0.0](https://github.com/dschewchenko/big.esm/compare/v1.3.2...v2.0.0) (2025-12-18)
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
* feat!: big.esm v2 rewrite core ([#31](https://github.com/dschewchenko/big.esm/issues/31)) ([5d05e63](https://github.com/dschewchenko/big.esm/commit/5d05e63b425eaf07722859bd1ff354ec97aaad13))
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
### BREAKING CHANGES
|
|
8
|
+
|
|
9
|
+
* operations + alignScale now mutate inputs. Сlone with cloneBig for immutability.
|
|
10
|
+
|
|
11
|
+
## [1.3.2](https://github.com/dschewchenko/big.esm/compare/v1.3.1...v1.3.2) (2025-10-26)
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
### Bug Fixes
|
|
15
|
+
|
|
16
|
+
* migrate to bun and fix dependencies ([302f12b](https://github.com/dschewchenko/big.esm/commit/302f12bcf300a0f14f2af970c34b0251e1bbda81))
|
|
17
|
+
|
|
1
18
|
## [1.3.1](https://github.com/dschewchenko/big.esm/compare/v1.3.0...v1.3.1) (2023-06-25)
|
|
2
19
|
|
|
3
20
|
|
package/README.md
CHANGED
|
@@ -13,13 +13,16 @@ It provides advanced functionality for performing arithmetic operations with pre
|
|
|
13
13
|
- Fully written in TypeScript, so it provides type definitions out of the box.
|
|
14
14
|
- Tree-shaking is supported.
|
|
15
15
|
|
|
16
|
-
Full bundle size (ESM) — 4.2 kB minified and 1.8 kB gzipped.
|
|
17
|
-
`sqrtBig` operation is heavy (more than half of bundle), because it reuses most of the operations from `big.esm`.
|
|
18
|
-
|
|
19
16
|
## Installation
|
|
20
17
|
|
|
21
|
-
Install `big.esm` using
|
|
22
|
-
|
|
18
|
+
Install `big.esm` using Bun:
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
bun add big.esm
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
or npm:
|
|
25
|
+
|
|
23
26
|
```bash
|
|
24
27
|
npm install big.esm
|
|
25
28
|
```
|
|
@@ -33,22 +36,57 @@ yarn add big.esm
|
|
|
33
36
|
## Usage
|
|
34
37
|
|
|
35
38
|
```js
|
|
36
|
-
import {
|
|
39
|
+
import { addBig, cloneBig, createBig } from "big.esm";
|
|
37
40
|
|
|
38
|
-
const a = createBig("12345678910.12345678910");
|
|
41
|
+
const a = createBig("12345678910.12345678910");
|
|
39
42
|
const b = createBig("9876543210.9876543210");
|
|
40
|
-
|
|
41
|
-
|
|
43
|
+
|
|
44
|
+
addBig(a, b);
|
|
45
|
+
console.log(a.toString()); // 22222222121.1111111101
|
|
46
|
+
|
|
47
|
+
// If you need immutability, clone first:
|
|
48
|
+
const c = cloneBig(a);
|
|
49
|
+
addBig(c, b);
|
|
42
50
|
```
|
|
43
51
|
|
|
52
|
+
Pipeline (chainable, mutates its internal `Big`):
|
|
53
|
+
|
|
54
|
+
```js
|
|
55
|
+
import { pipeBig } from "big.esm";
|
|
56
|
+
|
|
57
|
+
console.log(
|
|
58
|
+
pipeBig("1.5e3").add(500).div(2, 0, "down").toString()
|
|
59
|
+
); // 1000
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## Benchmarks
|
|
63
|
+
|
|
64
|
+
More info - [BENCHMARK.md](https://github.com/dschewchenko/big.esm/blob/main/BENCHMARK.md)
|
|
65
|
+
|
|
66
|
+
- **Speed (ops)**: `big.esm v2` vs `big.js` — `26.26x faster` (median; min `2.17x`, max `154.43x`) → `2.26x faster` than `big.esm v1` (mutable mode; median `11.63x` vs `big.js`).
|
|
67
|
+
- **Speed (pipeBig)**: `pipeBig` vs `big.js` — `29.8x faster` (median; min `2.84x`, max `148.27x`).
|
|
68
|
+
- **Size (full)**: `big.esm v2` — `5.25 KB` minified / `1.87 KB` brotli (≈`1.30x` / `1.46x` smaller than `big.js`).
|
|
69
|
+
- **Size (pipe-only)**: `bigPipe (v2)` — `4.40 KB` minified / `1.62 KB` brotli (≈`1.55x` / `1.68x` smaller than `big.js`).
|
|
70
|
+
|
|
44
71
|
## Compatibility
|
|
45
72
|
|
|
46
|
-
`big.esm` is compatible with all modern browsers and Node.js
|
|
73
|
+
`big.esm` is compatible with all modern browsers, Bun 1.0+, and Node.js 16+. It uses `BigInt` internally, so it is not compatible with older runtimes. On info from [caniuse.com](https://caniuse.com/#feat=bigint) `BigInt` is supported by 98.84% of all browsers(as of 2025-12-18).
|
|
47
74
|
|
|
48
75
|
## Notes
|
|
49
76
|
|
|
50
77
|
- `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.
|
|
51
|
-
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
## Breaking changes (v2)
|
|
81
|
+
|
|
82
|
+
Starting from v2, the library is **mutable-first** to stay **small and fast** (fewer allocations, less GC, no runtime "clone vs mutate" checks in hot paths):
|
|
83
|
+
|
|
84
|
+
- Arithmetic helpers (`addBig`, `subBig`, `mulBig`, `divBig`, `modBig`, `powBig`, `sqrtBig`, `absBig`) **mutate the first argument** and return it.
|
|
85
|
+
- `alignScale(a, b)` **mutates** the operand with the smaller scale.
|
|
86
|
+
- `minBig`/`maxBig` return **one of the inputs** (no cloning).
|
|
87
|
+
- `pipeBig(big)` / `new BigPipe(big)` **new** api, **mutates** the passed `Big`.
|
|
88
|
+
|
|
89
|
+
If these changes are breaking for your codebase, clone before calling operations (`cloneBig(a)`) or adjust your code to work with mutation.
|
|
52
90
|
|
|
53
91
|
## API
|
|
54
92
|
|
|
@@ -56,15 +94,13 @@ More information in the [documentation](https://dschewchenko.github.io/big.esm/)
|
|
|
56
94
|
|
|
57
95
|
### Core
|
|
58
96
|
|
|
59
|
-
#### `
|
|
97
|
+
#### `createBig(value: BigValue, scale?: number | string): Big`
|
|
60
98
|
|
|
61
|
-
Creates a
|
|
99
|
+
Creates a `Big` instance from a `string`, `number`, `bigint`, `Big`, or `BigObject`. Preferred constructor helper.
|
|
62
100
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
#### `createBig(value: string | number | bigint, scale?: number | string): Big`
|
|
101
|
+
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.
|
|
66
102
|
|
|
67
|
-
|
|
103
|
+
### Utilities
|
|
68
104
|
|
|
69
105
|
#### `cloneBig(a: Big): Big`
|
|
70
106
|
|
|
@@ -72,7 +108,7 @@ Creates a new `Big` instance from another `Big` instance.
|
|
|
72
108
|
|
|
73
109
|
#### `alignScale(a: Big, b: Big): [Big, Big]`
|
|
74
110
|
|
|
75
|
-
Aligns the scale of two `Big` instances. The scale of the result will be equal to the maximum scale of the two numbers
|
|
111
|
+
Aligns the scale of two `Big` instances by mutating the one with the smaller scale. The scale of the result will be equal to the maximum scale of the two numbers
|
|
76
112
|
|
|
77
113
|
#### `isNumericValue(value: any): boolean`
|
|
78
114
|
|
|
@@ -80,57 +116,61 @@ Checks if the value is a valid numeric value for creating a `Big` instance.
|
|
|
80
116
|
|
|
81
117
|
### Mathematical operations
|
|
82
118
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
**Note:** In high-load applications, it is recommended to use the `mutable` option to reduce memory usage and improve performance.
|
|
119
|
+
Math operations mutate the first argument and return it.
|
|
86
120
|
|
|
87
|
-
#### `addBig(a: Big, b: Big
|
|
121
|
+
#### `addBig(a: Big, b: Big): Big`
|
|
88
122
|
|
|
89
|
-
Adds
|
|
123
|
+
Adds `b` to `a` (mutates `a`).
|
|
90
124
|
|
|
91
|
-
#### `subBig(a: Big, b: Big
|
|
125
|
+
#### `subBig(a: Big, b: Big): Big`
|
|
92
126
|
|
|
93
|
-
Subtracts
|
|
127
|
+
Subtracts `b` from `a` (mutates `a`).
|
|
94
128
|
|
|
95
|
-
#### `mulBig(a: Big, b: Big
|
|
129
|
+
#### `mulBig(a: Big, b: Big): Big`
|
|
96
130
|
|
|
97
|
-
Multiplies
|
|
131
|
+
Multiplies `a` by `b` (mutates `a`).
|
|
98
132
|
|
|
99
|
-
#### `divBig(a: Big, b: Big, precision = 20, roundingMode = "half-up"
|
|
133
|
+
#### `divBig(a: Big, b: Big, precision = 20, roundingMode = "half-up"): Big`
|
|
100
134
|
|
|
101
|
-
Divides
|
|
135
|
+
Divides `a` by `b` (mutates `a`).
|
|
102
136
|
|
|
103
|
-
#### `modBig(a: Big, b: Big
|
|
137
|
+
#### `modBig(a: Big, b: Big): Big`
|
|
104
138
|
|
|
105
|
-
Calculates
|
|
139
|
+
Calculates `a % b` (mutates `a`).
|
|
106
140
|
|
|
107
|
-
#### `powBig(a: Big, exp: number
|
|
141
|
+
#### `powBig(a: Big, exp: number): Big`
|
|
108
142
|
|
|
109
|
-
Raises `a` to
|
|
143
|
+
Raises `a` to `exp` (mutates `a`).
|
|
110
144
|
|
|
111
|
-
#### `sqrtBig(a: Big, root = 2, precision = 20
|
|
145
|
+
#### `sqrtBig(a: Big, root = 2, precision = 20): Big`
|
|
112
146
|
|
|
113
|
-
Calculates the root of `a
|
|
147
|
+
Calculates the root of `a` (mutates `a`).
|
|
114
148
|
|
|
115
|
-
#### `absBig(a: Big
|
|
149
|
+
#### `absBig(a: Big): Big`
|
|
116
150
|
|
|
117
|
-
|
|
151
|
+
Replaces `a` with `|a|` (mutates `a`).
|
|
118
152
|
|
|
119
153
|
#### `compareBig(a: Big, b: Big): -1 | 0 | 1`
|
|
120
154
|
|
|
121
155
|
Compares two `Big` instances. Returns `-1` if `a < b`, `0` if `a == b` and `1` if `a > b`.
|
|
122
156
|
|
|
123
|
-
#### `minBig(a: Big, b: Big
|
|
157
|
+
#### `minBig(a: Big, b: Big): Big`
|
|
158
|
+
|
|
159
|
+
Returns the minimum of `a` and `b` by reference (no cloning).
|
|
160
|
+
|
|
161
|
+
#### `maxBig(a: Big, b: Big): Big`
|
|
162
|
+
|
|
163
|
+
Returns the maximum of `a` and `b` by reference (no cloning).
|
|
124
164
|
|
|
125
|
-
|
|
165
|
+
### Pipeline
|
|
126
166
|
|
|
127
|
-
#### `
|
|
167
|
+
#### `pipeBig(initial: BigValue): BigPipeline`
|
|
128
168
|
|
|
129
|
-
|
|
169
|
+
Creates a chainable pipeline that mutates its internal `Big` in-place.
|
|
130
170
|
|
|
131
|
-
|
|
171
|
+
#### `new BigPipe(initial: BigValue): BigPipe`
|
|
132
172
|
|
|
133
|
-
|
|
173
|
+
Class form of the pipeline.
|
|
134
174
|
|
|
135
175
|
## Roadmap
|
|
136
176
|
|
package/dist/big.d.ts
CHANGED