add [FastClonerPreserveIdentity]

Author: lofcz

README.md

@@ -269,6 +269,57 @@ public struct MyHandle
 
 This is the default behavior for system types like `System.Net.Http.Headers.HeaderDescriptor` to prevent breaking internal framework logic. Use this attribute if your custom structs behave similarly.
 
+### Identity Preservation
+
+By default, FastCloner prioritizes performance by not tracking object identity during cloning. This means if the same object instance appears multiple times in your graph, each reference becomes a separate clone.
+
+For scenarios where you need to preserve object identity (e.g., shared references should remain shared in the clone), use `[FastClonerPreserveIdentity]`:
+
+```csharp
+[FastClonerClonable]
+[FastClonerPreserveIdentity] // Enable identity tracking for this type
+public class Document
+{
+    public User Author { get; set; }
+    public User LastEditor { get; set; } // May reference the same User as Author
+}
+
+var doc = new Document { Author = user, LastEditor = user };
+var clone = doc.FastDeepClone();
+// clone.Author == clone.LastEditor (same cloned instance)
+```
+
+The attribute can be applied at type level or member level:
+
+```csharp
+[FastClonerClonable]
+public class Container
+{
+    // Only this member tracks identity
+    [FastClonerPreserveIdentity]
+    public List<Node> Nodes { get; set; }
+    
+    // This member clones without identity tracking (faster)
+    public List<Item> Items { get; set; }
+}
+```
+
+You can also explicitly disable identity preservation for a member when the type has it enabled:
+
+```csharp
+[FastClonerClonable]
+[FastClonerPreserveIdentity]
+public class Graph
+{
+    public Node Root { get; set; }
+    
+    [FastClonerPreserveIdentity(false)] // Opt out for this member
+    public List<string> Labels { get; set; }
+}
+```
+
+> **Note**: Identity preservation adds overhead for tracking seen objects. Circular references are always detected regardless of this setting.
+
 ## Limitations
 
 - Cloning unmanaged resources, such as `IntPtr`s may result in side-effects, as there is no metadata for the length of buffers such pointers often point to.
@@ -314,7 +365,7 @@ FastCloner's source generator is carefully engineered for zero impact on IDE res
 
 ## Contributing
 
-If you are looking to add new functionality, please open an issue first to verify your intent is aligned with the scope of the project. The library is covered by over [600 tests](https://github.com/lofcz/FastCloner/tree/next/src/FastCloner.Tests), please run them against your work before proposing changes. When reporting issues, providing a minimal reproduction we can plug in as a new test greatly reduces turnaround time.
+If you are looking to add new functionality, please open an issue first to verify your intent is aligned with the scope of the project. The library is covered by over [700 tests](https://github.com/lofcz/FastCloner/tree/next/src/FastCloner.Tests), please run them against your work before proposing changes. When reporting issues, providing a minimal reproduction we can plug in as a new test greatly reduces turnaround time.
 
 ## License
 

src/FastCloner.Benchmark/BenchClone.cs

@@ -0,0 +1,36 @@
+using BenchmarkDotNet.Attributes;
+using BenchmarkDotNet.Order;
+
+namespace FastCloner.Benchmark;
+
+[RankColumn]
+[Orderer(SummaryOrderPolicy.FastestToSlowest)]
+[MemoryDiagnoser]
+public class BenchClone
+{
+    private ComplexModel model = null!;
+
+    [GlobalSetup]
+    public void Setup()
+    {
+        model = TestDataGenerator.CreateSampleModel();
+    }
+
+    [Benchmark(Baseline = true)]
+    public ComplexModel FastCloner_SourceGen()
+    {
+        return model.FastDeepClone();
+    }
+
+    [Benchmark]
+    public ComplexModel IDeepCloneable_SourceGen()
+    {
+        return model.DeepClone();
+    }
+
+    [Benchmark]
+    public ComplexModel Mapperly_SourceGen()
+    {
+        return MapperlyCloner.Clone(model);
+    }
+}

src/FastCloner.Benchmark/FastCloner.Benchmark.csproj

@@ -18,13 +18,14 @@
       <PackageReference Include="DeepCopy.Expression" Version="1.5.0" />
       <PackageReference Include="Dolly" Version="0.0.9" />
       <PackageReference Include="FastDeepCloner" Version="1.3.6" />
+      <PackageReference Include="IDeepCloneable" Version="0.0.27" />
       <PackageReference Include="MessagePack" Version="3.1.4" />
       <PackageReference Include="NClone" Version="1.2.0" />
       <PackageReference Include="Newtonsoft.Json" Version="13.0.4" />
       <PackageReference Include="ObjectCloner" Version="2.2.2" />
       <PackageReference Include="protobuf-net" Version="3.2.56" />
-      <PackageReference Include="Riok.Mapperly" Version="3.7.0" />
-      <PackageReference Include="System.Runtime.Serialization.Formatters" Version="10.0.0" />
+      <PackageReference Include="Riok.Mapperly" Version="4.3.1" />
+      <PackageReference Include="System.Runtime.Serialization.Formatters" Version="10.0.2" />
     </ItemGroup>
 
     <ItemGroup>

src/FastCloner.Benchmark/Models.cs

@@ -0,0 +1,96 @@
+using FastCloner.SourceGenerator.Shared;
+using IDeepCloneable;
+using Riok.Mapperly.Abstractions;
+
+namespace FastCloner.Benchmark;
+
+/// <summary>
+/// Complex model for benchmarking deep cloning operations.
+/// </summary>
+[DeepCloneable]
+[FastClonerClonable]
+[FastClonerTrustNullability]
+public partial class ComplexModel
+{
+    public string Id { get; set; } = string.Empty;
+    public string Name { get; set; } = string.Empty;
+    public int Version { get; set; }
+    public DateTime CreatedAt { get; set; }
+    public DateTime? UpdatedAt { get; set; }
+    public UserInfo? Owner { get; set; }
+    public List<UserInfo>? Contributors { get; set; }
+    public Dictionary<string, string>? Metadata { get; set; }
+    public List<DataItem>? Items { get; set; }
+    public Settings? Settings { get; set; }
+}
+
+public class UserInfo
+{
+    public string UserId { get; set; } = string.Empty;
+    public string UserName { get; set; } = string.Empty;
+    public string Email { get; set; } = string.Empty;
+    public UserRole Role { get; set; }
+    public ContactInfo? Contact { get; set; }
+}
+
+public class ContactInfo
+{
+    public string Phone { get; set; } = string.Empty;
+    public string Address { get; set; } = string.Empty;
+    public string City { get; set; } = string.Empty;
+    public string Country { get; set; } = string.Empty;
+}
+
+public class DataItem
+{
+    public string ItemId { get; set; } = string.Empty;
+    public string Title { get; set; } = string.Empty;
+    public string Description { get; set; } = string.Empty;
+    public double Value { get; set; }
+    public List<string>? Tags { get; set; }
+    public List<SubItem>? SubItems { get; set; }
+    public Dictionary<string, string>? Properties { get; set; }
+}
+
+public class SubItem
+{
+    public string SubId { get; set; } = string.Empty;
+    public string Label { get; set; } = string.Empty;
+    public int Quantity { get; set; }
+    public decimal Price { get; set; }
+}
+
+public class Settings
+{
+    public bool IsEnabled { get; set; }
+    public int MaxItems { get; set; }
+    public TimeSpan Timeout { get; set; }
+    public List<string>? AllowedDomains { get; set; }
+    public Dictionary<string, int>? Limits { get; set; }
+    public AdvancedSettings? Advanced { get; set; }
+}
+
+public class AdvancedSettings
+{
+    public int CacheSize { get; set; }
+    public bool UseCompression { get; set; }
+    public string CompressionLevel { get; set; } = string.Empty;
+    public List<string>? Features { get; set; }
+}
+
+public enum UserRole
+{
+    Guest = 0,
+    User = 1,
+    Admin = 2,
+    Owner = 3,
+}
+
+/// <summary>
+/// Mapperly mapper for ComplexModel (compile-time code generation).
+/// </summary>
+[Mapper(UseDeepCloning = true)]
+public static partial class MapperlyCloner
+{
+    public static partial ComplexModel Clone(ComplexModel source);
+}

src/FastCloner.Benchmark/Program.cs

@@ -12,7 +12,7 @@ static void Main(string[] args)
         ManualConfig config = DefaultConfig.Instance
             .WithOptions(ConfigOptions.DisableOptimizationsValidator);
 
-        Summary summary = BenchmarkRunner.Run<BenchDynamic>(config);
+        Summary summary = BenchmarkRunner.Run<BenchClone>(config);
         Console.WriteLine(summary);
     }
 }