SwiftMap 1.1.0

<div align="right"><a href="README.pt-BR.md">🇧🇷 Português</a></div>

<div align="center">

SwiftMap

Zero-allocation, expression-tree-compiled object mapper for .NET

Convention-based property mapping backed by compiled expression trees — zero reflection at call time. Source generator mode achieves manual-mapping parity at compile time (Mapperly-style).

</div>

Why SwiftMap?

• Source generator mode — [Mapper] partial class emits mapping bodies at compile time; zero startup cost, zero delegate dispatch, zero reflection at call time — identical to hand-written code
• Runtime expression-tree mode — mappings compile once to native delegates via FastExpressionCompiler; subsequent calls are allocation-free
• Fluent, discoverable API — ForMember, Ignore, AfterMap, ReverseMap, NullSubstitute, Condition, Patch, and more
• No heavy dependencies — single NuGet package; only depends on Microsoft.Extensions.DependencyInjection.Abstractions
• Records & init-only properties — full support for C# 9+ records via primary constructor selection
• First-class DI support — drop-in services.AddSwiftMap(...) with profile scanning

Installation

.NET CLI

dotnet add package SwiftMap

Package Manager Console

Install-Package SwiftMap

PackageReference

<PackageReference Include="SwiftMap" Version="1.0.0" />

Quick Start

Source Generator Mode (recommended — compile-time, zero overhead)

using SwiftMap;

[Mapper]
public partial class AppMapper
{
    public partial PersonDto   Map(Person source);
    public partial OrderDto    Map(Order source);
    public partial ProductDto  Map(Product source);
}

// Usage — no DI, no startup cost, velocity = manual code
var mapper = new AppMapper();
var dto = mapper.Map(person);

The [Mapper] attribute triggers the included Roslyn source generator. It analyses your types at compile time and emits efficient object-initializer bodies — supporting flat objects, nested objects (null-safe is-pattern), collections (for-loop, no LINQ), records (primary constructor), enums, and nullable unwrapping.

Runtime Expression-Tree Mode

// 1. Create a mapper — once at startup or via DI
var mapper = Mapper.Create(cfg =>
    cfg.CreateMap<PersonSource, PersonDest>());

// 2. Map by source type inference
var dest = mapper.Map<PersonDest>(source);

// 3. Map with explicit type parameters (slightly faster — no GetType() call)
var dest = mapper.Map<PersonSource, PersonDest>(source);

// 4. Map into an existing instance
mapper.Map(source, existingDestination);

Configuration

Convention mapping — no config needed

Matching properties are wired up automatically by name (case-insensitive):

var mapper = Mapper.Create(_ => { });
var dto = mapper.Map<CustomerDto>(customer);

Fluent API

var mapper = Mapper.Create(cfg =>
    cfg.CreateMap<Customer, CustomerDto>(map =>
        map.ForMember(d => d.AddressCity,  opt => opt.MapFrom(s => s.Address!.City))
           .Ignore(d => d.InternalId)
           .ForMember(d => d.Name,         opt => opt.NullSubstitute("Unknown"))
           .ForMember(d => d.Score,        opt => opt.Condition(s => s.IsActive))
           .AfterMap((src, dest) => dest.Name = dest.Name.ToUpperInvariant())));

Reverse mapping

cfg.CreateMap<OrderDto, Order>()
   .ReverseMap(); // registers the inverse mapping automatically

Profiles

Organise large sets of mappings into cohesive units:

public class AppProfile : MapProfile
{
    public AppProfile()
    {
        CreateMap<Customer, CustomerDto>()
            .ForMember(d => d.AddressCity, opt => opt.MapFrom(s => s.Address!.City));

        CreateMap<Order, OrderDto>().ReverseMap();
    }
}

var mapper = Mapper.Create(cfg => cfg.AddProfile<AppProfile>());

Attribute-driven mapping

[MapTo(typeof(ProductDto))]
public class Product { ... }

public class TargetDto
{
    [MapProperty("FullName")]   // maps from a differently-named source property
    public string Name { get; set; }

    [IgnoreMap]                 // skipped during mapping
    public string Secret { get; set; }
}

Dependency Injection

// Inline configuration
services.AddSwiftMap(cfg => cfg.CreateMap<Order, OrderDto>());

// Scan assemblies for MapProfile subclasses and [MapTo]/[MapFrom] attributes
services.AddSwiftMap(typeof(Program).Assembly);

HTTP PATCH — Patch Semantics

Patch applies only the non-null fields from source onto an existing destination instance, leaving everything else untouched. Designed for HTTP PATCH endpoints where the client sends only the fields it wants to change.

// Only Name was sent — Age and Email are null (not provided by client)
var updateDto = new UpdateUserDto { Name = "João", Age = null };
var user = await dbContext.Users.FindAsync(id); // { Name = "Maria", Age = 30, Email = "m@m.com" }

mapper.Patch(updateDto, user);
// Result: { Name = "João", Age = 30, Email = "m@m.com" }
// Age and Email were preserved — they were null in the dto

Works automatically by convention — no CreateMap required. For advanced scenarios:

// Skip fields that match their default value (0, false, Guid.Empty, etc.)
mapper.Patch(dto, entity, cfg => cfg.AsPatch(PatchBehavior.SkipDefaultFields));

// Register patch behavior in a profile
public class AppProfile : MapProfile
{
    public AppProfile()
    {
        CreateMap<UpdateUserDto, User>().AsPatch();
    }
}

Benchmarks

Benchmarked against AutoMapper 13.0.1 and Mapster 7.4.0 on .NET 9.

BenchmarkDotNet v0.15.8  ·  Windows 11  ·  AMD Ryzen 5 3600 3.60GHz (6C/12T)
.NET SDK 9.0.312  ·  .NET 9.0.14  ·  X64 RyuJIT x86-64-v3
ShortRun: 3 warmups + 7 iterations

Simple flat object (7 properties)

Nested object (parent + child)

Collection mapping

Record (primary constructor)

At a glance

All measurements: same allocated memory as manual code (no overhead).

Project Structure

src/
├── SwiftMap/                              # Runtime expression-tree mapper
│   ├── Mapper.cs                          # Entry point — Mapper.Create(...)
│   ├── IMapper.cs                         # Public interface
│   ├── MapperConfig.cs                    # Configuration + compiled delegate cache
│   ├── TypeMapConfig.cs                   # Fluent API: ForMember, Ignore, AfterMap...
│   ├── MapProfile.cs                      # Base class for profiles
│   ├── Attributes/
│   │   └── MapToAttribute.cs              # [MapTo], [MapFrom], [IgnoreMap], [MapProperty], [Mapper]
│   ├── Extensions/
│   │   └── ServiceCollectionExtensions.cs # AddSwiftMap(...)
│   └── Internal/
│       ├── MappingCompiler.cs             # Expression tree compiler (core engine)
│       └── TypePair.cs                    # (Source, Destination) dictionary key
└── SwiftMap.SourceGenerator/              # Roslyn IIncrementalGenerator
    ├── MapperGenerator.cs                 # [Generator] entry point
    ├── Models/                            # MapperClassModel, MappingMethodModel, MappedPropertyModel
    ├── Pipeline/
    │   └── MapperModelExtractor.cs        # Semantic analysis
    └── Emit/
        ├── MappingBodyEmitter.cs          # Code generation
        └── SourceWriter.cs                # Indented string builder

Roadmap

• FastExpressionCompiler integration — CompileFast() replaces Expression.Compile() for faster delegate creation
• Source generator mode — [Mapper] partial class emits mapping bodies at compile time; reaches manual-mapping parity
• Patch semantics — mapper.Patch(dto, entity) applies only non-null fields; built-in support for HTTP PATCH endpoints
• Async mapping — MapAsync<TDest>(source) for pipelines that need async value resolution
• IQueryable projection — ProjectTo<TDest>() for ORM query projection
• NuGet release — SwiftMap is available on nuget.org/packages/SwiftMap

Contributing

Contributions are welcome! See CONTRIBUTING.md for full guidelines.

Quick steps:

1. Fork and create a feature branch (git checkout -b feature/my-feature)
2. Add or update tests to cover your change
3. Run the benchmarks to verify no performance regression:

   dotnet run -c Release --project benchmarks/SwiftMap.Benchmarks
   

4. Open a pull request — for significant changes, open an issue first to discuss the approach

License

SwiftMap is released under the MIT License.