cstruct-buffer/README.md

Binary serialization framework for C-style structs

# 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

``` bash
npm install cstruct-buffer
```

## Basic Usage

### Struct Definition

``` typescript
@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
``` typescript
@CStruct.Layout({ 
  pack?: number;  // Member alignment (0=default)
  align?: number; // Struct alignment (0=natural)
})
```

### Field Decorator Parameters

#### Primitive Types (U8/I16/F32 etc.)
``` typescript
@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
``` typescript
@CStruct.Str(maxBytes, align?)
```

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

#### Struct Types
``` typescript
@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
``` typescript
@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
``` typescript
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
``` typescript
// From network/data stream
const receivedBuffer = new Uint8Array([...]);

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

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

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

## Memory Layout Validation
``` typescript
// 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