README.md

Epoch

A Rust framework for building event-sourced systems with CQRS patterns.

Overview

Epoch is an opinionated event sourcing framework that prioritizes simplicity and performance. The core idea:

Aggregates are living snapshots. State is persisted immediately after every command — no event replay on reads. Events are still stored for audit, projections, and history. An opt-in versioned snapshot store enables historical state reconstruction when you need it.

Quick Start

[dependencies]
epoch = { version = "0.1", features = ["derive", "postgres"] }

Features

• derive (default) — Proc macros for event data and enum subsetting
• in-memory — In-memory event store, bus, and snapshot store for testing
• postgres — PostgreSQL-backed event store, bus, and snapshot store
• upcasting — Forward-compatible event schema evolution via versioned JSON transformations

Crate Structure

Crate	Purpose
epoch	Main crate, re-exports with feature flags
epoch_core	Core traits and abstractions
epoch_derive	Proc macros (EventData, subset_enum)
epoch_mem	In-memory implementations (testing)
epoch_pg	PostgreSQL implementations (production)

Examples

• hello-world.rs — Basic aggregate and projection usage
• saga-order-fulfillment.rs — Multi-aggregate saga coordination
• event-correlation-causation.rs — Event correlation and causation tracking
• versioned-snapshots.rs — Automatic snapshot capture, retention, and historical state_at reconstruction
• schema-evolution.rs — Forward-compatible event upcasting with chained steps and dead-letter policy (requires --features upcasting)

Documentation

• Guide — Architecture, patterns, and design decisions
• Schema Evolution Guide — How to evolve persisted event schemas without breaking existing data

License

LGPL-3.0-or-later