FlowMapper 2.1.0

FlowMapper V2

FlowMapper is a compile-time data mapping platform for .NET.

It combines object-object mapping, micro-ORM, deserialization, source generation, and execution pipelines under a unified architecture focused on performance, extensibility, and zero runtime reflection.

var dto = flow.Map<User, UserDto>(user);                    // Object → Object
var rows = await flow.QueryAsync<CustomerDto>(sql);         // SQL → DTO
var json = flow.FromJson<CustomerDto>(jsonString);           // JSON → DTO

Architecture

           SQL / JSON / XML / Object
                     │
                     ▼
         ┌───────────────────────┐
         │   Compiler Pipeline   │
         │  (13 optimization passes) │
         └───────────┬───────────┘
                     │
                     ▼
         ┌───────────────────────┐
         │   Execution Plan      │
         │   (Materialization,   │
         │    Mapping, SQL Artifacts)│
         └───────────┬───────────┘
                     │
         ┌───────────┴───────────┐
         ▼                       ▼
   Mapping Pipeline     Materialization Pipeline
   (Object → Object)    (DataReader → Object)
         │                       │
         ▼                       ▼
   Runtime Engine ────────── Execution Scope
         │
         ▼
     DTO / Entity

Why FlowMapper?

Comparison

Installation

<PackageReference Include="FlowMapper" Version="2.1.0" />

Requires .NET 8.0+

Quick Start

// 1. Define a profile
public class AppProfile : ProfileDefinition
{
    public AppProfile()
    {
        CreateMap<User, UserDto>()
            .ForMember(d => d.FullName, opt => opt.MapFrom(s => $"{s.Name} ({s.Email})"));
    }
}

// 2. Register
services.AddFlowMapper();

// 3. Inject and use
public class MyService
{
    private readonly IFlowMapper _flow;
    public MyService(IFlowMapper flow) { _flow = flow; }

    public async Task Execute()
    {
        // Object → Object
        var dto = _flow.Map<User, UserDto>(new User { Id = 1, Name = "John", Email = "john@email.com" });

        // SQL → DTO with nested materialization via aliases
        var customers = await _flow.QueryAsync<CustomerDto>(@"
            SELECT u.Id, u.Name,
                   p.Id   AS Profile_Id,
                   p.Name AS Profile_Name
            FROM Users u
            LEFT JOIN Profiles p ON p.UserId = u.Id");

        // JSON → DTO (nested)
        var json = """{ "Id": 1, "Name": "Maria", "Profile": { "Id": 10, "Name": "Admin" } }""";
        var jDto = _flow.FromJson<CustomerDto>(json);

        // XML → DTO (nested)
        var xml = """<CustomerDto><Id>1</Id><Name>Peter</Name><Profile><Id>10</Id><Name>Support</Name></Profile></CustomerDto>""";
        var xDto = _flow.FromXml<CustomerDto>(xml);

        // CSV → DTO
        var csv = new[] { "Id;Name;Email", "1;John;john@email.com", "2;Maria;maria@email.com" };
        var list = _flow.FromText<UserDto>(csv, TextDelimiter.Semicolon, hasHeader: true);
    }
}

Features

Object-Object Mapping (AutoMapper-like)

public class AppProfile : ProfileDefinition
{
    public AppProfile()
    {
        CreateMap<User, UserDto>()
            .ForMember(d => d.FullName, opt => opt.MapFrom(s => $"{s.Name} ({s.Email})"))
            .ReverseMap();

        CreateMap<Customer, CustomerDto>()
            .ForPath(d => d.Profile.Name, opt => opt.MapFrom(s => s.ProfileName));
    }
}

var dto = _flow.Map<User, UserDto>(user);

SQL → DTO with Cascade Nested Materialization

Auto-maps flat SQL resultsets into nested DTOs using column aliases and property-driven grouping.

class CustomerDto {
    public int Id { get; set; }
    public string Name { get; set; }
    public ProfileDto Profile { get; set; }  // ← nested
}
class ProfileDto {
    public int Id { get; set; }
    public string Name { get; set; }
}

SELECT u.Id, u.Name,
       p.Id   AS Profile_Id,   -- ← prefix "Profile_"
       p.Name AS Profile_Name  -- ← prefix "Profile_"
FROM Users u
LEFT JOIN Profiles p ON p.UserId = u.Id

var customers = await _flow.QueryAsync<CustomerDto>(sql);
// CustomerDto.Profile is auto-populated for each row

JSON → DTO (Nested)

var json = """{ "Id": 1, "Name": "Maria", "Profile": { "Id": 10, "Name": "Admin" } }""";
var dto = _flow.FromJson<CustomerDto>(json);
// dto.Profile.Name == "Admin"

XML → DTO (Nested)

var xml = """<CustomerDto><Id>1</Id><Name>Peter</Name><Profile><Id>10</Id><Name>Support</Name></Profile></CustomerDto>""";
var dto = _flow.FromXml<CustomerDto>(xml);

Full-Text Search

// Register FTS profile
public class ProductFtsProfile : FtsProfileDefinition
{
    public ProductFtsProfile()
    {
        Entity<Product>().HasFullTextIndex(p => p.Name);
    }
}

// Search with automatic FTS condition injection
var results = await _flow.SearchFtsAsync<ProductDto>(
    "SELECT Id, Name FROM Products WHERE Price > 100 ORDER BY Name",
    "keyword", new[] { "Name" });

Runtime Diagnostics

var telemetry = sp.GetRequiredService<IDiagnosticTelemetry>();
telemetry.OnDiagnostic += d => Console.WriteLine($"{d.Code}: {d.Message}");

TXT → DTO (Flat)

With header — matches column names to property names (case-insensitive):

var csv = new[] { "Id,Name,ProfileId,ProfileName", "1,John,10,Admin", "2,Maria,20,Support" };
var list = _flow.FromText<CustomerCsvDto>(csv, TextDelimiter.Semicolon);

Positional (hasHeader: false) — matches by column order:

var lines = new[] { "1,John", "2,Maria" };
var list = _flow.FromText<UserDto>(lines, TextDelimiter.Semicolon, hasHeader: false);

Advanced Configuration

services.AddFlowMapper(builder =>
{
    // Providers (with connection string)
    builder.AddProvider<SqlServerProvider>(connectionString);
    builder.AddProvider<PostgreSqlProvider>(connectionString);
    builder.AddProvider<MySqlProvider>(connectionString);
    builder.AddProvider<OracleProvider>(connectionString);

    // Provider (parameterless — reads connection from config)
    builder.AddProvider<SqlServerProvider>();

    // Profiles (mapping definitions)
    builder.AddProfile<AppProfile>();

    // FTS profiles (full-text search index definitions)
    builder.AddFtsProfile<CatalogFtsProfile>();

    // Data options
    builder.ConfigureData(opts =>
    {
        opts.CascadeSeparator = "_";
        opts.DefaultTimeout = 30;
        opts.FtsLanguage = "portuguese"; // PostgreSQL only
        opts.Retry.Enabled = true;
        opts.Retry.MaxRetries = 3;
        opts.Retry.InitialDelayMs = 100;
    });

    // Mapping options
    builder.ConfigureMapping(opts =>
    {
        opts.EnableFlatten = true;
        opts.PreferConstructorMapping = false;
        opts.EnableCache = true;
        opts.Strictness = StrictnessLevel.Warning;
    });
});

var flow = sp.GetRequiredService<IFlowMapper>();

Project Structure

Ecosystem

        FlowCore (CQRS / Mediator)
              │
              ▼
         FlowMapper
         ┌──┴──┐
    Object    Data
    Mapping   Access
         │       │
         ▼       ▼
     FlowRuntime
         │
         ▼
   Applications

FlowMapper is part of a growing .NET ecosystem. The modular design allows each layer to be used independently.

License

MIT