https://github.com/gsknnft/bigint-buffer
💪🔢 @gsknnft/bigint-buffer: Secure Buffer Utilities for TC39 BigInt Proposal
https://github.com/gsknnft/bigint-buffer
bignum binary buffer crypto esm napi nodejs polyfill serialization solana tc39-bigint web3
Last synced: 4 months ago
JSON representation
💪🔢 @gsknnft/bigint-buffer: Secure Buffer Utilities for TC39 BigInt Proposal
- Host: GitHub
- URL: https://github.com/gsknnft/bigint-buffer
- Owner: gsknnft
- License: apache-2.0
- Created: 2025-10-25T02:43:21.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-12-19T22:35:25.000Z (6 months ago)
- Last Synced: 2025-12-22T09:43:30.218Z (6 months ago)
- Topics: bignum, binary, buffer, crypto, esm, napi, nodejs, polyfill, serialization, solana, tc39-bigint, web3
- Language: HTML
- Homepage:
- Size: 3.24 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# @gsknnft/bigint-buffer
[](https://www.npmjs.com/package/@gsknnft/bigint-buffer)
[](https://nodejs.org)
BigInt <-> Buffer conversion with native bindings, fast JS fallback paths, and built-in conversion helpers.
## Install
```bash
npm install @gsknnft/bigint-buffer
```
## Quick Start
```ts
import {
toBigIntBE,
toBigIntLE,
toBufferBE,
toBufferLE,
bigintToHex,
hexToBigint,
bigintToBase64,
base64ToBigint,
} from "@gsknnft/bigint-buffer";
const value = toBigIntBE(Buffer.from("deadbeef", "hex"));
const out = toBufferLE(value, 8);
const hex = bigintToHex(123456789n); // "075bcd15"
const roundTrip = hexToBigint(hex);
const b64 = bigintToBase64(123456789n);
const fromB64 = base64ToBigint(b64);
```
## FixedPoint Helpers
```ts
import {
toFixedPoint,
fromFixedPoint,
addFixedPoint,
subtractFixedPoint,
averageFixedPoint,
compareFixedPoint,
} from "@gsknnft/bigint-buffer";
const a = toFixedPoint(12.34, 9);
const b = toFixedPoint(7.66, 9);
const sum = addFixedPoint(a, b);
const avg = averageFixedPoint([a, b]);
const cmp = compareFixedPoint(a, b);
const n = fromFixedPoint(sum, 9);
```
## Native Loading
The package tries native first, then falls back to JS:
1. `node-gyp-build` prebuild lookup from installed package root
2. `bindings` lookup with explicit `module_root` when resolvable
3. pure JS fallback
Set `BIGINT_BUFFER_NATIVE_PATH` to override lookup root when needed.
Enable debug logging:
```bash
BIGINT_BUFFER_DEBUG=1 node your-app.js
```
Silence fallback warning:
```bash
BIGINT_BUFFER_SILENT_NATIVE_FAIL=1 node your-app.js
```
## Electron Packaging
Include the native binary in unpacked resources:
- `node_modules/@gsknnft/bigint-buffer/build/Release/bigint_buffer.node`
Common location at runtime:
- `resources/app.asar.unpacked/node_modules/@gsknnft/bigint-buffer/build/Release/bigint_buffer.node`
If your packager relocates native files, set `BIGINT_BUFFER_NATIVE_PATH` to the directory containing `build/Release/bigint_buffer.node`.
## Browser Notes
This package supports browser builds via fallback paths and conversion bundles.
If your bundler does not polyfill Node globals/modules automatically, add polyfills for:
- `Buffer`
- `path`
- `fs`
## Exports
Top-level package exports:
- ESM: `dist/index.js`
- CJS: `dist/index.cjs`
- Types: `dist/index.d.ts`
- Native binary export: `./build/Release/bigint_buffer.node`
- Conversion subpath: `@gsknnft/bigint-buffer/conversion`
## Commands
```bash
npm run build # bundle + declarations + conversion sync + native sync
npm run compile # build + typecheck
npm test # vitest
npm run check # eslint
npm run rebuild # node-gyp rebuild + build + conversion build
npm run prebuilds # prebuildify for native binaries
```
Internal build scripts (`scripts/*.ts`) are executed via `tsx` for stable ESM compatibility in local and CI environments.
## Quality Snapshot
Latest local run (Node 24, Vitest v4, v8 coverage):
- Tests: `141 passed`
- Coverage: `Statements 84.15%`, `Branches 72.36%`, `Functions 88.37%`, `Lines 85.88%`
- Benchmark snapshot: see `benchmark.md`
- Publish dry-run: clean tarball (no test/bench JS artifacts)
Reproduce:
```bash
pnpm exec vitest run --coverage --pool=forks
pnpm run benchmark
pnpm pack --dry-run
```
## Runtime Compatibility
- Node: `>=20`
- Package format: ESM + CJS
- Native addon: N-API (`bigint_buffer.node`)
## License
Apache-2.0