Add property filter and fix null property diff bug (#30)

* Add property filter
* Force diff in array diff when property filter set
* Fix diff for nulls
* Fix diff context and add test
* Add release notes for 1.3.1

Author: weichch

ReleaseNotes.md

@@ -1,5 +1,10 @@
 # Release Notes
 
+## 1.3.1
+
+- Added `PropertyFilter` to `JsonDiffOptions` (#29)
+- Fixed bug in diffing null-valued properties (#31)
+
 ## 1.3.0
 
 - **Added `DeepEquals` implementation for `JsonDocument` and `JsonElement`**

src/Directory.Build.props

@@ -9,7 +9,7 @@
   </PropertyGroup>
 
   <PropertyGroup>
-    <JsonDiffPatchPackageVersion>1.3.0</JsonDiffPatchPackageVersion>
+    <JsonDiffPatchPackageVersion>1.3.1</JsonDiffPatchPackageVersion>
     <Authors>Wei Chen</Authors>
     <PackageProjectUrl>https://github.com/weichch/system-text-json-jsondiffpatch</PackageProjectUrl>
     <Copyright>Copyright © Wei Chen 2022</Copyright>

src/SystemTextJson.JsonDiffPatch/Diffs/JsonDiffContext.cs

@@ -0,0 +1,47 @@
+using System.Text.Json.Nodes;
+
+namespace System.Text.Json.JsonDiffPatch.Diffs
+{
+    /// <summary>
+    /// Represents JSON diff context.
+    /// </summary>
+    public class JsonDiffContext
+    {
+        private readonly JsonNode _leftNode;
+        private readonly JsonNode _rightNode;
+
+        internal JsonDiffContext(JsonNode left, JsonNode right)
+        {
+            _leftNode = left;
+            _rightNode = right;
+        }
+
+        /// <summary>
+        /// Gets the left value in comparison.
+        /// </summary>
+        /// <typeparam name="T">The type of left value.</typeparam>
+        public T Left<T>()
+        {
+            if (_leftNode is T leftValue)
+            {
+                return leftValue;
+            }
+
+            throw new InvalidOperationException($"Type must be '{nameof(JsonNode)}' or derived type.");
+        }
+
+        /// <summary>
+        /// Gets the right value in comparison.
+        /// </summary>
+        /// <typeparam name="T">The type of right value.</typeparam>
+        public T Right<T>()
+        {
+            if (_rightNode is T rightValue)
+            {
+                return rightValue;
+            }
+
+            throw new InvalidOperationException($"Type must be '{nameof(JsonNode)}' or derived type.");
+        }
+    }
+}

src/SystemTextJson.JsonDiffPatch/Diffs/JsonDiffOptions.cs

@@ -60,6 +60,12 @@ public JsonElementComparison JsonElementComparison
         /// </summary>
         public IEqualityComparer<JsonValue>? ValueComparer { get; set; }
 
+        /// <summary>
+        /// Gets or sets the filter function to ignore JSON property. To ignore a property,
+        /// implement this function and return <c>false</c>.
+        /// </summary>
+        public Func<string, JsonDiffContext, bool>? PropertyFilter { get; set; }
+
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         internal JsonComparerOptions CreateComparerOptions() => new(JsonElementComparison, ValueComparer);
     }

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

@@ -197,6 +197,8 @@ static void AddDiffResult(
         internal static bool MatchArrayItem(ref ArrayItemMatchContext context, JsonDiffOptions? options,
             in JsonComparerOptions comparerOptions)
         {
+            // Prefer DeepEquals because LCS is weighted as per deep equality, and deep equality
+            // usually generates smaller diff
             if (context.Left.DeepEquals(context.Right, comparerOptions))
             {
                 context.DeepEqual();
@@ -206,7 +208,7 @@ internal static bool MatchArrayItem(ref ArrayItemMatchContext context, JsonDiffO
             if (options is not null && context.Left is JsonObject or JsonArray &&
                 context.Right is JsonObject or JsonArray)
             {
-                if (FuzzyMatchArrayItem(ref context, options, out var fuzzyResult))
+                if (FallbackMatchArrayItem(ref context, options, out var fuzzyResult))
                 {
                     return fuzzyResult;
                 }
@@ -220,7 +222,7 @@ internal static bool MatchArrayItem(ref ArrayItemMatchContext context, JsonDiffO
             return false;
         }
 
-        internal static bool MatchArrayItem(
+        internal static bool MatchArrayValueItem(
             ref ArrayItemMatchContext context,
             ref JsonValueWrapper wrapperLeft,
             ref JsonValueWrapper wrapperRight,
@@ -241,11 +243,12 @@ internal static bool MatchArrayItem(
             return false;
         }
 
-        private static bool FuzzyMatchArrayItem(ref ArrayItemMatchContext context, JsonDiffOptions options,
+        private static bool FallbackMatchArrayItem(ref ArrayItemMatchContext context, JsonDiffOptions options,
             out bool result)
         {
             result = false;
 
+            // Scenario 1: keyed objects or arrays
             var keyFinder = options.ArrayObjectItemKeyFinder;
             if (keyFinder is not null)
             {
@@ -254,25 +257,28 @@ private static bool FuzzyMatchArrayItem(ref ArrayItemMatchContext context, JsonD
 
                 if (keyX is null && keyY is null)
                 {
-                    // Use DeepEquals if both items are not keyed
                     return false;
                 }
 
                 result = Equals(keyX, keyY);
                 return true;
             }
 
+            // Scenario 2: match objects or arrays by position in parent array
             if (options.ArrayObjectItemMatchByPosition)
             {
                 if (context.LeftPosition == context.RightPosition)
                 {
                     result = true;
                     return true;
                 }
+            }
 
-                // We don't return a result for objects at different position
-                // so that we could still compare them using DeepEquals, or
-                // return "not equal" if this method is called after.
+            // Scenario 3: force a later diff operation when property filter is set
+            if (options.PropertyFilter is not null)
+            {
+                result = true;
+                return true;
             }
 
             return false;

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

@@ -224,37 +224,49 @@ private static void DiffInternal(
         {
             Debug.Assert(delta.Document is null);
 
-            left ??= "";
-            right ??= "";
+            // Fast diff scenarios
 
-            // Compare two objects
-            if (left is JsonObject leftObj && right is JsonObject rightObj)
+            if (ReferenceEquals(left, right))
             {
-                DiffObject(ref delta, leftObj, rightObj, options);
                 return;
             }
 
-            // Compare two arrays
-            if (left is JsonArray leftArr && right is JsonArray rightArr)
+            if (left is null || right is null)
             {
-                DiffArray(ref delta, leftArr, rightArr, options);
+                delta.Modified(left, right);
                 return;
             }
 
-            // For long texts
-            // Compare two long texts
-            if (IsLongText(left, right, options, out var leftText, out var rightText))
+            // Full diff scenarios
+
+            if (left is JsonObject leftObj && right is JsonObject rightObj)
             {
-                Debug.Assert(options is not null);
-                DiffLongText(ref delta, leftText!, rightText!, options!);
-                return;
+                DiffObject(ref delta, leftObj, rightObj, options);
             }
-
-            // 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
-            var comparerOptions = options?.CreateComparerOptions() ?? default;
-            if (!left.DeepEquals(right, comparerOptions))
+            else if (left is JsonArray leftArr && right is JsonArray rightArr)
+            {
+                DiffArray(ref delta, leftArr, rightArr, options);
+            }
+            else if (left is JsonValue leftVal && right is JsonValue rightVal)
+            {
+                if (IsLongText(leftVal, rightVal, options, out var leftText, out var rightText))
+                {
+                    Debug.Assert(options is not null);
+                    DiffLongText(ref delta, leftText!, rightText!, options!);
+                }
+                else
+                {
+                    // Check value deep equality as per options, i.e. semantic or raw text equality
+                    var comparerOptions = options?.CreateComparerOptions() ?? default;
+                    if (!leftVal.DeepEquals(rightVal, comparerOptions))
+                    {
+                        delta.Modified(leftVal, rightVal);
+                    }
+                }
+            }
+            else
             {
+                Debug.Assert(left.GetType() != right.GetType(), "Json value type must not equal.");
                 delta.Modified(left, right);
             }
         }

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

@@ -17,8 +17,20 @@ private static void DiffObject(
             var leftProperties = (left as IDictionary<string, JsonNode?>).Keys;
             var rightProperties = (right as IDictionary<string, JsonNode?>).Keys;
 
+            JsonDiffContext? diffContext = null;
+            var propertyFilter = options?.PropertyFilter;
+            if (propertyFilter is not null)
+            {
+                diffContext = new JsonDiffContext(left, right);
+            }
+
             foreach (var prop in leftProperties)
             {
+                if (propertyFilter is not null && !propertyFilter(prop, diffContext!))
+                {
+                    continue;
+                }
+
                 var leftValue = left[prop];
                 if (!right.TryGetPropertyValue(prop, out var rightValue))
                 {
@@ -39,6 +51,11 @@ private static void DiffObject(
 
             foreach (var prop in rightProperties)
             {
+                if (propertyFilter is not null && !propertyFilter(prop, diffContext!))
+                {
+                    continue;
+                }
+
                 var rightValue = right[prop];
                 if (!left.ContainsKey(prop))
                 {

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

@@ -43,8 +43,8 @@ private static void DiffLongText(
         }
 
         private static bool IsLongText(
-            JsonNode? left,
-            JsonNode? right,
+            JsonValue left,
+            JsonValue right,
             JsonDiffOptions? options,
             out string? leftText,
             out string? rightText)
@@ -57,11 +57,6 @@ private static bool IsLongText(
                 return false;
             }
 
-            if (left is not JsonValue || right is not JsonValue)
-            {
-                return false;
-            }
-
             while (true)
             {
                 if (options.TextDiffMinLength <= 0)
@@ -70,8 +65,8 @@ private static bool IsLongText(
                 }
 
                 // Perf: This is slower than direct property access
-                var valueLeft = left.AsValue().GetValue<object>();
-                var valueRight = right.AsValue().GetValue<object>();
+                var valueLeft = left.GetValue<object>();
+                var valueRight = right.GetValue<object>();
 
                 if (valueLeft is JsonElement elementLeft && valueRight is JsonElement elementRight)
                 {

src/SystemTextJson.JsonDiffPatch/Diffs/Lcs.cs

@@ -153,7 +153,7 @@ public static Lcs Get(Span<JsonNode?> x, Span<JsonNode?> y, JsonDiffOptions? opt
 
                     if (x[i - 1] is JsonValue && y[j - 1] is JsonValue)
                     {
-                        itemMatched = JsonDiffPatcher.MatchArrayItem(ref matchContext,
+                        itemMatched = JsonDiffPatcher.MatchArrayValueItem(ref matchContext,
                             ref wrapperCacheSpan[i - 1],
                             ref wrapperCacheSpan[x.Length + j - 1],
                             options,