or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

buffer-conversion.mdbuffer-management.mdfloating-point-operations.mdindex.mdinteger-operations.mdstring-operations.mdvarint-operations.md
tile.json

tessl/npm-bytebuffer

The swiss army knife for binary data in JavaScript

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/bytebuffer@5.0.x

To install, run

npx @tessl/cli install tessl/npm-bytebuffer@5.0.0

index.mddocs/

ByteBuffer

ByteBuffer.js is a comprehensive JavaScript library for efficient binary data manipulation that provides a fast and complete ByteBuffer implementation using ArrayBuffers in browsers or Node.js Buffers on the server. It offers extensive binary data operations including support for all integer types, floating point numbers, protobuf-style varints with zig-zag encoding, multiple string encodings, and comprehensive buffer manipulation operations.

Package Information

  • Package Name: bytebuffer
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install bytebuffer

Core Imports

const ByteBuffer = require("bytebuffer");

For browsers (using global script):

// ByteBuffer is available as global variable
const bb = new ByteBuffer();

Basic Usage

const ByteBuffer = require("bytebuffer");

// Create a new ByteBuffer with default capacity (16 bytes)
const bb = new ByteBuffer();

// Write different data types
bb.writeInt32(42);
bb.writeFloat(3.14);
bb.writeUTF8String("Hello World!");

// Prepare for reading
bb.flip();

// Read the data back
const intValue = bb.readInt32();      // 42
const floatValue = bb.readFloat();    // 3.14
const stringValue = bb.readUTF8String(bb.readVarint32()); // "Hello World!"

// Convert to different formats
const base64 = bb.toBase64();
const hexString = bb.toHex();
const buffer = bb.toBuffer(); // Node.js Buffer

Architecture

ByteBuffer is built around several key components:

  • Cross-Platform Support: Automatically adapts to environment (Node.js Buffer / Browser ArrayBuffer)
  • Multiple Variants: Three API-compatible versions (bytebuffer, bytebuffer-dataview, bytebuffer-node)
  • Type System: Comprehensive support for all binary data types with endianness control
  • Position Management: Sophisticated position and limit management with mark/reset capabilities
  • String Encodings: Multiple encoding support (UTF-8, Base64, hex, binary, debug)
  • Performance Options: Optional assertion checking and memcpy binding for optimization

Capabilities

Buffer Creation and Management

Core buffer creation, resizing, and management operations for working with binary data containers.

// Static factory methods
ByteBuffer.allocate(capacity, littleEndian, noAssert);
ByteBuffer.wrap(buffer, encoding, littleEndian, noAssert);
ByteBuffer.concat(buffers, encoding, littleEndian, noAssert);

// Constructor
new ByteBuffer(capacity, littleEndian, noAssert);

// Buffer management
capacity();
resize(capacity);
ensureCapacity(capacity);
clear();
flip();

Buffer Management

Integer Operations

Read and write operations for 8, 16, 32, and 64-bit signed and unsigned integers with endianness support.

// 8-bit integers
writeInt8(value, offset);
readInt8(offset);
writeUint8(value, offset);
readUint8(offset);

// 16-bit integers
writeInt16(value, offset);
readInt16(offset);
writeUint16(value, offset);
readUint16(offset);

// 32-bit integers
writeInt32(value, offset);
readInt32(offset);
writeUint32(value, offset);
readUint32(offset);

// 64-bit integers (requires Long.js)
writeInt64(value, offset);
readInt64(offset);
writeUint64(value, offset);
readUint64(offset);

Integer Operations

Floating Point Operations

Read and write operations for 32-bit and 64-bit floating point numbers.

// 32-bit floats
writeFloat32(value, offset);
readFloat32(offset);

// 64-bit doubles
writeFloat64(value, offset);
readFloat64(offset);

Floating Point Operations

Variable Integer Encoding

Protobuf-style variable-length integer encoding with ZigZag support for efficient storage of integers.

// Varint32 operations
writeVarint32(value, offset);
readVarint32(offset);
writeVarint32ZigZag(value, offset);
readVarint32ZigZag(offset);

// Varint64 operations
writeVarint64(value, offset);
readVarint64(offset);
writeVarint64ZigZag(value, offset);
readVarint64ZigZag(offset);

// Utility functions
ByteBuffer.calculateVarint32(value);
ByteBuffer.zigZagEncode32(n);
ByteBuffer.zigZagDecode32(n);

Variable Integer Encoding

String Operations

Read and write operations for strings with multiple encoding formats and length-prefixed variants.

// UTF-8 strings
writeUTF8String(str, offset);
readUTF8String(length, metrics, offset);

// C-style null-terminated strings
writeCString(str, offset);
readCString(offset);

// Length-prefixed strings
writeIString(str, offset);  // uint32 length
readIString(offset);
writeVString(str, offset);  // varint32 length
readVString(offset);

// String utilities
ByteBuffer.calculateUTF8Bytes(str);
ByteBuffer.calculateUTF8Chars(str);

String Operations

Buffer Conversion and Encoding

Convert between different buffer formats and encode/decode using various schemes.

// Buffer conversion
toBuffer(forceCopy);
toArrayBuffer();

// String encoding/decoding
toString(encoding, begin, end);
toBase64(begin, end);
toHex(begin, end);
toBinary(begin, end);
toUTF8(begin, end);
toDebug(columns);

// Factory methods from encodings
ByteBuffer.fromBase64(str, littleEndian);
ByteBuffer.fromHex(str, littleEndian, noAssert);
ByteBuffer.fromBinary(str, littleEndian);
ByteBuffer.fromUTF8(str, littleEndian, noAssert);

Buffer Conversion and Encoding

Types

/**
 * ByteBuffer constructor options and properties
 */
interface ByteBufferOptions {
  capacity?: number;      // Initial capacity (default: 16)
  littleEndian?: boolean; // Byte order (default: false for big endian)
  noAssert?: boolean;     // Skip assertions (default: false)
}

/**
 * ByteBuffer instance properties
 */
interface ByteBufferInstance {
  buffer: Buffer | ArrayBuffer;  // Backing buffer
  view?: Uint8Array | DataView; // Typed array view (browser only)
  offset: number;               // Current read/write position
  limit: number;               // End boundary of valid data
  markedOffset: number;        // Marked position (-1 if not set)
  littleEndian: boolean;       // Byte order flag
  noAssert: boolean;          // Assertion skip flag
}

/**
 * String metrics for UTF-8 operations
 */
const METRICS_CHARS = 'c';  // Character-based metrics
const METRICS_BYTES = 'b';  // Byte-based metrics

Constants

// Version
ByteBuffer.VERSION = "5.0.1";

// Endianness constants
ByteBuffer.LITTLE_ENDIAN = true;
ByteBuffer.BIG_ENDIAN = false;

// Default configuration
ByteBuffer.DEFAULT_CAPACITY = 16;
ByteBuffer.DEFAULT_ENDIAN = ByteBuffer.BIG_ENDIAN;
ByteBuffer.DEFAULT_NOASSERT = false;

// Varint limits
ByteBuffer.MAX_VARINT32_BYTES = 5;
ByteBuffer.MAX_VARINT64_BYTES = 10;

// String metrics
ByteBuffer.METRICS_CHARS = 'c';
ByteBuffer.METRICS_BYTES = 'b';

// External dependencies
ByteBuffer.Long;    // Long.js library reference
ByteBuffer.memcpy;  // Optional memcpy binding