cstruct-buffer

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());
}

Compatibility Notes

• Bit fields are NOT supported
• Flexible arrays must be last field
• Default alignment follows compiler behavior
• Struct nesting depth is unlimited

License

MIT