Grove.Tree.EventSerializer (Grove v0.1.1)

View Source

Columnar event encoding with RLE compression for Eg-walker persistence.

Uses a columnar format optimized for sequential editing patterns:

  • Event IDs: RLE compressed (80-95% of edits are sequential from same replica)
  • Parents: Sparse encoding (most events have single parent)
  • Operations: Type-grouped for better compression
  • Timestamps: Delta-encoded

Binary Format

GROVE_EG (8 bytes magic)
VERSION  (1 byte)
EVENT_COUNT (4 bytes, big-endian)
COLUMNAR_DATA (variable, zlib compressed)

The columnar data contains:

  • Event ID runs: [{replica_id, start_seq, count}]
  • Parent indices: Sparse map of event_index => [parent_indices]
  • Op type runs: [{op_type_atom, count}]
  • Operations: List of operation tuples
  • Timestamps: List of delta-encoded timestamps
  • Critical flags: Bitstring (1 bit per event)

Summary

Types

encoded()

Functions

decode_events(arg1)

Decodes binary back to a list of events.

decode_snapshot(arg1)

Decodes binary back to a snapshot.

encode_events(events)

Encodes a list of events into a compact binary format.

encode_snapshot(snapshot)

Encodes a snapshot to binary format (ETF + zlib).

Types

encoded()

@type encoded() :: binary()

Functions

decode_events(arg1)

@spec decode_events(encoded()) :: {:ok, [Grove.Tree.Event.t()]} | {:error, term()}

Decodes binary back to a list of events.

Returns {:ok, events} on success, {:error, reason} on failure.

Examples

{:ok, events} = EventSerializer.decode_events(binary)

decode_snapshot(arg1)

@spec decode_snapshot(binary()) :: {:ok, Grove.Tree.Snapshot.t()} | {:error, term()}

Decodes binary back to a snapshot.

Examples

{:ok, snapshot} = EventSerializer.decode_snapshot(binary)

encode_events(events)

@spec encode_events([Grove.Tree.Event.t()]) :: encoded()

Encodes a list of events into a compact binary format.

Events should be in topological order for optimal compression.

Examples

binary = EventSerializer.encode_events(events)

encode_snapshot(snapshot)

@spec encode_snapshot(Grove.Tree.Snapshot.t()) :: binary()

Encodes a snapshot to binary format (ETF + zlib).

Examples

binary = EventSerializer.encode_snapshot(snapshot)