Try it Live

Run Uint examples in the interactive playground

Uint64

A branded type for 64-bit unsigned integers (0 to 18,446,744,073,709,551,615). Represented as JavaScript bigint to handle values beyond Number.MAX_SAFE_INTEGER.

Overview

Uint64Type provides:

Compile-time type branding
Range validation (0 to 2^64-1)
Full arithmetic and bitwise operations
Safe handling of large values via bigint

Type Definition

import type { brand } from '../../../brand.js';

export type Uint64Type = bigint & { readonly [brand]: "Uint64" };

Range

Minimum: 0
Maximum: 18,446,744,073,709,551,615 (2^64 - 1)
Size: 64 bits (8 bytes)

Constants

import * as Uint64 from '@voltaire/primitives/Uint64';

Uint64.MIN;   // 0n
Uint64.MAX;   // 18446744073709551615n
Uint64.ZERO;  // 0n
Uint64.ONE;   // 1n
Uint64.SIZE;  // 8 (bytes)

Construction

from

Create from bigint, number, or string:

import * as Uint64 from '@voltaire/primitives/Uint64';

const a = Uint64.from(100n);
const b = Uint64.from(42);
const c = Uint64.from("18446744073709551615");
const d = Uint64.from("0xffffffffffffffff");

fromBigInt

const value = Uint64.fromBigInt(1000000000000n);

fromNumber

const value = Uint64.fromNumber(9007199254740991);  // MAX_SAFE_INTEGER

fromHex

const value = Uint64.fromHex("0xffffffffffffffff");  // MAX

fromBytes

Create from Uint8Array (big-endian, up to 8 bytes):

const bytes = new Uint8Array([0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00]);
const value = Uint64.fromBytes(bytes);  // 4294967296n

fromAbiEncoded

Create from 32-byte ABI-encoded data:

const encoded = new Uint8Array(32);
encoded[31] = 100;
const value = Uint64.fromAbiEncoded(encoded);  // 100n

tryFrom

Safe construction that returns undefined on invalid input:

const valid = Uint64.tryFrom(100n);   // Uint64Type
const invalid = Uint64.tryFrom(-1n);  // undefined

Conversion

toBigInt

const bigint = Uint64.toBigInt(Uint64.from(100n));  // 100n

toNumber

const num = Uint64.toNumber(Uint64.from(100n));  // 100
// Throws if value > Number.MAX_SAFE_INTEGER

toHex

const hex = Uint64.toHex(Uint64.from(255n));  // "0xff"

toBytes

const bytes = Uint64.toBytes(Uint64.from(256n));  // Uint8Array

toAbiEncoded

const encoded = Uint64.toAbiEncoded(Uint64.from(100n));  // 32-byte Uint8Array

toString

const str = Uint64.toString(Uint64.from(18446744073709551615n));
// "18446744073709551615"

Arithmetic

plus

const sum = Uint64.plus(Uint64.from(100n), Uint64.from(50n));  // 150n
// Throws on overflow

minus

const diff = Uint64.minus(Uint64.from(100n), Uint64.from(50n));  // 50n
// Throws on underflow

times

const product = Uint64.times(Uint64.from(1000000n), Uint64.from(1000000n));
// 1000000000000n

dividedBy

const quotient = Uint64.dividedBy(Uint64.from(100n), Uint64.from(7n));  // 14n

modulo

const remainder = Uint64.modulo(Uint64.from(100n), Uint64.from(7n));  // 2n

toPower

const result = Uint64.toPower(Uint64.from(2n), Uint64.from(32n));
// 4294967296n

Comparison

equals

Uint64.equals(Uint64.from(100n), Uint64.from(100n));  // true

lessThan / greaterThan

Uint64.lessThan(Uint64.from(50n), Uint64.from(100n));     // true
Uint64.greaterThan(Uint64.from(100n), Uint64.from(50n));  // true

isZero

Uint64.isZero(Uint64.from(0n));  // true

minimum / maximum

const min = Uint64.minimum(Uint64.from(100n), Uint64.from(50n));  // 50n
const max = Uint64.maximum(Uint64.from(100n), Uint64.from(50n));  // 100n

Bitwise Operations

bitwiseAnd / bitwiseOr / bitwiseXor

const and = Uint64.bitwiseAnd(Uint64.from(0xff00n), Uint64.from(0x0ff0n));
const or = Uint64.bitwiseOr(Uint64.from(0xff00n), Uint64.from(0x00ffn));
const xor = Uint64.bitwiseXor(Uint64.from(0xff00n), Uint64.from(0xf0f0n));

bitwiseNot

const not = Uint64.bitwiseNot(Uint64.from(0n));  // MAX

shiftLeft / shiftRight

const left = Uint64.shiftLeft(Uint64.from(1n), 32);   // 4294967296n
const right = Uint64.shiftRight(Uint64.from(4294967296n), 16);  // 65536n

Bit Analysis

bitLength

Uint64.bitLength(Uint64.from(0n));     // 0
Uint64.bitLength(Uint64.from(255n));   // 8
Uint64.bitLength(Uint64.from(256n));   // 9

leadingZeros

Uint64.leadingZeros(Uint64.from(1n));    // 63
Uint64.leadingZeros(Uint64.from(256n));  // 55

popCount

Uint64.popCount(Uint64.from(0n));            // 0
Uint64.popCount(Uint64.from(255n));          // 8
Uint64.popCount(Uint64.from(0b10101010n));   // 4

Validation

isValid

Uint64.isValid(100n);                       // true
Uint64.isValid(18446744073709551615n);      // true
Uint64.isValid(-1n);                        // false
Uint64.isValid(18446744073709551616n);      // false

Use Cases

Nanosecond timestamps: High-precision timing
File sizes: Large file sizes in bytes
Database IDs: Auto-incrementing identifiers
Counters: Large event counters
Cumulative gas: Total gas across many transactions
Token supply: Tokens with high supply counts

Example: High-Precision Timing

import * as Uint64 from '@voltaire/primitives/Uint64';

// Nanosecond precision timestamp
const nanos = Uint64.from(1735689600000000000n);  // Jan 1, 2025 in nanoseconds

// Convert to seconds
const billion = Uint64.from(1000000000n);
const seconds = Uint64.dividedBy(nanos, billion);

// Calculate duration
const startNanos = Uint64.from(1735689600000000000n);
const endNanos = Uint64.from(1735689601500000000n);
const durationNanos = Uint64.minus(endNanos, startNanos);  // 1.5 billion nanoseconds

Example: Large File Handling

import * as Uint64 from '@voltaire/primitives/Uint64';

// File size in bytes (10 TB)
const fileSize = Uint64.from(10995116277760n);

// Convert to human-readable
const KB = Uint64.from(1024n);
const MB = Uint64.times(KB, KB);
const GB = Uint64.times(MB, KB);
const TB = Uint64.times(GB, KB);

const sizeInTB = Uint64.dividedBy(fileSize, TB);
console.log(`${Uint64.toString(sizeInTB)} TB`);  // "10 TB"

Why Uint64 Uses BigInt

JavaScript’s Number type can only safely represent integers up to 2^53-1 (9,007,199,254,740,991). Since Uint64’s maximum value is 2^64-1, it requires bigint for accurate representation:

// Number loses precision beyond MAX_SAFE_INTEGER
const unsafe = 9007199254740993;  // Actually stored as 9007199254740992

// BigInt maintains full precision
const safe = 9007199254740993n;  // Exactly 9007199254740993

API Reference

Category	Methods
Construction	`from`, `fromNumber`, `fromBigInt`, `fromHex`, `fromBytes`, `fromAbiEncoded`, `tryFrom`
Conversion	`toNumber`, `toBigInt`, `toHex`, `toBytes`, `toAbiEncoded`, `toString`, `clone`
Arithmetic	`plus`, `minus`, `times`, `dividedBy`, `modulo`, `toPower`
Comparison	`equals`, `lessThan`, `greaterThan`, `isZero`, `minimum`, `maximum`
Bitwise	`bitwiseAnd`, `bitwiseOr`, `bitwiseXor`, `bitwiseNot`, `shiftLeft`, `shiftRight`
Bit Analysis	`bitLength`, `leadingZeros`, `popCount`
Validation	`isValid`

Try it Live

​Uint64

​Overview

​Type Definition

​Range

​Constants

​Construction

​from

​fromBigInt

​fromNumber

​fromHex

​fromBytes

​fromAbiEncoded

​tryFrom

​Conversion

​toBigInt

​toNumber

​toHex

​toBytes

​toAbiEncoded

​toString

​Arithmetic

​plus

​minus

​times

​dividedBy

​modulo

​toPower

​Comparison

​equals

​lessThan / greaterThan

​isZero

​minimum / maximum

​Bitwise Operations

​bitwiseAnd / bitwiseOr / bitwiseXor

​bitwiseNot

​shiftLeft / shiftRight

​Bit Analysis

​bitLength

​leadingZeros

​popCount

​Validation

​isValid

​Use Cases

​Example: High-Precision Timing

​Example: Large File Handling

​Why Uint64 Uses BigInt

​API Reference