tessl/npm-bytebuffer

The swiss army knife for binary data in JavaScript

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Integer Operations

Name: tessl/npm-bytebuffer
Author: tessl

Read and write operations for 8, 16, 32, and 64-bit signed and unsigned integers with endianness support. These operations provide comprehensive binary integer I/O capabilities.

Capabilities

8-bit Integer Operations

Read and write 8-bit signed and unsigned integers.

/**
 * Write signed 8-bit integer (-128 to 127)
 * @param {number} value - Integer value to write
 * @param {number} offset - Offset to write at (default: current offset)
 * @returns {ByteBuffer} This ByteBuffer for chaining
 */
writeInt8(value, offset);

/**
 * Alias for writeInt8
 */
writeByte(value, offset);

/**
 * Read signed 8-bit integer (-128 to 127)
 * @param {number} offset - Offset to read from (default: current offset)
 * @returns {number|{value: number, offset: number}} Integer value or result object
 */
readInt8(offset);

/**
 * Alias for readInt8
 */
readByte(offset);

/**
 * Write unsigned 8-bit integer (0 to 255)
 * @param {number} value - Integer value to write
 * @param {number} offset - Offset to write at (default: current offset)
 * @returns {ByteBuffer} This ByteBuffer for chaining
 */
writeUint8(value, offset);

/**
 * Alias for writeUint8
 */
writeUInt8(value, offset);

/**
 * Read unsigned 8-bit integer (0 to 255)
 * @param {number} offset - Offset to read from (default: current offset)
 * @returns {number|{value: number, offset: number}} Integer value or result object
 */
readUint8(offset);

/**
 * Alias for readUint8
 */
readUInt8(offset);

Usage Examples:

const ByteBuffer = require("bytebuffer");
const bb = ByteBuffer.allocate(8);

// Write 8-bit integers
bb.writeInt8(-42);      // Signed byte
bb.writeUint8(255);     // Unsigned byte
bb.writeByte(100);      // Using alias

// Read back
bb.flip();
const signedValue = bb.readInt8();    // -42
const unsignedValue = bb.readUint8(); // 255
const byteValue = bb.readByte();      // 100

// Absolute positioning
bb.writeInt8(50, 0);    // Write at position 0
const value = bb.readInt8(0); // Read from position 0

16-bit Integer Operations

Read and write 16-bit signed and unsigned integers with endianness support.

/**
 * Write signed 16-bit integer (-32768 to 32767)
 * @param {number} value - Integer value to write
 * @param {number} offset - Offset to write at (default: current offset)
 * @returns {ByteBuffer} This ByteBuffer for chaining
 */
writeInt16(value, offset);

/**
 * Alias for writeInt16
 */
writeShort(value, offset);

/**
 * Read signed 16-bit integer (-32768 to 32767)
 * @param {number} offset - Offset to read from (default: current offset)
 * @returns {number|{value: number, offset: number}} Integer value or result object
 */
readInt16(offset);

/**
 * Alias for readInt16
 */
readShort(offset);

/**
 * Write unsigned 16-bit integer (0 to 65535)
 * @param {number} value - Integer value to write
 * @param {number} offset - Offset to write at (default: current offset)
 * @returns {ByteBuffer} This ByteBuffer for chaining
 */
writeUint16(value, offset);

/**
 * Alias for writeUint16
 */
writeUInt16(value, offset);

/**
 * Read unsigned 16-bit integer (0 to 65535)
 * @param {number} offset - Offset to read from (default: current offset)
 * @returns {number|{value: number, offset: number}} Integer value or result object
 */
readUint16(offset);

/**
 * Alias for readUint16
 */
readUInt16(offset);

Usage Examples:

const bb = ByteBuffer.allocate(16);

// Write 16-bit integers (respects current endianness)
bb.writeInt16(-1000);      // Signed short
bb.writeUint16(65000);     // Unsigned short
bb.writeShort(500);        // Using alias

// Endianness affects byte order
bb.LE(); // Switch to little endian
bb.writeInt16(0x1234);     // Will be stored as 0x34, 0x12

bb.BE(); // Switch to big endian  
bb.writeInt16(0x1234);     // Will be stored as 0x12, 0x34

// Read back
bb.flip();
const signedValue = bb.readInt16();    // -1000
const unsignedValue = bb.readUint16(); // 65000
const shortValue = bb.readShort();     // 500

32-bit Integer Operations

Read and write 32-bit signed and unsigned integers with endianness support.

/**
 * Write signed 32-bit integer (-2147483648 to 2147483647)
 * @param {number} value - Integer value to write
 * @param {number} offset - Offset to write at (default: current offset)
 * @returns {ByteBuffer} This ByteBuffer for chaining
 */
writeInt32(value, offset);

/**
 * Alias for writeInt32
 */
writeInt(value, offset);

/**
 * Read signed 32-bit integer (-2147483648 to 2147483647)
 * @param {number} offset - Offset to read from (default: current offset)
 * @returns {number|{value: number, offset: number}} Integer value or result object
 */
readInt32(offset);

/**
 * Alias for readInt32
 */
readInt(offset);

/**
 * Write unsigned 32-bit integer (0 to 4294967295)
 * @param {number} value - Integer value to write
 * @param {number} offset - Offset to write at (default: current offset)
 * @returns {ByteBuffer} This ByteBuffer for chaining
 */
writeUint32(value, offset);

/**
 * Alias for writeUint32
 */
writeUInt32(value, offset);

/**
 * Read unsigned 32-bit integer (0 to 4294967295)
 * @param {number} offset - Offset to read from (default: current offset)
 * @returns {number|{value: number, offset: number}} Integer value or result object
 */
readUint32(offset);

/**
 * Alias for readUint32
 */
readUInt32(offset);

Usage Examples:

const bb = ByteBuffer.allocate(32);

// Write 32-bit integers
bb.writeInt32(-100000);        // Signed int
bb.writeUint32(3000000000);    // Unsigned int
bb.writeInt(42);               // Using alias

// Handle large unsigned values
bb.writeUint32(0xFFFFFFFF);    // Maximum uint32

// Read back
bb.flip();
const signedValue = bb.readInt32();    // -100000
const unsignedValue = bb.readUint32(); // 3000000000
const intValue = bb.readInt();         // 42
const maxValue = bb.readUint32();      // 4294967295

64-bit Integer Operations

Read and write 64-bit signed and unsigned integers using Long.js for JavaScript precision.

/**
 * Write signed 64-bit integer (requires Long.js)
 * @param {number|Long|string} value - Integer value to write
 * @param {number} offset - Offset to write at (default: current offset)
 * @returns {ByteBuffer} This ByteBuffer for chaining
 */
writeInt64(value, offset);

/**
 * Alias for writeInt64
 */  
writeLong(value, offset);

/**
 * Read signed 64-bit integer (requires Long.js)
 * @param {number} offset - Offset to read from (default: current offset)
 * @returns {Long|{value: Long, offset: number}} Long value or result object
 */
readInt64(offset);

/**
 * Alias for readInt64
 */
readLong(offset);

/**
 * Write unsigned 64-bit integer (requires Long.js)
 * @param {number|Long|string} value - Integer value to write
 * @param {number} offset - Offset to write at (default: current offset)
 * @returns {ByteBuffer} This ByteBuffer for chaining
 */
writeUint64(value, offset);

/**
 * Alias for writeUint64
 */
writeUInt64(value, offset);

/**
 * Read unsigned 64-bit integer (requires Long.js)
 * @param {number} offset - Offset to read from (default: current offset)
 * @returns {Long|{value: Long, offset: number}} Long value or result object
 */
readUint64(offset);

/**
 * Alias for readUint64
 */
readUInt64(offset);

Usage Examples:

const ByteBuffer = require("bytebuffer");
const Long = ByteBuffer.Long; // Access to Long.js

const bb = ByteBuffer.allocate(64);

// Write 64-bit integers using Long.js
const bigNumber = Long.fromString("9223372036854775807");
bb.writeInt64(bigNumber);

// Can also use string representation
bb.writeLong("-9223372036854775808");

// Or regular numbers for smaller values
bb.writeUint64(1000000000000);

// Read back as Long objects
bb.flip();
const longValue = bb.readInt64();      // Returns Long object
const minLong = bb.readLong();         // Returns Long object
const uintValue = bb.readUint64();     // Returns Long object

// Convert Long to string or number
console.log(longValue.toString());     // "9223372036854775807"
console.log(longValue.toNumber());     // May lose precision for large values

// Work with Long arithmetic
const sum = longValue.add(Long.fromNumber(100));
bb.writeInt64(sum);

Byte Array Operations

Read and write arrays of bytes.

/**
 * Read specified number of bytes as raw data
 * @param {number} length - Number of bytes to read
 * @param {number} offset - Offset to read from (default: current offset)
 * @returns {ByteBuffer} New ByteBuffer containing the bytes
 */
readBytes(length, offset);

/**
 * Write bytes (alias for append)
 * @param {ByteBuffer|Buffer|ArrayBuffer|Uint8Array|Array} source - Bytes to write
 * @param {string} encoding - String encoding if source is string
 * @param {number} offset - Offset to write at (default: current offset)
 * @returns {ByteBuffer} This ByteBuffer for chaining
 */
writeBytes(source, encoding, offset);

Usage Examples:

const bb = ByteBuffer.allocate(16);

// Write array of bytes
bb.writeBytes([0x48, 0x65, 0x6C, 0x6C, 0x6F]); // "Hello" in ASCII

// Write from another ByteBuffer
const data = ByteBuffer.wrap([1, 2, 3, 4]);
bb.writeBytes(data);

// Read specific number of bytes
bb.flip();
const helloBytes = bb.readBytes(5);  // Gets first 5 bytes
const remaining = bb.readBytes(4);   // Gets next 4 bytes

// Convert bytes to array
const helloArray = helloBytes.toBuffer().slice();
console.log(helloArray); // [0x48, 0x65, 0x6C, 0x6C, 0x6F]

BitSet Operations

Read and write arrays of boolean values as compact bit sets.

/**
 * Write array of booleans as compact bitset
 * @param {Array<boolean>} value - Array of boolean values
 * @param {number} offset - Offset to write at (default: current offset)
 * @returns {ByteBuffer} This ByteBuffer for chaining
 */
writeBitSet(value, offset);

/**
 * Read bitset as array of boolean values
 * @param {number} offset - Offset to read from (default: current offset)
 * @returns {Array<boolean>|{value: Array<boolean>, offset: number}} Boolean array or result object
 */
readBitSet(offset);

Usage Examples:

const bb = ByteBuffer.allocate(16);

// Write boolean array as bitset
const flags = [true, false, true, true, false, false, true, false];
bb.writeBitSet(flags);

// Read back as boolean array
bb.flip();
const readFlags = bb.readBitSet(); // [true, false, true, true, false, false, true, false]

// BitSets are stored efficiently - 8 booleans = 1 byte
console.log(bb.offset); // 1 (only used 1 byte for 8 flags)

Error Handling

Integer operations may throw errors in the following cases:

RangeError: When values exceed the valid range for the integer type
TypeError: When non-numeric values are provided for integer operations
Error: When attempting to read beyond buffer limits (if assertions enabled)
Error: When Long.js is not available for 64-bit operations

Example Error Handling:

const bb = ByteBuffer.allocate(4);

try {
    // This will throw RangeError if assertions enabled
    bb.writeInt8(300); // Value exceeds signed 8-bit range
} catch (error) {
    console.error("Value out of range:", error.message);
}

try {
    // This will throw Error if trying to read beyond buffer
    bb.readInt32(); // Buffer only has 4 bytes but may not have data
} catch (error) {
    console.error("Read error:", error.message);
}

Install with Tessl CLI