Refactorings (#1038)

Various refactorings

* Renamed CollectionNotEmptyExpression to HasExpression
* Renamed EqualsAnyOfExpression to AnyExpression
* Changed SparseFieldSetExpression.Fields type from IReadOnlyCollection to IImmutableSet
* Changed SparseFieldTableExpression.Table type from IReadOnlyDictionary to IImmutableDictionary and fixed equality comparison to discard order
* Changed SortExpression.Elements type from IReadOnlyDictionary to IImmutableList
* Changed ResourceFieldChainExpression.Fields type from IReadOnlyCollection to IImmutableList
* Changed PaginationQueryStringValueExpression.Elements type from IReadOnlyCollection to IImmutableList
* Changed AnyExpression.Constants type from IReadOnlyCollection to IImmutableSet
* Changed LogicalExpression.Terms type from IReadOnlyCollection to IImmutableList
* Changed IncludeExpression.Elements type and IncludeElementExpression.Children type from IReadOnlyCollection to IImmutableList
* Add support for `IReadOnlySet<>` usage in resource models
* Changed DisableQueryStringAttribute.ParameterNames type from IReadOnlyCollection to IReadOnlySet
* Changed IResourceContextProvider.GetResourceContexts() to return a set instead of a list. Made ResourceContext sealed and immutable and implemented Equals/GetHashCode so it works with sets.
* Use "endpoint" in RequestMethodNotAllowedException message
* Renamed StandardQueryStringParameters to JsonApiQueryStringParameters
* Replaced obsolete IQueryLayerComposer.GetResourceDefinitionAccessor() with injected service
* Replaced obsolete IResourceFactory.GetResourceDefinitionAccessor() with injected service
* Made TId in IResourceDefinition contravariant
* Corrected terminology: relationships use left/right instead of primary/secondary
* Removed obsolete IJsonApiRequest.BasePath
* Removed EntityFrameworkCoreSupport (no longer needed for EF Core 5+)
* Always set IJsonApiRequest.OperationKind from middleware
* Renamed OperationKind to WriteOperationKind, exposed as IJsonApiRequest.WriteOperation
* Add HTTP Method to trace logging

Author: Bart Koelman

benchmarks/Serialization/JsonApiDeserializerBenchmarks.cs

@@ -38,15 +38,18 @@ public JsonApiDeserializerBenchmarks()
             IResourceGraph resourceGraph = _dependencyFactory.CreateResourceGraph(options);
 
             var serviceContainer = new ServiceContainer();
-            serviceContainer.AddService(typeof(IResourceDefinitionAccessor), new ResourceDefinitionAccessor(resourceGraph, serviceContainer));
+            var resourceDefinitionAccessor = new ResourceDefinitionAccessor(resourceGraph, serviceContainer);
+
+            serviceContainer.AddService(typeof(IResourceDefinitionAccessor), resourceDefinitionAccessor);
             serviceContainer.AddService(typeof(IResourceDefinition<BenchmarkResource>), new JsonApiResourceDefinition<BenchmarkResource>(resourceGraph));
 
             var targetedFields = new TargetedFields();
             var request = new JsonApiRequest();
             var resourceFactory = new ResourceFactory(serviceContainer);
             var httpContextAccessor = new HttpContextAccessor();
 
-            _jsonApiDeserializer = new RequestDeserializer(resourceGraph, resourceFactory, targetedFields, httpContextAccessor, request, options);
+            _jsonApiDeserializer = new RequestDeserializer(resourceGraph, resourceFactory, targetedFields, httpContextAccessor, request, options,
+                resourceDefinitionAccessor);
         }
 
         [Benchmark]

docs/internals/queries.md

@@ -18,7 +18,7 @@ Processing a request involves the following steps:
 	- The readers also implement `IQueryConstraintProvider`, which exposes expressions through `ExpressionInScope` objects.
 - `QueryLayerComposer` (used from `JsonApiResourceService`) collects all query constraints.
 	- It combines them with default options and `IResourceDefinition` overrides and composes a tree of `QueryLayer` objects.
-	- It lifts the tree for nested endpoints like /blogs/1/articles and rewrites includes.
+	- It lifts the tree for secondary endpoints like /blogs/1/articles and rewrites includes.
 	- `JsonApiResourceService` contains no more usage of `IQueryable`.
 - `EntityFrameworkCoreRepository` delegates to `QueryableBuilder` to transform the `QueryLayer` tree into `IQueryable` expression trees.
 	`QueryBuilder` depends on `QueryClauseBuilder` implementations that visit the tree nodes, transforming them to `System.Linq.Expression` equivalents.

docs/usage/extensibility/resource-definitions.md

@@ -202,8 +202,8 @@ public class EmployeeDefinition : JsonApiResourceDefinition<Employee>
     {
     }
 
-    public override IReadOnlyCollection<IncludeElementExpression> OnApplyIncludes(
-        IReadOnlyCollection<IncludeElementExpression> existingIncludes)
+    public override IImmutableList<IncludeElementExpression> OnApplyIncludes(
+        IImmutableList<IncludeElementExpression> existingIncludes)
     {
         if (existingIncludes.Any(include =>
             include.Relationship.Property.Name == nameof(Employee.Manager)))

docs/usage/extensibility/services.md

@@ -18,9 +18,10 @@ public class TodoItemService : JsonApiResourceService<TodoItem>
     public TodoItemService(IResourceRepositoryAccessor repositoryAccessor,
         IQueryLayerComposer queryLayerComposer, IPaginationContext paginationContext,
         IJsonApiOptions options, ILoggerFactory loggerFactory, IJsonApiRequest request,
-        IResourceChangeTracker<TodoItem> resourceChangeTracker)
+        IResourceChangeTracker<TodoItem> resourceChangeTracker,
+        IResourceDefinitionAccessor resourceDefinitionAccessor)
         : base(repositoryAccessor, queryLayerComposer, paginationContext, options,
-            loggerFactory, request, resourceChangeTracker)
+            loggerFactory, request, resourceChangeTracker, resourceDefinitionAccessor)
     {
         _notificationService = notificationService;
     }

docs/usage/reading/including-relationships.md

@@ -62,7 +62,7 @@ which is equivalent to:
 GET /api/articles?include=author&include=author.livingAddress&include=author.livingAddress.country
 ```
 
-This can be used on nested endpoints too:
+This can be used on secondary endpoints too:
 
 ```http
 GET /api/blogs/1/articles?include=author.livingAddress.country

docs/usage/reading/pagination.md

@@ -6,9 +6,7 @@ Resources can be paginated. This request would fetch the second page of 10 artic
 GET /articles?page[size]=10&page[number]=2 HTTP/1.1
 ```
 
-## Nesting
-
-Pagination can be used on nested endpoints, such as:
+Pagination can be used on secondary endpoints, such as:
 
 ```http
 GET /blogs/1/articles?page[number]=2 HTTP/1.1

docs/usage/reading/sorting.md

@@ -34,9 +34,9 @@ GET /api/blogs?sort=count(articles) HTTP/1.1
 
 This sorts the list of blogs by their number of articles.
 
-## Nesting
+## Secondary endpoints
 
-Sorting can be used on nested endpoints, such as:
+Sorting can be used on secondary endpoints, such as:
 
 ```http
 GET /api/blogs/1/articles?sort=caption HTTP/1.1

docs/usage/reading/sparse-fieldset-selection.md

@@ -2,15 +2,15 @@
 
 As an alternative to returning all fields (attributes and relationships) from a resource, the `fields[]` query string parameter can be used to select a subset.
 Put the resource type to apply the fieldset on between the brackets.
-This can be used on the resource being requested, as well as on nested endpoints and/or included resources.
+This can be used on primary and secondary endpoints. The selection is applied on both primary and included resources.
 
-Top-level example:
+Primary endpoint example:
 
 ```http
 GET /articles?fields[articles]=title,body,comments HTTP/1.1
 ```
 
-Nested endpoint example:
+Secondary endpoint example:
 
 ```http
 GET /api/blogs/1/articles?fields[articles]=title,body,comments HTTP/1.1

src/Examples/JsonApiDotNetCoreExample/Definitions/TodoItemDefinition.cs

@@ -36,13 +36,13 @@ private SortExpression GetDefaultSortOrder()
             });
         }
 
-        public override Task OnWritingAsync(TodoItem resource, OperationKind operationKind, CancellationToken cancellationToken)
+        public override Task OnWritingAsync(TodoItem resource, WriteOperationKind writeOperation, CancellationToken cancellationToken)
         {
-            if (operationKind == OperationKind.CreateResource)
+            if (writeOperation == WriteOperationKind.CreateResource)
             {
                 resource.CreatedAt = _systemClock.UtcNow;
             }
-            else if (operationKind == OperationKind.UpdateResource)
+            else if (writeOperation == WriteOperationKind.UpdateResource)
             {
                 resource.LastModifiedAt = _systemClock.UtcNow;
             }

src/Examples/MultiDbContextExample/Repositories/DbContextARepository.cs

@@ -14,8 +14,9 @@ public sealed class DbContextARepository<TResource> : EntityFrameworkCoreReposit
         where TResource : class, IIdentifiable<int>
     {
         public DbContextARepository(ITargetedFields targetedFields, DbContextResolver<DbContextA> contextResolver, IResourceGraph resourceGraph,
-            IResourceFactory resourceFactory, IEnumerable<IQueryConstraintProvider> constraintProviders, ILoggerFactory loggerFactory)
-            : base(targetedFields, contextResolver, resourceGraph, resourceFactory, constraintProviders, loggerFactory)
+            IResourceFactory resourceFactory, IEnumerable<IQueryConstraintProvider> constraintProviders, ILoggerFactory loggerFactory,
+            IResourceDefinitionAccessor resourceDefinitionAccessor)
+            : base(targetedFields, contextResolver, resourceGraph, resourceFactory, constraintProviders, loggerFactory, resourceDefinitionAccessor)
         {
         }
     }