Cacah.Eventra 1.0.0

<div align="center">

⚡ Eventra

Domain Events for .NET — Simple, Clean, Powerful.

Getting Started • Documentation • Samples • Contributing

</div>

✨ Apa Itu Eventra?

Eventra adalah framework Domain Event ringan untuk .NET, dibangun di atas MediatR dan terintegrasi dengan Entity Framework Core.

Cocok untuk project yang menggunakan Clean Architecture + CQRS dan ingin menambahkan konsep Domain Event ala DDD — tanpa kerumitan Event Sourcing, Outbox Pattern, atau distributed event.

Filosofi: "Domain events, made simple."

🎯 Masalah yang Dipecahkan

Bayangkan Anda punya toko online. Ketika ada pesanan baru, ada banyak hal yang harus dilakukan:

1. Kurangi stok barang.
2. Kirim email ke pembeli.
3. Beri tahu admin gudang.
4. Update cache.
5. Catat ke audit log.

Kalau semua ini dilakukan dalam satu fungsi besar, kodenya jadi panjang, susah diubah, dan susah di-test.

Eventra menyelesaikannya dengan Domain Event:

• Fungsi utama hanya melakukan satu hal: "Buat Pesanan".
• Setelah pesanan dibuat, ia berteriak: OrderCreatedEvent.
• Bagian lain yang "mendengarkan" akan bereaksi sendiri-sendiri.

🚀 Fitur Utama

📦 Instalasi

Via .NET CLI

# Core (wajib)
dotnet add package Eventra

# Integrasi EF Core (opsional)
dotnet add package Eventra.EntityFrameworkCore

Via PackageReference

<ItemGroup>
  <PackageReference Include="Eventra" Version="1.0.0" />
  <PackageReference Include="Eventra.EntityFrameworkCore" Version="1.0.0" />
</ItemGroup>

🏁 Getting Started

1. Setup DI

var builder = WebApplication.CreateBuilder(args);

// Register DbContext.
builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("Default")));

// Register Eventra + MediatR.
builder.Services.AddEventra(
    typeof(Program).Assembly,                    // assembly Anda (berisi handler)
    typeof(ProductCreatedEvent).Assembly);       // assembly event

var app = builder.Build();
app.Run();

2. Definisikan Event

Gunakan record agar immutable, dan warisi DomainEvent:

using Eventra.Core.BaseClasses;

public sealed record ProductCreatedEvent(
    Guid ProductId,
    string ProductName
) : DomainEvent;

3. Buat Entity

Warisi Entity (atau AggregateRoot):

using Eventra.Core.BaseClasses;

public class Product : Entity
{
    public Guid Id { get; private set; }
    public string Name { get; private set; } = string.Empty;

    private Product() { } // EF Core

    public static Product Create(string name)
    {
        var product = new Product
        {
            Id = Guid.NewGuid(),
            Name = name
        };

        // Raise event — akan di-dispatch setelah SaveChanges sukses.
        product.RaiseDomainEvent(new ProductCreatedEvent(product.Id, name));

        return product;
    }
}

4. Buat Handler

Implement IDomainEventHandler<T>:

using Eventra.Core.Abstractions;
using Microsoft.Extensions.Logging;

public sealed class SendEmailOnProductCreatedHandler
    : IDomainEventHandler<ProductCreatedEvent>
{
    private readonly ILogger<SendEmailOnProductCreatedHandler> _logger;

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

    public Task Handle(
        ProductCreatedEvent notification,
        CancellationToken cancellationToken)
    {
        _logger.LogInformation(
            "📧 Produk {Name} dibuat. Kirim email ke admin...",
            notification.ProductName);

        return Task.CompletedTask;
    }
}

5. Simpan + Dispatch

using Eventra.Core.Abstractions;
using Eventra.EntityFrameworkCore.Extensions;

public sealed class CreateProductCommandHandler
    : IRequestHandler<CreateProductCommand, Guid>
{
    private readonly AppDbContext _dbContext;
    private readonly IDomainEventDispatcher _dispatcher;

    public CreateProductCommandHandler(
        AppDbContext dbContext,
        IDomainEventDispatcher dispatcher)
    {
        _dbContext = dbContext;
        _dispatcher = dispatcher;
    }

    public async Task<Guid> Handle(
        CreateProductCommand request,
        CancellationToken cancellationToken)
    {
        var product = Product.Create(request.Name);
        _dbContext.Products.Add(product);

        // Commit + dispatch event otomatis.
        await _dbContext.SaveChangesAndDispatchEventsAsync(
            _dispatcher,
            cancellationToken);

        return product.Id;
    }
}

Selesai! Event akan otomatis di-dispatch ke semua handler setelah commit.

📚 Documentation

Konsep Dasar

Arsitektur

┌─────────────────────────────────────────────────────────────┐
│                     Command Handler                         │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ 1. product = Product.Create(name)                     │  │
│  │ 2. dbContext.Products.Add(product)                    │  │
│  │ 3. dbContext.SaveChangesAndDispatchEventsAsync(...)   │  │
│  └───────────────────────────────────────────────────────┘  │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│              DbContextExtensions                            │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ 1. Kumpulkan entity yang punya DomainEvents           │  │
│  │ 2. Snapshot event-nya ke list                         │  │
│  │ 3. SaveChangesAsync() ──────► Database                │  │
│  │ 4. ClearDomainEvents() di entity                      │  │
│  │ 5. dispatcher.DispatchAsync(events)                   │  │
│  └───────────────────────────────────────────────────────┘  │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│              DomainEventDispatcher                          │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ foreach event:                                        │  │
│  │   try { mediator.Publish(event) }                     │  │
│  │   catch { logger.LogError(...) }  ← tidak rethrow     │  │
│  └───────────────────────────────────────────────────────┘  │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                        MediatR                              │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐ │
│  │ Handler A       │  │ Handler B       │  │ Handler C   │ │
│  │ (Send Email)    │  │ (Audit Log)     │  │ (Update     │ │
│  │                 │  │                 │  │  Cache)     │ │
│  └─────────────────┘  └─────────────────┘  └─────────────┘ │
└─────────────────────────────────────────────────────────────┘

Struktur Project

Eventra/
 ┣ 📂 src
 ┃ ┣ 📂 Eventra.Core                    ← Abstraksi, base class, dispatcher
 ┃ ┗ 📂 Eventra.EntityFrameworkCore     ← Integrasi EF Core
 ┣ 📂 samples
 ┃ ┗ 📂 Eventra.SampleApp               ← Contoh console app
 ┣ 📂 tests
 ┃ ┗ 📂 Eventra.Core.Tests              ← Unit test
 ┣ 📜 Eventra.sln
 ┗ 📜 README.md

Keputusan Desain Penting

🎮 Samples

Lihat folder samples/ untuk contoh lengkap.

Menjalankan Sample

cd samples/Eventra.SampleApp
dotnet run

Output:

=== Membuat produk pertama ===
info: Eventra.Core.Dispatchers.DomainEventDispatcher[0]
      Dispatching domain event: ProductCreatedEvent (Id: ...)
info: Eventra.SampleApp.SendEmailOnProductCreatedHandler[0]
      📧 [EMAIL] Produk 'Kopi Arabica' (Id: ...) baru dibuat. Kirim email...
info: Eventra.SampleApp.LogOnProductCreatedHandler[0]
      📝 [AUDIT LOG] Produk 'Kopi Arabica' dibuat pada ... UTC.
Produk dibuat dengan Id: ...

=== Membuat produk kedua ===
...

🧪 Testing

dotnet test

Unit test mencakup:

1. Dispatch 1 event ke 1 handler.
2. Dispatch 1 event ke multiple handler.
3. Error di handler tidak menggagalkan dispatch.

⚠️ Non-Goals

Eventra tidak mendukung (dan tidak akan mendukung):

• ❌ Event Sourcing (menyimpan semua event di database)
• ❌ Outbox Pattern
• ❌ Distributed Event (Kafka, RabbitMQ)
• ❌ Event versioning
• ❌ Retry otomatis

Fokus pada in-process domain event yang sederhana dan mudah dipahami.

Kalau butuh fitur di atas, gunakan library khusus seperti:

• EventFlow — Event Sourcing
• Marten — Event Sourcing di PostgreSQL
• MassTransit — Distributed messaging

🤝 Contributing

Kontribusi selalu diterima! Silakan:

1. Fork repository ini.
2. Buat branch fitur (git checkout -b feature/AmazingFeature).
3. Commit perubahan (git commit -m 'Add some AmazingFeature').
4. Push ke branch (git push origin feature/AmazingFeature).
5. Buat Pull Request.

Lihat CONTRIBUTING.md untuk detail.

📋 Requirements

📄 License

Distributed under the MIT License. Lihat LICENSE untuk detail.

📚 Referensi

• Domain Events by Martin Fowler
• MediatR GitHub
• Clean Architecture
• EF Core Docs

🙏 Acknowledgements

• Jimmy Bogard — MediatR
• Martin Fowler — Domain Events concept
• Robert C. Martin — Clean Architecture

<div align="center">

Made with ❤️ for the .NET community.

⬆ Back to Top

</div>