CStruct-Buffer

A TypeScript library for precise C-style memory layout serialization/deserialization.

Core Features

• 🏗️ Define structs with C-like memory layout
• 🔢 Support for all major numeric types (8/16/32/64-bit, signed/unsigned, float/double)
• 📝 String support (ASCII/UTF-8)
• 🧩 Nested structs and arrays
• ⚡ Optimized binary serialization/deserialization
• ↔️ Endianness control (little/big endian)
• 🧠 Automatic alignment and padding calculation
• 🔍 Runtime validation and error checking

Installation

npm install cstruct-buffer

Basic Usage

Struct Definition

@CStruct.Layout({ pack: 4 })
class SensorData extends CStruct {
  @CStruct.U32(1, 8)  // Single value with 8-byte alignment
  timestamp: number = 0;
  
  @CStruct.F64(3)     // Fixed array of 3 doubles
  readings: number[] = [0.0, 0.0, 0.0];
  
  @CStruct.Str(0, 1)  // Flexible string (last field)
  status: string = "OK";
}

Decorator Specifications

Class Layout Options

@CStruct.Layout({ 
  pack?: number;  // Member alignment (0=default)
  align?: number; // Struct alignment (0=natural)
})

Field Decorator Parameters

Primitive Types (U8/I16/F32 etc.)

@CStruct.U8(arrLength?, align?)
@CStruct.U16(arrLength?, align?)
@CStruct.U32(arrLength?, align?)
@CStruct.U64(arrLength?, align?)
@CStruct.I8(arrLength?, align?)
@CStruct.I16(arrLength?, align?)
@CStruct.I32(arrLength?, align?)
@CStruct.I64(arrLength?, align?)
@CStruct.F32(arrLength?, align?)
@CStruct.F64(arrLength?, align?)

| Position | Parameter | Description |----------|---------------|------------------------- | 1 | arrLength = 1 | Array length: 0=flexible, 1=single, >1=fixed | 2 | align = 0 | Field alignment (optional, default=0)

String Types

@CStruct.Str(maxBytes, align?)

| Position | Parameter | Description |----------|--------------|------------------------- | 1 | maxBytes = 0 | Max bytes (0=flexible length) | 2 | align = 0 | Field alignment (optional)

Struct Types

@CStruct.Struct(StructClass, arrLength?, align?)

| Position | Parameter | Description |----------|---------------|------------------------- | 1 | StructClass | Nested struct class (must extend CStruct) | 2 | arrLength = 1 | Array length | 3 | align = 0 | Field alignment (optional, default=0)

Advanced Patterns

Nested Structures

@CStruct.Layout({ pack: 8 })
class Vector3D extends CStruct {
  @CStruct.F32(3) coordinates: number[] = [0,0,0];
}

@CStruct.Layout({ align: 16 })
class PhysicsObject extends CStruct {
  @CStruct.Struct(Vector3D) 
  position: Vector3D = new Vector3D();
  
  @CStruct.Struct(Vector3D, 4)  // Fixed array of 4 vectors
  vertices: Vector3D[] = Array(4).fill(new Vector3D());
}

Core Operations

Serialization

const sensor = new SensorData();
sensor.timestamp = Date.now();
sensor.readings = [25.3, 26.1, 24.9];
sensor.status = "ACTIVE";

// Serialize with default endianness (little-endian)
const buffer = sensor.serialize();

// Serialize with big-endian
const beBuffer = sensor.serialize('big');

Deserialization

// From network/data stream
const receivedBuffer = new Uint8Array([...]);

// Deserialize with validation
const restoredSensor = SensorData.deserialize(receivedBuffer);

console.log(restoredSensor.status); // "ACTIVE"

Endian Control

// Cross-platform data exchange
const networkBuffer = sensor.serialize('big');
const localCopy = SensorData.deserialize(networkBuffer, 'big');

Memory Layout Validation

// Verify struct size matches C implementation
console.log(sensor.size); // 64 (bytes)

// Check field offsets
console.log(sensor.Fields[0].offset); // 0
console.log(sensor.Fields[1].offset); // 8

Compatibility Notes

1. Bit fields are NOT supported
2. Flexible arrays must be last field
3. Default alignment follows compiler behavior
4. Struct nesting depth is unlimited

License

MIT