ImmutaMap 9.2.2

ImmutaMap

High‑performance, allocation‑aware mapping for immutable (and mutable) .NET types.

Seamlessly map between records, classes, anonymous types, and dynamic targets with inline configuration, attribute / type transforms, and async support.

Why ImmutaMap?

Most mappers were designed around mutable POCOs. When you lean into C# records and immutable design, you either:

• Lose ergonomics (manual constructor plumbing everywhere), or
• Fall back to reflection (slow, alloc heavy), or
• Maintain piles of hand‑written projection code.

ImmutaMap focuses on immutable‑first scenarios while still supporting classic mutable types. It compiles mapping plans (constructor + property delegates), caches them, and applies only the transforms you ask for.

Key capabilities:

• Map record → class, class → record, class → class, record → record.
• Inline fluent configuration (rename, skip, transform property / type / attribute).
• Sync & async transforms (per property or per type) without changing your domain models.
• Update immutable instances using With (expression or anonymous type) – new instance every time.
• Copy into existing mutable targets (Copy, CopyAsync), including name remaps.
• Attribute‑driven transforms (source & target side) with full control.
• Dynamic mapping (ToDynamic) – shape an object on the fly.

Full test coverage examples: TargetBuilderTests.cs

Quick Start

Install via source today (NuGet packaging WIP):

git clone https://github.com/TripleG3/ImmutaMap.git
cd ImmutaMap
dotnet build

Reference ImmutaMap from your project, then:

var person = new PersonRecord("Mike", "Doe", 42);
var dto = person.To<PersonRecord, PersonDto>();

Core API Surface

Examples

1. Simple Map (record → class)

var record = new PersonRecord("Mike", "Doe", 42);
var cls = record.To<PersonRecord, PersonClass>(_ => { });

2. Rename a Property

var employee = record.To<PersonRecord, Employee>(cfg =>
{
	cfg.MapName(r => r.FirstName, e => e.GivenName)
		.MapName(r => r.LastName,  e => e.Surname);
});

3. Skip & Case‑Insensitive Mapping

var model = something.To<Source, Target>(cfg =>
{
	cfg.IgnoreCase = true; // 'firstname' -> 'FirstName'
	cfg.Skip(s => s.Secret);
});

4. Per‑Property Transform

var updated = order.To<Order, OrderDto>(cfg =>
{
	cfg.MapPropertyType(o => o.Total, total => Math.Round(total, 2));
});

5. Attribute‑Driven Transform (Source)

var result = person.To<PersonRecord, PersonClass>(cfg =>
{
	cfg.MapSourceAttribute<FirstNameAttribute>((attr, value) => attr.RealName);
});

6. Global Type Transform

var message = dto.To<MessageDto, Message>(cfg =>
{
	cfg.MapType<DateTime>(d => d.ToLocalTime());
});

7. Async Type Transform

var msg = await dto.ToAsync<MessageDto, Message>(cfg =>
{
	cfg.MapTypeAsync<DateTime>(async d => d.ToLocalTime());
});

8. Updating Immutable Instance (With)

var person = new PersonRecord("Mike", "Doe", 42);
var older = person.With(p => p.Age, age => age + 1);
var renamed = person.With(new { FirstName = "John" });

9. Copy Into Existing Mutable Target

target.Copy(source); // shallow mapped properties by name

target.Copy(source, cfg =>
{
	cfg.MapName(s => s.Counter, t => t.Count)
		.MapName(s => s.Item_2,  t => t.Item2);
});

10. Dynamic Mapping

dynamic shaped = person.ToDynamic(cfg =>
{
	cfg.Skip(p => p.Age);
});
Console.WriteLine(shaped.FirstName);

Async Patterns

Async overloads mirror sync but use AsyncConfiguration<,> and accept:

• MapTypeAsync<T>(Func<T, Task<object?>>)
• MapPropertyTypeAsync(expr, ValueTask<object>)

They can be combined with sync transforms.

Error Handling

Set WillNotThrowExceptions = true in a configuration to suppress mapper exceptions (they will be swallowed). Default is to throw mapping issues (e.g., access / type errors) to surface problems early.

Performance Notes

Benchmarks (representative, will vary):

Optimization features:

• Plan & constructor delegate caching.
• Compiled expression getters / setters (backing field for init‑only).
• Fast path when no transformers present.
• Async path defers allocation until needed.

When to Use / When Not to Use

Use ImmutaMap when:

• You work heavily with records / immutable objects.
• You need inline, one‑off mapping logic without global profiles.
• You want attribute or type‑wide transforms without ceremony.

Avoid when:

• You require runtime code generation across assemblies (not exposed yet).
• You need precompiled static source generators (future consideration).

Extension Points

Create custom transformers by implementing:

• ITransformer (sync)
• IAsyncTransformer (async) Add them to configuration.Transformers / configuration.AsyncTransformers.

Roadmap (Planned)

• Bulk compiled property copy delegate (remove per‑property loop cost).
• Specialized typed delegate paths (reduced boxing / indirection).
• Dynamic source fast‑plan caching.
• Optional source generator package.

Contributing

1. Fork & branch from main.
2. Add/modify tests in ImmutaMap.Test for new behavior.
3. Run: dotnet test (all green) & dotnet run --project ImmutaMap.Benchmarks if perf related.
4. Submit PR with rationale + benchmark deltas (if perf change).

Minimal End‑to‑End Sample

var record = new PersonRecord("First", "Last", 30);
var enriched = record
	.To<PersonRecord, Employee>(cfg =>
	{
		cfg.MapName(r => r.FirstName, e => e.GivenName)
		   .MapType<DateTime>(d => d.ToLocalTime());
	})
	.With(e => e.GivenName, name => name.ToUpper());

// Copy into existing target
var target = new Employee();
target.Copy(enriched, cfg => cfg.MapName(e => e.GivenName, t => t.DisplayName));

License

MIT. See LICENSE.

Questions / ideas? Open an issue or PR – feedback drives the roadmap.