Vorn.EntityManagement 4.6.0-alpha

Vorn.EntityManagement

Philosophy

Vorn.EntityManagement is the foundation of the Vorn data platform. The package embraces CQRS and mediator-driven orchestration to keep entity workflows composable, testable, and cache aware. The library intentionally separates persistence logic from the domain model through command/query records so that your application can evolve without sacrificing correctness. The design centers on three pillars:

1. Explicit intent – CRUD operations are expressed as MediatR requests so that every write or query is observable and interceptable by cross-cutting behaviors (logging, validation, or auditing).
2. Cache-first experience – The provided cache abstractions (IEntityCache, EntityMemoryCache, and invalidation services) ensure that entity lifetimes are controlled in one location while avoiding stale reads.
3. Descriptor-driven access – Entities expose typed descriptors (EntityDescriptor) that filter reads, updates, and removals. This promotes discoverable API surface instead of ad-hoc query objects.

Package structure

The package exposes a cohesive set of primitives that can be combined in vertical slices. Core components include:

• Entity – Base record for aggregate roots with identity helpers.
• EntityDescriptor – Value object representing the filter used in queries and bulk operations.
• EntityService<TEntity, TDescriptor, TDto, TDescriptorDto> – High-level service that wraps MediatR and mapping delegates to provide DTO-friendly operations.
• Commands and queries – Records such as AddEntityCommand, UpdateEntitiesCommand, RemoveEntitiesByDescriptorCommand, and GetEntityByIdQuery express the intent for MediatR handlers in your application.
• Infrastructure helpers – Caching (EntityCacheInvalidationService, EntityMemoryCache), repository abstraction (IEntityRepository), and notification pipeline support (EntityNotification).

These building blocks allow you to layer domain logic, infrastructure, and presentation independently while reusing the same entity orchestration flows.

Getting started

1. Install the package

Install-Package Vorn.EntityManagement

2. Define your entity

public sealed class Document : Entity
{
    public string Title { get; init; } = string.Empty;
    public string Body { get; init; } = string.Empty;
}

public sealed class DocumentDescriptor : EntityDescriptor
{
    public required string TenantId { get; init; }
    public override IReadOnlyDictionary<string, object?> AsDictionary()
        => new Dictionary<string, object?> { ["tenant"] = TenantId };
}

3. Implement handlers

Handlers react to commands and queries using your persistence stack (Entity Framework Core, Dapper, etc.).

internal sealed class AddDocumentHandler(IMediator mediator, IDocumentDbContext db) 
    : IRequestHandler<AddEntityCommand<Document, DocumentDescriptor>, Document?>
{
    public async Task<Document?> Handle(
        AddEntityCommand<Document, DocumentDescriptor> request,
        CancellationToken cancellationToken)
    {
        db.Documents.Add(request.Entity);
        await db.SaveChangesAsync(cancellationToken);
        return request.Entity;
    }
}

4. Expose an application service

EntityService wires together MediatR and DTO mapping so consumers can work with transport-friendly types while keeping domain logic in handlers.

public sealed class DocumentService(IMediator mediator)
    : EntityService<Document, DocumentDescriptor, DocumentDto, DocumentDescriptorDto>(
        mediator,
        dto => new DocumentDto { Id = dto.Id, Title = dto.Title },
        dto => new Document { Id = dto.Id, Title = dto.Title },
        descriptor => new DocumentDescriptor { TenantId = descriptor.TenantId });

The service now exposes methods such as AddAsync, UpdateAsync, RemoveAsync, and GetAsync across both entity and DTO representations.

5. Configure caching (optional)

You can plug in the in-memory cache or create your own implementation.

services.AddSingleton<IEntityCache, EntityMemoryCache>();
services.AddSingleton<IEntityCacheInvalidationService, EntityCacheInvalidationService>();

By routing mutations through the provided commands, cache invalidation happens automatically and subscribers can react to EntityNotification events.

Usage tips

• Use descriptors to capture multi-tenant or contextual filtering concerns. Queries like CountEntitiesQuery<TEntity, TDescriptor> already accept descriptors and flow through your handlers.
• Combine the package with Vorn.EntityManagement.Generators to reduce boilerplate descriptors and handlers.
• MediatR pipelines let you add behaviors such as validation, tracing, and audit logging without changing the surface API.

Release artifacts

The README file is bundled with the NuGet package (PackageReadmeFile) so consumers can review philosophy and usage from NuGet.org, Visual Studio, or dotnet list package --include-transitive output.