Add semantic comparison to DeepEquals and Diff methods (#8)

* Add equality comparer parameter to DeepEquals
* Add semantic comparer
* Add default diff options
* Adding tests for `DeepEquals`
* Add docs for release

Author: weichch

Benchmark.md

@@ -4,50 +4,74 @@
 
 ``` ini
 
-BenchmarkDotNet=v0.13.1, OS=Windows 10.0.19043.1415 (21H1/May2021Update)
+BenchmarkDotNet=v0.13.1, OS=Windows 10.0.19043.1586 (21H1/May2021Update)
 11th Gen Intel Core i7-1185G7 3.00GHz, 1 CPU, 8 logical and 4 physical cores
 .NET SDK=6.0.200
   [Host]     : .NET 6.0.2 (6.0.222.6406), X64 RyuJIT
   DefaultJob : .NET 6.0.2 (6.0.222.6406), X64 RyuJIT
 
 
 ```
-|                    Method |      Mean |       Min |       Max |       P95 |       P80 | Allocated |
-|-------------------------- |----------:|----------:|----------:|----------:|----------:|----------:|
-|              Diff_JsonNet | 107.55 μs |  95.29 μs | 122.73 μs | 118.01 μs | 113.43 μs |    132 KB |
-|       Diff_SystemTextJson |  91.79 μs |  75.05 μs | 126.17 μs | 112.61 μs | 101.81 μs |     70 KB |
-|          Diff_JsonNet_Rfc | 130.02 μs | 115.41 μs | 156.85 μs | 151.16 μs | 136.42 μs |    150 KB |
-|   Diff_SystemTextJson_Rfc | 106.12 μs |  95.75 μs | 120.03 μs | 115.57 μs | 110.23 μs |     93 KB |
-|             Patch_JsonNet | 116.92 μs | 107.06 μs | 137.86 μs | 133.26 μs | 122.34 μs |    162 KB |
-|      Patch_SystemTextJson |  45.05 μs |  37.98 μs |  56.60 μs |  55.13 μs |  47.42 μs |     37 KB |
-|        DeepEquals_JsonNet |  69.14 μs |  62.38 μs |  76.96 μs |  74.78 μs |  71.95 μs |     91 KB |
-| DeepEquals_SystemTextJson |  53.43 μs |  47.96 μs |  65.03 μs |  60.30 μs |  56.35 μs |     40 KB |
-|         DeepClone_JsonNet |  51.28 μs |  44.65 μs |  62.34 μs |  58.69 μs |  54.52 μs |     70 KB |
-|  DeepClone_SystemTextJson |  47.82 μs |  38.78 μs |  59.26 μs |  56.94 μs |  51.11 μs |     45 KB |
+|                             Method |      Mean |       Min |       Max |       P95 |       P80 | Allocated |
+|----------------------------------- |----------:|----------:|----------:|----------:|----------:|----------:|
+|                       Diff_JsonNet | 170.86 μs | 112.81 μs | 250.44 μs | 242.28 μs | 222.06 μs |    132 KB |
+|                Diff_SystemTextJson | 161.13 μs | 110.60 μs | 272.51 μs | 245.99 μs | 194.82 μs |     70 KB |
+|       Diff_SystemTextJson_Semantic | 188.61 μs | 121.51 μs | 312.77 μs | 243.53 μs | 223.13 μs |     77 KB |
+|                   Diff_JsonNet_Rfc | 188.54 μs | 143.31 μs | 305.56 μs | 276.16 μs | 231.28 μs |    150 KB |
+|            Diff_SystemTextJson_Rfc | 181.22 μs | 107.66 μs | 287.07 μs | 248.40 μs | 223.91 μs |     92 KB |
+|                      Patch_JsonNet | 205.86 μs | 123.47 μs | 319.94 μs | 277.28 μs | 242.98 μs |    162 KB |
+|               Patch_SystemTextJson |  78.75 μs |  54.53 μs | 113.21 μs |  98.50 μs |  88.62 μs |     37 KB |
+|                 DeepEquals_JsonNet | 122.18 μs |  82.64 μs | 196.77 μs | 169.75 μs | 148.24 μs |     91 KB |
+|          DeepEquals_SystemTextJson |  89.19 μs |  55.40 μs | 151.38 μs | 123.07 μs | 116.02 μs |     39 KB |
+| DeepEquals_SystemTextJson_Semantic | 119.93 μs |  79.38 μs | 189.04 μs | 173.98 μs | 150.50 μs |     46 KB |
+|                  DeepClone_JsonNet |  89.48 μs |  51.36 μs | 136.46 μs | 121.85 μs | 104.55 μs |     70 KB |
+|           DeepClone_SystemTextJson |  64.91 μs |  38.96 μs |  97.91 μs |  87.33 μs |  77.57 μs |     45 KB |
 
 
 ## Large JSON object
 
 ``` ini
 
-BenchmarkDotNet=v0.13.1, OS=Windows 10.0.19043.1415 (21H1/May2021Update)
+BenchmarkDotNet=v0.13.1, OS=Windows 10.0.19043.1586 (21H1/May2021Update)
 11th Gen Intel Core i7-1185G7 3.00GHz, 1 CPU, 8 logical and 4 physical cores
 .NET SDK=6.0.200
   [Host]     : .NET 6.0.2 (6.0.222.6406), X64 RyuJIT
   DefaultJob : .NET 6.0.2 (6.0.222.6406), X64 RyuJIT
 
 
 ```
-|                    Method |      Mean |       Min |       Max |       P95 |       P80 | Allocated |
-|-------------------------- |----------:|----------:|----------:|----------:|----------:|----------:|
-|              Diff_JsonNet | 11.155 ms |  9.132 ms | 13.732 ms | 12.802 ms | 11.896 ms |      4 MB |
-|       Diff_SystemTextJson |  8.375 ms |  7.334 ms |  9.132 ms |  8.978 ms |  8.690 ms |      3 MB |
-|          Diff_JsonNet_Rfc | 12.774 ms |  9.807 ms | 17.990 ms | 17.479 ms | 13.374 ms |      6 MB |
-|   Diff_SystemTextJson_Rfc | 11.664 ms | 10.341 ms | 12.918 ms | 12.668 ms | 12.142 ms |      5 MB |
-|             Patch_JsonNet | 12.146 ms | 10.344 ms | 13.576 ms | 13.302 ms | 12.647 ms |      5 MB |
-|      Patch_SystemTextJson |  4.693 ms |  2.422 ms |  5.685 ms |  5.412 ms |  5.061 ms |      2 MB |
-|        DeepEquals_JsonNet |  4.164 ms |  2.584 ms |  5.424 ms |  4.917 ms |  4.652 ms |      2 MB |
-| DeepEquals_SystemTextJson |  3.254 ms |  2.071 ms |  3.837 ms |  3.709 ms |  3.499 ms |      2 MB |
-|         DeepClone_JsonNet |  3.997 ms |  2.529 ms |  5.165 ms |  4.772 ms |  4.531 ms |      2 MB |
-|  DeepClone_SystemTextJson |  3.396 ms |  2.085 ms |  3.981 ms |  3.811 ms |  3.609 ms |      2 MB |
+|                             Method |      Mean |      Min |       Max |       P95 |       P80 | Allocated |
+|----------------------------------- |----------:|---------:|----------:|----------:|----------:|----------:|
+|                       Diff_JsonNet |  6.825 ms | 4.746 ms | 13.074 ms | 11.310 ms |  9.284 ms |      4 MB |
+|                Diff_SystemTextJson |  5.898 ms | 4.996 ms |  7.424 ms |  6.910 ms |  6.329 ms |      3 MB |
+|       Diff_SystemTextJson_Semantic |  6.466 ms | 4.683 ms | 10.261 ms |  8.130 ms |  7.464 ms |      4 MB |
+|                   Diff_JsonNet_Rfc | 12.654 ms | 8.208 ms | 17.506 ms | 15.528 ms | 14.234 ms |      6 MB |
+|            Diff_SystemTextJson_Rfc | 10.018 ms | 6.678 ms | 16.484 ms | 13.998 ms | 11.816 ms |      5 MB |
+|                      Patch_JsonNet |  9.128 ms | 5.115 ms | 14.050 ms | 11.422 ms | 10.736 ms |      5 MB |
+|               Patch_SystemTextJson |  3.772 ms | 2.576 ms |  5.572 ms |  4.933 ms |  4.421 ms |      2 MB |
+|                 DeepEquals_JsonNet |  4.549 ms | 3.280 ms |  6.667 ms |  6.059 ms |  5.529 ms |      2 MB |
+|          DeepEquals_SystemTextJson |  3.673 ms | 2.321 ms |  6.153 ms |  5.028 ms |  4.303 ms |      2 MB |
+| DeepEquals_SystemTextJson_Semantic |  4.630 ms | 2.824 ms |  7.049 ms |  6.303 ms |  5.708 ms |      2 MB |
+|                  DeepClone_JsonNet |  3.294 ms | 2.014 ms |  5.439 ms |  4.518 ms |  4.190 ms |      2 MB |
+|           DeepClone_SystemTextJson |  1.761 ms | 1.475 ms |  2.107 ms |  2.000 ms |  1.927 ms |      2 MB |
+
+
+## `DeepEquals` benchmarks
+
+``` ini
+
+BenchmarkDotNet=v0.13.1, OS=Windows 10.0.19043.1586 (21H1/May2021Update)
+11th Gen Intel Core i7-1185G7 3.00GHz, 1 CPU, 8 logical and 4 physical cores
+.NET SDK=6.0.200
+  [Host]     : .NET 6.0.2 (6.0.222.6406), X64 RyuJIT
+  DefaultJob : .NET 6.0.2 (6.0.222.6406), X64 RyuJIT
+
+
+```
+|                    Method |       Mean |        Min |        Max |        P95 |        P80 | Allocated |
+|-------------------------- |-----------:|-----------:|-----------:|-----------:|-----------:|----------:|
+|             JsonNet_Array | 1,198.9 ns |   907.5 ns | 1,704.5 ns | 1,557.5 ns | 1,349.9 ns |   1,248 B |
+|        JsonNet_ParseArray | 2,879.1 ns | 2,216.4 ns | 3,697.3 ns | 3,361.4 ns | 3,124.2 ns |   5,920 B |
+|      SystemTextJson_Array |   857.1 ns |   643.5 ns | 1,312.3 ns | 1,183.3 ns | 1,033.4 ns |     864 B |
+| SystemTextJson_ParseArray | 2,141.7 ns | 2,027.8 ns | 2,188.0 ns | 2,184.4 ns | 2,159.7 ns |   1,264 B |
 

README.md

@@ -1,4 +1,4 @@
-# system-text-json-jsondiffpatch
+# SystemTextJson.JsonDiffPatch
 
 High-performance, low-allocating JSON objects diff and patch extension for System.Text.Json.
 
@@ -12,6 +12,7 @@ High-performance, low-allocating JSON objects diff and patch extension for Syste
 - Support smart array diffing (e.g. move detect) using LCS and custom array item matcher
 - _(Only when not using RFC 6902 format)_ Support diffing long text using [google-diff-match-patch](http://code.google.com/p/google-diff-match-patch/), or write your own diff algorithm
 - Bonus `JsonNode.DeepClone` and `JsonNode.DeepEquals` methods
+- Bouns `JsonValueComparer` that implements semantic comparison of two `JsonValue` objects (including `JsonValue` backed by `JsonElement`)
 - JSON assert for xUnit, MSTest v2 and NUnit with customizable delta output
 
 ## Install
@@ -57,6 +58,22 @@ JsonNode? cloned = node.DeepClone();
 var node1 = JsonNode.Parse(...);
 var node2 = JsonNode.Parse(...);
 bool equal = node1.DeepEquals(node2);
+bool semanticEqual = node1.DeepEquals(node2, JsonElementComparison.Semantic);
+```
+
+### Semantic Value Comparison
+```csharp
+var node1 = JsonNode.Parse("[\"2019-11-27\"]").First().AsValue();
+var node2 = JsonNode.Parse("[\"2019-11-27T00:00:00.000\"]").First().AsValue();
+
+// dateCompare is 0
+var dateCompare = JsonValueComparer.Compare(node1, node2);
+
+var node3 = JsonNode.Parse("[1]").First().AsValue();
+var node4 = JsonNode.Parse("[1.00]").First().AsValue();
+
+// numCompare is 0
+var numCompare = JsonValueComparer.Compare(node3, node4);
 ```
 
 ### Patch & Unpatch

ReleaseNotes.md

@@ -0,0 +1,11 @@
+# Release Notes
+
+## 1.1.0
+- Added `JsonValueComparer` that implements semantic comparison of two `JsonValue` objects (including the ones backed by `JsonElement`)
+- **[BREAKING CHANGE]** `Diff` method no longer uses `object.Equals` to compare values encapsulated in `JsonValue<T>`. `JsonValueComparer` is used instead
+- Added semantic equality to `DeepEquals` method
+- Added options to `JsonDiffOptions` to enable semantic diff
+- Added `JsonDiffPatcher.DefaultOptions` for customizing default diff options
+
+## 1.0.0
+- Initial release

src/Directory.Build.props

@@ -17,7 +17,7 @@
   </PropertyGroup>
 
   <PropertyGroup>
-    <Version>1.0.0</Version>
+    <Version>1.1.0</Version>
     <AssemblyVersion>1.0.0.0</AssemblyVersion>
     <FileVersion>1.0.0.0</FileVersion>
   </PropertyGroup>

src/SystemTextJson.JsonDiffPatch/Diffs/DefaultArrayItemComparer.cs

@@ -29,7 +29,7 @@ public bool MatchArrayItem(ref ArrayItemMatchContext context)
                 }
             }
 
-            if (context.Left.DeepEquals(context.Right))
+            if (context.Left.DeepEquals(context.Right, _options.CreateComparerOptions()))
             {
                 context.DeepEqual();
                 return true;

src/SystemTextJson.JsonDiffPatch/Diffs/JsonDiffOptions.cs

@@ -1,4 +1,5 @@
-using System.Text.Json.JsonDiffPatch.Diffs;
+using System.Collections.Generic;
+using System.Text.Json.JsonDiffPatch.Diffs;
 using System.Text.Json.Nodes;
 
 namespace System.Text.Json.JsonDiffPatch
@@ -9,6 +10,7 @@ namespace System.Text.Json.JsonDiffPatch
     public class JsonDiffOptions
     {
         internal static readonly JsonDiffOptions Default = new();
+        private JsonComparerOptions _comparerOptions;
 
         /// <summary>
         /// Specifies whether to suppress detect array move. Default value is <c>false</c>.
@@ -60,5 +62,26 @@ public class JsonDiffOptions
         /// Gets or sets the function to diff long texts.
         /// </summary>
         public Func<string, string, string?>? TextDiffProvider { get; set; }
+
+        /// <summary>
+        /// Gets or sets the mode to compare two <see cref="JsonElement"/> instances.
+        /// </summary>
+        public JsonElementComparison JsonElementComparison { get; set; }
+
+        /// <summary>
+        /// Gets or sets the <see cref="JsonValue"/> comparer.
+        /// </summary>
+        public IEqualityComparer<JsonValue>? ValueComparer { get; set; }
+
+        internal ref JsonComparerOptions CreateComparerOptions()
+        {
+            if (JsonElementComparison != _comparerOptions.JsonElementComparison
+                || !Equals(ValueComparer, _comparerOptions.ValueComparer))
+            {
+                _comparerOptions = new JsonComparerOptions(JsonElementComparison, ValueComparer);
+            }
+
+            return ref _comparerOptions;
+        }
     }
 }

src/SystemTextJson.JsonDiffPatch/Diffs/JsonDiffPatcher.Diff.cs

@@ -222,8 +222,8 @@ private static void DiffInternal(
             JsonDiffOptions? options)
         {
             Debug.Assert(delta.Document is null);
-            
-            options ??= JsonDiffOptions.Default;
+
+            options ??= DefaultOptions?.Invoke() ?? JsonDiffOptions.Default;
 
             left ??= "";
             right ??= "";
@@ -252,10 +252,9 @@ private static void DiffInternal(
 
             // None of the above methods returned a result, fallback to check if both values are deeply equal
             // This should also handle DateTime and other CLR types that are strings in JSON
-            if (!left.DeepEquals(right))
+            if (!left.DeepEquals(right, options.CreateComparerOptions()))
             {
                 delta.Modified(left, right);
-                return;
             }
         }
     }

src/SystemTextJson.JsonDiffPatch/JsonComparerOptions.cs

@@ -0,0 +1,31 @@
+using System.Collections.Generic;
+using System.Text.Json.Nodes;
+
+namespace System.Text.Json.JsonDiffPatch
+{
+    /// <summary>
+    /// Represents the options for internal JSON comparer.
+    /// </summary>
+    public readonly struct JsonComparerOptions
+    { 
+        /// <summary>
+        /// Creates an instance of the options.
+        /// </summary>
+        public JsonComparerOptions(JsonElementComparison jsonElementComparison,
+            IEqualityComparer<JsonValue>? valueComparer)
+        {
+            JsonElementComparison = jsonElementComparison;
+            ValueComparer = valueComparer;
+        }
+
+        /// <summary>
+        /// Gets the mode to compare two <see cref="JsonElement"/> instances.
+        /// </summary>
+        public JsonElementComparison JsonElementComparison { get; }
+
+        /// <summary>
+        /// Gets the value comparer.
+        /// </summary>
+        public IEqualityComparer<JsonValue>? ValueComparer { get; }
+    }
+}