Mapsicle 1.0.4

Mapsicle 🍦

Mapsicle is a high-performance, zero-dependency object mapper for .NET. It uses compiled Expression Trees to achieve near-native mapping speed with zero configuration required.

"The fastest mapping is the one you don't have to configure."

🚀 Why Switch from AutoMapper?

⚠️ AutoMapper is now commercial software. As of version 13+, AutoMapper requires a paid license for commercial use. Mapsicle remains 100% free and MIT licensed forever.

Real Talk: When to Use What

✅ Use Mapsicle when:

• You want zero configuration complexity
• You want to avoid commercial licensing fees
• Performance matters (APIs, high-throughput services)
• You're mapping simple-to-moderate object graphs
• You hate NuGet dependency bloat

⚠️ Use AutoMapper when:

• You need complex ForMember logic with external dependencies
• You're deeply invested in AutoMapper's ecosystem and have a commercial license

📊 Benchmark Results

Real benchmarks using BenchmarkDotNet on Apple M1, .NET 8.0:

Key Insights:

• Single object mapping: Mapsicle is 22% faster than AutoMapper
• Flattening: Mapsicle is 48% faster than AutoMapper (no config needed!)
• Cold start: ~284μs for first mapping (expression compilation)
• Memory: Same allocation as AutoMapper (120 bytes for single object)

Run benchmarks yourself:

cd tests/Mapsicle.Benchmarks
dotnet run -c Release

📦 Installation

dotnet add package Mapsicle

That's it. No DI registration, no profiles, no configuration.

⚡ Quick Start

Basic Mapping

using Mapsicle;

var user = new User { Id = 1, Name = "Alice", Email = "alice@mail.com" };

// One line. That's it.
UserDto dto = user.MapTo<UserDto>();

Collection Mapping

var users = new List<User> { new() { Name = "Alice" }, new() { Name = "Bob" } };

// Direct List<T> result
List<UserDto> dtos = users.MapTo<UserDto>();

// Or as an array
UserDto[] array = users.MapToArray<UserDto>();

Map to Existing Object

var existing = new UserDto { Id = 1, Name = "Old", Email = "keep@me.com" };
var source = new User { Id = 1, Name = "New" };

source.Map(existing);
// existing.Name = "New", existing.Email = "keep@me.com" (preserved)

🌟 Features

1. Automatic Flattening

No configuration needed. Just follow the naming convention:

public class Order { public Customer Customer { get; set; } }
public class Customer { public string Email { get; set; } }

// Destination DTO
public class OrderDto
{
    public string CustomerEmail { get; set; }  // Auto-mapped from Customer.Email!
}

var dto = order.MapTo<OrderDto>();  // CustomerEmail is populated automatically

2. Attribute-Based Configuration

public class UserDto
{
    [MapFrom("UserName")]           // Map from different property name
    public string Name { get; set; }

    [IgnoreMap]                      // Never mapped
    public string Password { get; set; } = "NOT_MAPPED";
}

3. Dictionary Mapping

// Object to Dictionary
var dict = user.ToDictionary();
// { "Id": 1, "Name": "Alice", "Email": "alice@mail.com" }

// Dictionary to Object
var restored = dict.MapTo<User>();

4. Smart Type Coercion

5. Record & Immutable Type Support

public record UserRecord(int Id, string Name);
var rec = source.MapTo<UserRecord>();  // Works via constructor

6. Cache Management

var info = Mapper.CacheInfo();  // { MapToEntries: 5, Total: 5 }
Mapper.ClearCache();            // Reset for testing

🔧 Migration from AutoMapper

Before (AutoMapper)

// Startup.cs
services.AddAutoMapper(typeof(MappingProfile));

// MappingProfile.cs
public class MappingProfile : Profile
{
    public MappingProfile()
    {
        CreateMap<User, UserDto>();
        CreateMap<Order, OrderDto>()
            .ForMember(d => d.CustomerEmail, opt => opt.MapFrom(s => s.Customer.Email));
    }
}

// Usage
var dto = _mapper.Map<UserDto>(user);

After (Mapsicle)

// No startup config needed!

// Usage
var dto = user.MapTo<UserDto>();

// Flattening works automatically with naming convention
// Order.Customer.Email → OrderDto.CustomerEmail ✅

⚠️ Limitations

• Circular References: Not supported (will cause StackOverflowException)
• Complex Resolvers: No ForMember with custom logic—use [MapFrom] for simple cases
• Deep Customization: If you need per-field transformation logic, write it manually

📁 Project Structure

Mapsicle/
├── src/Mapsicle/           # Core library (~400 lines)
└── tests/
    ├── Mapsicle.Tests/     # 56+ unit tests
    └── Mapsicle.Benchmarks/ # Performance benchmarks

🤝 Contributing

PRs welcome! Areas for contribution:

• Performance optimizations
• Additional type coercion scenarios
• Documentation improvements

📄 License

MIT License © Arnel Isiderio Robles

<p align="center"> <strong>Stop configuring. Start mapping.</strong><br> <em>Free forever. Zero dependencies. Pure performance.</em> </p>