Ported existing unit tests and changed how included[] is built.

It now always emits related resources in relationship declaration order, even in deeply nested circular chains where a subsequent inclusion chain is deeper and adds more relationships to an already converted resource.

Performance impact, summary:
- In the endpoint test, this commit improves performance for rendering includes, while slightly decreasing it for the other two scenarios. All are still faster or the same compared to the master branch.
- In BenchmarkDotNet, this commit slightly increases rendering time, compared to earlier commits in this PR, but it is still faster than the master branch.

Measurement results for GET http://localhost:14140/api/v1/todoItems?include=owner,assignee,tags:
    Write response body .............................  0:00:00:00.0010385 -> 0:00:00:00.0008060 ...  77% (was: 130%)

Measurement results for GET http://localhost:14140/api/v1/todoItems?filter=and(startsWith(description,'T'),equals(priority,'Low'),not(equals(owner,null)),not(equals(assignee,null))):
    Write response body .............................  0:00:00:00.0006601 -> 0:00:00:00.0005629 ...  85% (was: 70%)

Measurement results for POST http://localhost:14140/api/v1/operations (10x add-resource):
    Write response body .............................  0:00:00:00.0003432 -> 0:00:00:00.0003411 ...  99% (was: 95%)

|                            Method |     Mean |   Error |  StdDev |
|---------------------------------- |---------:|--------:|--------:|
| LegacySerializeOperationsResponse | 239.0 us | 3.17 us | 2.81 us |
|       SerializeOperationsResponse | 153.8 us | 0.72 us | 0.60 us |
| (new) SerializeOperationsResponse | 168.6 us | 1.74 us | 1.63 us |

|                          Method |     Mean |   Error |  StdDev |
|-------------------------------- |---------:|--------:|--------:|
| LegacySerializeResourceResponse | 177.6 us | 0.56 us | 0.50 us |
|       SerializeResourceResponse | 101.3 us | 0.31 us | 0.29 us |
| (new) SerializeResourceResponse | 123.7 us | 1.12 us | 1.05 us |

Author: Bart Koelman

src/JsonApiDotNetCore/Serialization/Response/IncludedCollection.cs

@@ -0,0 +1,273 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using JsonApiDotNetCore.Configuration;
+using JsonApiDotNetCore.Resources;
+using JsonApiDotNetCore.Resources.Annotations;
+using JsonApiDotNetCore.Serialization.Objects;
+
+namespace JsonApiDotNetCore.Serialization.Response
+{
+    /// <summary>
+    /// Represents a dependency tree of resource objects. It provides the values for 'data' and 'included' in the response body. The tree is built by
+    /// recursively walking the resource relationships from the inclusion chains. Note that a subsequent chain may add additional relationships to a resource
+    /// object that was produced by an earlier chain. Afterwards, this tree is used to fill relationship objects in the resource objects (depending on sparse
+    /// fieldsets) and to emit all entries in relationship declaration order.
+    /// </summary>
+    internal sealed class ResourceObjectTreeNode : IEquatable<ResourceObjectTreeNode>
+    {
+        // Placeholder root node for the tree, which is never emitted itself.
+        private static readonly ResourceType RootType = new("(root)", typeof(object), typeof(object));
+        private static readonly IIdentifiable RootResource = new EmptyResource();
+
+        // Direct children from root. These are emitted in 'data'.
+        private List<ResourceObjectTreeNode> _directChildren;
+
+        // Related resource objects per relationship. These are emitted in 'included'.
+        private Dictionary<RelationshipAttribute, HashSet<ResourceObjectTreeNode>> _childrenByRelationship;
+
+        private bool IsTreeRoot => RootType.Equals(Type);
+
+        // The resource this node was built for. We only store it for the LinkBuilder.
+        public IIdentifiable Resource { get; }
+
+        // The resource type. We use its relationships to maintain order.
+        public ResourceType Type { get; }
+
+        // The produced resource object from Resource. For each resource, at most one ResourceObject and one tree node must exist.
+        public ResourceObject ResourceObject { get; }
+
+        public ResourceObjectTreeNode(IIdentifiable resource, ResourceType type, ResourceObject resourceObject)
+        {
+            ArgumentGuard.NotNull(resource, nameof(resource));
+            ArgumentGuard.NotNull(type, nameof(type));
+            ArgumentGuard.NotNull(resourceObject, nameof(resourceObject));
+
+            Resource = resource;
+            Type = type;
+            ResourceObject = resourceObject;
+        }
+
+        public static ResourceObjectTreeNode CreateRoot()
+        {
+            return new ResourceObjectTreeNode(RootResource, RootType, new ResourceObject());
+        }
+
+        public void AttachDirectChild(ResourceObjectTreeNode treeNode)
+        {
+            ArgumentGuard.NotNull(treeNode, nameof(treeNode));
+
+            _directChildren ??= new List<ResourceObjectTreeNode>();
+            _directChildren.Add(treeNode);
+        }
+
+        public void EnsureHasRelationship(RelationshipAttribute relationship)
+        {
+            ArgumentGuard.NotNull(relationship, nameof(relationship));
+
+            _childrenByRelationship ??= new Dictionary<RelationshipAttribute, HashSet<ResourceObjectTreeNode>>();
+
+            if (!_childrenByRelationship.ContainsKey(relationship))
+            {
+                _childrenByRelationship[relationship] = new HashSet<ResourceObjectTreeNode>();
+            }
+        }
+
+        public void AttachRelationshipChild(RelationshipAttribute relationship, ResourceObjectTreeNode rightNode)
+        {
+            ArgumentGuard.NotNull(relationship, nameof(relationship));
+            ArgumentGuard.NotNull(rightNode, nameof(rightNode));
+
+            HashSet<ResourceObjectTreeNode> rightNodes = _childrenByRelationship[relationship];
+            rightNodes.Add(rightNode);
+        }
+
+        /// <summary>
+        /// Recursively walks the tree and returns the set of unique nodes. Uses relationship declaration order.
+        /// </summary>
+        public ISet<ResourceObjectTreeNode> GetUniqueNodes()
+        {
+            AssertIsTreeRoot();
+
+            var visited = new HashSet<ResourceObjectTreeNode>();
+
+            VisitSubtree(this, visited);
+
+            return visited;
+        }
+
+        private static void VisitSubtree(ResourceObjectTreeNode treeNode, ISet<ResourceObjectTreeNode> visited)
+        {
+            if (visited.Contains(treeNode))
+            {
+                return;
+            }
+
+            if (!treeNode.IsTreeRoot)
+            {
+                visited.Add(treeNode);
+            }
+
+            VisitDirectChildrenInSubtree(treeNode, visited);
+            VisitRelationshipChildrenInSubtree(treeNode, visited);
+        }
+
+        private static void VisitDirectChildrenInSubtree(ResourceObjectTreeNode treeNode, ISet<ResourceObjectTreeNode> visited)
+        {
+            if (treeNode._directChildren != null)
+            {
+                foreach (ResourceObjectTreeNode child in treeNode._directChildren)
+                {
+                    VisitSubtree(child, visited);
+                }
+            }
+        }
+
+        private static void VisitRelationshipChildrenInSubtree(ResourceObjectTreeNode treeNode, ISet<ResourceObjectTreeNode> visited)
+        {
+            if (treeNode._childrenByRelationship != null)
+            {
+                foreach (RelationshipAttribute relationship in treeNode.Type.Relationships)
+                {
+                    if (treeNode._childrenByRelationship.TryGetValue(relationship, out HashSet<ResourceObjectTreeNode> rightNodes))
+                    {
+                        VisitRelationshipChildInSubtree(rightNodes, visited);
+                    }
+                }
+            }
+        }
+
+        private static void VisitRelationshipChildInSubtree(HashSet<ResourceObjectTreeNode> rightNodes, ISet<ResourceObjectTreeNode> visited)
+        {
+            foreach (ResourceObjectTreeNode rightNode in rightNodes)
+            {
+                VisitSubtree(rightNode, visited);
+            }
+        }
+
+        public ISet<ResourceObjectTreeNode> GetRightNodesInRelationship(RelationshipAttribute relationship)
+        {
+            return _childrenByRelationship != null && _childrenByRelationship.TryGetValue(relationship, out HashSet<ResourceObjectTreeNode> rightNodes)
+                ? rightNodes
+                : null;
+        }
+
+        /// <summary>
+        /// Provides the value for 'data' in the response body. Uses relationship declaration order.
+        /// </summary>
+        public IList<ResourceObject> GetResponseData()
+        {
+            AssertIsTreeRoot();
+
+            return GetDirectChildren().Select(child => child.ResourceObject).ToArray();
+        }
+
+        /// <summary>
+        /// Provides the value for 'included' in the response body. Uses relationship declaration order.
+        /// </summary>
+        public IList<ResourceObject> GetResponseIncluded()
+        {
+            AssertIsTreeRoot();
+
+            var visited = new HashSet<ResourceObjectTreeNode>();
+
+            foreach (ResourceObjectTreeNode child in GetDirectChildren())
+            {
+                VisitRelationshipChildrenInSubtree(child, visited);
+            }
+
+            return visited.Select(node => node.ResourceObject).ToArray();
+        }
+
+        private IList<ResourceObjectTreeNode> GetDirectChildren()
+        {
+            return _directChildren == null ? Array.Empty<ResourceObjectTreeNode>() : _directChildren;
+        }
+
+        private void AssertIsTreeRoot()
+        {
+            if (!IsTreeRoot)
+            {
+                throw new InvalidOperationException("Internal error: this method should only be called from the root of the tree.");
+            }
+        }
+
+        public bool Equals(ResourceObjectTreeNode other)
+        {
+            if (ReferenceEquals(null, other))
+            {
+                return false;
+            }
+
+            if (ReferenceEquals(this, other))
+            {
+                return true;
+            }
+
+            return ResourceObjectComparer.Instance.Equals(ResourceObject, other.ResourceObject);
+        }
+
+        public override bool Equals(object other)
+        {
+            return Equals(other as ResourceObjectTreeNode);
+        }
+
+        public override int GetHashCode()
+        {
+            return ResourceObject.GetHashCode();
+        }
+
+        public override string ToString()
+        {
+            var builder = new StringBuilder();
+            builder.Append(IsTreeRoot ? Type.PublicName : $"{ResourceObject.Type}:{ResourceObject.Id}");
+
+            if (_directChildren != null)
+            {
+                builder.Append($", children: {_directChildren.Count}");
+            }
+            else if (_childrenByRelationship != null)
+            {
+                builder.Append($", children: {string.Join(',', _childrenByRelationship.Select(pair => $"{pair.Key.PublicName} ({pair.Value.Count})"))}");
+            }
+
+            return builder.ToString();
+        }
+
+        private sealed class EmptyResource : IIdentifiable
+        {
+            public string StringId { get; set; }
+            public string LocalId { get; set; }
+        }
+
+        private sealed class ResourceObjectComparer : IEqualityComparer<ResourceObject>
+        {
+            public static readonly ResourceObjectComparer Instance = new();
+
+            private ResourceObjectComparer()
+            {
+            }
+
+            public bool Equals(ResourceObject x, ResourceObject y)
+            {
+                if (ReferenceEquals(x, y))
+                {
+                    return true;
+                }
+
+                if (x is null || y is null || x.GetType() != y.GetType())
+                {
+                    return false;
+                }
+
+                return x.Type == y.Type && x.Id == y.Id && x.Lid == y.Lid;
+            }
+
+            public int GetHashCode(ResourceObject obj)
+            {
+                return HashCode.Combine(obj.Type, obj.Id, obj.Lid);
+            }
+        }
+    }
+}