fractus

README

Fractus

Fractus is a lightweight, serialization library for Go. It encodes and decodes structs into a compact binary format focused on low allocations and high throughput.

Supported types:

• Fixed-size primitives (int8, int16, int32, int64, uint*, float32, float64, bool)
• Variable-size types (string, []byte, slices of primitives/strings)
• Struct pointers (encoded by value)
• Optional unsafe zero-copy modes for strings and primitive slices (opt-in)

The goal is fast, deterministic encoding/decoding with a small allocation footprint. See docs/FORMAT.md for the wire-format specification.

---

Features

• Struct encoding/decoding: Works with exported fields of Go structs.
• Slices and strings: Handles variable-length data with varint length prefixes.
• Unsafe modes: SafeOptions toggles zero-copy for strings and primitive slices.
• Fuzz & property-based tests: Ensures round-trip correctness.

---

Installation

go get github.com/rawbytedev/fractus

---

Usage

Encode / Decode

package main

import (
    "fmt"
    "github.com/rawbytedev/fractus"
)

type Example struct {
    Name   string
    Age    int32
    Scores []float64
}

func main() {
    f := fractus.NewFractus(fractus.SafeOptions{})

    val := Example{Name: "Alice", Age: 30, Scores: []float64{95.5, 88.0}}
    data, err := f.Encode(val)
    if err != nil {
        panic(err)
    }

    var out Example
    if err := f.Decode(data, &out); err != nil {
        panic(err)
    }

    fmt.Printf("Decoded: %+v\n", out)
}

---

Benchmarks

Fractus aims to minimize allocations and improve throughput:

go test -bench=. -benchmem

With buffer reuse and optional unsafe modes, allocations can be reduced significantly for hot-path encoders and decoders.

---

Testing

Fractus includes fuzz and property-based tests:

go test ./...

• FuzzEncodeDecode ensures correctness across mixed types.
• quick.Check encoding/decoding for random structs.
• Error cases are tested (non-structs, unexported fields, wrong pointer types).

---

Important

• UnsafeStrings: When enabled, decoded strings may alias the original buffer. Ensure the buffer outlives the string usage, or disable this option for safe copies.
• Unexported fields: Skipped during encoding.
• Unsupported types: Maps, interfaces, complex numbers, and nested slices (except []byte) are not supported.

Benchmarks and format

• Benchmarks are available in fractus_bench_test.go (run with go test -bench=. -benchmem).
• Wire-format is documented in docs/FORMAT.md.

---

License

MIT License. See LICENSE for details.

Documentation

Index

• Variables
• func FixedSize(k reflect.Kind) int
• type FieldInfo
• type FieldPlan
• type Fractus
  • func NewFractus(opts SafeOptions) *Fractus
  • func (f *Fractus) Decode(in []byte, out any) (err error)
  • func (f *Fractus) Encode(in any) (out []byte, err error)
  • func (f *Fractus) Reset()
• type SafeDecoder
  • func NewSafeDecoder(fractus *Fractus) *SafeDecoder
  • func (s *SafeDecoder) Decode(data []byte, out any) error
• type SafeOptions

Variables

var (
	ErrNotStruct    = errors.New("expected struct")
	ErrNotStructPtr = errors.New("expected pointer to struct")
	ErrUnsupported  = errors.New("unsupported type")
)

Functions

func FixedSize

func FixedSize(k reflect.Kind) int

Types

type FieldInfo

type FieldInfo struct {
	// contains filtered or unexported fields
}

type FieldPlan

type FieldPlan struct {
	// contains filtered or unexported fields
}

type Fractus

type Fractus struct {
	// Opts controls unsafe behaviour (zero-copy) and alignment checks.
	Opts SafeOptions
	// contains filtered or unexported fields
}

func NewFractus

func NewFractus(opts SafeOptions) *Fractus

NewFractus constructs a new Fractus encoder/decoder. Fractus can be used for both encoding and decoding. Provide SafeOptions to opt into unsafe, zero-copy modes.

func (*Fractus) Decode

func (f *Fractus) Decode(in []byte, out any) (err error)

/ *** Decode turns the provided byte slice into value The type of the decoded values should be compatible with the respective values in out. Decode reads a Fractus-encoded byte slice into the provided struct pointer. If unsafe modes are enabled decoded strings/slices may alias the original input buffer; the caller must ensure the input remains valid while values are used. For a safe wrapper that retains the payload, use `SafeDecoder`.

func (*Fractus) Encode

func (f *Fractus) Encode(in any) (out []byte, err error)

Encode turns the value provided into a byte slice(Fractus format binary) The binary reflect the value encoded only struct are accepted, only exported values are encoded Encode serializes the provided struct value into Fractus binary format. Only exported struct fields are encoded. Caller may enable zero-copy modes via `Opts` but must then ensure the source buffer remains live.

func (*Fractus) Reset

func (f *Fractus) Reset()

Reset clears all buffer used during encoding/decoding Reset clears internal buffers used during encode/decode so they can be reused.

type SafeDecoder

type SafeDecoder struct {
	// contains filtered or unexported fields
}

SafeDecoder for memory lifetime management Ensure that Decoding using unsafe doesn't affect values SafeDecoder keeps a reference to the payload to ensure any zero-copy references produced by `Fractus.Decode` remain valid for the lifetime of the SafeDecoder value.

func NewSafeDecoder

func NewSafeDecoder(fractus *Fractus) *SafeDecoder

func (*SafeDecoder) Decode

func (s *SafeDecoder) Decode(data []byte, out any) error

type SafeOptions

type SafeOptions struct {
	UnsafeStrings    bool
	UnsafePrimitives bool
	CheckAlignment   bool
}