Mappy.dotNet 2.1.0

🍁Mappy - Object Mapping

Introduction

Mappy is a lightweight object mapping utility for C# applications. It allows you to easily map objects between models and DTOs, handle nested objects, and map collections. This utility supports both synchronous and asynchronous mapping operations, with options for custom transformations.

Features

• Simple Object Mapping: Map properties between objects with identical names and types.
• Nested Object Mapping: Automatically maps nested properties.
• Collection Mapping: Handles collections of objects and maps them to the destination collection type.
• Custom Mapping: Supports custom transformations using lambda expressions.
• Asynchronous Mapping: Enables async operations for custom transformations.
• Null Safety: Handles null values gracefully.
• Support mapping private properties.
• Type Safety: Ensures type safety by matching properties based on type rather than just name, preventing errors when types differ.
• Circular Reference Handling: Implements circular reference handling function. 🆕
• Performance: Provides good performance for typical scenarios. 🆕

Installation

To install Mappy, you can use NuGet:

dotnet add package Mappy.dotNet --version 2.1.0

Usage

1. Simple Mapping

var source = new Source { Id = 1, Name = "Test" };
var destination = source.Map<Destination>();
Console.WriteLine($"Simple Mapping - Source Name: {source.Name}, Destination Name: {destination.Name}");

Simple Mapping - Source Name: Test, Destination Name: Test

2. Nested Object Mapping

var nestedSource = new NestedSource { Id = 1, Inner = new InnerSource { Detail = "DetailInfo" } };
var nestedDestination = nestedSource.Map<NestedDestination>();
Console.WriteLine($"Nested Mapping - Source Detail: {nestedSource.Inner.Detail}, Destination Detail: {nestedDestination.Inner.Detail}");

Nested Mapping - Source Detail: DetailInfo, Destination Detail: DetailInfo

3. Collection Mapping

var sourceList = new List<Source>
            {
                new Source { Id = 1, Name = "Item1" },
                new Source { Id = 2, Name = "Item2" }
            };
var destinationList = sourceList.MapCollection<Destination>();
Console.WriteLine("Collection Mapping:");
foreach (var item in destinationList)
{
    Console.WriteLine($"Source Name: {item.Name}");
}

Collection Mapping:
Source Name: Item1
Source Name: Item2

4. Async Mapping

var asyncSource = new Source { Id = 2, Name = "AsyncTest" };
var asyncDestination = await asyncSource.MapAsync<Destination>(async d =>
{
    d.Name = await Task.FromResult(asyncSource.Name + " - Async");
});
Console.WriteLine($"Async Mapping - Source Name: {asyncSource.Name}, Destination Name: {asyncDestination.Name}");

Async Mapping - Source Name: AsyncTest, Destination Name: AsyncTest - Async

5. Custom Mapping

var source4 = new Source { Id = 1, Name = "Test" };

var customDestination = source.Map<Destination>(d =>
{
    // Custom logic: Add a suffix to the Name property
    d.Name = $"{source.Name} - Custom Mapped";
});

Console.WriteLine($"Custom Mapping - Source Name: {source.Name}, Destination Name: {customDestination.Name}");

Custom Mapping - Source Name: Test, Destination Name: Test - Custom Mapped

6. Asynchronous Custom Mapping

var asyncSource4 = new Source { Id = 2, Name = "AsyncTest" };

var asyncCustomDestination = await asyncSource.MapAsync<Destination>(async d =>
{
    // Custom async logic: Simulate an async transformation
    d.Name = await Task.FromResult(source.Name + " - Async Custom");
});

Console.WriteLine($"Async Custom Mapping - Source Name: {asyncSource.Name}, Destination Name: {asyncCustomDestination.Name}");

Async Custom Mapping - Source Name: AsyncTest, Destination Name: Test - Async Custom

7. Type Safety :🆕

try
{
    var source = new Source { Id = 1, Name = "Test" };
    var invalidDestination = source.Map<InvalidDestination>(); // Will throw InvalidOperationException due to type mismatch
}
catch (InvalidOperationException ex)
{
    Console.WriteLine($"Type Safety Error: {ex.Message}");
}

8. Performance Test (Simple & Async) :🆕

int count = 10000;
var largeSourceList = Enumerable.Range(1, count).Select(i => new Source { Id = i, Name = "Test" }).ToList();

// Measuring Simple Mapping Performance
var stopwatch = System.Diagnostics.Stopwatch.StartNew();
var largeDestinationList = largeSourceList.MapCollection<Destination>();
stopwatch.Stop();
Console.WriteLine($"Simple Collection Mapping Performance: {stopwatch.ElapsedMilliseconds} ms for {count} items");

// Measuring Asynchronous Mapping Performance
stopwatch.Restart();
var largeAsyncDestinationList = await largeSourceList.MapCollectionAsync<Destination>(async d =>
{
    d.Name = await Task.FromResult("Async - " + d.Name);
});
stopwatch.Stop();
Console.WriteLine($"Asynchronous Collection Mapping Performance: {stopwatch.ElapsedMilliseconds} ms for {count} items");

Simple Collection Mapping Performance: 18 ms for 10000 items
Asynchronous Collection Mapping Performance: 29 ms for 10000 items

Performance Considerations

While Mappy is effective for typical scenarios, it may not be optimized for very large datasets or scenarios with high-frequency mapping needs. The performance of the library could be impacted by reflection-based operations, especially for large collections and complex nested mappings.

Contributing

Contributions to Mappy are welcome! If you find any issues or have suggestions for improvements, feel free to create a pull request or report an issue.

License

This project is open source and can be freely modified and distributed.