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 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 npm:
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 { createBig, addBig } from 'big.esm';
39
+ import { addBig, cloneBig, createBig } from "big.esm";
37
40
 
38
- const a = createBig("12345678910.12345678910"); // or new Big("12345678910.12345678910")
41
+ const a = createBig("12345678910.12345678910");
39
42
  const b = createBig("9876543210.9876543210");
40
- const result = addBig(a, b);
41
- console.log(result.toString()); // 22222222121.1111111101
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 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 96.47% of all browsers(as of 2023-06-25).
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
- - `sqrtBig()` is heavy and slow operation. It's implemented using the Newton's method with nth root calculation. In most cases, there will be no problems.
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
- #### `new Big(value: BigValue, scale?: number | string): Big`
97
+ #### `createBig(value: BigValue, scale?: number | string): Big`
60
98
 
61
- 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.
99
+ Creates a `Big` instance from a `string`, `number`, `bigint`, `Big`, or `BigObject`. Preferred constructor helper.
62
100
 
63
- ### Utilities
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
- Alias for `new Big(value, scale)`.
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
- In math operations `mutable` option is used to specify whether to mutate the first argument or create a new instance. By default, a new instance is created.
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, mutable = false): Big`
121
+ #### `addBig(a: Big, b: Big): Big`
88
122
 
89
- Adds two `Big` instances.
123
+ Adds `b` to `a` (mutates `a`).
90
124
 
91
- #### `subBig(a: Big, b: Big, mutable = false): Big`
125
+ #### `subBig(a: Big, b: Big): Big`
92
126
 
93
- Subtracts two `Big` instances.
127
+ Subtracts `b` from `a` (mutates `a`).
94
128
 
95
- #### `mulBig(a: Big, b: Big, mutable = false): Big`
129
+ #### `mulBig(a: Big, b: Big): Big`
96
130
 
97
- Multiplies two `Big` instances.
131
+ Multiplies `a` by `b` (mutates `a`).
98
132
 
99
- #### `divBig(a: Big, b: Big, precision = 20, roundingMode = "half-up", mutable = false): Big`
133
+ #### `divBig(a: Big, b: Big, precision = 20, roundingMode = "half-up"): Big`
100
134
 
101
- Divides two `Big` instances. The default precision is 20. The default rounding mode is "half-up".
135
+ Divides `a` by `b` (mutates `a`).
102
136
 
103
- #### `modBig(a: Big, b: Big, mutable = false): Big`
137
+ #### `modBig(a: Big, b: Big): Big`
104
138
 
105
- Calculates the remainder of dividing two `Big` instances.
139
+ Calculates `a % b` (mutates `a`).
106
140
 
107
- #### `powBig(a: Big, exp: number, mutable = false): Big`
141
+ #### `powBig(a: Big, exp: number): Big`
108
142
 
109
- Raises `a` to the power of `b`.
143
+ Raises `a` to `exp` (mutates `a`).
110
144
 
111
- #### `sqrtBig(a: Big, root = 2, precision = 20, mutable = false): Big`
145
+ #### `sqrtBig(a: Big, root = 2, precision = 20): Big`
112
146
 
113
- Calculates the root of `a`. The default root is 2, which means the square root. The default precision is 20.
147
+ Calculates the root of `a` (mutates `a`).
114
148
 
115
- #### `absBig(a: Big, mutable = false): Big`
149
+ #### `absBig(a: Big): Big`
116
150
 
117
- Returns the absolute value of `a`.
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, mutable = false): 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
- Returns the minimum of two `Big` instances. If the numbers are equal, returns the first number.
165
+ ### Pipeline
126
166
 
127
- #### `maxBig(a: Big, b: Big, mutable = false): Big`
167
+ #### `pipeBig(initial: BigValue): BigPipeline`
128
168
 
129
- Returns the maximum of two `Big` instances. If the numbers are equal, returns the first number.
169
+ Creates a chainable pipeline that mutates its internal `Big` in-place.
130
170
 
131
- ## Benchmark
171
+ #### `new BigPipe(initial: BigValue): BigPipe`
132
172
 
133
- Benchmark results are available [here](https://github.com/dschewchenko/big.esm/blob/master/BENCHMARK.md).
173
+ Class form of the pipeline.
134
174
 
135
175
  ## Roadmap
136
176
 
package/dist/big.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { BigObject, PossibleNumber } from "./types";
1
+ import { BigObject, PossibleNumber } from './types';
2
2
  /**
3
3
  * The Big class for working with large numbers and fractions using BigInt.
4
4
  *