TrueMapper 1.1.0

TrueMapper

🚀 TrueMapper - Advanced Object Mapping Library for .NET

TrueMapper is a powerful, feature-rich object-to-object mapping library for .NET that provides intuitive MapTo() extension methods, comprehensive collection support, smart type conversion, conditional mapping, middleware support, circular reference detection, performance metrics, and much more.

✨ Key Features

🎯 Intuitive Extension Methods

• Fluent MapTo<T>() API for seamless object mapping
• Intelligent type routing: obj.MapTo<Type>() vs collection.MapTo<List<Type>>()
• Clear error messages for invalid mapping scenarios
• Zero-configuration setup for most use cases

📋 Comprehensive Collection Support

• Support for all major .NET collection types: List<T>, T[], HashSet<T>, Queue<T>, Stack<T>, LinkedList<T>
• Observable and concurrent collections: ObservableCollection<T>, ConcurrentBag<T>, ConcurrentQueue<T>, etc.
• Proper null handling in collection mappings
• Strongly-typed collection transformations

🎯 Smart Type Conversion

• Intelligent type conversion with advanced logic
• Handles complex scenarios like enum-to-string, numeric overflow protection
• Custom boolean representations (yes/no, on/off, 1/0)
• Safe numeric conversions with overflow detection

🔄 Conditional Mapping

• Apply mapping logic based on runtime conditions
• Support for conditional transformations
• Flexible rule-based mapping scenarios

🛠️ Middleware Pipeline

• Extensible middleware architecture
• Built-in middleware for validation, logging, caching
• Custom transformation pipeline support
• Pre and post-processing capabilities

🔍 Circular Reference Detection

• Automatic detection and handling of circular references
• Configurable depth limits
• Memory-safe deep object traversal

📊 Performance Metrics

• Built-in performance monitoring
• Memory usage tracking
• Detailed mapping statistics
• Garbage collection monitoring

🏗️ Advanced Configuration

• Fluent API for easy setup
• Auto-discovery mapping profiles
• Multiple configuration strategies
• Profile-based configuration management

📦 Installation

# Install via NuGet Package Manager
Install-Package TrueMapper

# Install via .NET CLI
dotnet add package TrueMapper

# Install via PackageReference
<PackageReference Include="TrueMapper" Version="1.0.0" />

🚀 Quick Start

Basic Usage

using TrueMapper.Core.Extensions;

// Simple object mapping with fluent API
var source = new SourceClass { Name = "John", Age = 30 };
var destination = source.MapTo<DestinationClass>();

// Collection mapping to List<T>
var sourceList = new List<SourceClass> { source };
var destinationList = sourceList.MapTo<List<DestinationClass>>();

// Collection mapping to different collection types
var destinationArray = sourceList.MapTo<DestinationClass[]>();
var destinationHashSet = sourceList.MapTo<HashSet<DestinationClass>>();

// Anonymous objects
var anonymousSource = new { Name = "Jane", Age = 25 };
var result = anonymousSource.MapTo<DestinationClass>();

Intelligent Type Routing

TrueMapper automatically routes to the appropriate mapping logic:

// Single object mapping
Person person = new Person { Name = "John" };
PersonDto dto = person.MapTo<PersonDto>();  // Returns PersonDto

// Collection mapping
List<Person> people = GetPeople();
List<PersonDto> dtos = people.MapTo<List<PersonDto>>();  // Returns List<PersonDto>

// Error: Invalid mapping (collection to single object)
var invalid = people.MapTo<PersonDto>();  // Throws clear error message

Advanced Collection Support

var sourceList = GetSourceItems();

// Various collection types supported
var list = sourceList.MapTo<List<DestinationItem>>();
var array = sourceList.MapTo<DestinationItem[]>();
var hashSet = sourceList.MapTo<HashSet<DestinationItem>>();
var queue = sourceList.MapTo<Queue<DestinationItem>>();
var stack = sourceList.MapTo<Stack<DestinationItem>>();
var observableCollection = sourceList.MapTo<ObservableCollection<DestinationItem>>();

Traditional API (still supported)

using TrueMapper.Core.Core;

var mapper = new TrueMapper();

// Standard mapping with both type parameters
var result1 = mapper.Map<SourceClass, DestinationClass>(source);

// Simplified mapping with destination type inference
var result2 = mapper.Map<DestinationClass>(source);

// Collection mapping
var sourceList = new List<object> { source };
var destinationList = mapper.Map<DestinationClass>(sourceList);

Advanced Configuration

using TrueMapper.Core.Core;

var mapper = new TrueMapper();

// Configure with fluent API
mapper.Configure()
    .WithCircularReferenceDetection(true)
    .WithMetrics(true)
    .WithMaxDepth(20)
    .WithNullPropagation(false);

// Create custom mapping profiles
mapper.Configure()
    .CreateMap<Source, Destination>()
    .ForMember(dest => dest.FullName, src => $"{src.FirstName} {src.LastName}")
    .When(src => src.IsActive, 
          (src, dest) => dest.Status = "Active",
          (src, dest) => dest.Status = "Inactive")
    .Ignore(dest => dest.InternalId)
    .Transform(dest => {
        dest.ProcessedAt = DateTime.UtcNow;
        return dest;
    });

var result = mapper.Map<Source, Destination>(source);

🛡️ Advanced Features

Conditional Mapping

mapper.Configure()
    .CreateMap<User, UserDto>()
    .When(user => user.IsAdmin,
          (user, dto) => dto.Permissions = "All",
          (user, dto) => dto.Permissions = "Limited");

Middleware Pipeline

// Built-in validation middleware
pipeline.Use(ValidationMiddleware.NullCheck());
pipeline.Use(ValidationMiddleware.Custom(
    ctx => ctx.Source != null,
    "Source cannot be null"));

// Built-in logging middleware
pipeline.Use(LoggingMiddleware.Create(msg => Console.WriteLine(msg)));

// Built-in caching middleware
pipeline.Use(CachingMiddleware.Create(
    ctx => $"{ctx.SourceType.Name}_{ctx.Source.GetHashCode()}",
    ttlMinutes: 30));

// Custom transformation middleware
pipeline.Use(TransformationMiddleware.PostTransform(obj => {
    if (obj is ITrackable trackable)
        trackable.LastModified = DateTime.UtcNow;
    return obj;
}));

Profile-Based Configuration

[MappingProfile(Name = "UserProfile", Priority = 1)]
public class UserMappingProfile : MappingProfile
{
    protected override void ConfigureMappings()
    {
        CreateMap<User, UserDto>()
            .ForMember(dto => dto.DisplayName, user => user.GetDisplayName())
            .Ignore(dto => dto.InternalNotes);

        CreateMap<UserDto, User>()
            .When(dto => !string.IsNullOrEmpty(dto.Email),
                  (dto, user) => user.Email = dto.Email.ToLowerInvariant());
    }
}

// Auto-discovery
var registry = ProfileDiscovery.CreateAutoDiscoveredRegistry();
var mapper = new TrueMapper(registry.GetMergedConfiguration());

Performance Monitoring

var mapper = new TrueMapper();

// Perform mappings...
mapper.Map<Source, Destination>(source);

// Get performance metrics
var metrics = mapper.GetMetrics();
Console.WriteLine($"Total mappings: {metrics.TotalMappings}");
Console.WriteLine($"Average time: {metrics.AverageMappingTime}ms");
Console.WriteLine($"Peak memory: {metrics.MemoryStats.PeakMemoryUsage} bytes");
Console.WriteLine($"Circular refs detected: {metrics.CircularReferencesDetected}");

🆚 TrueMapper vs AutoMapper

📊 Performance Benchmarks

BenchmarkDotNet=v0.13.0, OS=Windows 10.0.19044
Intel Core i7-9750H CPU 2.60GHz, 1 CPU, 12 logical and 6 physical cores
.NET 8.0.0 (8.0.0.0), X64 RyuJIT

|          Method |     Mean |   Error |  StdDev |      Gen0 | Allocated |
|---------------- |---------:|--------:|--------:|----------:|----------:|
|     TrueMapper  | 127.3 ns | 2.1 ns  | 1.8 ns  |   0.0229  |     144 B |
|     AutoMapper  | 285.7 ns | 5.2 ns  | 4.9 ns  |   0.0534  |     336 B |
|  ManualMapping  |  45.2 ns | 0.8 ns  | 0.7 ns  |   0.0153  |      96 B |

🏗️ Architecture

TrueMapper is built with a modular architecture:

• Core: Main mapping engine and interfaces
• Configuration: Fluent API and profile management
• Converters: Smart type conversion system
• Middleware: Extensible processing pipeline
• Performance: Metrics and monitoring
• Profiles: Auto-discovery and management
• Extensions: Convenience methods and utilities

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/iuliansilitra/TrueMapper.git
cd TrueMapper
dotnet restore
dotnet build
dotnet test

📝 License

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

🔗 Links

• Documentation
• API Reference
• Examples
• Benchmarks

🏆 Why Choose TrueMapper?

1. 🎯 Smart by Default: Intelligent type conversion without manual configuration
2. 🛡️ Safe and Robust: Built-in circular reference detection and memory management
3. 📈 Performance Focused: Optimized algorithms with built-in monitoring
4. 🔧 Highly Configurable: Flexible configuration options for any scenario
5. 🚀 Modern Architecture: Designed for .NET 8+ with async and middleware support
6. 📦 Easy to Use: Intuitive API with extensive documentation and examples

Made by Iulian Silitra

⭐ Star this repo if you find it useful!