👁 Image
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

👁 License: MIT
👁 Discord

👁 Codacy Badge
👁 Quality Gate Status
👁 Security Rating
👁 Maintainability Rating
👁 Code Smells
👁 Lines of Code
👁 Technical Debt
👁 Reliability Rating
👁 Duplicated Lines (%)
👁 Vulnerabilities
👁 Bugs

👁 Build status
👁 NuGet
👁 Latest

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

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

Repository Structure

The repository is organized as follows:

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

License

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