Core buffers

@webbuf/webbuf

Rust/WASM optimized buffers

Install

npm install @webbuf/webbuf

Usage

import { WebBuf } from "@webbuf/webbuf";

// Create from various sources
const backing = new Uint8Array([0xee, 72, 105, 0xff]);
const selected = WebBuf.view(backing.subarray(1, 3));
new TextDecoder().decode(selected.bytes); // "Hi", not the sentinels
const shared = selected.subarray(0, 1);
const copied = selected.slice(0, 1);
shared.bytes[0] = 66;
selected.toUtf8(); // "Bi": subarray shares storage
copied.toUtf8(); // "H": slice owns a copy
selected instanceof Uint8Array; // false
ArrayBuffer.isView(selected); // false

const buf1 = WebBuf.alloc(32);
const buf2 = WebBuf.fromHex("deadbeef");
const buf3 = WebBuf.fromBase64("SGVsbG8=");
const buf4 = WebBuf.fromUtf8("Hello, world!");
const buf5 = WebBuf.fromArray([1, 2, 3, 4]);

// Convert to strings
buf2.toHex(); // "deadbeef"
buf3.toBase64(); // "SGVsbG8="
buf4.toUtf8(); // "Hello, world!"

// Buffer operations
const combined = WebBuf.concat([buf1, buf2]);
const cloned = buf1.clone();
const reversed = buf1.toReverse();

// Comparison
buf1.equals(buf2); // false
buf1.compare(buf2); // -1, 0, or 1

WebBuf 4 byte access

This is the in-progress WebBuf 4 source contract, not a claim that version 4 is already published. WebBuf has a Uint8Array; it is not a Uint8Array. Use buf.bytes[i] for indexed access and pass buf.bytes to TextDecoder, Web Crypto, Node Buffer and WASM. The wrapper itself is not a native BufferSource.

The bytes property is readonly in TypeScript, but its contents are mutable. Native views preserve the selected byte offset and length. Iteration, length, byteLength, byteOffset, buffer and named encoding helpers remain available.

view, subarray and read share selected storage; slice, clone and fromUint8Array copy. Constructing from an ArrayBuffer views it; constructing from an array or iterable copies it. from without a mapper shares native-array or WebBuf input, while a mapper produces a copy.

Stored bytes use ordinary ArrayBuffer backing. SharedArrayBuffer views cannot be wrapped: explicitly copy them with fromUint8Array(sharedView) or new WebBuf(sharedView). Wrapping a Node Buffer produces a plain Uint8Array view of its selected storage without copying.

API reference (3 exports)

Classes

WebBuf

class

constructor(source?: number | ArrayBuffer | ArrayLike<number> | Iterable<number>, byteOffset?: number, length?: number): WebBuf
static concat(list: (Uint8Array | WebBuf)[]): WebBuf
static alloc(size: number, fill?: number): WebBuf
static view(buffer: Uint8Array | WebBuf): WebBuf
static fromUint8Array(buffer: Uint8Array): WebBuf
static fromArray(array: number[]): WebBuf
static fromUtf8(str: string): WebBuf
static fromString(str: string, encoding?: "utf8" | "hex" | "base64"): WebBuf
static FROM_BASE64_ALGO_THRESHOLD: number
static TO_BASE64_ALGO_THRESHOLD: number
static FROM_HEX_ALGO_THRESHOLD: number
static TO_HEX_ALGO_THRESHOLD: number
static fromHexPureJs(hex: string): WebBuf
static fromHexWasm(hex: string): WebBuf
static fromHex(hex: string): WebBuf
static fromBase64PureJs(b64: string, stripWhitespace?: boolean): WebBuf
static fromBase64Wasm(b64: string, stripWhitespace?: boolean): WebBuf
static fromBase64(b64: string, stripWhitespace?: boolean): WebBuf
static fromBase32(str: string, options?: Base32Options): WebBuf
static from(source: ArrayLike<number> | Iterable<number> | string, mapFn?: ((v: number, k: number) => number) | string, thisArg?: unknown): WebBuf
static compare(buf1: WebBuf, buf2: WebBuf): number
readonly bytes: Uint8Array<ArrayBuffer>
readonly length: number
readonly byteLength: number
readonly byteOffset: number
readonly buffer: ArrayBuffer
set(source: ArrayLike<number> | WebBuf, offset?: number): void
fill(value: number, start?: number, end?: number): WebBuf
slice(start?: number, end?: number): WebBuf
subarray(start?: number, end?: number): WebBuf
reverse(): WebBuf
clone(): WebBuf
toReverse(): WebBuf
copy(target: WebBuf, targetStart?: number, sourceStart?: number, sourceEnd?: number): number
toHexPureJs(): string
toHexWasm(): string
toHex(): string
toBase64PureJs(): string
toBase64Wasm(): string
toBase64(): string
toBase32(options?: Base32Options): string
toUtf8(): string
toString(encoding?: "utf8" | "hex" | "base64"): string
inspect(): string
toArray(): number[]
compare(other: WebBuf): number
equals(other: WebBuf): boolean
write(buf: WebBuf, offset?: number): number
read(offset: number, ext: number): WebBuf
wipe(): void
[Symbol.iterator](): IterableIterator<number>

Interfaces

Base32Options

interface

Options for base32 encoding/decoding

alphabet?: Base32Alphabet
padding?: boolean

Type aliases

Base32Alphabet

type

Base32 alphabet types matching the Rust base32 crate

type Base32Alphabet = "Crockford" | "Rfc4648" | "Rfc4648Lower" | "Rfc4648Hex" | "Rfc4648HexLower" | "Z"