CoreMap

CoreMap is a lightweight, di friendly object mapping library designed for Clean Architecture in modern .NET applications. It promotes manual mapping via handler classes, encouraging full control, maintainability, and testability.

✨ Features

• 🔌 DI-integrated mapper resolution – mapping handlers are fully resolved from your DI container
• 🧩 Supports constructor injection – mapping logic can depend on other services (e.g. complex mapping helper services)
• ♻️ Scoped mapping handlers by default – efficient and consistent, but configurable
• ⚙️ Zero reflection, zero magic – fully explicit, traceable, and easy to debug
• 🧪 Easy to test – works seamlessly with standard unit test libraries and mocking frameworks
• 🌐 Minimal dependencies – compatible with .NET Standard 2.0 and .NET 8.0+

❓ Why CoreMap?

You might ask: Why use CoreMap when powerful libraries like AutoMapper or Mapster already exist?

While those tools are excellent and offer rich features, CoreMap was created with a different goal in mind:

✅ To enforce manual, explicit mappings that reduce ambiguity and avoid surprises — especially for teams following Clean Architecture and MediatR-style design.

CoreMap favors:

• Clarity over cleverness – no magic, no reflection, no unexpected behavior.
• Mental flow consistency – you're already using IRequest + IRequestHandler patterns with MediatR-Style and with CoreMap, you follow the same structure:
  DTOs & Entities + IMapHandler<TInput, TOutput>.
  This reduces mental context switching and increases speed through familiarity.
• New dev friendliness – explicit handler-based mapping makes the codebase easier to reason about for anyone unfamiliar with AutoMapper-style conventions.
• Strict control – essential for mapping across boundaries like DTOs ↔ domain models, where implicit behavior can introduce subtle bugs.
• Service injection support – unlike static extension methods, CoreMap handlers are resolved from DI, allowing you to inject services (e.g. ID generators, localization providers) when mappings require context.

CoreMap doesn't try to replace general-purpose mappers — it focuses on intentional mapping in architecturally disciplined applications.

🔖 Versioning Policy

🚧 Pre-1.0.0 (0.x.x)

• The project is considered Work In Progress.
• Breaking changes can occur at any time without notice.
• No guarantees are made about stability or upgrade paths.

✅ Post-1.0.0 (1.x.x and beyond)

Follows a common-sense semantic versioning pattern:

• Major (X.0.0)

  • Introduces major features or architectural changes
  • May include well documented breaking changes

• Minor (1.X.0)

  • Adds new features or enhancements
  • May include significant bug fixes
  • No breaking changes

• Patch (1.0.X)

  • Hotfixes or urgent bug fixes
  • Safe to upgrade
  • No breaking changes

📦 Installation

dotnet add package CoreMap

🚀 Usage

1. Create Entities

public record ArticleEntity
{
    public Guid Id { get; init; }
    public string Title { get; init; } = default!;
    public string Description { get; init; } = default!;
    public AuthorEntity WrittenBy { get; init; } = default!;
}

public record AuthorEntity
{
    public Guid Id { get; init; }
    public string Name { get; init; } = default!;
}

2. Create Responses (DTOs)

internal record ArticleResponse
{
    public Guid Id { get; init; }
    public string Title { get; init; } = default!;
    public string Description { get; init; } = default!;
    public AuthorResponse Author { get; init; } = default!;
}

internal class AuthorResponse
{
    public Guid Id { get; init; }
    public string Title { get; init; } = default!;
    public string Description { get; init; } = default!;
}

3. Create Mapping Handlers

internal class AuthorResponseToEntityMap : ICoreMapHandler<AuthorResponse, AuthorEntity>
{
    public AuthorEntity Handler(AuthorResponse data, ICoreMap alsoMap) => new AuthorEntity()
    {
        Id = data.Id,
        Name = data.Title
    };
}

internal class ArticleResponseToEntityMap : ICoreMapHandler<ArticleResponse, ArticleEntity>
{
    public ArticleEntity Handler(ArticleResponse data, ICoreMap alsoMap) => new ArticleEntity()
    {
        Description = data.Description,
        Id = data.Id,
        Title = data.Title,
        WrittenBy = alsoMap.MapEach(data.Author).To<AuthorEntity>()
    };
}

4. Register Services

public static IServiceCollection AddServices(IServiceCollection services)
{
    // Assembly-scanned registration
    services.AddCoreMap(o => { }, new Type[]
    {
        typeof(Startup)
    });

    // Or manual registration
    services.AddCoreMap(o => { });
    services.AddScoped<ICoreMapHandler<ArticleResponse, ArticleEntity>, ArticleResponseToEntityMap>();
    services.AddScoped<ICoreMapHandler<AuthorResponse, AuthorEntity>, AuthorResponseToEntityMap>();

    return services;
}

5. Mapping Examples

Fluent Mapping (Preferred)

Map a single object

ArticleEntity item = coreMap.Map(response).To<ArticleEntity>();

Map a collection

ICollection<ArticleEntity> entities =
    coreMap.MapEach(responses).To<ArticleEntity>();

Traditional Mapping (Still Supported)

Map a single object

ArticleEntity item = coreMap.MapTo<ArticleResponse, ArticleEntity>(response);

Map a collection

ICollection<ArticleEntity> entities =
    coreMap.MapEachTo<ArticleResponse, ArticleEntity>(responses);