Mapsicle 1.0.3

Mapsicle 🍦

Mapsicle is a high-performance, zero-dependency object mapper for .NET. It uses compiled Expression Trees to match properties at near-native speed, designed as a lightweight alternative to lightweight libraries.

Author

• Arnel Isiderio Robles

The Pitch

Quick Start

Install via NuGet:

dotnet add package Mapsicle

1. Simple Object Mapping

Just call .MapTo<T>() on any object. Matches properties by name (case-insensitive).

using Mapsicle;

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

// Map to UserDto
UserDto dto = user.MapTo<UserDto>();

2. List Mapping

Works seamlessly with lists and collections.

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

// Map to valid List<UserDto>
// Map to valid List<UserDto> (Returns List<T> directly)
List<UserDto> dtos = users.MapTo<UserDto>();

3. Update Existing Instance

Update a target object with values from a source. useful for database entities.

var existingUser = new UserDto { Id = 1, Name = "Old Name" };
var input = new User { Id = 1, Name = "New Name" };

// Updates existingUser in-place (ID=1, Name="New Name")
input.Map(existingUser);

Limitations

• Circular References: Mapsicle does not support object graphs with circular references (e.g. Parent → Child → Parent). Mapping such objects will result in a StackOverflowException. Ensure your DTOs describe a Directed Acyclic Graph (DAG).
• Complex Logic: No ForMember or custom resolvers. Strictly property-to-property mapping.

Behavior & Limitations

Mapsicle is designed to be simple and fast. It follows Strict Type Matching:

• Property Matching: Properties are matched by name (case-insensitive).
• Type Compatibility: Properties are only mapped if the Source type is assignable to the Destination type.
  • string → string: ✅ Mapped
  • int → int: ✅ Mapped
  • User → User (Same Class): ✅ Mapped (Reference Copy)
  • SubClass → BaseClass: ✅ Mapped
  • MapTo<T>(IEnumerable) → List<T>: ✅ Mapped (Collections are automatically mapped to Lists)
  • ClassA → ClassB (Different Classes): ✅ Mapped (Deep Copy via Recursive Mapping)
  • int → string: ✅ Mapped (Coerced via ToString())
  • Enum → int: ✅ Mapped (Coerced via Casting)
  • Enum → int: ✅ Mapped (Coerced via Casting)
  • int → int?: ✅ Mapped (Nullable Wrapping)
  • int? → int: ✅ Mapped (Nullable Unwrapping, defaults to 0 if null)
• Unmatched Properties: Properties in Source or Destination that do not match are simply ignored (no errors).

Constructor & Record Support

Mapsicle supports creating objects via constructors, enabling mapping to immutable Records:

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

Performance Logic

Mapsicle achieves its speed by using System.Linq.Expressions to generate and compile mapping code dynamically at runtime.

1. First Run: When you call .MapTo<T>() for the first time on a pair of types (e.g., User → UserDto), Mapsicle inspects the properties of both types.
2. Compilation: It builds a specialized delegate (function) that copies values from source to destination, handling type checks and assignments. This delegate is compiled into native code.
3. Caching: This compiled delegate is stored in a ConcurrentDictionary.
4. Subsequent Runs: Every future call fetches the compiled delegate from the cache and executes it immediately, incurring overhead comparable to writing the mapping code by hand.

License

MIT