Init projects (#1)

Initialize projects and repo

Author: weichch

README.md

@@ -1 +1,152 @@
-# system-text-json-jsondiffpath
+# system-text-json-jsondiffpath
+
+High-performance, low-allocating JSON objects diff and patch extension for `System.Text.Json`.
+
+## Features
+
+- Use [jsondiffpatch](https://github.com/benjamine/jsondiffpatch) delta format described [here](https://github.com/benjamine/jsondiffpatch/blob/master/docs/deltas.md)
+- Target `.NET Standard 2.0` and leverage latest .NET features
+- Similar diff experience as [jsondiffpatch.net](https://github.com/wbish/jsondiffpatch.net) (based on Newtonsoft.Json)
+- Fast large JSON document diffing with less memory consumption
+- Support smart array diffing (e.g. move detect) using LCS and custom array item matcher
+- Support diffing long text using [google-diff-match-patch](http://code.google.com/p/google-diff-match-patch/), or write your own diff algorithm
+- `JsonNode.Clone` and `JsonNode.DeepEquals` methods
+
+- (_Under development_) Patch, unpatch, formatters etc
+
+# Install
+
+Install from [NuGet.org](https://www.nuget.org/packages/SystemTextJson.JsonDiffPatch/):
+
+```
+Install-Package SystemTextJson.JsonDiffPatch
+```
+
+## Usage
+### Diff
+
+```csharp
+// Diff JSON files
+JsonDocument? diff = JsonDiffPatcher.DiffFile(file1, file2);
+// Diff Span<byte>
+JsonDocument? diff = JsonDiffPatcher.Diff(span1, span2);
+// Diff streams
+JsonDocument? diff = JsonDiffPatcher.Diff(stream1, stream2);
+// Diff JSON strings
+JsonDocument? diff = JsonDiffPatcher.Diff(json1, json2);
+// Diff JSON readers
+JsonDocument? diff = JsonDiffPatcher.Diff(ref reader1, ref reader2);
+
+// Diff mutable JsonNode objects
+var node1 = JsonNode.Parse(...);
+var node2 = JsonNode.Parse(...);
+JsonNode? diff = node1.Diff(node2);
+```
+
+### Clone
+
+```csharp
+var node = JsonNode.Parse(...);
+JsonNode? cloned = node.Clone();
+```
+
+### DeepEquals
+
+```csharp
+var node1 = JsonNode.Parse(...);
+var node2 = JsonNode.Parse(...);
+bool equal = node1.DeepEquals(node2);
+```
+
+### Options
+
+```csharp
+public struct JsonDiffOptions
+{
+    /// <summary>
+    /// Specifies whether to suppress detect array move. Default value is <c>false</c>.
+    /// </summary>
+    public bool SuppressDetectArrayMove { get; set; }
+
+    /// <summary>
+    /// Specifies whether to include moved item value. Default value is <c>false</c>.
+    /// </summary>
+    /// <remarks>
+    /// See <see link="https://github.com/benjamine/jsondiffpatch/blob/master/docs/deltas.md#array-moves"/>.
+    /// </remarks>
+    public bool IncludeValueOnMove { get; set; }
+
+    /// <summary>
+    /// Gets or sets the function to match array items.
+    /// </summary>
+    public ArrayItemMatch? ArrayItemMatcher { get; set; }
+
+    /// <summary>
+    /// Gets or sets the function to find key of a <see cref="JsonObject"/>
+    /// or <see cref="JsonArray"/>. This is used when matching array items by
+    /// their keys. If this function returns <c>null</c>, the items being
+    /// compared are treated as "not keyed". When comparing two "not keyed"
+    /// objects, their contents are compared. This function is only used when
+    /// <see cref="ArrayItemMatcher"/> is set to <c>null</c>.
+    /// </summary>
+    public Func<JsonNode?, int, object?>? ArrayObjectItemKeyFinder { get; set; }
+
+    /// <summary>
+    /// Gets or sets whether two instances of JSON object types (object and array)
+    /// are considered equal if their position is the same in their parent
+    /// arrays regardless of their contents. This property is only used when
+    /// <see cref="ArrayItemMatcher"/> is set to <c>null</c>. By settings this
+    /// property to <c>true</c>, a diff could be returned faster but larger in
+    /// size. Default value is <c>false</c>.
+    /// </summary>
+    public bool ArrayObjectItemMatchByPosition { get; set; }
+
+    /// <summary>
+    /// Gets or sets whether to prefer <see cref="ArrayObjectItemKeyFinder"/> and
+    /// <see cref="ArrayObjectItemMatchByPosition"/> than using deep value comparison
+    /// to match array object items. By settings this property to <c>true</c>,
+    /// a diff could be returned faster but larger in size. Default value is <c>false</c>.
+    /// </summary>
+    public bool PreferFuzzyArrayItemMatch { get; set; }
+
+    /// <summary>
+    /// Gets or sets the minimum length for diffing texts using <see cref="TextMatcher"/>
+    /// or default text diffing algorithm, aka Google's diff-match-patch algorithm. When text
+    /// diffing algorithm is not used, text diffing is fallback to value replacement. If this
+    /// property is set to <c>0</c>, diffing algorithm is disabled. Default value is <c>0</c>.
+    /// </summary>
+    public int TextDiffMinLength { get; set; }
+
+    /// <summary>
+    /// Gets or sets the function to match long texts.
+    /// </summary>
+    public TextMatch? TextMatcher { get; set; }
+}
+```
+
+## Benchmark
+
+``` ini
+
+BenchmarkDotNet=v0.13.1, OS=Windows 10.0.19042.631 (20H2/October2020Update)
+Intel Core i7-10750H CPU 2.60GHz, 1 CPU, 12 logical and 6 physical cores
+.NET SDK=5.0.403
+  [Host]     : .NET 5.0.12 (5.0.1221.52207), X64 RyuJIT
+  DefaultJob : .NET 5.0.12 (5.0.1221.52207), X64 RyuJIT
+
+
+```
+|                     Method |        Mean |         Min |         Max |         P95 |         P80 | Allocated |
+|--------------------------- |------------:|------------:|------------:|------------:|------------:|----------:|
+|         DemoObject_JsonNet |    165.4 μs |    158.4 μs |    168.6 μs |    168.0 μs |    167.4 μs |    173 KB |
+|  DemoObject_DefaultOptions |    152.8 μs |    146.9 μs |    160.1 μs |    159.3 μs |    155.3 μs |     84 KB |
+|     DemoObject_NoArrayMove |    152.0 μs |    147.4 μs |    154.0 μs |    153.6 μs |    153.2 μs |     84 KB |
+|         DemoObject_Mutable |    104.1 μs |    101.6 μs |    106.1 μs |    106.0 μs |    105.1 μs |     70 KB |
+|        LargeObject_JsonNet | 89,434.7 μs | 84,515.2 μs | 92,858.6 μs | 92,387.7 μs | 91,774.2 μs | 23,628 KB |
+| LargeObject_DefaultOptions |  7,446.1 μs |  7,156.2 μs |  7,794.0 μs |  7,775.8 μs |  7,518.6 μs |  4,085 KB |
+|    LargeObject_NoArrayMove |  7,364.3 μs |  7,072.5 μs |  7,575.8 μs |  7,530.3 μs |  7,472.6 μs |  4,087 KB |
+|        LargeObject_Mutable |  6,699.4 μs |  6,400.8 μs |  7,017.8 μs |  6,935.1 μs |  6,804.6 μs |  3,538 KB |
+
+
+_\* Generated using example objects [here](https://github.com/weichch/system-text-json-jsondiffpath/tree/main/test/Examples) and benchmark tests [here](https://github.com/weichch/system-text-json-jsondiffpath/tree/main/test/SystemTextJson.JsonDiffPatch.Benchmark/SimpleDiffBenchmark.cs)_
+

icon.png

@@ -0,0 +1,43 @@
+
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 16
+VisualStudioVersion = 16.0.31829.152
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SystemTextJson.JsonDiffPatch", "SystemTextJson.JsonDiffPatch\SystemTextJson.JsonDiffPatch.csproj", "{2F8D59B0-53DE-4EE7-A704-D3F89A00D9DC}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "test", "test", "{AE524BA2-D5E2-4D5F-BC95-9AA064D46234}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SystemTextJson.JsonDiffPatch.UnitTests", "..\test\SystemTextJson.JsonDiffPatch.UnitTests\SystemTextJson.JsonDiffPatch.UnitTests.csproj", "{832E60B1-0225-48B3-9AAD-638A0F5AA15E}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SystemTextJson.JsonDiffPatch.Benchmark", "..\test\SystemTextJson.JsonDiffPatch.Benchmark\SystemTextJson.JsonDiffPatch.Benchmark.csproj", "{0F173CC9-EA04-4243-A506-E2C59C905A5E}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Any CPU = Debug|Any CPU
+		Release|Any CPU = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{2F8D59B0-53DE-4EE7-A704-D3F89A00D9DC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{2F8D59B0-53DE-4EE7-A704-D3F89A00D9DC}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{2F8D59B0-53DE-4EE7-A704-D3F89A00D9DC}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{2F8D59B0-53DE-4EE7-A704-D3F89A00D9DC}.Release|Any CPU.Build.0 = Release|Any CPU
+		{832E60B1-0225-48B3-9AAD-638A0F5AA15E}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{832E60B1-0225-48B3-9AAD-638A0F5AA15E}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{832E60B1-0225-48B3-9AAD-638A0F5AA15E}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{832E60B1-0225-48B3-9AAD-638A0F5AA15E}.Release|Any CPU.Build.0 = Release|Any CPU
+		{0F173CC9-EA04-4243-A506-E2C59C905A5E}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{0F173CC9-EA04-4243-A506-E2C59C905A5E}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{0F173CC9-EA04-4243-A506-E2C59C905A5E}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{0F173CC9-EA04-4243-A506-E2C59C905A5E}.Release|Any CPU.Build.0 = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+	GlobalSection(NestedProjects) = preSolution
+		{832E60B1-0225-48B3-9AAD-638A0F5AA15E} = {AE524BA2-D5E2-4D5F-BC95-9AA064D46234}
+		{0F173CC9-EA04-4243-A506-E2C59C905A5E} = {AE524BA2-D5E2-4D5F-BC95-9AA064D46234}
+	EndGlobalSection
+	GlobalSection(ExtensibilityGlobals) = postSolution
+		SolutionGuid = {F15DC234-2EF5-47F9-BB66-3C651311A3E5}
+	EndGlobalSection
+EndGlobal

src/SystemTextJson.JsonDiffPatch.sln

@@ -0,0 +1,14 @@
+using System.Text.Json.Nodes;
+
+namespace System.Text.Json.Diffs
+{
+    /// <summary>
+    /// Defines a function that determines whether two items in arrays are equal.
+    /// </summary>
+    /// <param name="x">The element in array1.</param>
+    /// <param name="indexX">The index of <paramref name="x"/> in array1.</param>
+    /// <param name="y">The element in array2.</param>
+    /// <param name="indexY">The index of <paramref name="y"/> in array2.</param>
+    public delegate bool ArrayItemMatch(JsonNode? x, int indexX,
+        JsonNode? y, int indexY, out bool deepEqual);
+}

src/SystemTextJson.JsonDiffPatch/Diffs/ArrayItemMatch.cs

@@ -0,0 +1,96 @@
+using System.Text.Json.Nodes;
+
+namespace System.Text.Json.Diffs
+{
+    internal readonly struct DefaultArrayItemComparer
+    {
+        private readonly JsonDiffOptionsView _options;
+
+        public DefaultArrayItemComparer(in JsonDiffOptionsView options)
+        {
+            _options = options;
+        }
+
+        public bool MatchArrayItem(
+            JsonNode? x, int indexX, JsonNode? y, int indexY,
+            out bool deepEqual)
+        {
+            // Returns if one JSON node matches another. Nodes are considered match if:
+            // - they are deeply equal, OR
+            // - they are of JavaScript object type JsonObject and JsonArray and their
+            //   positions in corresponding arrays are equal
+            // See: https://github.com/benjamine/jsondiffpatch/blob/a8cde4c666a8a25d09d8f216c7f19397f2e1b569/src/filters/arrays.js#L43
+
+            deepEqual = false;
+
+            if (_options.PreferFuzzyArrayItemMatch
+                && x is JsonObject or JsonArray
+                && y is JsonObject or JsonArray)
+            {
+                if (FuzzyMatchItem(x, indexX, y, indexY,
+                    out var fuzzyResult, out deepEqual))
+                {
+                    return fuzzyResult;
+                }
+            }
+
+            if (x.DeepEquals(y))
+            {
+                deepEqual = true;
+                return true;
+            }
+
+            if (!_options.PreferFuzzyArrayItemMatch
+                && x is JsonObject or JsonArray
+                && y is JsonObject or JsonArray)
+            {
+                if (FuzzyMatchItem(x, indexX, y, indexY,
+                    out var fuzzyResult, out deepEqual))
+                {
+                    return fuzzyResult;
+                }
+            }
+
+            return false;
+        }
+
+        private bool FuzzyMatchItem(JsonNode? x, int indexX,
+            JsonNode? y, int indexY,
+            out bool result, out bool deepEqual)
+        {
+            result = false;
+            deepEqual = false;
+
+            var keyFinder = _options.ArrayObjectItemKeyFinder;
+            if (keyFinder is not null)
+            {
+                var keyX = keyFinder(x, indexX);
+                var keyY = keyFinder(y, indexY);
+
+                if (keyX is null && keyY is null)
+                {
+                    // Use DeepEquals if both items are not keyed
+                    return false;
+                }
+
+                result = Equals(keyX, keyY);
+                return true;
+            }
+
+            if (_options.ArrayObjectItemMatchByPosition)
+            {
+                if (indexX == indexY)
+                {
+                    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.
+            }
+
+            return false;
+        }
+    }
+}