feat: FacetMap attribute

[Tim-Maes]

feat: [FacetMap] attribute for cross-assembly extension method mappings

Problem

In DDD architectures where DTOs live in a shared/contracts project (referenced by both frontend and backend), using [Facet] causes type identity issues. C# treats MyDto from Assembly A as a different type than MyDto from Assembly B, even with identical namespace and class names. This leads to cast errors when crossing boundaries like SignalR hubs.

Solution

A new [FacetMap] attribute that generates extension methods for mapping between a source entity and an externally-defined target DTO. The DTO can be a plain POCO in any assembly with no Facet dependency.

// Shared project (no Facet reference needed)
public class CustomerDto
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string Email { get; set; }
}

// Domain project (references Facet + shared project)
[FacetMap(typeof(Customer), typeof(CustomerDto), "PasswordHash", "CreatedAt",
    GenerateToSource = true)]
public static partial class CustomerMappings { }

// Usage
var dto = customer.ToCustomerDto();
var entity = dto.ToCustomer();

// Direct projection access
var query = dbContext.Customers.Select(CustomerMappings.CustomerToCustomerDtoProjection);

// Generic SelectFacet works too (automatic discovery)
var dtos = dbContext.Customers.SelectFacet<Customer, CustomerDto>().ToListAsync();
var dtos = dbContext.Customers.SelectFacet<CustomerDto>().ToListAsync();

What's generated

For each [FacetMap] marker class, Facet generates:

Member	Description
To{Target}(this Source)	Extension method mapping source to target
To{Source}(this Target)	Reverse mapping (when GenerateToSource = true)
ApplyTo{Source}(this Target, Source)	Apply mapped properties to existing source instance
{Source}To{Target}Projection	Expression<Func<Source, Target>> for LINQ/EF Core

SelectFacet generic projection support

FacetMap projections are now fully compatible with the generic SelectFacet<TOut>() extension methods from Facet.Extensions. This enables generic patterns like:

protected IAsyncEnumerable<TOut> ProjectOrCastAsyncEnumerable<TOut>(IQueryable<T> queryable) where TOut : class
{
    return typeof(TOut) == typeof(T)
        ? queryable.Cast<TOut>()
            .AsAsyncEnumerable()
        : queryable.SelectFacet<T, TOut>()
            .AsAsyncEnumerable();
}

Previously, SelectFacet only discovered projections defined directly on the target type (the [Facet] pattern). Since FacetMap targets are plain POCOs with no Facet dependency, their projections live on the marker class instead. A new FacetProjectionRegistry in Facet.Extensions performs automatic assembly scanning to discover these projections by convention.

Features supported

• Property include/exclude
• Collection mapping (List, IList, ICollection, IEnumerable, arrays, ImmutableArray, etc.)
• Nested type mapping (auto-detected from type differences)
• Enum-to-string/int conversion (auto-detected)
• Nullable property handling (both directions)
• [MapFrom] attribute for property name remapping
• [MapWhen] attribute for conditional mapping
• Custom mapping configuration (IFacetMapConfiguration)
• Projection-based configuration (IFacetProjectionMapConfiguration)
• Custom reverse mapping configuration
• BeforeMap/AfterMap hooks
• Init-only property support
• LINQ projection expressions
• SelectFacet<TOut>() generic projection discovery
• Multiple [FacetMap] attributes on the same class
• CollectionTargetType override
• Global configuration defaults (GenerateToSource, GenerateProjection, MaxDepth)

No breaking changes

• Does NOT modify the existing [Facet] attribute or generator
• Does NOT change any existing generated output
• Purely additive: new attribute, new generator, new output file
• SelectFacet changes are backwards-compatible (existing [Facet] types use the fast reflection path; FacetMap discovery is only triggered as a fallback)

Tagging issue #143

[github-actions]

📦 Preview packages published

Version: 6.6.8-preview.pr389.213

Install with:

dotnet add package Facet --version 6.6.8-preview.pr389.213

This pre-release is published automatically from this PR and will be overwritten on the next push.