Hexalith.EventStores 1.3.0

Hexalith.EventStores

A lightweight and efficient event store implementation for .NET applications using event sourcing patterns. This library provides a robust foundation for building event-sourced systems with support for event persistence, snapshots, and versioning.

Build Status

Overview

Hexalith.EventStores provides a flexible event storage solution for applications implementing event sourcing patterns. It offers:

• Event stream persistence with versioning
• Snapshot support for performance optimization
• Concurrent access control with session management
• Abstract interfaces for implementing different storage backends
• Thread-safe operations with cancellation support

Key Components

Abstractions

• IEventStore: Core interface for event store operations (add, get, snapshot, version management)
• IEventStoreProvider: Factory interface for opening event store instances
• EventMessage: Container for polymorphic event with metadata

Implementations

• KeyValueEventStore: Implementation using key-value storage for persistence
• KeyValueEventStoreProvider: Provider for creating KeyValueEventStore instances

Getting Started

Installation

dotnet add package Hexalith.EventStores

Basic Usage

// Create event store provider
IKeyValueProvider keyValueProvider = new YourKeyValueProvider();
IEventStoreProvider provider = new KeyValueEventStoreProvider(keyValueProvider);

// Open an event store (creates if not exists)
IEventStore store = await provider.OpenStoreAsync(
    "YourAggregateName",
    "YourAggregateId",
    cancellationToken);

try
{
    // Store events using the helper extension method
    var events = new List<EventMessage>
    {
        new YourDomainEvent { /* event data */ }.CreateMessage()
    };

    long version = await store.AddAsync(events, cancellationToken);

    // Retrieve events
    IEnumerable<EventMessage> storedEvents = await store.GetAsync(cancellationToken);

    // Create a snapshot
    await store.SnapshotAsync(
        version,
        CalculateSnapshot(storedEvents),
        cancellationToken);
}
finally
{
    // Close the store when done
    store.Close();
}

Advanced Features

Snapshots

Snapshots allow for efficient retrieval of event stream state without replaying all events:

// Create a snapshot at the current version
long version = await store.VersionAsync(cancellationToken);
await store.SnapshotAsync(
    version,
    CalculateSnapshot(events),
    cancellationToken);

// Retrieve using snapshot
var events = await store.GetAsync(useSnapshot: true, cancellationToken);

Session Management

The event store implements session-based locking to prevent concurrent access. When using OpenStoreAsync, the store is automatically opened. For custom timeout configuration:

// Open with custom timeouts (after getting the store)
await store.OpenAsync(
    TimeSpan.FromMinutes(5),  // session timeout
    TimeSpan.FromSeconds(10), // open timeout
    cancellationToken);

Examples

The repository includes examples demonstrating how to use Hexalith.EventStores in practical scenarios:

Bank Account Example

A simple application that demonstrates core event sourcing concepts using a bank account domain model:

• Creating and using an event store with file-based persistence
• Implementing domain events with polymorphic serialization
• Adding and retrieving events with proper sequencing
• Modeling a domain with C# records and event sourcing patterns

View Bank Account Example

Additional Examples (Planned)

Future releases will include examples covering:

• Domain-Driven Design with event sourcing
• Microservices communication patterns
• Performance optimization techniques
• Custom storage backend implementations

View Examples Overview

Repository Structure

The repository is organized as follows:

• src: Source code for the event store libraries
  • Hexalith.EventStores.Abstractions: Core interfaces and models
  • Hexalith.EventStores: Implementation of the event store
• test: Test projects
• examples: Example implementations
• Hexalith.Builds: Shared build configurations

License

This project is licensed under the MIT License - see the LICENSE file for details.