@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: 1.4.5 adds FixedPoint utilities, native bindings in build/Release/ out of the box, and improved JS fallback for environments without native support. CI-verified for Node 20–24. All users should upgrade for best compatibility and new features.

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

Conversion Utilities

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);

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:

  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 endian-safe and validated across Node and browser builds.

Support

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