VelocityMapper 1.2.1-preview

VelocityMapper

The fastest .NET mapper. Zero reflection. Zero overhead. Powered by Source Generators.

VelocityMapper uses Source Generators to generate optimized mapping code at compile-time. Familiar AutoMapper-style API with superior performance.

📦 Installation

dotnet add package VelocityMapper

Supported frameworks: .NET 6, 8, 9, 10

⚠️ Required: Enable Source Generator in Your Project

VelocityMapper requires the Source Generator to work. Add this to your .csproj:

<ItemGroup>
  <ProjectReference Include="path/to/VelocityMapper.Generators.csproj" 
                    OutputItemType="Analyzer" 
                    ReferenceOutputAssembly="false" />
</ItemGroup>

If you installed via NuGet, the analyzer is automatically included - no additional configuration needed.

If you're referencing the source project, you must add the reference above to enable code generation at compile-time.

🚀 Quick Start

1. Create your models

public class User
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
    public Address Address { get; set; }
}

public class UserDto
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
    public AddressDto Address { get; set; }
}

2. Configure mappings

using VelocityMapper;

public static class AppMapperConfig
{
    [MapperConfiguration]
    public static void ConfigureMappers()
    {
        MapperSetup.CreateMap<User, UserDto>();
        MapperSetup.CreateMap<Address, AddressDto>();
    }
}

3. Use the mapper

var user = new User { Id = 1, Name = "John", Email = "john@email.com" };

// ⚡ Create new instance
var dto = Mapper.To<UserDto>(user);

// Zero allocation - map to existing object
var existingDto = new UserDto();
Mapper.To(user, existingDto);

📚 API

Basic Mapping

// New instance
var dto = Mapper.To<UserDto>(user);

// To existing object (zero allocation)
Mapper.To(user, existingDto);

Collection Mapping

// ⚡ NEW API - Cleaner and faster with Span!
var users = GetUsers(); // List<User>, User[], IEnumerable<User>

// ToList - Auto-optimized with CollectionsMarshal.AsSpan (.NET 8+)
List<UserDto> dtos = Mapper.ToList<UserDto>(users);

// ToArray - Optimized with Span zero-copy
UserDto[] array = Mapper.ToArray<UserDto>(users);

// ToEnumerable - Lazy evaluation (deferred execution)
IEnumerable<UserDto> enumerable = Mapper.ToEnumerable<UserDto>(users);
var filtered = enumerable.Where(x => x.Id > 10).ToList();

// ToSpan - TRUE zero allocation (advanced)
Span<UserDto> destination = stackalloc UserDto[100];
Mapper.ToSpan(users.AsSpan(), destination);

// Legacy API (still supported, but ToList/ToArray are faster)
List<UserDto> dtos2 = CollectionMapper.MapToList(users, Mapper.To<UserDto>);

🔄 Mapping Behavior

Extra Properties are Automatically Ignored

VelocityMapper maps based on destination properties. Properties that exist only in the source are automatically ignored:

public class User
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
    public string PasswordHash { get; set; }  // Only exists in entity
}

public class UserDto
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
    // PasswordHash doesn't exist → ignored automatically!
}

var dto = Mapper.To<UserDto>(user);
// dto will have: Id, Name, Email
// PasswordHash is silently ignored ✓

Attributes

public class UserDto
{
    public int Id { get; set; }
    
    [MapFrom("FirstName")]  // Map from differently named property
    public string Name { get; set; }
    
    [IgnoreMap]  // Explicitly ignore (documentation)
    public string CacheKey { get; set; }
}

🏎️ Performance

Benchmark on .NET 10 (Intel Core i5-14600KF):

VelocityMapper is faster than hand-written code.

🔧 How It Works

The Source Generator analyzes your code at compile-time and generates optimized methods:

// You write:
Mapper.CreateMap<User, UserDto>();
var dto = Mapper.To<UserDto>(user);

// The generator automatically creates:
public static UserDto To(User source)
{
    return new UserDto
    {
        Id = source.Id,           // Value types first (cache-friendly)
        Age = source.Age,
        Name = source.Name,       // Reference types after
        Email = source.Email,
        Address = source.Address is { } addr ? To(addr) : null  // Nested mapping
    };
}

📋 Quick Reference

New API: ToList, ToArray and ToEnumerable automatically detect List/Array and use fast-path with Span!

📄 License

MIT License - see LICENSE