@gsknnft/bigint-buffer 1.3.2 → 1.4.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/.travis.yml CHANGED
@@ -1,7 +1,7 @@
1
1
  language: node_js
2
2
  node_js:
3
3
  - node
4
- - '10'
4
+ - '24'
5
5
  sudo : false
6
6
  env:
7
7
  global:
@@ -16,19 +16,19 @@ services:
16
16
  - xvfb
17
17
  cache:
18
18
  directories:
19
- - $HOME/.npm
19
+ - $HOME/.pnpm
20
20
  matrix:
21
21
  fast_finish: true
22
22
  include:
23
23
  - os: linux
24
- node_js: '10'
24
+ node_js: '24'
25
25
  env: TEST_SUITE=test:browser
26
26
  - os: windows
27
- node_js: '10'
27
+ node_js: '24'
28
28
  env: TEST_SUITE=test:node
29
- script: npm run $TEST_SUITE
29
+ script: pnpm run $TEST_SUITE
30
30
  before_deploy:
31
- - npm pack
31
+ - pnpm pack
32
32
  deploy:
33
33
  - provider: releases
34
34
  api_key: "$GITHUB_TOKEN"
@@ -36,16 +36,16 @@ deploy:
36
36
  file: bigint-buffer-*.tgz
37
37
  skip_cleanup: true
38
38
  on:
39
- branch: master
39
+ branch: main
40
40
  node: '10'
41
41
  condition: "$TEST_SUITE = test:node"
42
42
  tags: true
43
43
  - provider: npm
44
44
  api_key: "$NPM_TOKEN"
45
45
  skip_cleanup: true
46
- email: mwei@cs.ucsd.edu
46
+ email: gsknnft@gmail.com
47
47
  on:
48
- branch: master
49
- node: '10'
48
+ branch: main
49
+ node: '24'
50
50
  condition: "$TEST_SUITE = test:node"
51
51
  tags: true
package/README.md CHANGED
@@ -2,15 +2,22 @@
2
2
 
3
3
  [![NPM Version](https://img.shields.io/npm/v/@gsknnft/bigint-buffer.svg?style=flat-square)](https://www.npmjs.com/package/@gsknnft/bigint-buffer)
4
4
  [![Node Version](https://img.shields.io/node/v/@gsknnft/bigint-buffer.svg?style=flat-square)](https://nodejs.org)
5
- [![Maintained Fork](https://img.shields.io/badge/fork-maintained-blue?style=flat-square)](https://github.com/gsknnft/bigintbuffer)
5
+ [![Maintained Fork](https://img.shields.io/badge/fork-maintained-blue?style=flat-square)](https://github.com/gsknnft/bigint-buffer)
6
+ Modern, secure BigInt ↔ Buffer conversion with native bindings, browser fallbacks, and the full `bigint-conversion` API built in.
6
7
 
7
8
  ---
8
9
 
9
10
  ## 🔐 Security Notice: This Module Has Been Reclaimed
11
+ This fork (`@gsknnft/bigint-buffer`) is actively maintained, secure, and recommended for all users. Native now builds clean. All conversion helpers are live and set.
12
+ **removed useless deps - back to ZERO dependancies unless chosen native bindings**
13
+ ---
14
+
15
+ Modern, secure BigInt ↔ Buffer conversion with native bindings, browser fallbacks, and the full `bigint-conversion` API built in.
10
16
 
11
17
  As of October 2025, `bigint-buffer@1.1.5` is **compromised and flagged by multiple audit tools** due to unresolved vulnerabilities in its native bindings and transitive dependencies. No upstream patch has been published.
18
+ As the original `bigint-buffer` package is deprecated. This repo (`@gsknnft/bigint-buffer`) is the official, actively maintained successor. All users should migrate for security, performance, and modern features.
12
19
 
13
- This fork — `@gsknnft/bigint-buffer@1.3.2` — is a **sovereign override**:
20
+ This repo — `@gsknnft/bigint-buffer@1.4.0` — is a **sovereign override**:
14
21
  - ✅ Rebuilt with modern TypeScript and Rollup
15
22
  - ✅ Native bindings patched and rebuilt via `node-gyp`
16
23
  - ✅ Browser fallback formalized via `"browser"` field
@@ -22,187 +29,177 @@ If you're using `bigint-buffer` in a secure or reproducible system, **migrate to
22
29
  ```json
23
30
  "pnpm": {
24
31
  "overrides": {
25
- "bigint-buffer": "@gsknnft/bigint-buffer@1.3.2"
32
+ "bigint-buffer": "@gsknnft/bigint-buffer@1.4.0"
26
33
  }
27
34
  }
28
35
  ```
29
- ## 🔍 Differences from Upstream
30
-
31
- - Rebuilt native bindings with modern Node compatibility
32
- - Scoped under `@gsknnft` for audit clarity
33
- - Uses `cpy-cli` instead of deprecated `cpx`
34
- - Rollup-based bundling for ESM/CJS duality
35
- - Peer dependency alignment and reproducibility guarantees
36
36
 
37
- ---
38
37
 
39
38
  **This fork is maintained by CoreFlame/GSKNNFT as part of the SigilNet ecosystem.**
40
- It is the only currently known secure, reproducible implementation of BigInt ↔ Buffer conversion with native fallback.
41
39
 
42
40
  ---
43
41
 
44
- ### 🚀 Conversion Utilities (Built-In)
45
-
46
- `@gsknnft/bigint-buffer` includes direct conversion tools — no need to install `bigint-conversion` separately.
42
+ ## Why BigInts?
47
43
 
48
- >You no longer need `bigint-conversion` as a separate dependency.
44
+ BigInts are primitive arbitrary precision integers, overcoming the limitations of JS numbers (max 53 bits). They enable safe manipulation of 64, 128, 256+ bit values (e.g., database IDs, hashes) with much better performance than Buffer or BN.js.
49
45
 
50
- #### Importing
46
+ **Performance highlights:**
51
47
 
52
- ```ts
53
- import {
54
- bigintToBuf,
55
- bufToBigint,
56
- bigintToHex,
57
- hexToBigint,
58
- bigintToText,
59
- textToBigint,
60
- bigintToBase64,
61
- base64ToBigint
62
- } from '@gsknnft/bigint-buffer';
63
48
  ```
64
-
65
- #### Examples
66
-
67
- ```ts
68
- const hex = bigintToHex(123456789n); // → "075bcd15"
69
- const buf = bigintToBuf(123456789n); // → <Buffer 07 5b cd 15>
70
- const text = bigintToText(123456789n); // → "123456789"
71
- const base64 = bigintToBase64(123456789n); // → "B1vNFQ=="
49
+ Buffer equality: 12M ops/s
50
+ BigInt equality: 798M ops/s
51
+ BN.js equality: 73M ops/s
52
+ BN.js multiply: 4.7M ops/s
53
+ BigInt multiply: 15M ops/s
72
54
  ```
73
55
 
74
- > All conversions are endian-safe, round-trip validated, and available in both Node and browser environments.
75
-
76
56
  ---
77
57
 
78
- ### 🧠 Why This Matters
58
+ ## Why This Package?
79
59
 
80
- - No audit vulnerabilities
81
- - ✅ Native bindings preserved
82
- - ✅ Conversion logic fused directly into the core
83
- - ✅ Unified types and exports
84
- - ✅ No need for `bigint-conversion` or external wrappers
60
+ It is the only currently known secure, reproducible implementation of BigInt ↔ Buffer conversion with native fallback.
85
61
 
86
- ---
62
+ - Efficient, secure conversion between BigInt and Buffer (native N-API bindings in Node, pure JS fallback in browser)
63
+ - All conversion helpers built-in (no need for `bigint-conversion`)
64
+ - Endian-safe, round-trip validated
65
+ - Unified types and exports
66
+ - No audit vulnerabilities
67
+ - Patched and rebuilt native bindings (Node 18+)
68
+ - First-class ESM/CJS exports plus browser bundle
69
+ - Conversion helpers in-core (no separate `bigint-conversion`)
70
+ - Actively maintained by GSKNNFT/CoreFlame
87
71
 
88
- The original introduced utilities for converting TC39 BigInts to and from buffers. This fork builds on that foundation with modern tooling, patched bindings, and reproducible builds.
72
+ ## 🔍 Differences from Upstream
89
73
 
90
- This utility is necessary because BigInts, as proposed, do not support direct conversion between Buffers (or UInt8Arrays), but rather require conversion from buffers to hexadecimal strings then to BigInts, which is suboptimal. This utility includes N-API bindings, so under node, conversion is performed without generating a hexadecimal string. In the browser, normal string conversion is used.
74
+ - Rebuilt native bindings with modern Node compatibility
75
+ - Scoped under `@gsknnft` for audit clarity
76
+ - Uses `cpy-cli` instead of deprecated `cpx`
77
+ - Rollup-based bundling for ESM/CJS duality
78
+ - Peer dependency alignment and reproducibility guarantees
91
79
 
92
80
  ---
93
81
 
94
- # Why use BigInts?
95
-
96
- BigInts are currently a stage 3 proposal, supported in Node 10 and V8 v6.7. BigInts are primitive arbitrary precision integers, overcoming the limitations of the number type in javascript, which only supports up to 53 bits of precision.
82
+ ## Install
83
+ ```bash
84
+ pnpm add @gsknnft/bigint-buffer
85
+ # or npm/yarn
86
+ ```
97
87
 
98
- In many applications, manipulating 64, 128 or even 256 bit numbers is quite common. For example, database identifiers are often 128 bits, and hashes are often 256 bits (If you're looking for hashing support, try out [bigint-hash](https://github.com/no2chem/bigint-hash)). Before BigInts, manipulating these numbers safely required either allocating a Buffer or UInt8Arrays, which is quite expensive compared to a number, since Buffers are allocated on the heap.
88
+ ---
99
89
 
100
- BigInts solve this problem by introducing a primitive that can hold
101
- arbitrary precision integers, reducing memory pressure and allowing
102
- the runtime to better optimize arithmetic operations. This results in significant performance improvements - 10x-100x for simple equality comparisons (using `===` vs `Buffer.compare()`):
90
+ ## Quick Start
91
+ ```ts
92
+ import {
93
+ toBigIntBE, toBigIntLE, toBufferBE, toBufferLE,
94
+ bigintToBuf, bufToBigint, bigintToHex, hexToBigint,
95
+ bigintToText, textToBigint, bigintToBase64, base64ToBigint
96
+ } from '@gsknnft/bigint-buffer';
103
97
 
104
- ```
105
- Buffer equality comparison: 11916844±4.23% ops/s 83.91±17.293 ns/op (91 runs)
106
- bigint equality comparison: 798024851±0.29% ops/s 1.25±0.017 ns/op (91 runs)
98
+ toBigIntBE(Buffer.from('deadbeef', 'hex')); // 3735928559n
99
+ toBufferLE(0xdeadbeefn, 6); // <Buffer ef be ad de 00 00>
100
+ bigintToHex(123456789n); // "075bcd15"
101
+ textToBigint('Hello'); // 0x48656c6c6f
102
+ bigintToBase64(123456789n); // "B1vNFQ=="
107
103
  ```
108
104
 
109
- Before BigInts, you probably used a library such as the widely used [bn.js](https://www.npmjs.com/package/bn.js).
110
- bn.js fares a little better than a plain Buffer, but is still 5-10x slower than the bigint:
111
- ```
112
- BN equality comparison: 73255774±0.67% ops/s 13.65±0.442 ns/op (89 runs)
113
- ```
105
+ ---
114
106
 
115
- bigints are also much better with arithmetic, here are the results compared to BN for multiplying two
116
- 128-bit integers, yielding a 4x improvement:
117
- ```
118
- BN multiply: 4763236±0.49% ops/s 209.94±5.111 ns/op (93 runs)
119
- bigint multiply: 15268666±0.92% ops/s 65.49±2.938 ns/op (92 runs)
120
- ```
107
+ ### 🚀 Advanced Conversion Utilities (Built-In)
121
108
 
122
- # So what's the problem?
109
+ Need only the conversion helpers?
110
+ ## Usage
123
111
 
124
- BigInts, unfortunately lack an efficient way to be converted back and forth between buffers. When dealing with serialized data or legacy node code, you'll often want to generate a BigInt from a buffer, or convert a BigInt to a Buffer in order to send a BigInt over the wire.
112
+ ### Classic Buffer/BigInt API
125
113
 
126
- Currently, the only method to generate a new BigInt is with the BigInt constructor. Unfortunately, it doesn't support Buffers, though it may in the future:
114
+ ```js
115
+ import { toBigIntLE, toBigIntBE, toBufferLE, toBufferBE } from '@gsknnft/bigint-buffer';
127
116
 
128
- ```
129
- > BigInt(Buffer.from([1]))
130
- SyntaxError: Cannot convert to a BigInt
117
+ const bigInt = toBigIntBE(Buffer.from('deadbeef', 'hex'));
118
+ const buf = toBufferLE(123456789n, 8);
131
119
  ```
132
120
 
133
- Instead, you need to convert the Buffer to a hexadecimal string of the correct format. For example:
121
+ ```ts
122
+ import { conversionUtils } from '@gsknnft/bigint-buffer';
134
123
 
135
- ```
136
- > BigInt(`0x${buf.toString('hex')}`);
137
- 1n
124
+ // TypedArray, ArrayBuffer, hex/text/base64 helpers
125
+ const arrBuf = conversionUtils.bigintToBuf(123456789n, true); // ArrayBuffer
126
+ const hex = conversionUtils.bigintToHex(123456789n, true); // '0x...' format
127
+ const text = conversionUtils.bigintToText(123456789n);
138
128
  ```
139
129
 
140
- These conversions are not only quite expensive, but obviate a lot of the performance gains we get from BigInts. For example, on a large buffer, this conversion can take over 100x the time to do a comparison:
141
- ```
142
- bigint from hex string from buffer (huge): 1230607±1.02% ops/s 812.61±40.013 ns/op (89 runs)
143
- ```
130
+ > All conversions are endian-safe, round-trip validated, and available in both Node and browser environments.
131
+
132
+ ---
133
+
134
+ ### 🧠 Why This Matters
144
135
 
145
- # And... bigint-buffer helps how?
136
+ - No audit vulnerabilities
137
+ - ✅ Native bindings preserved
138
+ - ✅ Conversion logic fused directly into the core
139
+ - ✅ Unified types and exports
140
+ - ✅ No need for `bigint-conversion` or external wrappers
146
141
 
147
- bigint-buffer introduces four functions for conversion between buffers and bigints. A small example follows:
148
- ```typescript
149
- import {toBigIntBE, toBigIntLE, toBufferBE, toBufferLE} from '@gsknnft/bigint-buffer';
150
142
 
151
- // Get a big endian buffer of the given width
152
- toBufferBE(0xdeadbeefn, 8);
153
- // ↪ <Buffer 00 00 00 00 de ad be ef>
143
+ ---
154
144
 
155
- // Get a little endian buffer of the given width
156
- toBufferLE(0xdeadbeefn, 8);
157
- // <Buffer ef be ad de 00 00 00 00>
145
+ ## Runtime: Native vs JS
146
+ - Native binding lives at `build/Release/bigint_buffer.node` and loads automatically.
147
+ - Check the path in use:
148
+ ```ts
149
+ import { isNative } from '@gsknnft/bigint-buffer';
150
+ console.log(isNative); // true when native is loaded
151
+ ```
152
+ - Pure JS fallback stays available for browsers and non-native installs.
158
153
 
159
- // Get a BigInt from a buffer in big endian format
160
- toBigIntBE(Buffer.from('deadbeef', 'hex'));
161
- // ↪ 3735928559n (0xdeadbeefn)
154
+ ---
162
155
 
163
- // Get a BigInt from a buffer in little endian format
164
- toBigIntLE(Buffer.from('deadbeef', 'hex'));
165
- // 4022250974n (0xefbeadd0en)
166
- ```
156
+ ## Docs & Types
157
+ - Core usage: this README
158
+ - Full conversion docs: `src/conversion/docs/` (generated from `bigint-conversion`)
159
+ - API: [gsknnft.github.io/bigint-buffer/](https://gsknnft.github.io/bigint-buffer/)
160
+ - Types: ship in `dist/*.d.ts`
167
161
 
168
- bigint-buffer uses N-API native bindings to perform the conversion efficiently without generating the
169
- immediate hex strings necessary in pure javascript. This results in a significant performance increase,
170
- about 2x for small buffer to bigint conversions, and 8x better than BN:
162
+ ---
171
163
 
172
- ```
173
- BN to buffer (small): 981703±68.30% ops/s 1018.64±3194.648 ns/op (81 runs)
174
- bigint from hex string from buffer (small): 2804915±5.00% ops/s 356.52±85.371 ns/op (88 runs)
175
- LE bigint-buffer ToBigInt (small): 5932704±1.62% ops/s 168.56±12.971 ns/op (87 runs)
176
- ```
164
+ ## Commands
177
165
 
178
- And about 3.3x for bigint to buffer conversions, and 17x better than BN:
179
- ```
180
- BN to buffer (large): 339437±2.85% ops/s 2946.06±385.504 ns/op (81 runs)
181
- BE bigint to hex string to buffer (large): 1714292±1.35% ops/s 583.33±37.995 ns/op (90 runs)
182
- BE bigint-buffer to buffer (large, truncated): 5977218±4.68% ops/s 167.30±37.284 ns/op (87 runs)
166
+ ```bash
167
+ pnpm run build # compile + bundle
168
+ pnpm run test # vitest (node + conversion tests)
169
+ pnpm run coverage # conversion coverage
170
+ pnpm run rebuild:native # rebuild the N-API binding
183
171
  ```
184
172
 
185
- # Typescript Support
173
+ ## Benchmarks
186
174
 
187
- bigint-buffer supplies typescript bindings, but BigInts are still not supported in typescript, though
188
- a pull request has been opened, so support should be coming soon. If you are using typescript,
189
- @calebsander has put up a pull request and the instructions in [this post](https://github.com/Microsoft/TypeScript/issues/15096#issuecomment-419654748).
175
+ Run benchmarks with:
176
+ ```bash
177
+ pnpm run benchmark # performance benchmarks
178
+ ```
190
179
 
191
- # Install
180
+ ---
192
181
 
193
- Add bigint-buffer to your project with:
182
+ ## Modern Testing
194
183
 
195
- > `pnpm add @gsknnft/bigint-buffer`
184
+ Uses [Vitest](https://vitest.dev) for fast, type-safe tests and coverage:
196
185
 
197
- or
186
+ ```bash
187
+ pnpm run test # run all tests
188
+ pnpm run coverage # see coverage report
189
+ ```
198
190
 
199
- > `npm install @gsknnft/bigint-buffer`
191
+ ---
200
192
 
201
- # Documentation
193
+ ## API Surface
194
+ - Native: `toBigIntBE/LE`, `toBufferBE/LE`, `validateBigIntBuffer`, `isNative`
195
+ - Conversion: `bigintToBuf`, `bufToBigint`, `bigintToHex`, `hexToBigint`, `bigintToText`, `textToBigint`, `bigintToBase64`, `base64ToBigint`, `bufToHex`, `hexToBuf`, `textToBuf`, `bufToText`, `parseHex`, `TypedArray`
202
196
 
203
- Basic API documentation can be found [here](https://gsknnft.github.io/bigint-buffer/). Note that v1.0.0 changes
204
- the name of the original functions to meet style guidelines.
197
+ All helpers are endian-safe and validated across Node and browser builds.
205
198
 
206
- # Benchmarks
199
+ ---
207
200
 
208
- Benchmarks can be run by executing `pnpm run benchmark` from the package directory.
201
+ ## Support & Project Status
202
+ - Version: 1.4.0
203
+ - Maintainer: GSKNNFT/CoreFlame
204
+ - Node: ≥18 (native), browser bundle included
205
+ - Issues: https://github.com/gsknnft/bigint-buffer/issues
package/WHY_BIGINT.md ADDED
@@ -0,0 +1,127 @@
1
+ # @gsknnft/bigint-buffer
2
+
3
+ ## Secure Buffer Utilities for TC39 BigInt Proposal
4
+
5
+ ---
6
+
7
+ The original introduced utilities for converting TC39 BigInts to and from buffers. This fork builds on that foundation with modern tooling, patched bindings, and reproducible builds.
8
+
9
+ This utility is necessary because BigInts, as proposed, do not support direct conversion between Buffers (or UInt8Arrays), but rather require conversion from buffers to hexadecimal strings then to BigInts, which is suboptimal. This utility includes N-API bindings, so under node, conversion is performed without generating a hexadecimal string. In the browser, normal string conversion is used.
10
+
11
+ ---
12
+
13
+ # Why use BigInts?
14
+
15
+ BigInts are currently a stage 3 proposal, supported in Node 10 and V8 v6.7. BigInts are primitive arbitrary precision integers, overcoming the limitations of the number type in javascript, which only supports up to 53 bits of precision.
16
+
17
+ In many applications, manipulating 64, 128 or even 256 bit numbers is quite common. For example, database identifiers are often 128 bits, and hashes are often 256 bits (If you're looking for hashing support, try out [bigint-hash](https://github.com/no2chem/bigint-hash)). Before BigInts, manipulating these numbers safely required either allocating a Buffer or UInt8Arrays, which is quite expensive compared to a number, since Buffers are allocated on the heap.
18
+
19
+ BigInts solve this problem by introducing a primitive that can hold
20
+ arbitrary precision integers, reducing memory pressure and allowing
21
+ the runtime to better optimize arithmetic operations. This results in significant performance improvements - 10x-100x for simple equality comparisons (using `===` vs `Buffer.compare()`):
22
+
23
+ ```
24
+ Buffer equality comparison: 11916844±4.23% ops/s 83.91±17.293 ns/op (91 runs)
25
+ bigint equality comparison: 798024851±0.29% ops/s 1.25±0.017 ns/op (91 runs)
26
+ ```
27
+
28
+ Before BigInts, you probably used a library such as the widely used [bn.js](https://www.npmjs.com/package/bn.js).
29
+ bn.js fares a little better than a plain Buffer, but is still 5-10x slower than the bigint:
30
+ ```
31
+ BN equality comparison: 73255774±0.67% ops/s 13.65±0.442 ns/op (89 runs)
32
+ ```
33
+
34
+ bigints are also much better with arithmetic, here are the results compared to BN for multiplying two
35
+ 128-bit integers, yielding a 4x improvement:
36
+ ```
37
+ BN multiply: 4763236±0.49% ops/s 209.94±5.111 ns/op (93 runs)
38
+ bigint multiply: 15268666±0.92% ops/s 65.49±2.938 ns/op (92 runs)
39
+ ```
40
+
41
+ # So what's the problem?
42
+
43
+ BigInts, unfortunately lack an efficient way to be converted back and forth between buffers. When dealing with serialized data or legacy node code, you'll often want to generate a BigInt from a buffer, or convert a BigInt to a Buffer in order to send a BigInt over the wire.
44
+
45
+ Currently, the only method to generate a new BigInt is with the BigInt constructor. Unfortunately, it doesn't support Buffers, though it may in the future:
46
+
47
+ ```
48
+ > BigInt(Buffer.from([1]))
49
+ SyntaxError: Cannot convert to a BigInt
50
+ ```
51
+
52
+ Instead, you need to convert the Buffer to a hexadecimal string of the correct format. For example:
53
+
54
+ ```
55
+ > BigInt(`0x${buf.toString('hex')}`);
56
+ 1n
57
+ ```
58
+
59
+ These conversions are not only quite expensive, but obviate a lot of the performance gains we get from BigInts. For example, on a large buffer, this conversion can take over 100x the time to do a comparison:
60
+ ```
61
+ bigint from hex string from buffer (huge): 1230607±1.02% ops/s 812.61±40.013 ns/op (89 runs)
62
+ ```
63
+
64
+ # And... bigint-buffer helps how?
65
+
66
+ bigint-buffer introduces four functions for conversion between buffers and bigints. A small example follows:
67
+ ```typescript
68
+ import {toBigIntBE, toBigIntLE, toBufferBE, toBufferLE} from '@gsknnft/bigint-buffer';
69
+
70
+ // Get a big endian buffer of the given width
71
+ toBufferBE(0xdeadbeefn, 8);
72
+ // ↪ <Buffer 00 00 00 00 de ad be ef>
73
+
74
+ // Get a little endian buffer of the given width
75
+ toBufferLE(0xdeadbeefn, 8);
76
+ // ↪ <Buffer ef be ad de 00 00 00 00>
77
+
78
+ // Get a BigInt from a buffer in big endian format
79
+ toBigIntBE(Buffer.from('deadbeef', 'hex'));
80
+ // ↪ 3735928559n (0xdeadbeefn)
81
+
82
+ // Get a BigInt from a buffer in little endian format
83
+ toBigIntLE(Buffer.from('deadbeef', 'hex'));
84
+ // ↪ 4022250974n (0xefbeadd0en)
85
+ ```
86
+
87
+ bigint-buffer uses N-API native bindings to perform the conversion efficiently without generating the
88
+ immediate hex strings necessary in pure javascript. This results in a significant performance increase,
89
+ about 2x for small buffer to bigint conversions, and 8x better than BN:
90
+
91
+ ```
92
+ BN to buffer (small): 981703±68.30% ops/s 1018.64±3194.648 ns/op (81 runs)
93
+ bigint from hex string from buffer (small): 2804915±5.00% ops/s 356.52±85.371 ns/op (88 runs)
94
+ LE bigint-buffer ToBigInt (small): 5932704±1.62% ops/s 168.56±12.971 ns/op (87 runs)
95
+ ```
96
+
97
+ And about 3.3x for bigint to buffer conversions, and 17x better than BN:
98
+ ```
99
+ BN to buffer (large): 339437±2.85% ops/s 2946.06±385.504 ns/op (81 runs)
100
+ BE bigint to hex string to buffer (large): 1714292±1.35% ops/s 583.33±37.995 ns/op (90 runs)
101
+ BE bigint-buffer to buffer (large, truncated): 5977218±4.68% ops/s 167.30±37.284 ns/op (87 runs)
102
+ ```
103
+
104
+ # Typescript Support
105
+
106
+ bigint-buffer supplies typescript bindings, but BigInts are still not supported in typescript, though
107
+ a pull request has been opened, so support should be coming soon. If you are using typescript,
108
+ @calebsander has put up a pull request and the instructions in [this post](https://github.com/Microsoft/TypeScript/issues/15096#issuecomment-419654748).
109
+
110
+ # Install
111
+
112
+ Add bigint-buffer to your project with:
113
+
114
+ > `pnpm add @gsknnft/bigint-buffer`
115
+
116
+ or
117
+
118
+ > `npm install @gsknnft/bigint-buffer`
119
+
120
+ # Documentation
121
+
122
+ Basic API documentation can be found [here](https://gsknnft.github.io/bigint-buffer/). Note that v1.0.0 changes
123
+ the name of the original functions to meet style guidelines.
124
+
125
+ # Benchmarks
126
+
127
+ Benchmarks can be run by executing `pnpm run benchmark` from the package directory.
package/benchmark.md ADDED
@@ -0,0 +1,38 @@
1
+ > @gsknnft/bigint-buffer@1.4.0 benchmark C:\Users\G\Desktop\Builds\bigint-buffer
2
+ > node -r ts-node/register src/index.bench.ts
3
+
4
+ no-op: 140382903±5.47% ops/s 7.12±1.674 ns/op (71 runs)
5
+ bigint from hex string (small): 15586811±2.71% ops/s 64.16±8.076 ns/op (83 runs)
6
+ bigint from hex string from buffer (small): 4936021±2.82% ops/s 202.59±25.869 ns/op (79 runs)
7
+ BN from hex string from buffer (small): 4686836±2.41% ops/s 213.36±23.744 ns/op (82 runs)
8
+ LE bigint-buffer ToBigInt (small): 10685450±3.19% ops/s 93.59±13.871 ns/op (83 runs)
9
+ BE bigint-buffer ToBigInt (small): 8994196±2.88% ops/s 111.18±14.787 ns/op (82 runs)
10
+ bigint from hex string (mid, aligned): 11155353±4.58% ops/s 89.64±18.736 ns/op (80 runs)
11
+ bigint from hex string from buffer (mid, aligned): 2985658±2.65% ops/s 334.93±41.248 ns/op (83 runs)
12
+ BN from hex string from buffer (mid, aligned): 4216666±2.90% ops/s 237.15±32.015 ns/op (83 runs)
13
+ LE bigint-buffer ToBigInt (mid, aligned): 9561077±2.93% ops/s 104.59±13.984 ns/op (80 runs)
14
+ BE bigint-buffer ToBigInt (mid, aligned): 9513798±2.82% ops/s 105.11±13.846 ns/op (84 runs)
15
+ bigint from hex string (huge): 4330410±2.55% ops/s 230.93±27.561 ns/op (84 runs)
16
+ bigint from hex string from buffer (huge): 1925677±3.48% ops/s 519.30±83.489 ns/op (82 runs)
17
+ BN from hex string from buffer (huge): 1762721±2.97% ops/s 567.30±78.855 ns/op (84 runs)
18
+ LE bigint-buffer ToBigInt (huge): 6599407±2.63% ops/s 151.53±18.491 ns/op (83 runs)
19
+ BE bigint-buffer ToBigInt (huge): 6264231±3.18% ops/s 159.64±23.154 ns/op (80 runs)
20
+ LE bigint to hex string to buffer (small): 2754040±3.04% ops/s 363.10±52.008 ns/op (85 runs)
21
+ BE bigint to hex string to buffer (small): 2945555±2.41% ops/s 339.49±39.112 ns/op (88 runs)
22
+ BN to buffer (small): 8719840±3.77% ops/s 114.68±19.967 ns/op (82 runs)
23
+ LE bigint-buffer to buffer (small): 7767544±2.11% ops/s 128.74±12.561 ns/op (82 runs)
24
+ BE bigint-buffer to buffer (small): 7741353±2.44% ops/s 129.18±14.810 ns/op (85 runs)
25
+ LE bigint to hex string to buffer (large): 3431814±1.96% ops/s 291.39±27.043 ns/op (86 runs)
26
+ BE bigint to hex string to buffer (large): 3599237±2.56% ops/s 277.84±33.636 ns/op (86 runs)
27
+ BN to buffer (large): 0.00±0.00% ops/s 0.00±0.000 ns/op (0 run)
28
+ LE bigint-buffer to buffer (large): 7295219±2.67% ops/s 137.08±17.019 ns/op (83 runs)
29
+ BE bigint-buffer to buffer (large): 7219012±2.63% ops/s 138.52±16.929 ns/op (83 runs)
30
+ LE bigint to hex string to buffer (large): 3659717±2.25% ops/s 273.25±28.524 ns/op (83 runs)
31
+ BE bigint to hex string to buffer (large): 3911365±2.31% ops/s 255.67±27.772 ns/op (85 runs)
32
+ LE bigint-buffer to buffer (large, truncated): 7847676±2.46% ops/s 127.43±14.823 ns/op (86 runs)
33
+ BE bigint-buffer to buffer (large, truncated): 7874737±2.54% ops/s 126.99±15.015 ns/op (83 runs)
34
+ Buffer equality comparison: 21013935±3.30% ops/s 47.59±7.120 ns/op (79 runs)
35
+ BN equality comparison: 53940357±3.45% ops/s 18.54±2.941 ns/op (81 runs)
36
+ bigint equality comparison: 134130208±6.63% ops/s 7.46±2.094 ns/op (69 runs)
37
+ BN multiply: 5698232±2.26% ops/s 175.49±18.643 ns/op (85 runs)
38
+ bigint multiply: 111639669±7.88% ops/s 8.96±2.743 ns/op (58 runs)