Webbuf NPM | npm.io

WebBuf

WebBuf is a powerful, flexible class that extends JavaScript's Uint8Array to provide additional functionality for handling binary data. It includes methods for manipulating binary data, converting to and from different formats (e.g., base64, hex, strings), and reading/writing values in both little-endian and big-endian formats. This library is ideal for applications that need efficient and low-level control over binary data, like encoding/decoding or working with protocols. It also supports "fixed-size" buffers with the FixedBuf class, which enforces a specific buffer size at compile-time.

Finally, the base64 and hex conversion methods are written in rust and built to WebAssembly for performance. They are about five times faster than pure JavaScript implementations for large data (~ 10 MB).

Features

Extended Uint8Array with extra methods for binary manipulation.
Conversion methods: supports Base64, Hex, Strings, and arrays.
Efficient concatenation and allocation methods.
Clone and copy functionality for working with buffers.
Support for reading and writing unsigned and signed integers in both Little Endian (LE) and Big Endian (BE) formats, including 8-bit, 16-bit, 32-bit, 64-bit, 128-bit, and 256-bit integers.
Utility methods like compare, equals, fill, and more.

Installation

Install via npm:

npm install webbuf

Usage

Basic Usage

import { WebBuf } from "webbuf";

// Allocating a buffer
const buf = WebBuf.alloc(10);

// Filling the buffer
buf.fill(0);

// Working with base64
const base64Str = buf.toBase64();
const decodedBuf = WebBuf.fromBase64(base64Str);

// Cloning a buffer
const clonedBuf = buf.clone();

// Comparing buffers
const anotherBuf = WebBuf.alloc(10);
console.log(buf.equals(anotherBuf)); // false

Conversion Examples

String to WebBuf:

const buf = WebBuf.fromString("Hello, World!");
console.log(buf.toString()); // Outputs: Hello, World!

Hex to WebBuf:

const hexBuf = WebBuf.fromHex("48656c6c6f");
console.log(hexBuf.toString()); // Outputs: Hello

Base64 to WebBuf:

const base64Buf = WebBuf.fromBase64("SGVsbG8=");
console.log(base64Buf.toString()); // Outputs: Hello

Reading and Writing Data

Read/Write Integers:

const buf = WebBuf.alloc(8);

// Writing a 32-bit little-endian integer
buf.writeUint32LE(123456, 0);

// Reading the value back
const val = buf.readUint32LE(0);
console.log(val); // Outputs: 123456

Working with BigInt:

const buf = WebBuf.alloc(16);

// Writing a 128-bit little-endian BigInt
buf.writeBigUint128LE(0x1234567890abcdef1234567890abcdefn, 0);

// Reading the value back
const bigVal = buf.readBigUint128LE(0);
console.log(bigVal.toString(16)); // Outputs: 1234567890abcdef1234567890abcdef

API Reference

Static Methods

WebBuf.concat(list: Uint8Array[]): WebBuf
Concatenates a list of Uint8Array or WebBuf into a single WebBuf.
WebBuf.alloc(size: number): WebBuf
Allocates a new WebBuf of the specified size.
WebBuf.fromUint8Array(buffer: Uint8Array): WebBuf
Returns a WebBuf that is a view of the same data as the input Uint8Array.
WebBuf.fromArray(array: number[]): WebBuf
Creates a WebBuf from an array of numbers.
WebBuf.fromString(str: string): WebBuf
Converts a string into a WebBuf.
WebBuf.fromHex(hex: string): WebBuf
Converts a hex string to a WebBuf.
WebBuf.fromBase64(b64: string): WebBuf
Converts a base64 string into a WebBuf.
WebBuf.from(source, mapFn?, thisArg?): WebBuf
Overrides the Uint8Array.from method to return a WebBuf.

Instance Methods

toBase64(): string
Converts the WebBuf to a base64 string.
toString(): string
Converts the WebBuf to a UTF-8 string.
toHex(): string
Converts the WebBuf to a hexadecimal string.
toArray(): number[]
Converts the WebBuf to a standard array of numbers.
clone(): WebBuf
Returns a copy of the WebBuf.
compare(other: WebBuf): number
Compares two buffers lexicographically. Returns 0 if equal, -1 if this is smaller, or 1 if this is larger.
equals(other: WebBuf): boolean
Returns true if the contents of two buffers are identical.
copy(target: WebBuf, targetStart?: number, sourceStart?: number, sourceEnd?: number): number
Copies a section of WebBuf data to another WebBuf.

Reading/Writing Numbers

Read and write unsigned integers (8-bit, 16-bit, 32-bit, 64-bit, 128-bit, 256-bit) in both Little Endian (LE) and Big Endian (BE) formats:
- readUintLE, readUintBE
- readUint8, readUint16LE, readUint16BE
- readUint32LE, readUint32BE
- readBigUint64LE, readBigUint64BE
- writeUintLE, writeUintBE, writeBigUint64LE, writeBigUint64BE
- writeBigUint128LE, writeBigUint128BE
- writeBigUint256LE, writeBigUint256BE
Read and write signed integers in both Little Endian and Big Endian formats:
- readIntLE, readIntBE
- readInt8, readInt16LE, readInt16BE
- readInt32LE, readInt32BE
- readBigInt64LE, readBigInt64BE
- readBigInt128LE, readBigInt128BE
- readBigInt256LE, readBigInt256BE

FixedBuf

The FixedBuf class is a specialized extension of the WebBuf class designed to manage buffers with a fixed size at compile-time. This class provides a way to work with fixed-size buffers in TypeScript, ensuring that the size of the buffer is known and enforced by the type system. It also offers various utilities for creating, encoding, and cloning fixed-size buffers, while retaining all the powerful features of WebBuf.

Features:

Fixed Size: FixedBuf enforces the buffer size at both runtime and compile-time, ensuring that all operations adhere to the specified buffer size.
Flexible Construction: You can create a FixedBuf from existing buffers, random data, hexadecimal strings, or Base64-encoded strings.
Serialization Support: Convert buffers to/from hexadecimal and Base64 formats.
Cloning: Create deep copies of fixed-size buffers.

Constructor

constructor(size: N, buf: WebBuf)

Creates a new FixedBuf of size N, wrapping around an existing WebBuf instance. The size is enforced at runtime, ensuring that the provided WebBuf matches the fixed size.

Methods

buf: WebBuf
Returns the underlying WebBuf instance.
```
get buf(): WebBuf;
```

Static Methods

fromBuf<N>(size: N, buf: WebBuf): FixedBuf<N>
Creates a FixedBuf from an existing WebBuf of a specific size.
```
const fixedBuf = FixedBuf.fromBuf(32, someWebBuf);
```
alloc<N>(size: N, fill?: number): FixedBuf<N>
Allocates a new FixedBuf of a fixed size, optionally filled with the specified value. If no value is provided, the buffer will be initialized with zeros.
```
const buf = FixedBuf.alloc(16, 0xff); // 16-byte buffer filled with 0xff
```
fromHex<N>(size: N, hex: string): FixedBuf<N>
Creates a FixedBuf of a specific size from a hexadecimal string. The hex string must match the required length of the buffer.
```
const buf = FixedBuf.fromHex(16, "deadbeefcafebabe...");
```
fromBase64(size: number, base64: string): FixedBuf<number>
Creates a FixedBuf from a Base64-encoded string. The size of the resulting buffer is determined by the size parameter.
```
const buf = FixedBuf.fromBase64(16, "SGVsbG8gd29ybGQ=");
```
fromRandom<N>(size: N): FixedBuf<N>
Creates a FixedBuf of the given size filled with cryptographically secure random bytes.
```
const buf = FixedBuf.fromRandom(16);
```

Instance Methods

toHex(): string
Converts the FixedBuf to a hexadecimal string representation.
```
const hex = fixedBuf.toHex();
```
toBase64(): string
Converts the FixedBuf to a Base64-encoded string.
```
const base64 = fixedBuf.toBase64();
```
clone(): FixedBuf<N>
Creates a deep copy of the FixedBuf.
```
const clonedBuf = fixedBuf.clone();
```

Example Usage

import { WebBuf, FixedBuf } from "webbuf";

// Allocate a FixedBuf of 32 bytes filled with 0x00
const buf = FixedBuf.alloc(32);

// Create a FixedBuf from a hexadecimal string
const hexBuf = FixedBuf.fromHex(16, "deadbeefcafebabe1234567890abcdef");

// Clone the buffer
const clonedBuf = hexBuf.clone();

// Convert to Base64
const base64String = buf.toBase64();

The FixedBuf class provides a robust way to manage fixed-size buffers with added functionality like encoding, randomization, and type enforcement, making it a powerful complement to the WebBuf class for specialized use cases where buffer size consistency is crucial.