Skip to main content

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

CategoryMethods
Constructionfrom, fromNumber, fromBigInt, fromHex, fromBytes, fromAbiEncoded, tryFrom
ConversiontoNumber, toBigInt, toHex, toBytes, toAbiEncoded, toString, clone
Arithmeticplus, minus, times, dividedBy, modulo, toPower
Comparisonequals, lessThan, greaterThan, isZero, minimum, maximum
BitwisebitwiseAnd, bitwiseOr, bitwiseXor, bitwiseNot, shiftLeft, shiftRight
Bit AnalysisbitLength, leadingZeros, popCount
ValidationisValid