ZeroAlloc.EventSourcing

Zero-allocation event sourcing for .NET 8+. Struct-based aggregate state, in-memory and SQL backends, source-generated aggregate boilerplate, optional OpenTelemetry instrumentation.

dotnet add package ZeroAlloc.EventSourcing
dotnet add package ZeroAlloc.EventSourcing.InMemory

Quick Start

// Wire up DI
services
    .AddEventSourcing()
    .UseInMemoryEventStore();

// Define an aggregate
public sealed class OrderAggregate : Aggregate<OrderState>
{
    public Result<Unit, string> Place(string orderId, decimal total)
    {
        if (State.Placed) return "already placed";
        Raise(new OrderPlacedEvent(orderId, total));
        return Unit.Value;
    }

    protected override OrderState Apply(OrderState state, object @event) => @event switch
    {
        OrderPlacedEvent e => state with { OrderId = e.OrderId, Total = e.Total, Placed = true },
        _ => state,
    };
}

// Use
var repo = sp.GetRequiredService<IAggregateRepository<OrderAggregate, string>>();
var order = new OrderAggregate();
order.Place("order-1", 99.99m);
await repo.SaveAsync("order-1", order, CancellationToken.None);

Packages

Package	Purpose
ZeroAlloc.EventSourcing	Core abstractions — IEventStore, IAggregateRepository, Aggregate<TState>
ZeroAlloc.EventSourcing.InMemory	In-memory event store for tests and development
ZeroAlloc.EventSourcing.Sql	SQL Server and PostgreSQL backends
ZeroAlloc.EventSourcing.Generators	Roslyn source generators for aggregate boilerplate
ZeroAlloc.EventSourcing.Telemetry	BCL ActivitySource + Meter decorator — spans and metrics with no OTel SDK

Documentation

Getting Started

• Installation - Install the NuGet package
• Quick Start Example - 5-minute intro
• Your First Aggregate - Build your first aggregate

Core Concepts (Read These First)

• Event Sourcing Fundamentals - Core principles and motivations
• Aggregates - Domain entities that handle commands and raise events
• Events - Immutable facts that model what happened
• Event Store - How events are persisted and retrieved
• Snapshots - Optimize large aggregates with snapshots
• Projections - Build read models for queries
• Architecture - System design and patterns

Code Examples (Learn by Doing)

• Getting Started Examples - CreateFirstAggregate, AppendAndRead
• Domain Modeling Examples - OrderAggregate, OrderState, OrderEvents
• Testing Examples - TestingAggregates, TestingProjections
• Advanced Examples - CustomEventStore, CustomProjection, CustomSnapshotStore

Performance & Optimization

• Performance Characteristics - Latency, throughput, allocation profiles
• Zero-Allocation Design - Struct-based state and performance philosophy
• Optimization Strategies - Snapshots, batching, filtering, parallel loads
• Benchmark Results - Detailed measurements and methodology

Advanced Topics

• Custom Event Stores - Implement for SQL Server, PostgreSQL, MongoDB
• Custom Snapshot Stores - Snapshot patterns and strategies
• Advanced Projections - 10 patterns: filtering, composition, side effects, etc.
• Plugin Architecture - Build extensible systems with plugins
• Contributing Guide - How to contribute to the project

Additional Resources

• Adoption Guide - Business case and adoption strategy
• Latest News - Recent updates and improvements

Learning Paths

Path 1: Learn Event Sourcing (1-2 hours)

1. Event Sourcing Fundamentals
2. Your First Aggregate
3. Examples: CreateFirstAggregate
4. Examples: AppendAndRead

Path 2: Build Your First System (2-3 hours)

1. Installation
2. Aggregates
3. Events
4. Examples: OrderAggregate
5. Examples: TestingAggregates

Path 3: Optimize for Production (1-2 hours)

1. Performance Characteristics
2. Zero-Allocation Design
3. Optimization Strategies
4. Snapshots
5. Custom Snapshot Stores

Path 4: Extend the Framework (2-3 hours)

1. Custom Event Stores
2. Advanced Projections
3. Plugin Architecture
4. Examples: CustomEventStore

Path 5: Contribute to the Project (1-2 hours)

1. Contributing Guide
2. Examples: TestingAggregates
3. Fork, branch, test, and submit PR

By Topic

Understanding Event Sourcing

• Event Sourcing Fundamentals - What and why
• Aggregates - Command handlers
• Events - Immutable facts
• Event Store - Persistence

Building Applications

• Quick Start Example
• Domain Modeling Examples
• Architecture
• Snapshots
• Projections

Testing

• Testing Examples - Unit and integration tests
• Examples: TestingAggregates - Aggregate tests
• Examples: TestingProjections - Projection tests

Performance

• Performance Characteristics - Understand performance
• Zero-Allocation Design - Design for performance
• Optimization Strategies - Improve performance
• Benchmark Results - Real data

Custom Implementations

• Custom Event Stores - SQL, MongoDB, etc.
• Custom Snapshots - Redis, S3, etc.
• Advanced Projections - Complex read models
• Plugin Architecture - Extensible systems

File Organization

docs/
├── INDEX.md (this file)
├── ADOPTION_GUIDE.md
├── getting-started/
│   ├── installation.md
│   ├── quick-start-example.md
│   └── first-aggregate.md
├── core-concepts/
│   ├── fundamentals.md
│   ├── aggregates.md
│   ├── events.md
│   ├── event-store.md
│   ├── snapshots.md
│   ├── projections.md
│   └── architecture.md
├── examples/
│   ├── 01-getting-started/
│   │   ├── CreateFirstAggregate.cs
│   │   └── AppendAndRead.cs
│   ├── 02-domain-modeling/
│   │   ├── OrderAggregate.cs
│   │   ├── OrderEvents.cs
│   │   └── OrderState.cs
│   ├── 03-testing/
│   │   ├── TestingAggregates.cs
│   │   └── TestingProjections.cs
│   └── 04-advanced/
│       ├── CustomEventStore.cs
│       ├── CustomProjection.cs
│       └── CustomSnapshotStore.cs
├── performance/
│   ├── characteristics.md
│   ├── zero-allocation.md
│   ├── optimization.md
│   └── benchmarks.md
└── advanced/
    ├── custom-event-store.md
    ├── custom-snapshots.md
    ├── custom-projections.md
    ├── plugin-architecture.md
    └── contributing.md

Key Statistics

• 19 documentation/example files
• 7,000+ lines of documentation
• 2,673 lines of runnable C# code
• Covers all major concepts and patterns
• Real-world examples and benchmarks

Need Help?

• Check the FAQ in Quick Start
• Read Architecture Guide for system design
• See Contributing Guide for development setup
• Open an issue or discussion on GitHub

Document Status

• Performance & Benchmarks: Complete (4 files, 2,050 lines)
• Advanced Topics: Complete (5 files, 3,277 lines)
• Code Examples: Complete (10 files, 2,673 lines)

Last Updated: 2026-04-04