@gsknnft/bigint-buffer

Secure BigInt ⇆ Buffer conversion with native bindings, browser fallbacks, and the bigint-conversion helper APIs built in. This is the actively maintained fork of the original bigint-buffer.

Upgrade notice: The current 1.4.7 line ships chunked, allocation-free BE/LE converters (Buffer.read/writeBigUInt64* when available) that are fuzzed across empty, tiny, and huge buffers, alongside FixedPoint utilities and packaged native bindings. CI-verified for Node 20–24. Upgrade for the fastest conversions and consistent behaviour across environments.

---

Migration Guide

• If upgrading from legacy bigint-buffer, switch all imports to @gsknnft/bigint-buffer.
• All helpers are now available as named exports (no default export).
• For Electron, ensure the native binary is included in extraResources or asarUnpack so it ends up under resources/app.asar.unpacked/node_modules/@gsknnft/bigint-buffer/build/Release/.
• If your packager relocates files, set BIGINT_BUFFER_NATIVE_PATH to the directory containing build/Release/bigint_buffer.node before launching the app.
• For browser, add polyfills for Buffer, path, and fs as needed (see below).
• ESM, CJS, and TypeScript types are all supported out of the box.

---

---

Why This Package

• Native N-API binding with pure-JS fallback for browsers and constrained environments.
• Conversion helpers from bigint-conversion in-core (no extra deps).
• ESM and CJS exports plus a UMD/browser bundle.
• Actively maintained; legacy bigint-buffer is deprecated and flagged by audits.

---

Install

npm install @gsknnft/bigint-buffer
# or pnpm/yarn if preferred

---

Quick Start

import {
  toBigIntBE, toBigIntLE, toBufferBE, toBufferLE,
  bigintToBuf, bufToBigint, bigintToHex, hexToBigint,
  bigintToText, textToBigint, bigintToBase64, base64ToBigint,
  // New in 1.4.5
  toFixedPoint, fromFixedPoint, addFixedPoint, subtractFixedPoint,
  averageFixedPoint, compareFixedPoint, type FixedPoint,
} from "@gsknnft/bigint-buffer";

toBigIntBE(Buffer.from("deadbeef", "hex")); // 3735928559n
toBufferLE(0xdeadbeefn, 6);                 // <Buffer ef be ad de 00 00>
bigintToHex(123456789n);                    // "075bcd15"
textToBigint("Hello");                      // 0x48656c6c6f
bigintToBase64(123456789n);                 // "B1vNFQ=="

// FixedPoint usage
const fp = toFixedPoint(123456789n, 18);    // Convert bigint to FixedPoint
const sum = addFixedPoint(fp, fp);          // Add two FixedPoints
const avg = averageFixedPoint([fp, fp]);    // Average FixedPoints

// Browser usage (with polyfills) import { toBigIntBE } from "@gsknnft/bigint-buffer"; // Polyfill Buffer if needed: // import { Buffer } from "buffer";

// CJS usage const { toBigIntBE } = require("@gsknnft/bigint-buffer");

### Performance
- BE/LE conversions now stream bytes directly from buffers (64-bit chunks via Buffer.read/writeBigUInt64* when available) with no intermediate hex copies.
- JS fallback matches the native binding semantics and is exercised against empty, tiny, and very large inputs in CI.
- Native bindings still load automatically when present; the optimized fallback keeps browser and non-native runtimes fast.
- Browser bundlers must polyfill Node built-ins: add a node polyfill plugin (e.g. `rollup-plugin-polyfill-node`) or explicit aliases for `buffer`, `path`, and `fs` so the fallback loader can resolve.

### Pushing Performance Further
- For very large buffers, consider enabling the native binding (included in npm tarball) or adding SIMD/native glue in your host app if you need throughput beyond JS.

### Electron Packaging
- Ensure the native binding ships with your app: add `node_modules/@gsknnft/bigint-buffer/build/Release/bigint_buffer.node` to `extraResources`/`asarUnpack` so it ends up under `resources/app.asar.unpacked/node_modules/@gsknnft/bigint-buffer/build/Release/`.
- If your packager relocates files, set `BIGINT_BUFFER_NATIVE_PATH` to the directory containing `build/Release/bigint_buffer.node` before launching the app.

The loader will check, in order:
- `dist/build/Release/bigint_buffer.node`
- `build/Release/bigint_buffer.node`
- Electron asar-unpacked path
- `BIGINT_BUFFER_NATIVE_PATH` (if set)

### Conversion Utilities
```ts
import { conversionUtils } from "@gsknnft/bigint-buffer";

const arrBuf = conversionUtils.bigintToBuf(123456789n, true); // ArrayBuffer
const hex = conversionUtils.bigintToHex(123456789n, true);    // '0x...' format
const text = conversionUtils.bigintToText(123456789n);

// All helpers are available as named exports: import { bigintToBuf, bufToBigint, bigintToHex, hexToBigint } from "@gsknnft/bigint-buffer";

---

## Runtime
- Native binary: `build/Release/bigint_buffer.node` (included in npm package; loads automatically when available).
- Fallback: pure JS bundle for browser and non-native installs (now improved in 1.4.5).
- Check which path loaded:
  ```ts
  import { isNative } from "@gsknnft/bigint-buffer";
  console.log(isNative); // true when native binding is active

---

Commands

npm run build           # bundle + declarations + type check
npm test                # vitest with coverage
npm run test:node       # mocha against built JS (after build/compile)
npm run rebuild:native  # rebuild the N-API binding

---

API Surface (high level)

• Core: toBigIntBE/LE, toBufferBE/LE, validateBigIntBuffer, isNative
• Conversion: bigintToBuf, bufToBigint, bigintToHex, hexToBigint, bigintToText, textToBigint, bigintToBase64, base64ToBigint, bufToHex, hexToBuf, textToBuf, bufToText, parseHex

All helpers are available as named exports in both ESM and CJS. TypeScript types are included.

All helpers are endian-safe and validated across Node and browser builds.

---

• Version: 1.4.7 (FixedPoint, native bindings out-of-the-box, improved JS fallback, robust loader, and stable exports)
• Node: 20+ (tested through 24 LTS under CI)
• Issues: https://github.com/gsknnft/bigint-buffer/issues