ProjectIMap 2.0.0

ProjectIMap (v2.0.0)

A high-performance, zero-allocation, compile-time object-to-object mapper for .NET.

ProjectIMap bridges the gap between developer experience and bare-metal performance. By utilizing a modern Roslyn Incremental Source Generator, it provides the clean, centralized configuration of AutoMapper while delivering the zero-reflection execution speed of Mapster.

🚀 The Hybrid Architecture

Traditional mappers rely on heavy runtime reflection, JIT-compiled Expression Trees, or scattered inline configurations. ProjectIMap shifts the entire mapping engine to compile-time.

When you define a profile, the Roslyn generator analyzes your syntax tree and writes pure, plain C# extension methods directly into your assembly during the build process.

• No Reflection at Runtime: Zero startup penalty and zero heap allocations.
• No IMapper Interfaces: No Dependency Injection registration required for execution.
• 100% Debuggable: You can F12 directly into the generated mapping code to see exactly how your properties are assigned.

✨ Key Features

1. Dual-Path Generation (In-Memory & EF Core)

For every mapping configuration, ProjectIMap automatically generates two optimized execution paths:

• The Fast Path (MapTo...): A static extension method using null-conditional operators for safe, allocation-free, in-memory object mapping.
• The Projection Path (ProjectTo...): A pre-compiled Expression<Func<TSource, TDest>> specifically formatted for Entity Framework Core. It guarantees clean SQL translation (e.g., via LEFT JOINs) without throwing InvalidOperationException or containing illegal Expression.Block nodes.

2. Strict Nullable Safety

ProjectIMap enforces CLR-level nullable invariants. It will never blindly unwrap a nullable value type (int? → int). If a nullable boundary is crossed, the generator emits strict ternary guards (HasValue ? Value : default), preventing the dreaded InvalidProgramException and runtime crashes associated with dynamic IL mappers.

3. Trie-Based Flattening & Unflattening

Nested object properties are automatically flattened into DTOs using an optimized prefix-tree matching algorithm during the build phase.

• source.Customer.Address.City automatically maps to dest.CustomerAddressCity.
• This works bidirectionally, successfully unflattening flat DTOs back into complex domain models.

4. DFS Cycle Detection

Safely maps self-referencing object graphs (e.g., User → Manager → User) without throwing StackOverflowExceptions.

📦 Installation

Install the library via the .NET CLI:

dotnet add package ProjectIMap

Note: ProjectIMap v2 is bundled as a Roslyn Analyzer and Source Generator. Once installed, it will automatically run in the background of your IDE and integrate into your build pipeline without any extra configuration.

📖 Quick Start Guide
1. Define a Profile
Centralize your mapping logic by inheriting from MappingProfile. The Source Generator actively monitors these classes.

C#
using ProjectIMap;

public class UserProfile : MappingProfile
{
    public UserProfile()
    {
        CreateMap<User, UserDto>()
            // Standard property matching and flattening happens automatically.
            // Use ForMember to explicitly override conventions:
            .ForMember(dest => dest.FullName, opt => opt.MapFrom(src => $"{src.FirstName} {src.LastName}"));
    }
}
2. Map In-Memory (Standard Execution)
Because mapping code is generated at compile-time, you do not need to register or inject an IMapper. Simply call the generated extension method on your source object.

C#
var user = new User { FirstName = "John", LastName = "Doe" };

// Automatically generated at compile-time!
UserDto dto = user.MapToUserDto(); 

Console.WriteLine(dto.FullName); // Output: John Doe
3. Project via Entity Framework Core
When reading from a database, never map in memory. Use the generated ProjectTo... expression to instruct the SQL server to fetch only the required columns.

C#
// No runtime expression building overhead!
var activeUsers = await _dbContext.Users
    .Where(u => u.IsActive)
    .Select(UserToUserDtoMapper.ProjectToUserDto) // Generated EF-safe expression
    .ToListAsync();
🤖 AI Agent Integration Prompt (Copilot / ChatGPT)
ProjectIMap is uniquely architected. To ensure your AI coding assistants (like GitHub Copilot, ChatGPT, or Claude) generate accurate code using this library, copy and paste the block below into your AI's system instructions or chat context.

Plaintext
**ProjectIMap Code Generation Directives:**

I am using `ProjectIMap v2`, a Roslyn Source Generator-based object mapping framework for .NET. 

When generating mapping code, you MUST adhere strictly to these rules:

1. Configuration: All mapping configurations must reside in a class inheriting from `MappingProfile`. Define mappings inside the constructor using `CreateMap<TSource, TDest>()`.
2. Custom Logic: To override conventions, use `.ForMember(dest => dest.Property, opt => opt.MapFrom(src => [logic]))`. Do not write manual overrides for standard flattening (e.g., `src.Role.Name` to `dest.RoleName` happens automatically).
3. No Dependency Injection: Do NOT inject `IMapper` into services. The library generates static extension methods at compile time.
4. In-Memory Execution: Execute maps by calling the generated extension method directly on the object: `sourceObject.MapTo[DestinationType]()` (e.g., `user.MapToUserDto()`).
5. EF Core Projections: For database queries, do not map in-memory. Use the generated static expression property inside a LINQ select: `.Select([Source]To[Destination]Mapper.ProjectTo[Destination])` (e.g., `.Select(UserToUserDtoMapper.ProjectToUserDto)`).
6. Nullability: Trust the generator to handle null propagation safely. Do not write manual null-checks arou