LaisCosta.SimpleMapper 1.5.1

SimpleMapper.Lib

SimpleMapper is a lightweight, blazing-fast object mapper built exclusively for .NET 10+. It utilizes Expression Trees to compile mappings at runtime, ensuring performance close to hand-written code.

Features

• Map via Conventions: Automatic mapping of properties with identical names.
• Bidirectional Mapping (New!): Easily map back and forth with a single .ReverseMap() call.
• Deep Mapping (New!): Recursively maps nested complex objects and nested collections natively, keeping your tracking and hierarchy intact.
• Flattening: Automatically maps complex objects to flattened DTOs (e.g., Order.Customer.Name → OrderDTO.CustomerName).
• Flexible Configuration: Fluent API for cases where property names do not match.
• Configuration Validation: Validate if all fields of your DTO were mapped correctly with a single line of code.
• LINQ Integration: Use .ProjectTo<T>() to transform IQueryables directly into DTOs at the database level (SQL).
• Collections Support: Map lists and collections natively.

How to use

1. Installation

Add the project reference or install it via NuGet:

dotnet add package LaisCosta.SimpleMapper

2. Initial Configuration (Dependency Injection)

The easiest way to use SimpleMapper is by leveraging the native .NET Dependency Injection and organizing your mappings into profiles.

Step A: Create your mapping profiles

using SimpleMapper.Lib;

public class UserProfile : ISimpleMapperProfile
{
    public void Configure(MapperConfiguration config)
    {
        // Map by convention (Bidirectional)
        config.CreateMap<User, UserDTO>().ReverseMap();

        // Map with explicit configuration
        config.CreateMap<Product, ProductDTO>()
              .ForMember(dest => dest.DisplayName, opt => opt.MapFrom(src => src.FullDescription));

        // For Deep Mapping, simply map the nested types as well!
        config.CreateMap<Order, OrderDTO>().ReverseMap();
        config.CreateMap<Item, ItemDTO>().ReverseMap();
    }
}

Step B: Register in Program.cs

using SimpleMapper.Lib;

var builder = WebApplication.CreateBuilder(args);

// Automatically scans the assembly, compiles the expression trees, 
// and registers ISimpleMapper as a Singleton
builder.Services.AddSimpleMapper(typeof(Program));

var app = builder.Build();

(Alternative) Manual Configuration without DI Profiles:

var config = new MapperConfiguration();
config.CreateMap<User, UserDTO>().ReverseMap();

// Validation (Optional - Recommended for Dev/Test environments)
config.AssertConfigurationIsValid();

builder.Services.AddSingleton<ISimpleMapper>(new SimpleMapper(config));

3. Usage Examples

Once registered, simply inject ISimpleMapper into your controllers or services.

// Simple Mapping & Bidirectional Mapping
var dto = _mapper.Map<User, UserDTO>(user);
var backToEntity = _mapper.Map<UserDTO, User>(dto); // Works automatically thanks to .ReverseMap()!

// Automatic Flattening
// If your source has Address.City and the destination has AddressCity, SimpleMapper resolves it:
// Source: Order { Customer { Name: "John" } }
// Destination: OrderDTO { CustomerName: "John" }
var orderDto = _mapper.Map<Order, OrderDTO>(order);

// Deep Mapping (Nested Objects & Lists)
// If your destination matches the hierarchy of the source, SimpleMapper resolves it recursively!
// Source: User { OrderAtual: { Id: 1 }, Items: [ { Price: 10 } ] }
// Destination: UserDTO { OrderAtual: { Id: 1 }, Items: [ { Price: 10 } ] }
var deepDto = _mapper.Map<User, UserDTO>(userWithNestedData);

// Entity Framework Integration (LINQ)
// Avoid fetching unnecessary columns from the database:
var usersDto = dbContext.Users
    .ProjectTo<User, UserDTO>(config)
    .ToList();

// Collections
var dtoList = _mapper.MapEnumerable<Item, ItemDTO>(itemList);

// Syntactic Sugar (Extensions)
// You can also use extension methods for cleaner code:
var extensionDto = user.MapTo<UserDTO>(_mapper);
var list = originalList.MapToCollection<Source, Destination>(_mapper);

Advanced Features (v1.5.0)

Conditional Mapping (PreCondition and Condition)

Prevent null reference exceptions or unwanted overwrites by evaluating the object's state before mapping. All of this is compiled into native if/else statements under the hood, costing zero extra memory allocations.

config.CreateMap<Order, OrderDto>()
    .ForMember(dest => dest.AppliedDiscount, opt => 
    {
        // 1. PreCondition: Only attempts to map if the order is Completed
        opt.PreCondition(src => src.Status == "Completed"); 
        
        // 2. Condition: Only assigns the final value if the discount is greater than zero
        opt.Condition(src => src.DiscountAmount > 0);        
        
        // 3. MapFrom: The source property to map from
        opt.MapFrom(src => src.DiscountAmount);
    });

Inheritance and Reuse (Include)

Fluently map complex class hierarchies by reusing your existing configurations.

config.CreateMap<Animal, AnimalDto>()
      .Include<Dog, DogDto>(); // SimpleMapper resolves the derived class automatically

License

Distributed under the MIT License. See LICENSE for more information.