bigint-swissknife

The missing BigInt toolkit for JavaScript/TypeScript — Fast buffer conversions, math utilities, bounded integers, and more.

Why?

JavaScript's BigInt is powerful but incomplete. The standard library leaves you without:

• Buffer conversion — No native way to convert between BigInt and Uint8Array/Buffer
• Math functions — Math.max(), Math.min(), Math.abs() don't work with BigInt
• Bounded integers — No u8, i32, u256 types with overflow protection
• Random generation — No way to generate cryptographically random BigInts

This monorepo fills those gaps with fast, type-safe, browser-compatible packages.

Packages

Package	Version	Description	Highlights
@chainsafe/bigint-buffer2		BigInt ↔ Buffer conversion	🦀 Rust native bindings, ~30% faster than alternatives
@chainsafe/bigint-uint8array		BigInt ↔ Uint8Array with bounds checking	Signed/unsigned, big/little endian
@chainsafe/bigint-constrained		Bounded BigInts (u8, i32, u256, etc.)	Overflow protection on all operations
@chainsafe/bigint-math		Math utilities for BigInt	abs, sign, max, min, rand, bitLength
@chainsafe/bigint-buffer-polyfill		Buffer prototype extensions	buf.writeBigIntBE(), buf.readBigUIntLE()

Performance

bigint-buffer2 provides native Rust bindings that outperform pure JavaScript implementations:

The red bars (toBufferBEInto) show 30-40% speedup by writing directly into pre-allocated buffers.

Quick Start

# Core buffer conversion (recommended starting point)
npm install @chainsafe/bigint-buffer2

# Or pick what you need
npm install @chainsafe/bigint-uint8array  # bounds-checked conversions
npm install @chainsafe/bigint-constrained # bounded integers
npm install @chainsafe/bigint-math        # math utilities

Examples

// Buffer conversion (bigint-buffer2)
import { toBigIntBE, toBufferBE } from '@chainsafe/bigint-buffer2';
const num = toBigIntBE(new Uint8Array([0x01, 0x02, 0x03]));  // 66051n
const buf = toBufferBE(12345n, 4);  // Uint8Array [0, 0, 48, 57]

// Bounded integers (bigint-constrained)
import { u8, i32 } from '@chainsafe/bigint-constrained';
const byte = u8(255n);
byte.add(1n);  // throws RangeError: overflow

// Math utilities (bigint-math)
import { BigIntMath } from '@chainsafe/bigint-math';
BigIntMath.max(1n, 5n, 3n);        // 5n
BigIntMath.rand(1000000000000n);   // random BigInt 0..1T

Browser Support

All packages work in browsers. bigint-buffer2 automatically falls back to a pure JS implementation when native bindings aren't available.

Documentation

Full API documentation: vekexasia.github.io/bigint-swissknife

License

MIT License - see LICENSE for details.