AlephMapper 0.3.8

Terms of use^?

By using this project or its source code, for any purpose and in any shape or form, you grant your implicit agreement to all the following statements:

• You condemn Russia and its military aggression against Ukraine
• You recognize that Russia is an occupant that unlawfully invaded a sovereign state
• You support Ukraine's territorial integrity, including its claims over temporarily occupied territories of Crimea and Donbas
• You reject false narratives perpetuated by Russian state propaganda

To learn more about the war and how you can help, click here. Glory to Ukraine! 🇺🇦

AlephMapper

AlephMapper is a Source Generator that automatically creates projectable and/or updatable companion methods from your mapping logic. It enables you to write mapping methods once and use them both for in-memory objects and as expression trees for database queries (Entity Framework Core projections).

🚀 Features

• Expression Tree Generation - Automatically converts method bodies to expression trees
• Null-Conditional Operator Support - Configurable handling of ?. operators
• Updatable Methods - Generate update methods that modify existing instances

📦 Installation

dotnet add package AlephMapper

🏃‍♂️ Quick Start

1. Mark your mapping class or method with [Expressive]. Please ensure that your class is static and partial.

public static partial class PersonMapper
{
    [Expressive]
    public static PersonDto MapToPerson(Employee employee) => new PersonDto
    {
        Id = employee.EmployeeId,
        FullName = GetFullName(employee),
        Email = employee.ContactInfo.Email,
        Age = CalculateAge(employee.BirthDate),
        Department = employee.Department?.Name ?? "Unknown"
    };

    public static string GetFullName(Employee employee) => 
        $"{employee.FirstName} {employee.LastName}";

    public static int CalculateAge(DateTime birthDate) => 
        DateTime.Now.Year - birthDate.Year;
}

2. AlephMapper will generate the following method for you:

partial class PersonMapper 
{
    public static Expression<Func<Employee, PersonDto>> MapToPersonExpression() => employee => new PersonDto
    {
        Id = employee.EmployeeId,
        FullName = $"{employee.FirstName} {employee.LastName}",
        Email = employee.ContactInfo.Email,
        Age = DateTime.Now.Year - employee.BirthDate.Year,
        Department = employee.Department.Name ?? "Unknown"
    };
}

3. Use generated expression methods in Entity Framework queries

// The source generator creates PersonMapper.MapToPersonExpression() automatically
var personDtos = await dbContext.Employees
    .Select(PersonMapper.MapToPersonExpression())
    .ToListAsync();

4. Use the original methods for in-memory operations

var employee = GetEmployee();
var personDto = PersonMapper.MapToPerson(employee);
var fullName = PersonMapper.GetFullName(employee);

🔧 Advanced Features

Null-Conditional Operator Handling

AlephMapper provides flexible handling of null-conditional operators (?.):

[Expressive(NullConditionalRewrite = NullConditionalRewrite.Rewrite)]
public static partial class SafeMapper
{
    // This method uses null-conditional operators
    public static PersonSummary GetSummary(Person person) => new PersonSummary
    {
        Name = person.Name,
        Age = person.BirthInfo?.Age,
        City = person.BirthInfo?.Address?.City,
        HasAddress = person.BirthInfo?.Address != null
    };
}

Rewrite Options:

• None - Don't allow null-conditional operators (throws compile error)
• Ignore - Remove null-conditional operators (may cause NullReferenceException)
• Rewrite - Convert to explicit null checks: person.BirthInfo?.Age becomes person.BirthInfo != null ? person.BirthInfo.Age : null

Updatable Methods

From a single mapping, AlephMapper can emit an update-in-place overload that writes into an existing instance (instead of creating a new one). This is especially suitable for EF Core entity updates with change tracking: you keep the same tracked instance, so EF can detect modified properties and produce the correct UPDATE.

[Updatable]
public static Person MapToPerson(PersonUpdateDto dto) => new Person
{
    FirstName = dto.FirstName,
    LastName  = dto.LastName,
    Email     = dto.Email
    // ...
};

// Generated usage with EF Core change tracking:
var person = await db.People.FindAsync(id);           // tracked entity
PersonMapper.MapToPerson(dto, target: person); // mutate in-place
await db.SaveChangesAsync();                           // EF sees changes on the same instance

🔍 How It Works

For each method marked with [Expressive]:

1. MapToPersonDto(Employee employee) → generates MapToPersonDtoExpression() returning Expression<Func<Employee, PersonDto>>
2. Method calls are inlined - Calls to other methods are automatically inlined into the expression tree
3. Null-conditional operators are handled according to your specified rewrite policy

For each method marked with [Updatable]:

1. MapToPersonDto(Employee employee) → generates MapToPersonDto(Employee employee, PersonDto target) returning PersonDto
2. Method calls are inlined - Calls to other methods in the same class are automatically inlined into the method

⚠️ Limitations

Methods must be:

• expression-bodied,
• static
• be member of a partial static class.

🔄 Migration from Other Mappers

From AutoMapper

// AutoMapper
CreateMap<Employee, PersonDto>()
    .ForMember(dest => dest.FullName, opt => opt.MapFrom(src => src.FirstName + " " + src.LastName));

// AlephMapper
[Expressive]
public static partial class PersonMapper
{
    public static PersonDto MapToPerson(Employee employee) => new PersonDto
    {
        FullName = employee.FirstName + " " + employee.LastName,
        // ... other mappings
    };
}

From Manual Expression Trees

// Manual Expression Trees
Expression<Func<Employee, PersonDto>> expression = e => new PersonDto
{
    FullName = e.FirstName + " " + e.LastName
};

// AlephMapper - Same result, but with method reusability
[Expressive]
public static partial class PersonMapper
{
    public static PersonDto MapToPerson(Employee employee) => new PersonDto
    {
        FullName = GetFullName(employee) // This gets inlined in the expression
    };
    
    public static string GetFullName(Employee employee) => 
        employee.FirstName + " " + employee.LastName;
}

🤝 Contributing

We welcome contributions!

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by EntityFrameworkCore.Projectables and Expressionify
• Thanks to all contributors

🔗 Related Projects

• EntityFrameworkCore.Projectables - Similar concept with different approach
• Expressionify - Similar concept with different approach
• AutoMapper - Popular object-to-object mapper
• Mapster - Fast object mapper
• Facet

Star ⭐ this repository if AlephMapper helps you build better applications!