VeloxMapper.Core 3.1.0

VeloxMapper

VeloxMapper, modern .NET (net8+) platformu için tasarlanmış, öngörülebilirliği, performansı ve gözlemlenebilirliği (observability) önceliklendiren, deterministik ve fail-fast tabanlı bir nesne eşleştirme (object mapping) kütüphanesidir.

Bu proje, AutoMapper gibi kütüphanelerin sunduğu sonsuz esneklik ve kuralsızlık yerine; katı kuralları, derleme zamanı güvencesini ve çalışma zamanı determinizmini merkeze alır. Beklenmeyen "black box" davranışlarına ve çalışma zamanı null referans hatalarına izin vermez.

VeloxMapper şu ekipler için uygundur:

• Mimarileri üzerinde sıkı kontrol sahibi olmak isteyenler.
• Mapping davranışlarının hiçbir zaman karanlıkta kalmamasını (black box olmamasını) savunanlar.
• CI/CD süreçlerinde mapping değişikliklerini (snapshot testleri ile) doğrulamak isteyenler.
• NativeAOT ve yüksek performanslı (zero-allocation) sistemler geliştirenler.

VeloxMapper şu ekipler için UYGUN DEĞİLDİR:

• Bütün mapping bağımlılıklarının sihirli ve örtük (implicit) bir şekilde çözülmesini bekleyenler.
• Kuralsız, çok katmanlı, spagetti mapping kurallarına ihtiyaç duyanlar.
• "AutoMapper kodumu değiştirmeden birebir kopyalayayım" diyenler.

Temel Tasarım Prensipleri

1. Fail-Fast (Erken Hata): Tanımlanan herhangi bir konfigürasyon hatası, çelişkili eşleştirme, uyumsuz tür eşleşmeleri çalışma zamanını beklemeden, uygulama ayağa kalkarken (startup validation) hata fırlatır.
2. Deterministic Mapping: Aynı girdi ve aynı konfigürasyon, her zaman, her makinede, aynı çıktı modelini, aynı internal Mapping Plan'i ve aynı hesaplanan Deterministic SHA-256 hash'i üretir. Yan etki (side-effect) içermez.
3. Observability (Gözlemlenebilirlik): Bir mapping'in arka planda ne yaptığı her zaman raporlanabilir. VeloxMapper, üretilen tüm eşleştirme kuralları için okunaklı ağaç yapıları (JSON/Text) sunar ve CI entegrasyonu için hash stabilitesini garanti eder.
4. Hibrit Motor: İki katmanlı bir motor kullanır:
   • Layer 1 (Source Generator): [VeloxMap] niteliği (attribute) ile işaretlenmiş explicit opt-in nesneler için derleme zamanında NativeAOT uyumlu, allocationsız (allocation-free), saf C# metotları üretir.
   • Layer 2 (Expression Tree): Alternatif çalışma zamanı fallback'i. Dinamik senaryolarda mapping planlarını derleyerek güçlü-tipli (strongly-typed) delegateler (Func/Action) oluşturur.
5. Opinionated Tasarım: Bilinçli kısıtlamalar içerir. Sınırsız konfigürasyon sunmaz; doğru olan, belirgin olandır ilkesini benimser.

Kurulum ve Framework Desteği

VeloxMapper modüler olarak aşağıdaki framework desteklerini sunar:

• Core Abstractions (VeloxMapper.Core): netstandard2.0 (Opsiyonel kütüphane tüketimi için).
• Runtime Engine (VeloxMapper): net8.0+
• Source Generator (VeloxMapper.Generators): net8.0+ (IDE ve build araçları üzerinden çalışır).

dotnet add package VeloxMapper

Not: Source Generator (VeloxMapper.Generators), ana VeloxMapper paketiyle birlikte arka planda embedded analyzer olarak otomatik devreye girer; manuel olarak ikinci bir paket kurmanıza gerek yoktur.

Not: VeloxMapper, Entity Framework Core tabanlı hiçbir paket bağımlılığı taşımaz. Özel ProjectTo<T> mimarisi sadece CLR System.Linq.Expressions üzerinden firewall standartları çerçevesinde çalışır.

Temel Kullanım

using VeloxMapper;
using VeloxMapper.Configuration;
using VeloxMapper.Attributes;

// 1. Konfigürasyon tanımlama (Immutable konfigürasyon uygulanmak zorundadır)
var config = new MapperConfiguration(cfg =>
{
    // Patch işleminde boş değerleri hedef modele yansıtmayı durdurur.
    cfg.PatchMapping.IgnoreNullValues = true; 
    
    cfg.CreateMap<User, UserDto>();
});

var mapper = new VeloxMapper.VeloxMapper(config);

// 2. Dependency Injection (DI) Entegrasyonu
// VeloxMapper tamamen thread-safe olduğu için Singleton olarak IoC konteynerine yazdırılır:
// builder.Services.AddSingleton<IVeloxMapper>(mapper);

// 3. Map - Yeni nesne oluşturma
var user = new User { Id = 1, Name = "Umut" };
var dto = mapper.Map<User, UserDto>(user);

// 3. Patch - Varolan nesne üzerine özellikleri ezme (Opt-in Explicit Config)
var existingDto = new UserDto { Id = 1, RequestCount = 10 };
mapper.Patch(user, existingDto);

Varsayılan Patch Davranışı: VeloxMapper default olarak mapper.Patch işlemlerinde kaynak nesnedeki null değerleri hedefe yazar. Bunu engellemek, yukarıdaki örnekte görüldüğü gibi net bir konfigürasyon (cfg.PatchMapping.IgnoreNullValues = true) ile opt-in olmayı gerektirir.

Özel Eşleştirmeler (ForMember Alternatifleri)

AutoMapper'daki ForMember(dest => dest.FullName, opt => opt.MapFrom(src => src.Name + " " + src.LastName)) gibi lambda tabanlı karmaşık konfigürasyonlar, derinlemesine reflection gerektirdiği ve bellek tahsisini (allocation) artırdığı için VeloxMapper'da bilinçli olarak desteklenmez.

Eğer iki özelliği birleştirip tek özellik yapacaksanız veya karmaşık bir if/else dönüşümü gerekiyorsa, VeloxMapper size iki saf (pure) ve sıfır maliyetli yol sunar:

YOL 1: Model Üzerinden Çözüm (Domain-Driven / Önerilen)

Sihirli eşleştirmeler yazmak yerine, nesnenin doğasına hesaplanan (computed) bir özellik ekleyin. Source Generator bunu %100 NativeAOT uyumlu bir şekilde sorunsuz tanır:

public class User 
{
    public string Name { get; set; }
    public string LastName { get; set; }
    
    // VeloxMapper bunu otomatik tanır ve UserDto.FullName'e mapler!
    public string FullName => $"{Name} {LastName}"; 
}

YOL 2: Özel Dönüştürücü Kullanmak (IVeloxTypeConverter)

"Veritabanı varlık (entity) sınıflarıma dokunamam" diyorsanız, AutoMapper'ın o karmaşık lambda zinciri yerine, saf, derleme zamanında tip güvenli ve hatasız bir C# kodu yazılır:

// 1. Kural Sınıfını Yaz:
public class UserToUserDtoConverter : IVeloxTypeConverter<User, UserDto>
{
    public UserDto Convert(User? source)
    {
        ArgumentNullException.ThrowIfNull(source);
        
        return new UserDto
        {
            // Tertemiz nesne odaklı explicit atama
            FullName = $"{source.Name} {source.LastName}" 
        };
    }
}

// 2. Merkezi Olarak Config'e Kaydet:
var config = new MapperConfiguration(cfg =>
{
    cfg.AddCustomConverter(new UserToUserDtoConverter());
});

Source Generator vs Runtime Mapping

Kural 1: Source Generator Her Zaman Kazanır (Explicit Opt-in)

Hiyerarşi nettir. Geliştirici, hedeflenen sınıfları explicit olarak [VeloxMap] ile işaretlediği an, Roslyn Source Generator devreye girer. Bu sayede mapping işlemi %100 çalışma zamanı bağımsız hale gelir (AOT-Ready).

using VeloxMapper.Attributes;

[VeloxMap(typeof(User), typeof(UserDto))]
public class User { ... }

Kural 2: Runtime Fallback Sadece Gerektiğinde Devrededir

Eğer eşleştirilecek sınıf üzerinde attribute bulunmuyorsa veya çalışma zamanında dinamik olarak yapılandırılmış özel Type Converter kuralları (runtime rules) varsa donmuş (frozen) Expression Tree konfigürasyonu çalışma zamanında devreye girer, bellekte bir kez derlenir.

EF Core Projection (ProjectTo Firewall)

VeloxMapper, linq ifadeleri üzerinden projeksiyon planları çıkartırken bir firewall kullanır. Entity Framework (veya diğer IQueryable sağlayıcılarının) limitasyonlarına çarpmamak için katı bir AST (Abstract Syntax Tree) kısıtlaması uygular (ProjectionExpressionVisitor).

Desteklenen Senaryolar

Basit nitelik atamaları (MemberBinding) desteklenir.

dbContext.Users.ProjectTo<User, UserDto>(mapper).ToList();

Yasaklı Senaryolar

Projection sırasında IQueryable'a özel çeviricisi olmayan metot çağrılarına (MethodCallExpression) ve özel dönüştürücülere izin verilmez ve anında VeloxProjectionException fırlatarak çöker. Bu davranış bilinçlidir: EF Core'un bu karmaşık işlemleri SQL'e çeviremeyip çalışma zamanında InvalidOperationException üretmesini beklemek, "Fail-Fast" prensibine aykırıdır. Bu tür projeksiyon dışı işlemler için bellek içi (in-memory) fallback mapping önerilir.

Mapping Planları & Observability

VeloxMapper bir eşleştirmenin tüm iç işleyişini "Mapping Plan" nesneleri aracılığıyla size sunar. Sistemin kalbinde yatan yapı, her konfigurasyon planı için bir Deterministic SHA-256 hash üretmektir.

// Plan çıktısı alma
var plan = mapper.GetMappingPlan<User, UserDto>();

string textSummary = plan.ToString(PlanFormat.Text);
string jsonSummary = plan.ToString(PlanFormat.Json);

// Hash üretme
string hash = plan.GenerateHash();

Version / PlanSchema / Hash İlişkisi & CI Snapshots:

• VeloxVersion: VeloxMapper'ın genel versiyonudur, minor yamalarda değişir. Bu alan GenerateHash içine dahil edilmez.
• PlanSchemaVersion: Oluşturulan mapping JSON/Text şemasının versiyonudur ve GenerateHash'e dahil edilir. Şemaya yeni bir desteklendiği an hash değişir.
• CI environmentlerinde GenerateHash() kullanılarak mapping Snapshot Testing süreçleri güvenceye alınır. İstemediğiniz bir "Member" değişiminde CI süreçleri FailFast kuralı gereğince güvenle kırılacaktır.

Konfigürasyon & Conventions

VeloxMapper sonsuz özelleştirme felsefesine sahip değildir. Esneklik noktaları daraltılmıştır:

1. Naming Conventions: Sadece isim dönüşümlerine izin veren ICustomNamingConvention arayüzü eklenebilir (örn: PascalCase->camelCase).
2. Type Converters: Karşılığı olmayan özel tür çevrimleri için auto-mapper yapısını devreden çıkaran ve explicit çağrı gerektiren IVeloxTypeConverter<TSource, TDest> arayüzü kullanılır.
3. Kilitli Alanlar: Konfigürasyon bir kez çalıştırıldığı zaman immutable (değiştirilemez) hale gelir. Çalışma zamanı mutasyonlarına ve lazy eşleştirmelere yapısal olarak izin verilmez.

Hata Modeli

Tüm hataların root exception sınıfı VeloxException'dır. Çıkan hatalar hata fırlatılma alanına göre detaylandırılmıştır:

• VeloxConfigurationException: Eşleştirme konfigürasyonlarında birbiriyle çelişen eksik tip belirteçleri ve kural atamaları olduğunda oluşur (Startup validation).
• VeloxMappingException: Çalışma zamanında (runtime) mapping işlemi kaynaklı bir veri uyumsuzluğu yaşanması durumunda fırlatılır.
• VeloxProjectionException: EF Core veya IQueryable projection işleminin firewall AST engeline takılması durumunda atılır.
• VeloxAmbiguousConstructorException: VeloxMapper'ın hedefe dair doğru Constructor'ı belirleyemediği durumlarda oluşur.

Compile-Time Hataları: Layer 1 Source Generator hataları doğrudan IDE ve MSBuild üzerinde Roslyn Diagnostic Warning/Error (VM001, VM002 vb.) olarak verilir ve derlemeyi durdurur.

Performans Özellikleri & Kritik Detaylar

• Zero-Allocation Güvencesi: VeloxMapper dinamik olarak Reflection veya DynamicInvoke temelli çağrı yapmaz. Tüm ağaçlar allocationsız Strictly Typed Delegatelere (Action<T,T> veya Func<T, TResult>) derlenir.
• Thread-Safety Sözleşmesi: IVeloxMapper tam kapasite thread-safe'tir ve DI (Dependency Injection) konteynerine Singleton olarak enjekte edilebilir. Ayrıca, konfigurasyon bellekte tamamen immutable (donuk) çalışır.
• PreserveReferences (Döngüsel Referanslar): Varsayılan (default) olarak false kapalı gelir. VeloxMapper nesne koparma modelini hedeflediğinden bu sistem sadece runtime fallback planlarında opsiyonel çalışır.

Versiyonlama & Stabilite Sözleşmesi

• Semantic Versiyonlama (SemVer): Kesin olarak Semantic Versioning 2.0.0 takip edilir.
• Hash Stabilite Kuralları: Diagnostics üzerinden üretilen plan hashleri, hedefin eşleştirme adımlarındaki sıralama değişikliklerinden bağımsız, her zaman aynı yapıyı üretecek şekilde tutarlı hesaplanır.

AutoMapper Geçiş Notları

VeloxMapper bir "AutoMapper Drop-in Replacement" çözümü DEĞİLDİR. Kavramlar benzer görünse de uygulanan kısıtlar çok farklıdır.

• ReverseMap() gibi belirsiz ve örtük (implicit) yetenekler desteklenmez. Kaynak ve hedef yönleri mutlak (explicit) olarak belirtilmelidir.
• MethodCall projeksiyonları kısıtlanmıştır; karmaşık IQueryable projeksiyonlarının veritabanı performans sorunlarını maskelemesine izin verilmez.
• Geçiş düşünülüyorsa, uygulamanın determinizm, observabilitiy (gözlemlenebilirlik) ve AOT hazırlığı ihtiyaçları değerlendirilmelidir. Çok kompleks ve kuralsız mapping mantığı içeren projelerde geçiş, ciddi mimari refactoring'e yol açacaktır.

Lisans

Bu proje MIT Lisansı ile lisanlanmıştır. VeloxMapper'ın kalbinde yatan bu kesin ve strict yapı, tüm açık kaynak kullanıcılarına ve Enterprise ekiplere ücretsiz kullanıma sunulmuştur.