@gsknnft/bigint-buffer 1.3.0 → 1.3.2

package/README.md

@@ -10,7 +10,7 @@
 
 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.
 
-This fork — `@gsknnft/bigint-buffer@1.3.0` — is a **sovereign override**:
+This fork — `@gsknnft/bigint-buffer@1.3.2` — is a **sovereign override**:
 - ✅ Rebuilt with modern TypeScript and Rollup
 - ✅ Native bindings patched and rebuilt via `node-gyp`
 - ✅ Browser fallback formalized via `"browser"` field
@@ -22,7 +22,7 @@ If you're using `bigint-buffer` in a secure or reproducible system, **migrate to
 ```json
 "pnpm": {
   "overrides": {
-    "bigint-buffer": "@gsknnft/bigint-buffer@1.3.0"
+    "bigint-buffer": "@gsknnft/bigint-buffer@1.3.2"
   }
 }
 ```
@@ -85,6 +85,12 @@ const base64 = bigintToBase64(123456789n); // → "B1vNFQ=="
 
 ---
 
+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.
+
+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.
+
+---
+
 # Why use BigInts?
 
 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. 
@@ -140,7 +146,7 @@ bigint from hex string from buffer (huge): 1230607±1.02% ops/s 812.61±40.013 n
 
 bigint-buffer introduces four functions for conversion between buffers and bigints. A small example follows:
 ```typescript
-import {toBigIntBE, toBigIntLE, toBufferBE, toBufferLE} from 'bigint-buffer';
+import {toBigIntBE, toBigIntLE, toBufferBE, toBufferLE} from '@gsknnft/bigint-buffer';
 
 // Get a big endian buffer of the given width
 toBufferBE(0xdeadbeefn, 8);
@@ -176,8 +182,6 @@ BE bigint to hex string to buffer (large): 1714292±1.35% ops/s 583.33±37.995 n
 BE bigint-buffer to buffer (large, truncated): 5977218±4.68% ops/s 167.30±37.284 ns/op (87 runs)
 ```
 
-You can run the benchmarks by running `npm run benchmark`.
-
 # Typescript Support
 
 bigint-buffer supplies typescript bindings, but BigInts are still not supported in typescript, though
@@ -188,13 +192,17 @@ a pull request has been opened, so support should be coming soon. If you are usi
 
 Add bigint-buffer to your project with:
 
-> `npm install bigint-buffer`
+> `pnpm add @gsknnft/bigint-buffer`
+
+or
+
+> `npm install @gsknnft/bigint-buffer`
 
 # Documentation
 
-Basic API documentation can be found [here](https://no2chem.github.io/bigint-buffer/). Note that v1.0.0 changes
+Basic API documentation can be found [here](https://gsknnft.github.io/bigint-buffer/). Note that v1.0.0 changes
 the name of the original functions to meet style guidelines.
 
 # Benchmarks
 
-Benchmarks can be run by executing `npm run benchmark` from the package directory.
+Benchmarks can be run by executing `pnpm run benchmark` from the package directory.

package/dist/index.cjs

@@ -0,0 +1,205 @@
+'use strict';
+
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNative = void 0;
+exports.toBigIntLE = toBigIntLE;
+exports.validateBigIntBuffer = validateBigIntBuffer;
+exports.toBigIntBE = toBigIntBE;
+exports.toBufferLE = toBufferLE;
+exports.toBufferBE = toBufferBE;
+exports.bigintToBuf = bigintToBuf;
+exports.bufToBigint = bufToBigint;
+exports.bigintToHex = bigintToHex;
+exports.hexToBigint = hexToBigint;
+exports.bigintToText = bigintToText;
+exports.textToBigint = textToBigint;
+exports.bigintToBase64 = bigintToBase64;
+exports.base64ToBigint = base64ToBigint;
+let converter;
+exports.isNative = false;
+if (!process.browser) {
+    try {
+        converter = require('bindings')('bigint_buffer');
+        exports.isNative = !process.browser && converter !== undefined;
+    }
+    catch (e) {
+        console.warn('bigint: Failed to load bindings, pure JS will be used (try npm run rebuild?)');
+    }
+}
+/**
+ * Convert a little-endian buffer into a BigInt.
+ * @param buf The little-endian buffer to convert
+ * @returns A BigInt with the little-endian representation of buf.
+ */
+function toBigIntLE(buf) {
+    if (process.browser || converter === undefined) {
+        const reversed = Buffer.from(buf);
+        reversed.reverse();
+        const hex = reversed.toString('hex');
+        if (hex.length === 0) {
+            return BigInt(0);
+        }
+        return BigInt(`0x${hex}`);
+    }
+    return converter.toBigInt(buf, false);
+}
+function validateBigIntBuffer() {
+    try {
+        const test = toBigIntLE(Buffer.from([0x01, 0x00]));
+        return test === BigInt(1);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Convert a big-endian buffer into a BigInt
+ * @param buf The big-endian buffer to convert.
+ * @returns A BigInt with the big-endian representation of buf.
+ */
+function toBigIntBE(buf) {
+    if (process.browser || converter === undefined) {
+        const hex = buf.toString('hex');
+        if (hex.length === 0) {
+            return BigInt(0);
+        }
+        return BigInt(`0x${hex}`);
+    }
+    return converter.toBigInt(buf, true);
+}
+/**
+ * Convert a BigInt to a little-endian buffer.
+ * @param num   The BigInt to convert.
+ * @param width The number of bytes that the resulting buffer should be.
+ * @returns A little-endian buffer representation of num.
+ */
+function toBufferLE(num, width) {
+    if (process.browser || converter === undefined) {
+        const hex = num.toString(16);
+        const buffer = Buffer.from(hex.padStart(width * 2, '0').slice(0, width * 2), 'hex');
+        buffer.reverse();
+        return buffer;
+    }
+    // Allocation is done here, since it is slower using napi in C
+    return converter.fromBigInt(num, Buffer.allocUnsafe(width), false);
+}
+/**
+ * Convert a BigInt to a big-endian buffer.
+ * @param num   The BigInt to convert.
+ * @param width The number of bytes that the resulting buffer should be.
+ * @returns A big-endian buffer representation of num.
+ */
+function toBufferBE(num, width) {
+    if (process.browser || converter === undefined) {
+        const hex = num.toString(16);
+        return Buffer.from(hex.padStart(width * 2, '0').slice(0, width * 2), 'hex');
+    }
+    return converter.fromBigInt(num, Buffer.allocUnsafe(width), true);
+}
+// ========== Conversion Utilities ==========
+/**
+ * Convert a bigint to a Buffer with automatic sizing.
+ * Uses big-endian encoding and calculates the minimum buffer size needed.
+ * @param num The bigint to convert
+ * @returns A big-endian Buffer representation
+ */
+function bigintToBuf(num) {
+    if (num < BigInt(0)) {
+        throw new Error('bigintToBuf: negative bigint values are not supported');
+    }
+    if (num === BigInt(0)) {
+        return Buffer.from([0]);
+    }
+    // Calculate the number of bytes needed
+    const hex = num.toString(16);
+    const width = Math.ceil(hex.length / 2);
+    return toBufferBE(num, width);
+}
+/**
+ * Convert a Buffer to a bigint.
+ * Assumes big-endian encoding.
+ * @param buf The buffer to convert
+ * @returns A bigint representation of the buffer
+ */
+function bufToBigint(buf) {
+    return toBigIntBE(buf);
+}
+/**
+ * Convert a bigint to a hexadecimal string.
+ * @param num The bigint to convert
+ * @returns A hexadecimal string (without '0x' prefix)
+ */
+function bigintToHex(num) {
+    if (num < BigInt(0)) {
+        throw new Error('bigintToHex: negative bigint values are not supported');
+    }
+    const hex = num.toString(16);
+    // Ensure even length for proper byte representation
+    return hex.length % 2 === 0 ? hex : '0' + hex;
+}
+/**
+ * Convert a hexadecimal string to a bigint.
+ * @param hex The hexadecimal string (with or without '0x' prefix)
+ * @returns A bigint representation
+ */
+function hexToBigint(hex) {
+    // Remove '0x' prefix if present
+    const cleanHex = hex.startsWith('0x') ? hex.slice(2) : hex;
+    if (cleanHex.length === 0) {
+        return BigInt(0);
+    }
+    return BigInt(`0x${cleanHex}`);
+}
+/**
+ * Convert a bigint to a decimal text string.
+ * @param num The bigint to convert
+ * @returns A decimal string representation
+ */
+function bigintToText(num) {
+    return num.toString(10);
+}
+/**
+ * Convert a decimal text string to a bigint.
+ * @param text The decimal string to convert
+ * @returns A bigint representation
+ */
+function textToBigint(text) {
+    if (!text?.trim()) {
+        throw new Error('textToBigint: input string cannot be empty');
+    }
+    try {
+        return BigInt(text);
+    }
+    catch (e) {
+        throw new Error(`textToBigint: invalid decimal string "${text}"`);
+    }
+}
+/**
+ * Convert a bigint to a base64 string.
+ * @param num The bigint to convert
+ * @returns A base64 string representation
+ */
+function bigintToBase64(num) {
+    if (num < BigInt(0)) {
+        throw new Error('bigintToBase64: negative bigint values are not supported');
+    }
+    const buf = bigintToBuf(num);
+    return buf.toString('base64');
+}
+/**
+ * Convert a base64 string to a bigint.
+ * @param base64 The base64 string to convert
+ * @returns A bigint representation
+ */
+function base64ToBigint(base64) {
+    if (!base64?.trim()) {
+        throw new Error('base64ToBigint: input string cannot be empty');
+    }
+    // Trim whitespace and validate base64 format (allows padding)
+    const cleaned = base64.trim();
+    if (!/^[A-Za-z0-9+/]+=*$/.test(cleaned)) {
+        throw new Error('base64ToBigint: invalid base64 string format');
+    }
+    const buf = Buffer.from(cleaned, 'base64');
+    return bufToBigint(buf);
+}

package/dist/index.d.ts

@@ -26,3 +26,53 @@ export declare function toBufferLE(num: bigint, width: number): Buffer;
  * @returns A big-endian buffer representation of num.
  */
 export declare function toBufferBE(num: bigint, width: number): Buffer;
+/**
+ * Convert a bigint to a Buffer with automatic sizing.
+ * Uses big-endian encoding and calculates the minimum buffer size needed.
+ * @param num The bigint to convert
+ * @returns A big-endian Buffer representation
+ */
+export declare function bigintToBuf(num: bigint): Buffer;
+/**
+ * Convert a Buffer to a bigint.
+ * Assumes big-endian encoding.
+ * @param buf The buffer to convert
+ * @returns A bigint representation of the buffer
+ */
+export declare function bufToBigint(buf: Buffer): bigint;
+/**
+ * Convert a bigint to a hexadecimal string.
+ * @param num The bigint to convert
+ * @returns A hexadecimal string (without '0x' prefix)
+ */
+export declare function bigintToHex(num: bigint): string;
+/**
+ * Convert a hexadecimal string to a bigint.
+ * @param hex The hexadecimal string (with or without '0x' prefix)
+ * @returns A bigint representation
+ */
+export declare function hexToBigint(hex: string): bigint;
+/**
+ * Convert a bigint to a decimal text string.
+ * @param num The bigint to convert
+ * @returns A decimal string representation
+ */
+export declare function bigintToText(num: bigint): string;
+/**
+ * Convert a decimal text string to a bigint.
+ * @param text The decimal string to convert
+ * @returns A bigint representation
+ */
+export declare function textToBigint(text: string): bigint;
+/**
+ * Convert a bigint to a base64 string.
+ * @param num The bigint to convert
+ * @returns A base64 string representation
+ */
+export declare function bigintToBase64(num: bigint): string;
+/**
+ * Convert a base64 string to a bigint.
+ * @param base64 The base64 string to convert
+ * @returns A bigint representation
+ */
+export declare function base64ToBigint(base64: string): bigint;

package/dist/index.js

@@ -0,0 +1,203 @@
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNative = void 0;
+exports.toBigIntLE = toBigIntLE;
+exports.validateBigIntBuffer = validateBigIntBuffer;
+exports.toBigIntBE = toBigIntBE;
+exports.toBufferLE = toBufferLE;
+exports.toBufferBE = toBufferBE;
+exports.bigintToBuf = bigintToBuf;
+exports.bufToBigint = bufToBigint;
+exports.bigintToHex = bigintToHex;
+exports.hexToBigint = hexToBigint;
+exports.bigintToText = bigintToText;
+exports.textToBigint = textToBigint;
+exports.bigintToBase64 = bigintToBase64;
+exports.base64ToBigint = base64ToBigint;
+let converter;
+exports.isNative = false;
+{
+    try {
+        converter = require('bindings')('bigint_buffer');
+        exports.isNative = !false && converter !== undefined;
+    }
+    catch (e) {
+        console.warn('bigint: Failed to load bindings, pure JS will be used (try npm run rebuild?)');
+    }
+}
+/**
+ * Convert a little-endian buffer into a BigInt.
+ * @param buf The little-endian buffer to convert
+ * @returns A BigInt with the little-endian representation of buf.
+ */
+function toBigIntLE(buf) {
+    if (converter === undefined) {
+        const reversed = Buffer.from(buf);
+        reversed.reverse();
+        const hex = reversed.toString('hex');
+        if (hex.length === 0) {
+            return BigInt(0);
+        }
+        return BigInt(`0x${hex}`);
+    }
+    return converter.toBigInt(buf, false);
+}
+function validateBigIntBuffer() {
+    try {
+        const test = toBigIntLE(Buffer.from([0x01, 0x00]));
+        return test === BigInt(1);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Convert a big-endian buffer into a BigInt
+ * @param buf The big-endian buffer to convert.
+ * @returns A BigInt with the big-endian representation of buf.
+ */
+function toBigIntBE(buf) {
+    if (converter === undefined) {
+        const hex = buf.toString('hex');
+        if (hex.length === 0) {
+            return BigInt(0);
+        }
+        return BigInt(`0x${hex}`);
+    }
+    return converter.toBigInt(buf, true);
+}
+/**
+ * Convert a BigInt to a little-endian buffer.
+ * @param num   The BigInt to convert.
+ * @param width The number of bytes that the resulting buffer should be.
+ * @returns A little-endian buffer representation of num.
+ */
+function toBufferLE(num, width) {
+    if (converter === undefined) {
+        const hex = num.toString(16);
+        const buffer = Buffer.from(hex.padStart(width * 2, '0').slice(0, width * 2), 'hex');
+        buffer.reverse();
+        return buffer;
+    }
+    // Allocation is done here, since it is slower using napi in C
+    return converter.fromBigInt(num, Buffer.allocUnsafe(width), false);
+}
+/**
+ * Convert a BigInt to a big-endian buffer.
+ * @param num   The BigInt to convert.
+ * @param width The number of bytes that the resulting buffer should be.
+ * @returns A big-endian buffer representation of num.
+ */
+function toBufferBE(num, width) {
+    if (converter === undefined) {
+        const hex = num.toString(16);
+        return Buffer.from(hex.padStart(width * 2, '0').slice(0, width * 2), 'hex');
+    }
+    return converter.fromBigInt(num, Buffer.allocUnsafe(width), true);
+}
+// ========== Conversion Utilities ==========
+/**
+ * Convert a bigint to a Buffer with automatic sizing.
+ * Uses big-endian encoding and calculates the minimum buffer size needed.
+ * @param num The bigint to convert
+ * @returns A big-endian Buffer representation
+ */
+function bigintToBuf(num) {
+    if (num < BigInt(0)) {
+        throw new Error('bigintToBuf: negative bigint values are not supported');
+    }
+    if (num === BigInt(0)) {
+        return Buffer.from([0]);
+    }
+    // Calculate the number of bytes needed
+    const hex = num.toString(16);
+    const width = Math.ceil(hex.length / 2);
+    return toBufferBE(num, width);
+}
+/**
+ * Convert a Buffer to a bigint.
+ * Assumes big-endian encoding.
+ * @param buf The buffer to convert
+ * @returns A bigint representation of the buffer
+ */
+function bufToBigint(buf) {
+    return toBigIntBE(buf);
+}
+/**
+ * Convert a bigint to a hexadecimal string.
+ * @param num The bigint to convert
+ * @returns A hexadecimal string (without '0x' prefix)
+ */
+function bigintToHex(num) {
+    if (num < BigInt(0)) {
+        throw new Error('bigintToHex: negative bigint values are not supported');
+    }
+    const hex = num.toString(16);
+    // Ensure even length for proper byte representation
+    return hex.length % 2 === 0 ? hex : '0' + hex;
+}
+/**
+ * Convert a hexadecimal string to a bigint.
+ * @param hex The hexadecimal string (with or without '0x' prefix)
+ * @returns A bigint representation
+ */
+function hexToBigint(hex) {
+    // Remove '0x' prefix if present
+    const cleanHex = hex.startsWith('0x') ? hex.slice(2) : hex;
+    if (cleanHex.length === 0) {
+        return BigInt(0);
+    }
+    return BigInt(`0x${cleanHex}`);
+}
+/**
+ * Convert a bigint to a decimal text string.
+ * @param num The bigint to convert
+ * @returns A decimal string representation
+ */
+function bigintToText(num) {
+    return num.toString(10);
+}
+/**
+ * Convert a decimal text string to a bigint.
+ * @param text The decimal string to convert
+ * @returns A bigint representation
+ */
+function textToBigint(text) {
+    if (!text?.trim()) {
+        throw new Error('textToBigint: input string cannot be empty');
+    }
+    try {
+        return BigInt(text);
+    }
+    catch (e) {
+        throw new Error(`textToBigint: invalid decimal string "${text}"`);
+    }
+}
+/**
+ * Convert a bigint to a base64 string.
+ * @param num The bigint to convert
+ * @returns A base64 string representation
+ */
+function bigintToBase64(num) {
+    if (num < BigInt(0)) {
+        throw new Error('bigintToBase64: negative bigint values are not supported');
+    }
+    const buf = bigintToBuf(num);
+    return buf.toString('base64');
+}
+/**
+ * Convert a base64 string to a bigint.
+ * @param base64 The base64 string to convert
+ * @returns A bigint representation
+ */
+function base64ToBigint(base64) {
+    if (!base64?.trim()) {
+        throw new Error('base64ToBigint: input string cannot be empty');
+    }
+    // Trim whitespace and validate base64 format (allows padding)
+    const cleaned = base64.trim();
+    if (!/^[A-Za-z0-9+/]+=*$/.test(cleaned)) {
+        throw new Error('base64ToBigint: invalid base64 string format');
+    }
+    const buf = Buffer.from(cleaned, 'base64');
+    return bufToBigint(buf);
+}

package/dist/node.js

@@ -11,14 +11,24 @@ exports.toBufferBE = toBufferBE;
 // etc.
 const bindings_1 = __importDefault(require("bindings"));
 (0, bindings_1.default)('bigint_buffer');
+let converter;
 exports.isNative = false;
+{
+    try {
+        converter = require('bindings')('bigint_buffer');
+        exports.isNative = !false && converter !== undefined;
+    }
+    catch (e) {
+        console.warn('bigint: Failed to load bindings, pure JS will be used (try npm run rebuild?)');
+    }
+}
 /**
  * Convert a little-endian buffer into a BigInt.
  * @param buf The little-endian buffer to convert
  * @returns A BigInt with the little-endian representation of buf.
  */
 function toBigIntLE(buf) {
-    {
+    if (converter === undefined) {
         const reversed = Buffer.from(buf);
         reversed.reverse();
         const hex = reversed.toString('hex');
@@ -27,6 +37,7 @@ function toBigIntLE(buf) {
         }
         return BigInt(`0x${hex}`);
     }
+    return converter.toBigInt(buf, false);
 }
 function validateBigIntBuffer() {
     try {
@@ -43,13 +54,14 @@ function validateBigIntBuffer() {
  * @returns A BigInt with the big-endian representation of buf.
  */
 function toBigIntBE(buf) {
-    {
+    if (converter === undefined) {
         const hex = buf.toString('hex');
         if (hex.length === 0) {
             return BigInt(0);
         }
         return BigInt(`0x${hex}`);
     }
+    return converter.toBigInt(buf, true);
 }
 /**
  * Convert a BigInt to a little-endian buffer.
@@ -58,12 +70,14 @@ function toBigIntBE(buf) {
  * @returns A little-endian buffer representation of num.
  */
 function toBufferLE(num, width) {
-    {
+    if (converter === undefined) {
         const hex = num.toString(16);
         const buffer = Buffer.from(hex.padStart(width * 2, '0').slice(0, width * 2), 'hex');
         buffer.reverse();
         return buffer;
     }
+    // Allocation is done here, since it is slower using napi in C
+    return converter.fromBigInt(num, Buffer.allocUnsafe(width), false);
 }
 /**
  * Convert a BigInt to a big-endian buffer.
@@ -72,8 +86,9 @@ function toBufferLE(num, width) {
  * @returns A big-endian buffer representation of num.
  */
 function toBufferBE(num, width) {
-    {
+    if (converter === undefined) {
         const hex = num.toString(16);
         return Buffer.from(hex.padStart(width * 2, '0').slice(0, width * 2), 'hex');
     }
+    return converter.fromBigInt(num, Buffer.allocUnsafe(width), true);
 }

package/helper/bigint.d.ts

@@ -1,3 +1,3 @@
 // not used by code, only for documentation generation (since typedoc can't handle BigInt yet)
-type BigIntDoc = number
-declare const BigIntDoc: typeof Number
+type BigInt = number
+declare const BigInt: typeof Number