Tyto.Materializer 0.0.1-alpha.47

Tyto.Materializer

A high-performance, resilient projection engine for building Materialized Views in Event-Driven Architectures and CQRS systems.

Tyto.Materializer transforms a stream of domain events into query-optimized read models (Views). Unlike standard caching mechanisms (Last-Write-Wins), it enforces strong data consistency using optimistic concurrency control, ensuring your read models never get overwritten by stale data, even under high concurrency.

🚀 Key Features

• Event-Driven & Reactive: Seamlessly integrates with message buses to update views in near real-time.
• Optimistic Concurrency: Uses Version Vectors to handle race conditions automatically.
• Class-Based Projectors: Cleanly separate your projection logic into testable classes (IViewProjector) with full Dependency Injection support.
• Auto-Discovery: Automatically registers all projection rules implemented by a class using Reflection, keeping your startup configuration clean.
• Resilient: Built-in retry policies with exponential backoff for handling concurrency conflicts.
• Storage Agnostic: Plug-and-play storage providers (Redis, EF Core, InMemory).

📦 Installation

dotnet add package Tyto.Materializer

> Note: You will likely need a storage provider package as well, such as Tyto.Materializer.Redis.

⚡ Getting Started

1. Define Your View

Views are simple POCO classes that implement IProjectableView. This interface adds a Version property which the library uses to track state changes and prevent race conditions.

using Tyto.Materializer;

public class UserBalanceView : IProjectableView
{
    // The unique key for this view (e.g., UserId)
    public Guid UserId { get; set; } 
    
    public string FullName { get; set; } = string.Empty;
    public decimal CurrentBalance { get; set; }
    public DateTime LastUpdated { get; set; }
    
    // Managed automatically by Tyto
    public ProjectableVersion Version { get; set; }
}

2. Define a Projector

Instead of writing logic inside configuration files, define your projection logic in clean, testable classes implementing IViewProjector<TView, TEvent>. You can inject repositories, loggers, or other services here.

using Tyto.Materializer;

public class UserBalanceProjector : 
    IViewProjector<UserBalanceView, UserRegistered>,
    IViewProjector<UserBalanceView, MoneyDeposited>
{
    private readonly ILogger<UserBalanceProjector> _logger;

    public UserBalanceProjector(ILogger<UserBalanceProjector> logger)
    {
        _logger = logger;
    }

    public ValueTask ProjectAsync(UserBalanceView view, UserRegistered @event, CancellationToken ct)
    {
        // Tyto automatically handles creating the view instance if it doesn't exist.
        view.UserId = @event.UserId;
        view.FullName = @event.Name;
        view.CurrentBalance = 0;
        view.LastUpdated = DateTime.UtcNow;
        
        _logger.LogInformation("Projection created for user {Id}", @event.UserId);
        return ValueTask.CompletedTask;
    }

    public ValueTask ProjectAsync(UserBalanceView view, MoneyDeposited @event, CancellationToken ct)
    {
        view.CurrentBalance += @event.Amount;
        view.LastUpdated = DateTime.UtcNow;
        return ValueTask.CompletedTask;
    }
}

3. Configure in Program.cs

Wire everything up using the Fluent API.

builder.Services.AddTytoConfiguration(tyto => 
{
    tyto.AddMaterializer(materializer =>
    {
        materializer.ForView<UserBalanceView>()
            // 1. Identify the Key: How to extract the View ID from an Event
            .IdentifiedAs<Guid>(id => id.From<UserRegistered>(e => e.UserId))
            
            // 2. Configure Storage: Choose where to save the view
            .Store.UseRedis("localhost:6379,abortConnect=false") 
            
            // 3. Register Projectors: Use the class-based approach
            // This single line automatically registers BOTH UserRegistered and MoneyDeposited
            // handlers defined in the UserBalanceProjector class.
            .Projects<UserBalanceView, Guid, UserBalanceProjector>();
    });
});

🏗️ Architecture & Concurrency

In a distributed system, multiple events might try to update the same view at the exact same time. Tyto handles this robustly:

1. Read: The Materializer loads the current View (e.g., Version 1).
2. Project: It applies the logic from your Projector.
3. Atomic Save: It attempts to save the new state (Version 2).
4. Conflict Detection: If the underlying store detects that the version has changed (e.g., someone else saved Version 2 before we could), it throws a ConcurrencyException.
5. Retry: Tyto automatically catches this exception, reloads the fresh data (Version 2), re-applies your projection logic, and attempts to save again.

This guarantees Strong Eventual Consistency. Updates are never lost, and the final state is always the result of applying events in order.

🧩 Advanced Usage

Manual Projector Registration

If you prefer explicit registration over reflection/auto-discovery, or if you have different classes handling different events for the same view:

// Register handlers explicitly
.Projects<UserBalanceView, Guid, UserRegistered, UserBalanceProjector>()
.Projects<UserBalanceView, Guid, MoneyDeposited, AnotherProjector>()

In-Memory Provider

For Unit Testing, use the In-Memory provider. It simulates serialization and concurrency conflicts to ensure your logic is production-ready.

.Store.UseInMemory()

Dependency Injection

Because Projectors are resolved from the DI container, you can use any registered service (Repositories, Anti-Corruption Layers, etc.) within your ProjectAsync methods.

public class OrderProjector(IExchangeRateService rateService) : IViewProjector<OrderView, OrderPlaced>
{
    public async ValueTask ProjectAsync(OrderView view, OrderPlaced @event, CancellationToken ct)
    {
        var rate = await rateService.GetCurrentRateAsync(ct);
        view.Total = @event.Amount * rate;
    }
}