AstraFlow README

The project's README from github.com/seifmoustafa/AstraFlow. As one markdown file: README.md.

AstraFlow

AstraFlow — Engineered Clarity

A modular .NET suite of 16 focused packages for explicit request dispatch, object mapping, query projections, compile-time analyzers, source generators, diagnostics, observability, and test workflows. Install only the packages your application needs and keep optional integrations isolated.

Getting Started · Package Selection · Version & Upgrade Guide · Compatibility · Changelog · Branding

Release status & support policy: The 2.4.x line includes the standalone AstraFlow.Assertions package, expanded compile-time mapping generation, and read-only CLI assertion migration analysis. The 2.4.1 patch fixed the package README image on NuGet.org; 2.4.2 through 2.4.4 add compile-tested assertion migration compatibility, with 2.4.4 extending formatted failure reasons and case-insensitive string containment checks. Check NuGet.org for the latest package version before pinning it. All 1.x packages are deprecated — use the 2.x line.


Packages (16)

Category Package Targets Role
Core AstraFlow netstandard2.0, net8.0, net9.0, net10.0 Convenience umbrella for AstraFlow.Contracts, AstraFlow.Mediator, and AstraFlow.Mapper
Core AstraFlow.Contracts netstandard2.0, net8.0, net9.0, net10.0 Lightweight mediator abstractions (IRequest, INotification, streams, pipelines) with zero runtime dependencies
Core AstraFlow.Mediator netstandard2.0, net8.0, net9.0, net10.0 Request/command/stream dispatch, notifications, pipeline behaviors, processors, scanning, and handler coverage validation
Core AstraFlow.Mapper netstandard2.0, net8.0, net9.0, net10.0 Explicit object mapping catalogs, startup validation, named projections, and secure ID abstractions
Core AstraFlow.Mapper.Conventions netstandard2.0, net8.0, net9.0, net10.0 Opt-in convention mapping with deterministic plans, strict validation, and sensitive-field safeguards
Core AstraFlow.Security netstandard2.0, net8.0, net9.0, net10.0 Shared sensitive-name classification and redaction policy primitives
Core AstraFlow.Diagnostics netstandard2.0, net8.0, net9.0, net10.0 Framework-neutral JSON and Markdown registration and validation reports
Tooling AstraFlow.Analyzers netstandard2.0 (analyzer) Build-time Roslyn diagnostics for mediator, mapper, and projection contracts
Tooling AstraFlow.Generators netstandard2.0 (generator) Compile-time mediator/mapper metadata plus opt-in typed mapping generation ([AstraGenerateMapping])
Tooling AstraFlow.Cli net10.0 (.NET tool) CLI inspect, validate, report, diff, Mermaid/Canvas graphs, and read-only assertion migration scan (expanded in 2.4.0)
Integrations AstraFlow.AspNetCore net10.0 Minimal APIs, controllers, problem details, diagnostics endpoints, and health summaries
Integrations AstraFlow.FluentValidation net8.0, net9.0, net10.0 Validation pipeline behaviors (fail-fast and aggregate errors), localization hooks, and diagnostics
Integrations AstraFlow.OpenTelemetry net8.0, net9.0, net10.0 Production-safe ActivitySource tracing and Meter metrics with default redaction
Integrations AstraFlow.Mapper.EntityFrameworkCore net10.0 Optional EF Core queryable projection translation validation
Testing AstraFlow.Testing netstandard2.0, net8.0, net9.0, net10.0 Framework-neutral test fakes, recording harnesses, and flow test helpers
Testing AstraFlow.Assertions netstandard2.0, net8.0, net9.0, net10.0 Standalone, runner-neutral general-purpose assertions with zero production package dependencies

See the Package Selection Guide for boundary rules and dependency isolation guarantees (AstraFlow.Mapper never pulls EF Core; AstraFlow.Mediator never pulls FluentValidation or OpenTelemetry).


Install AstraFlow

Install the umbrella convenience package when a project uses both mediator and explicit mapping:

dotnet add package AstraFlow

For cleaner layer boundaries, reference only what each assembly needs:

# Shared domain/API contracts library (no runtime dependency)
dotnet add package AstraFlow.Contracts

# Application layer packages
dotnet add package AstraFlow.Mediator
dotnet add package AstraFlow.Mapper

AstraFlow.Assertions ships as a standalone package starting in 2.4.0. Add it to test projects that need general-purpose assertions; it is not included by the AstraFlow convenience package.


Dispatch a request

Register the assembly containing your handlers, resolve ISender, and dispatch typed requests with explicit cancellation flow:

using System;
using System.Threading;
using System.Threading.Tasks;
using AstraFlow;
using AstraFlow.Mediator;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddAstraFlow(assemblyMarkerTypes: typeof(CreateOrderHandler));

await using var serviceProvider = services.BuildServiceProvider();
var sender = serviceProvider.GetRequiredService<ISender>();
using var cancellationTokenSource = new CancellationTokenSource();

OrderCreated result = await sender.Send(
    new CreateOrder("ORD-1042"),
    cancellationTokenSource.Token);

public sealed record CreateOrder(string Number) : IRequest<OrderCreated>;

public sealed record OrderCreated(Guid Id, string Number);

public sealed class CreateOrderHandler : IRequestHandler<CreateOrder, OrderCreated>
{
    public Task<OrderCreated> Handle(
        CreateOrder request,
        CancellationToken cancellationToken)
    {
        return Task.FromResult(new OrderCreated(Guid.NewGuid(), request.Number));
    }
}

Use ISender, IPublisher, or IStreamSender when a consumer needs only one slice of the mediator contract. Missing or duplicate request handlers fail explicitly during startup validation.

See Getting Started, the Mediator Guide, and Mediator Scenarios.


Mapping, projections, and source generation

See the Mapper Guide, Projection Guide, Convention Mapping Guide, Generators Guide, and Analyzers Guide.


Testing and assertions

AstraFlow.Testing ships test fakes and harnesses for mediator pipelines, mapping catalogs, projections, diagnostics, and secure ID codecs on 2.3.0.

AstraFlow.Assertions (targeting 2.4.0) adds a zero-dependency, test-runner-neutral assertion package covering:

using AstraFlow.Assertions; // Available in 2.4.0

response.StatusCode.Should().Be(201);
items.Should().ContainSingle(item => item.Id == expectedId);

Func<Task> save = () => service.SaveAsync();
await save.Should().NotThrowAsync();

See the Testing Guide and Assertions Guide for full signatures, target matrix, and caveats.


Upgrading and 1.x deprecation policy

See the Version and Upgrade Guide, Migration Cookbook, and Changelog.


Target frameworks

Check Compatibility before installing integration packages into multi-targeted libraries.


Documentation map

Topic Guides
Onboarding & Packages Getting Started · Package Selection · Architecture · API Reference · Compatibility
Mediator & Integrations Mediator · Mediator Scenarios · ASP.NET Core · FluentValidation · OpenTelemetry
Mapper, Generators & CLI Mapper · Mapper Scenarios · Projections · Projection Scenarios · Conventions · EF Core · Generators · Analyzers · CLI
Diagnostics, Security & Tests Diagnostics · Endpoint Safety · Security · Testing · Assertions (2.4.0) · Benchmarks
Upgrades & Troubleshooting Version & Upgrade Guide · Migration Cookbook · Troubleshooting · Branding
Roadmap & Governance Roadmap · Decision Log · API Governance · Security & Supply Chain · Security Policy · Contributing · Support · MIT License

Build, test, and pack from source

dotnet build AstraFlow.slnx --configuration Release
dotnet test AstraFlow.slnx --configuration Release --no-build
.\scripts\pack.ps1

For release verification, SourceLink, reproducibility, and NuGet publishing rules, see the Release Checklist, Publishing Guide, and Community Release Guide. Note that NuGet package READMEs require absolute raw GitHub URLs matching the target release tag/branch before packing for NuGet.org.

AstraFlow (seifmoustafa/AstraFlow)

Searching Database…

What is this?AstraFlow is a modular .NET suite of 16 focused packages for explicit request dispatch, object mapping, query projections, compile-time analyzers, source generators, diagnostics, observability, and test workflows.
Is it a framework or a library?It is a set of NuGet libraries rather than one framework. You install only the packages your application needs and keep optional integrations isolated.
Which .NET versions does it target?Core packages target netstandard2.0 and net8.0 to net10.0. The ASP.NET Core and EF Core integrations require net10.0, and the CLI is a net10.0 .NET tool.
Is the 1.x line still usable?No. All 1.x packages are deprecated on NuGet.org, so new and existing projects should use the 2.x line. Check NuGet.org for the latest 2.x version before pinning it.
What does the compile-time generator actually produce?Opt-in [AstraGenerateMapping] methods produce typed mappings at compile time. Version 2.4.0 extends this to inherited public properties, Guid and temporal scalars, positional records, primary-constructor DTOs and init-only initializers.
What can the AstraFlow CLI do?The AstraFlow.Cli .NET tool inspects, validates, reports and diffs registrations, and exports Mermaid or Canvas graphs. It also runs a read-only scan for assertion migration.
What is new in the 2.4.x line?The 2.4.x line adds the standalone AstraFlow.Assertions package, expanded compile-time mapping generation, and read-only CLI assertion migration analysis.
Size
42.8 MB
Stars
664
Age
6mo
Commits · 90 Days