@vekexasia/bigint-buffer2: Fast BigInt/Buffer conversion

This project is part of the bigint-swissknife project. It provides fast BigInt/Buffer conversion with Rust native bindings and a pure JS fallback for browsers.

Why?

The original bigint-buffer library provided a solid foundation for working with BigInts, offering efficient conversion to and from buffers. However, it has several known issues (#40, #59, #22, #12) and lacks browser support.

This library addresses those limitations by providing:

• Native performance via Rust napi-rs bindings for Node.js
• Pure JS fallback for browsers and environments without native support
• Signed BigInt support with two's complement encoding
• Cross-platform native binaries built via CI (linux-x64, linux-arm64, darwin-x64, darwin-arm64, win32-x64)
• Drop-in replacement for the original bigint-buffer

Documentation

You can find typedoc documentation here.

Installation

Add the library to your project:

npm install @vekexasia/bigint-buffer2
Copy

or

yarn add @vekexasia/bigint-buffer2
Copy

Usage

import { toBigIntBE, toBigIntLE, toBufferBE, toBufferLE } from '@vekexasia/bigint-buffer2';

// Buffer to BigInt
const buffer = new Uint8Array([0x01, 0x02, 0x03, 0x04]);
const bigEndian = toBigIntBE(buffer);   // 16909060n
const littleEndian = toBigIntLE(buffer); // 67305985n

// BigInt to Buffer
const be = toBufferBE(16909060n, 4);  // Uint8Array [0x01, 0x02, 0x03, 0x04]
const le = toBufferLE(67305985n, 4);  // Uint8Array [0x01, 0x02, 0x03, 0x04]
Copy

Signed BigInt Support

import { toBigIntBESigned, toBigIntLESigned } from '@vekexasia/bigint-buffer2';

const buffer = new Uint8Array([0xff, 0xff]); // -1 in 2 bytes (two's complement)
const signed = toBigIntBESigned(buffer); // -1n
Copy

Implementation Detection

import { getImplementation } from '@vekexasia/bigint-buffer2';

console.log(getImplementation()); // 'native' or 'js'
Copy

Explicit Implementation Selection

For benchmarking or specific use cases, you can import implementations directly:

// Force JS fallback
import { toBigIntBE } from '@vekexasia/bigint-buffer2/js';

// Force native (Node.js only)
import { toBigIntBE } from '@vekexasia/bigint-buffer2/native';
Copy

TypeScript

The library is entirely written in TypeScript and comes with its own type definitions.

Performance

The toBufferInto methods provide 30-40% speedup over the original bigint-buffer library by avoiding buffer allocation:

Detailed Comparison

The green line shows toBufferBEInto which writes directly into a pre-allocated buffer, eliminating allocation overhead.

Run Benchmarks

npm run benchmark

# Generate charts (requires chart.js)
npx tsx scripts/generate-charts.ts
Copy

License

This project is licensed under the MIT License - see the LICENSE file for details.