AstraFlow.Mapper.EntityFrameworkCore 1.2.0

AstraFlow

AstraFlow is a MIT-licensed .NET package family for explicit CQRS dispatch and source-auditable object mapping.

It was built to keep production applications free from runtime license checks, hidden mapping behavior, and framework lock-in. The v1 design is deliberately small: secure defaults, clear errors, explicit extension points, and package-quality diagnostics before optional convention layers are added.

Packages

Documentation Map

Target Framework

AstraFlow currently targets net10.0. Per Microsoft's .NET support policy, .NET 10 is an active LTS release supported until November 14, 2028; .NET 8 and .NET 9 are supported until November 10, 2026.

Public API At A Glance

Registration

Mediator

Mapper

Diagnostics

Entity Framework Core

Design Principles

• Explicit by default: mapping rules must be code you can review.
• Security first: sensitive fields are not mapped by naming convention unless a future optional package is explicitly enabled.
• Clear failure modes: missing handlers, duplicate handlers, missing mappings, duplicate mappings, and undeclared mappings fail with actionable messages.
• No application lock-in: AstraFlow does not depend on NEXORA, Result, ASP.NET Core MVC, FluentValidation, tenants, permissions, or a specific ID encryption implementation.
• Extension-ready: pipelines, notification failure policies, projections, and secure ID codecs are designed as narrow public contracts.

Quick Start: Mediator

using AstraFlow.Mediator;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddAstraFlowMediator(typeof(CreateInvoiceCommand));

using var provider = services.BuildServiceProvider();
var sender = provider.GetRequiredService<ISender>();

var id = await sender.Send(new CreateInvoiceCommand("INV-1001"));

public sealed record CreateInvoiceCommand(string Number) : IRequest<Guid>;

public sealed class CreateInvoiceCommandHandler
    : IRequestHandler<CreateInvoiceCommand, Guid>
{
    public Task<Guid> Handle(CreateInvoiceCommand request, CancellationToken cancellationToken)
    {
        return Task.FromResult(Guid.NewGuid());
    }
}

Quick Start: Pipeline Behavior

Pipeline behaviors run in registration order and may short-circuit by not calling next.

services.AddScoped(typeof(IPipelineBehavior<,>), typeof(LoggingBehavior<,>));
services.AddScoped(typeof(IPipelineBehavior<,>), typeof(ValidationBehavior<,>));
services.AddScoped(typeof(IPipelineBehavior<,>), typeof(FeatureGateBehavior<,>));

Quick Start: Mapper

using AstraFlow.Mapper;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddAstraFlowMapper(typeof(UserMappingRule));

using var provider = services.BuildServiceProvider();
var mapper = provider.GetRequiredService<IMapper>();

var dto = mapper.Map<UserResponse>(new User(Guid.NewGuid(), "admin"));

public sealed record User(Guid Id, string UserName);
public sealed record UserResponse(Guid Id, string UserName);

public sealed class UserMappingRule : IDeclaredObjectMappingRule
{
    public IReadOnlyCollection<ObjectMappingPair> DeclaredMappings { get; } =
    [
        ObjectMappingPair.Create<User, UserResponse>()
    ];

    public bool CanMap(Type sourceType, Type destinationType)
    {
        return sourceType == typeof(User) && destinationType == typeof(UserResponse);
    }

    public object? Map(object? source, Type destinationType, IMapper mapper)
    {
        var user = (User)source!;
        return new UserResponse(user.Id, user.UserName);
    }
}

Quick Start: Projections

Register projections with the mapper marker assembly, then resolve them through the registry:

public sealed class UserListProjection : INamedProjection<User, UserListItem>
{
    public string Name => "list";

    public Expression<Func<User, UserListItem>> Expression =>
        user => new UserListItem(user.Id, user.UserName);
}

services.AddAstraFlowMapper(
    [typeof(UserListProjection)],
    options =>
    {
        options.ValidateProjectionCatalogOnStartup = true;
        options.ProjectionValidationMode = ProjectionValidationMode.Warning;
    });

var registry = provider.GetRequiredService<IProjectionRegistry>();
var query = db.Users.ProjectWith<User, UserListItem>(registry, "list");

Projection validation reports warnings by default. Set ProjectionValidationMode.Error in CI or strict startup validation when projection findings should fail the build or application startup.

Quick Start: EF Core Projection Checks

Install the optional package only in projects that need EF Core validation:

dotnet add package AstraFlow.Mapper.EntityFrameworkCore --version 1.2.0

Then ask EF Core to translate registered projections without executing the query:

using AstraFlow.Mapper.EntityFrameworkCore;

var efReport = dbContext.ValidateProjectionTranslations(registry);

Static projection validation catches high-risk expression patterns such as custom method calls. EF Core validation proves the source entity is mapped and the provider can generate SQL for the projection shape.

Secure ID Mapping

AstraFlow.Mapper provides the abstraction, not the cryptography. Applications own the encryption implementation.

services.AddScoped<ISecureIdCodec, MySecureIdCodec>();
services.AddScoped<SecureIdMapper>();

Mapping rules can then depend on SecureIdMapper and emit encrypted string IDs without coupling the package to application secrets.

Notification Failure Policies

Notifications are sequential by default. Configure how failures are handled:

services.Configure<NotificationPublishOptions>(options =>
{
    options.FailurePolicy = NotificationFailurePolicy.Aggregate;
});

Policies:

• FailFast: stop at the first failing handler.
• Continue: log failures and run remaining handlers.
• Aggregate: run all handlers, then throw one AggregateException.

Quick Start: Diagnostics

Register diagnostics after mediator and mapper services:

using AstraFlow.Diagnostics;

services.AddAstraFlowMediator(typeof(CreateInvoiceCommand));
services.AddAstraFlowMapper(typeof(UserMappingRule));
services.AddAstraFlowDiagnostics(options =>
{
    options.AssemblyMarkerTypes.Add(typeof(CreateInvoiceCommand));
    options.AssemblyMarkerTypes.Add(typeof(UserMappingRule));
});

Create reports:

var reporter = provider.GetRequiredService<IAstraFlowDiagnosticsReporter>();

var report = reporter.CreateReport();
var json = reporter.CreateJsonReport();
var markdown = reporter.CreateMarkdownReport();

Diagnostics are framework-neutral and do not expose request payloads, DTO payloads, secrets, tokens, or connection strings.

v1 Non-Goals

AstraFlow v1 intentionally does not include convention mapping, flattening, reverse-map generation, compatibility shims, source generators, or analyzers. Those belong in optional packages after the explicit core is stable in real production use.

Roadmap

The long-term plan is to continue improving projection safety, then add target-framework compatibility work, testing support, mediator parity features, optional convention mapping, advanced mapping parity, analyzers, source generators, OpenTelemetry hooks, benchmark projects, ASP.NET Core helpers, validation integration, CLI/templates, broader EF Core provider checks, and transition tooling. These will remain opt-in so the secure explicit core stays predictable.

Branding

The package icon is stored at assets/branding/astraflow-icon.png and is included in every NuGet package through PackageIcon.

Generator prompt:

Create a square app/package icon for a .NET library named AstraFlow. Use an abstract orbital star and flowing path motif that suggests explicit application flow, mediator dispatch, and auditable mapping. Keep it as a clean vector-friendly modern tech logo with crisp edges, centered symbol only, no text, strong silhouette readable at 64x64, generous padding, deep navy background with cyan, teal, white, and a small warm amber star accent. Avoid words, letters, code snippets, watermarks, photorealism, and complex gradients.

Repository Readiness

The package folder includes CI, a gated publish workflow, security policy, contributing guide, changelog, samples, and release checklist. Publishing should happen only after:

• package tests pass,
• NEXORA consumes the package projects successfully,
• package artifacts build with XML docs and symbols,
• the API surface is reviewed for v1 stability,
• NuGet Trusted Publishing is configured, or a scoped GitHub Actions publishing secret is configured in the release repository.

For first publish setup, create a dedicated GitHub repository, copy this folder into the repository root, configure Trusted Publishing or the documented GitHub secret, and run the gated publish workflow. See docs/publishing.md.

License

MIT.