Investigate FastCloner as DeepCloner replacement

- Replace Force.DeepCloner with FastCloner v3.4.4 (source imported)
- Add Update-FastCloner.ps1 script for source import automation
- Update ObjectExtensions.DeepClone to use FastClonerGenerator
- Add nullable annotations to DeepClone extension method
- Replace #if MODERN with #if true // MODERN for .NET 8+ targets
- Add benchmark comparison results

Benchmark results show FastCloner is 7-149% slower than DeepCloner
for our test cases, contrary to published benchmarks.

Author: niemyjski

benchmarks/DEEPCLONE_BENCHMARK_RESULTS.md

@@ -134,3 +134,80 @@ Apple M1 Max, 1 CPU, 10 logical and 10 physical cores
 - `DeepClone_StringArray_1000`: Array of 1000 strings
 - `DeepClone_ObjectList_100`: List of 100 medium nested objects
 - `DeepClone_ObjectDictionary_50`: Dictionary of 50 event documents
+
+---
+
+## FastCloner v3.4.4 Evaluation
+
+We evaluated [FastCloner](https://github.com/lofcz/FastCloner) as a potential replacement for Force.DeepCloner.
+
+### Results Summary (FastCloner v3.4.4)
+
+| Benchmark | Mean | Allocated | Use Case |
+|-----------|------|-----------|----------|
+| **DeepClone_SmallObject** | 132 ns | 144 B | Simple cache entries |
+| **DeepClone_FileSpec** | 402 ns | 1,072 B | File storage metadata |
+| **DeepClone_SmallObjectWithCollections** | 490 ns | 1,256 B | Config/metadata caching |
+| **DeepClone_StringArray_1000** | 501 ns | 8,057 B | String collections |
+| **DeepClone_DynamicWithDictionary** | 905 ns | 3,224 B | JSON-like dynamic data |
+| **DeepClone_MediumNestedObject** | 1,313 ns | 3,352 B | Typical queue messages |
+| **DeepClone_DynamicWithNestedObject** | 1,315 ns | 3,464 B | Nested dynamic objects |
+| **DeepClone_DynamicWithArray** | 3,343 ns | 8,984 B | Mixed-type arrays |
+| **DeepClone_LargeEventDocument_10MB** | 48,415 ns | 154,888 B | Error tracking events |
+| **DeepClone_ObjectList_100** | 120,509 ns | 374,672 B | Batch processing |
+| **DeepClone_ObjectDictionary_50** | 597,092 ns | 631,619 B | Keyed collections |
+| **DeepClone_LargeLogBatch_10MB** | 5,726,243 ns | 5,251,027 B | Bulk log ingestion |
+
+### Comparison: Force.DeepCloner vs FastCloner
+
+| Benchmark | DeepCloner | FastCloner | Change |
+|-----------|------------|------------|--------|
+| SmallObject | 52.93 ns | 132 ns | **+149% slower** |
+| FileSpec | 299.87 ns | 402 ns | **+34% slower** |
+| SmallObjectWithCollections | 384.61 ns | 490 ns | **+27% slower** |
+| StringArray_1000 | 470.19 ns | 501 ns | +7% slower |
+| DynamicWithDictionary | 797.00 ns | 905 ns | +14% slower |
+| MediumNestedObject | 1,020.19 ns | 1,313 ns | **+29% slower** |
+| DynamicWithNestedObject | 1,130.58 ns | 1,315 ns | +16% slower |
+| DynamicWithArray | 3,672.72 ns | 3,343 ns | **-9% faster** |
+| LargeEventDocument_10MB | 43,718.94 ns | 48,415 ns | +11% slower |
+| ObjectList_100 | 110,525.77 ns | 120,509 ns | +9% slower |
+| ObjectDictionary_50 | 555,214.24 ns | 597,092 ns | +8% slower |
+| LargeLogBatch_10MB | 3,662,330.45 ns | 5,726,243 ns | **+56% slower** |
+
+### Conclusion
+
+**FastCloner is consistently slower than DeepCloner** for our benchmark suite:
+
+- **Small objects**: 27-149% slower
+- **Medium objects**: 9-29% slower
+- **Large objects**: 8-56% slower
+- **Only exception**: DynamicWithArray is 9% faster
+
+This contradicts FastCloner's published benchmarks which show ~25x improvement over DeepCloner. The published benchmarks likely use the source generator (`FastDeepClone()`) rather than reflection-based cloning.
+
+### Raw Results (FastCloner v3.4.4)
+
+```
+BenchmarkDotNet v0.15.8, macOS Tahoe 26.2 (25C56) [Darwin 25.2.0]
+Apple M1 Max, 1 CPU, 10 logical and 10 physical cores
+.NET SDK 10.0.102
+  [Host]     : .NET 10.0.2 (10.0.2, 10.0.225.61305), Arm64 RyuJIT armv8.0-a
+  DefaultJob : .NET 10.0.2 (10.0.2, 10.0.225.61305), Arm64 RyuJIT armv8.0-a
+
+
+| Method                               | Mean           | Error         | StdDev       | Ratio   | RatioSD | Gen0     | Gen1     | Gen2     | Allocated | Alloc Ratio |
+|------------------------------------- |---------------:|--------------:|-------------:|--------:|--------:|---------:|---------:|---------:|----------:|------------:|
+| DeepClone_StringArray_1000           |       501.2 ns |       9.63 ns |     10.71 ns |   0.010 |    0.00 |   1.2836 |        - |        - |    8057 B |       0.052 |
+| DeepClone_ObjectList_100             |   120,508.5 ns |   2,405.40 ns |  5,177.89 ns |   2.489 |    0.11 |  59.5703 |  19.7754 |        - |  374672 B |       2.419 |
+| DeepClone_ObjectDictionary_50        |   597,091.5 ns |  11,791.91 ns | 11,030.16 ns |  12.333 |    0.23 |  96.6797 |  44.9219 |  17.5781 |  631619 B |       4.078 |
+| DeepClone_DynamicWithDictionary      |       905.2 ns |      17.14 ns |     19.05 ns |   0.019 |    0.00 |   0.5131 |   0.0038 |        - |    3224 B |       0.021 |
+| DeepClone_DynamicWithNestedObject    |     1,314.5 ns |      26.25 ns |     64.89 ns |   0.027 |    0.00 |   0.5512 |   0.0038 |        - |    3464 B |       0.022 |
+| DeepClone_DynamicWithArray           |     3,342.6 ns |      21.09 ns |     16.47 ns |   0.069 |    0.00 |   1.4305 |   0.0229 |        - |    8984 B |       0.058 |
+| DeepClone_LargeEventDocument_10MB    |    48,415.0 ns |     385.12 ns |    300.68 ns |   1.000 |    0.01 |  24.5972 |   4.5166 |        - |  154888 B |       1.000 |
+| DeepClone_LargeLogBatch_10MB         | 5,726,242.8 ns | 109,699.46 ns | 85,646.12 ns | 118.278 |    1.84 | 562.5000 | 257.8125 | 101.5625 | 5251027 B |      33.902 |
+| DeepClone_MediumNestedObject         |     1,312.7 ns |      25.56 ns |     39.80 ns |   0.027 |    0.00 |   0.5341 |   0.0038 |        - |    3352 B |       0.022 |
+| DeepClone_FileSpec                   |       401.5 ns |       6.40 ns |      6.57 ns |   0.008 |    0.00 |   0.1707 |        - |        - |    1072 B |       0.007 |
+| DeepClone_SmallObject                |       132.1 ns |       2.60 ns |      3.56 ns |   0.003 |    0.00 |   0.0229 |        - |        - |     144 B |       0.001 |
+| DeepClone_SmallObjectWithCollections |       490.3 ns |       3.48 ns |      2.71 ns |   0.010 |    0.00 |   0.1993 |        - |        - |    1256 B |       0.008 |
+```

build/Update-FastCloner.ps1

@@ -0,0 +1,120 @@
+$work_dir = Resolve-Path "$PSScriptRoot"
+$src_dir = Resolve-Path "$PSScriptRoot/../src/Foundatio"
+
+# Standard using directives and nullable enable to prepend to files
+$standardUsings = @"
+#nullable enable
+using System;
+using System.Collections.Generic;
+using System.Collections.Concurrent;
+using System.Linq;
+using System.Linq.Expressions;
+using System.Net.Http;
+using System.Reflection;
+using System.Runtime.CompilerServices;
+using System.Threading;
+
+"@
+
+Function UpdateFastCloner {
+    param([string]$version)
+
+    $sourceUrl = "https://github.com/lofcz/FastCloner/archive/refs/tags/v$version.zip"
+    $name = "FastCloner"
+
+    $zipPath = Join-Path $work_dir "$name.zip"
+    $extractPath = Join-Path $work_dir $name
+    $destPath = Join-Path $src_dir $name
+
+    # Download and extract
+    If (Test-Path $zipPath) { Remove-Item $zipPath }
+    Invoke-WebRequest $sourceUrl -OutFile $zipPath
+
+    If (Test-Path $extractPath) { Remove-Item $extractPath -Recurse -Force }
+    Expand-Archive -Path $zipPath -DestinationPath $extractPath
+    Remove-Item $zipPath
+
+    # Clean destination
+    If (Test-Path $destPath) { Remove-Item $destPath -Recurse -Force }
+
+    $dir = (Get-ChildItem $extractPath | Select-Object -First 1).FullName
+
+    # Create directory structure
+    New-Item $destPath -Type Directory | Out-Null
+    New-Item (Join-Path $destPath "Code") -Type Directory | Out-Null
+
+    # Copy LICENSE
+    Copy-Item (Join-Path $dir "LICENSE") -Destination $destPath -Force
+
+    # Copy and transform FastCloner.cs (skip FastClonerExtensions.cs - we have our own)
+    $srcFastClonerPath = Join-Path $dir "src/FastCloner"
+    Get-ChildItem -Path $srcFastClonerPath -Filter "FastCloner.cs" |
+        Foreach-Object {
+            $c = ($_ | Get-Content -Raw)
+            $c = $c -replace 'namespace FastCloner;','namespace Foundatio.FastCloner;'
+            $c = $c -replace 'using FastCloner\.Code;','using Foundatio.FastCloner.Code;'
+            # Remove existing using directives that we're adding
+            $c = $c -replace 'using System;[\r\n]+', ''
+            $c = $c -replace 'using System\.Collections\.Generic;[\r\n]+', ''
+            $c = $c -replace 'using System\.Collections\.Concurrent;[\r\n]+', ''
+            $c = $c -replace 'using System\.Linq;[\r\n]+', ''
+            $c = $c -replace 'using System\.Linq\.Expressions;[\r\n]+', ''
+            $c = $c -replace 'using System\.Reflection;[\r\n]+', ''
+            $c = $c -replace 'using System\.Runtime\.CompilerServices;[\r\n]+', ''
+            $c = $c -replace 'using System\.Threading;[\r\n]+', ''
+            # Make all public types internal (we only expose via ObjectExtensions.DeepClone)
+            $c = $c -replace 'public static class','internal static class'
+            $c = $c -replace 'public class','internal class'
+            $c = $c -replace 'public enum','internal enum'
+            $c = $c -replace 'public struct','internal struct'
+            # Replace MODERN preprocessor directives with always-true/false for .NET 8+
+            # Foundatio only targets net8.0 and net10.0, so MODERN is always true
+            $c = $c -replace '#if MODERN','#if true // MODERN'
+            $c = $c -replace '#if !MODERN','#if false // !MODERN'
+            $c = $c -replace '#elif MODERN','#elif true // MODERN'
+            $c = $c -replace '#elif !MODERN','#elif false // !MODERN'
+            # Add standard usings at the top
+            $c = $standardUsings + $c
+            $c | Set-Content (Join-Path $destPath $_.Name)
+        }
+
+    # Copy and transform Code/*.cs files
+    $srcCodePath = Join-Path $dir "src/FastCloner/Code"
+    $destCodePath = Join-Path $destPath "Code"
+    Get-ChildItem -Path $srcCodePath -Filter *.cs |
+        Foreach-Object {
+            $c = ($_ | Get-Content -Raw)
+            $c = $c -replace 'namespace FastCloner\.Code;','namespace Foundatio.FastCloner.Code;'
+            $c = $c -replace 'namespace FastCloner;','namespace Foundatio.FastCloner;'
+            $c = $c -replace 'using FastCloner\.Code;','using Foundatio.FastCloner.Code;'
+            $c = $c -replace 'using FastCloner;','using Foundatio.FastCloner;'
+            # Remove existing using directives that we're adding
+            $c = $c -replace 'using System;[\r\n]+', ''
+            $c = $c -replace 'using System\.Collections\.Generic;[\r\n]+', ''
+            $c = $c -replace 'using System\.Collections\.Concurrent;[\r\n]+', ''
+            $c = $c -replace 'using System\.Linq;[\r\n]+', ''
+            $c = $c -replace 'using System\.Linq\.Expressions;[\r\n]+', ''
+            $c = $c -replace 'using System\.Reflection;[\r\n]+', ''
+            $c = $c -replace 'using System\.Runtime\.CompilerServices;[\r\n]+', ''
+            $c = $c -replace 'using System\.Threading;[\r\n]+', ''
+            # Make all public types internal (we only expose via ObjectExtensions.DeepClone)
+            $c = $c -replace 'public static class','internal static class'
+            $c = $c -replace 'public class','internal class'
+            $c = $c -replace 'public enum','internal enum'
+            $c = $c -replace 'public struct','internal struct'
+            # Replace MODERN preprocessor directives with always-true/false for .NET 8+
+            # Foundatio only targets net8.0 and net10.0, so MODERN is always true
+            $c = $c -replace '#if MODERN','#if true // MODERN'
+            $c = $c -replace '#if !MODERN','#if false // !MODERN'
+            $c = $c -replace '#elif MODERN','#elif true // MODERN'
+            $c = $c -replace '#elif !MODERN','#elif false // !MODERN'
+            # Add standard usings at the top
+            $c = $standardUsings + $c
+            $c | Set-Content (Join-Path $destCodePath $_.Name)
+        }
+
+    # Cleanup
+    Remove-Item $extractPath -Recurse -Force
+}
+
+UpdateFastCloner "3.4.4"

src/Foundatio/DeepCloner/Helpers/ShallowClonerGenerator.cs

@@ -1,11 +1,13 @@
-using Foundatio.Force.DeepCloner.Helpers;
+using System.Diagnostics.CodeAnalysis;
+using Foundatio.FastCloner.Code;
 
 namespace Foundatio.Utility;
 
 public static class ObjectExtensions
 {
-    public static T DeepClone<T>(this T original)
+    [return: NotNullIfNotNull(nameof(original))]
+    public static T? DeepClone<T>(this T? original)
     {
-        return DeepClonerGenerator.CloneObject(original);
+        return FastClonerGenerator.CloneObject(original);
     }
 }

src/Foundatio/Extensions/ObjectExtensions.cs

@@ -0,0 +1,101 @@
+#nullable enable
+using System;
+using System.Collections.Generic;
+using System.Collections.Concurrent;
+using System.Linq;
+using System.Linq.Expressions;
+using System.Net.Http;
+using System.Reflection;
+using System.Runtime.CompilerServices;
+using System.Threading;
+namespace Foundatio.FastCloner.Code;
+
+internal class AhoCorasick
+{
+    private class Node
+    {
+        public readonly Dictionary<char, Node> Children = new Dictionary<char, Node>();
+        public Node? Failure;
+        public bool IsEndOfPattern;
+    }
+
+    private readonly Node root = new Node();
+    private readonly string[] patterns;
+
+    public AhoCorasick(string[] patterns)
+    {
+        this.patterns = patterns;
+        BuildTrie();
+        BuildFailureLinks();
+    }
+
+    private void BuildTrie()
+    {
+        foreach (string pattern in patterns)
+        {
+            Node current = root;
+            foreach (char c in pattern)
+            {
+                if (!current.Children.TryGetValue(c, out Node value))
+                {
+                    value = new Node();
+                    current.Children[c] = value;
+                }
+                current = value;
+            }
+            
+            current.IsEndOfPattern = true;
+        }
+    }
+
+    private void BuildFailureLinks()
+    {
+        Queue<Node> queue = new Queue<Node>();
+        
+        foreach (Node node in root.Children.Values)
+        {
+            node.Failure = root;
+            queue.Enqueue(node);
+        }
+
+        while (queue.Count > 0)
+        {
+            Node current = queue.Dequeue();
+            
+            foreach (KeyValuePair<char, Node> kvp in current.Children)
+            {
+                queue.Enqueue(kvp.Value);
+
+                Node? failure = current.Failure;
+                
+                while (failure != null && !failure.Children.ContainsKey(kvp.Key))
+                {
+                    failure = failure.Failure;
+                }
+
+                kvp.Value.Failure = failure?.Children.GetValueOrDefault(kvp.Key) ?? root;
+            }
+        }
+    }
+
+    public bool ContainsAnyPattern(string text)
+    {
+        Node? current = root;
+        
+        foreach (char c in text)
+        {
+            while (current != null && !current.Children.ContainsKey(c))
+            {
+                current = current.Failure;
+            }
+            
+            current = current?.Children.GetValueOrDefault(c) ?? root;
+
+            if (current.IsEndOfPattern)
+            {
+                return true;
+            }
+        }
+        return false;
+    }
+}