WebBufWebBuf

Core buffers

@webbuf/numbers

Fixed-sized numbers (unsigned, signed, float) optimized with Rust/WASM

Install

npm install @webbuf/numbers

Usage

import {
  decodeSignedBE,
  decodeSignedLE,
  encodeSignedBE,
  encodeSignedLE,
  U8,
  U16BE,
  U16LE,
  U32BE,
  U32LE,
  U64BE,
  U64LE,
  U128BE,
  U128LE,
  U256BE,
  U256LE,
  zigZagEncode,
  zigZagDecode,
} from "@webbuf/numbers";

const signedBE = encodeSignedBE(-129n);
const signedLE = encodeSignedLE(-129n);
if (signedBE.toHex() !== "ff7f" || signedLE.toHex() !== "7fff")
  throw new Error("Wrong signed byte order");
if (decodeSignedBE(signedBE) !== -129n || decodeSignedLE(signedLE) !== -129n)
  throw new Error("Wrong signed value");
if (encodeSignedBE(-128n, 2).toHex() !== "ff80")
  throw new Error("Expected explicit sign extension");
if (encodeSignedLE(0n, 0).length !== 0 || encodeSignedBE(0n).toHex() !== "00")
  throw new Error("Wrong zero encoding");

if (zigZagEncode(-2n) !== 3n) throw new Error("Wrong ZigZag encoding");
if (zigZagDecode(3n) !== -2n) throw new Error("Wrong ZigZag decoding");

// Create from number or bigint
const a = U32BE.fromN(1000);
const b = U64BE.fromBn(0x123456789abcdef0n);

// Arithmetic
const sum = a.add(U32BE.fromN(500));
const diff = a.sub(U32BE.fromN(100));
const product = a.mul(U32BE.fromN(2));
const quotient = a.div(U32BE.fromN(10));

// Convert to number/bigint
a.n; // 1000 (number)
a.bn; // 1000n (bigint)

// Buffer conversions
const beBuf = a.toBEBuf(); // Big-endian FixedBuf
const leBuf = a.toLEBuf(); // Little-endian FixedBuf
const restored = U32BE.fromBEBuf(beBuf);

// Hex conversions
const hex = a.toHex(); // "000003e8"
const fromHex = U32BE.fromHex("000003e8");

API reference (22 exports)

Functions

decodeSignedBE

function

Decode selected big-endian two's-complement bytes, accepting sign extension. Empty input is 0n. No mutation or copying; invalid kinds and detached or out-of-bounds storage throw TypeError. Not a constant-time operation.

decodeSignedBE(bytes: WebBuf): bigint

decodeSignedLE

function

Decode selected little-endian two's-complement bytes, accepting sign extension. Empty input is 0n. No mutation or copying; invalid kinds and detached or out-of-bounds storage throw TypeError. Not a constant-time operation.

decodeSignedLE(bytes: WebBuf): bigint

decodeSignedMagnitudeBE

function

BE counterpart of decodeSignedMagnitudeLE; sign is in the first byte.

decodeSignedMagnitudeBE(bytes: WebBuf): bigint

decodeSignedMagnitudeLE

function

Decode selected LE signed-magnitude bytes without mutation. Accept padding, empty input and either zero sign (returning 0n). Invalid input kinds or detached/out-of-bounds storage throw TypeError. Not constant-time.

decodeSignedMagnitudeLE(bytes: WebBuf): bigint

encodeSignedBE

function

Encode bigint as big-endian two's complement in independent storage. Default width is minimal and nonempty (zero is 00). Explicit nonnegative safe-integer byteLength sign-extends exactly; width zero accepts only zero. Overflow or invalid numeric width throws RangeError; wrong argument kinds throw TypeError. Never truncates. Native allocation limits still apply. No constant-time or secure-erasure guarantee.

encodeSignedBE(value: bigint, byteLength?: number): WebBuf

encodeSignedLE

function

Encode bigint as little-endian two's complement in independent storage. Default width is minimal and nonempty (zero is 00). Explicit nonnegative safe-integer byteLength sign-extends exactly; width zero accepts only zero. Overflow or invalid numeric width throws RangeError; wrong argument kinds throw TypeError. Never truncates. Native allocation limits still apply. No constant-time or secure-erasure guarantee.

encodeSignedLE(value: bigint, byteLength?: number): WebBuf

encodeSignedMagnitudeBE

function

BE counterpart of encodeSignedMagnitudeLE; sign is in the first byte.

encodeSignedMagnitudeBE(value: bigint, byteLength?: number): WebBuf

encodeSignedMagnitudeLE

function

Encode LE signed magnitude in independent storage. Default width is minimal and nonempty (zero is 00); explicit width zero accepts only zero. Larger widths zero-pad magnitude, placing sign in the highest byte. Invalid widths/overflow throw, never truncate. Not constant-time; native allocation limits apply.

encodeSignedMagnitudeLE(value: bigint, byteLength?: number): WebBuf

zigZagDecode

function

Invert ZigZag; this transform does not read or write encoded bytes.

zigZagDecode(value: bigint): bigint

zigZagEncode

function

Map an arbitrary-precision signed integer to an unsigned integer.

zigZagEncode(value: bigint): bigint

Classes

FixedNum

class
constructor<N extends number>(buf: FixedBuf<N>): FixedNum<N>
buf: FixedBuf<N>
toBn(): bigint
add(other: FixedNum<N>): FixedNum<N>
sub(other: FixedNum<N>): FixedNum<N>
mul(other: FixedNum<N>): FixedNum<N>
div(other: FixedNum<N>): FixedNum<N>
toBEBuf(): FixedBuf<N>
toLEBuf(): FixedBuf<N>
toHex(): string
readonly n: number
readonly bn: bigint

U128BE

class
constructor(buf: FixedBuf<16> | number | bigint): U128BE
static fromBn(bn: bigint): U128BE
static fromN(n: number): U128BE
static fromBEBuf(buf: FixedBuf<16> | WebBuf): U128BE
static fromLEBuf(buf: FixedBuf<16> | WebBuf): U128BE
static fromHex(hex: string): U128BE
toBn(): bigint
add(other: U128BE): U128BE
sub(other: U128BE): U128BE
mul(other: U128BE): U128BE
div(other: U128BE): U128BE
toBEBuf(): FixedBuf<16>
toLEBuf(): FixedBuf<16>
toHex(): string
readonly n: number
readonly bn: bigint
buf: FixedBuf<16>

U128LE

class
constructor(buf: FixedBuf<16> | number | bigint): U128LE
static fromBn(bn: bigint): U128LE
static fromN(n: number): U128LE
static fromBEBuf(buf: FixedBuf<16> | WebBuf): U128LE
static fromLEBuf(buf: FixedBuf<16> | WebBuf): U128LE
static fromHex(hex: string): U128LE
toBn(): bigint
add(other: U128LE): U128LE
sub(other: U128LE): U128LE
mul(other: U128LE): U128LE
div(other: U128LE): U128LE
toBEBuf(): FixedBuf<16>
toLEBuf(): FixedBuf<16>
toHex(): string
readonly n: number
readonly bn: bigint
buf: FixedBuf<16>

U16BE

class
constructor(buf: FixedBuf<2> | number | bigint): U16BE
static fromBn(bn: bigint): U16BE
static fromN(n: number): U16BE
static fromBEBuf(buf: FixedBuf<2> | WebBuf): U16BE
static fromLEBuf(buf: FixedBuf<2> | WebBuf): U16BE
static fromHex(hex: string): U16BE
toBn(): bigint
add(other: U16BE): U16BE
sub(other: U16BE): U16BE
mul(other: U16BE): U16BE
div(other: U16BE): U16BE
toBEBuf(): FixedBuf<2>
toLEBuf(): FixedBuf<2>
toHex(): string
readonly n: number
readonly bn: bigint
buf: FixedBuf<2>

U16LE

class
constructor(buf: FixedBuf<2> | number | bigint): U16LE
static fromBn(bn: bigint): U16LE
static fromN(n: number): U16LE
static fromBEBuf(buf: FixedBuf<2> | WebBuf): U16LE
static fromLEBuf(buf: FixedBuf<2> | WebBuf): U16LE
static fromHex(hex: string): U16LE
toBn(): bigint
add(other: U16LE): U16LE
sub(other: U16LE): U16LE
mul(other: U16LE): U16LE
div(other: U16LE): U16LE
toBEBuf(): FixedBuf<2>
toLEBuf(): FixedBuf<2>
toHex(): string
readonly n: number
readonly bn: bigint
buf: FixedBuf<2>

U256BE

class
constructor(buf: FixedBuf<32> | number | bigint): U256BE
static fromBn(bn: bigint): U256BE
static fromN(n: number): U256BE
static fromBEBuf(buf: FixedBuf<32> | WebBuf): U256BE
static fromLEBuf(buf: FixedBuf<32> | WebBuf): U256BE
static fromHex(hex: string): U256BE
toBn(): bigint
add(other: U256BE): U256BE
sub(other: U256BE): U256BE
mul(other: U256BE): U256BE
div(other: U256BE): U256BE
toBEBuf(): FixedBuf<32>
toLEBuf(): FixedBuf<32>
toHex(): string
readonly n: number
readonly bn: bigint
buf: FixedBuf<32>

U256LE

class
constructor(buf: FixedBuf<32> | number | bigint): U256LE
static fromBn(bn: bigint): U256LE
static fromN(n: number): U256LE
static fromBEBuf(buf: FixedBuf<32> | WebBuf): U256LE
static fromLEBuf(buf: FixedBuf<32> | WebBuf): U256LE
static fromHex(hex: string): U256LE
toBn(): bigint
add(other: U256LE): U256LE
sub(other: U256LE): U256LE
mul(other: U256LE): U256LE
div(other: U256LE): U256LE
toBEBuf(): FixedBuf<32>
toLEBuf(): FixedBuf<32>
toHex(): string
readonly n: number
readonly bn: bigint
buf: FixedBuf<32>

U32BE

class
constructor(buf: FixedBuf<4> | number | bigint): U32BE
static fromBn(bn: bigint): U32BE
static fromN(n: number): U32BE
static fromBEBuf(buf: FixedBuf<4> | WebBuf): U32BE
static fromLEBuf(buf: FixedBuf<4> | WebBuf): U32BE
static fromHex(hex: string): U32BE
toBn(): bigint
add(other: U32BE): U32BE
sub(other: U32BE): U32BE
mul(other: U32BE): U32BE
div(other: U32BE): U32BE
toBEBuf(): FixedBuf<4>
toLEBuf(): FixedBuf<4>
toHex(): string
readonly n: number
readonly bn: bigint
buf: FixedBuf<4>

U32LE

class
constructor(buf: FixedBuf<4> | number | bigint): U32LE
static fromBn(bn: bigint): U32LE
static fromN(n: number): U32LE
static fromBEBuf(buf: FixedBuf<4> | WebBuf): U32LE
static fromLEBuf(buf: FixedBuf<4> | WebBuf): U32LE
static fromHex(hex: string): U32LE
toBn(): bigint
add(other: U32LE): U32LE
sub(other: U32LE): U32LE
mul(other: U32LE): U32LE
div(other: U32LE): U32LE
toBEBuf(): FixedBuf<4>
toLEBuf(): FixedBuf<4>
toHex(): string
readonly n: number
readonly bn: bigint
buf: FixedBuf<4>

U64BE

class
constructor(buf: FixedBuf<8> | number | bigint): U64BE
static fromBn(bn: bigint): U64BE
static fromN(n: number): U64BE
static fromBEBuf(buf: FixedBuf<8> | WebBuf): U64BE
static fromLEBuf(buf: FixedBuf<8> | WebBuf): U64BE
static fromHex(hex: string): U64BE
toBn(): bigint
add(other: U64BE): U64BE
sub(other: U64BE): U64BE
mul(other: U64BE): U64BE
div(other: U64BE): U64BE
toBEBuf(): FixedBuf<8>
toLEBuf(): FixedBuf<8>
toHex(): string
readonly n: number
readonly bn: bigint
buf: FixedBuf<8>

U64LE

class
constructor(buf: FixedBuf<8> | number | bigint): U64LE
static fromBn(bn: bigint): U64LE
static fromN(n: number): U64LE
static fromBEBuf(buf: FixedBuf<8> | WebBuf): U64LE
static fromLEBuf(buf: FixedBuf<8> | WebBuf): U64LE
static fromHex(hex: string): U64LE
toBn(): bigint
add(other: U64LE): U64LE
sub(other: U64LE): U64LE
mul(other: U64LE): U64LE
div(other: U64LE): U64LE
toBEBuf(): FixedBuf<8>
toLEBuf(): FixedBuf<8>
toHex(): string
readonly n: number
readonly bn: bigint
buf: FixedBuf<8>

U8

class
constructor(buf: FixedBuf<1> | number | bigint): U8
static fromBn(bn: bigint): U8
static fromN(n: number): U8
static fromBEBuf(buf: FixedBuf<1> | WebBuf): U8
static fromLEBuf(buf: FixedBuf<1> | WebBuf): U8
static fromHex(hex: string): U8
toBn(): bigint
add(other: U8): U8
sub(other: U8): U8
mul(other: U8): U8
div(other: U8): U8
toBEBuf(): FixedBuf<1>
toLEBuf(): FixedBuf<1>
toHex(): string
readonly n: number
readonly bn: bigint
buf: FixedBuf<1>