Enable to force-disable pagination per relationship (#1750)

* Add assertion method to clarify intent

* Remove redundant nullability suppressions

* Enable to enforce disabling pagination per relationship

Author: bkoelman

docs/build-dev.ps1

@@ -18,6 +18,7 @@ function EnsureHttpServerIsInstalled {
         throw "Unable to find npm in your PATH. please install Node.js first."
     }
 
+    # If this command fails with ENOENT after installing Node.js on Windows, manually create the directory %APPDATA%\npm.
     npm list --depth 1 --global httpserver >$null
 
     if ($LastExitCode -eq 1) {

docs/usage/options.md

@@ -59,6 +59,9 @@ options.IncludeTotalResourceCount = true;
 To retrieve the total number of resources on secondary and relationship endpoints, the reverse of the relationship must to be available. For example, in `GET /customers/1/orders`, both the relationships `[HasMany] Customer.Orders` and `[HasOne] Order.Customer` must be defined.
 If `IncludeTotalResourceCount` is set to `false` (or the inverse relationship is unavailable on a non-primary endpoint), best-effort pagination links are returned instead. This means no `last` link and the `next` link only occurs when the current page is full.
 
+> [!TIP]
+> Since v5.8, pagination can be [turned off per relationship](~/usage/resources/relationships.md#disable-pagination).
+
 ## Relative Links
 
 All links are absolute by default. However, you can configure relative links:

docs/usage/reading/pagination.md

@@ -25,3 +25,6 @@ GET /api/blogs/1/articles?include=revisions&page[size]=10,revisions:5&page[numbe
 ## Configuring Default Behavior
 
 You can configure the global default behavior as described [here](~/usage/options.md#pagination).
+
+> [!TIP]
+> Since v5.8, pagination can be [turned off per relationship](~/usage/resources/relationships.md#disable-pagination).

docs/usage/resources/relationships.md

@@ -213,6 +213,17 @@ public class Person : Identifiable<int>
 
 The left side of this relationship is of type `Person` (public name: "persons") and the right side is of type `TodoItem` (public name: "todoItems").
 
+### Disable pagination
+
+_since v5.8_
+
+Pagination can be turned off per to-many relationship by setting `DisablePagination` to `true`.
+When doing so, it overrules the global pagination settings in options, and any pagination used in the query string
+for the relationship.
+
+This feature exists for cases where the number of *related* resources is typically small.
+For example, while the number of products is usually high, the number of products *in a shopping basket* is not.
+
 ## HasManyThrough
 
 _removed since v5.0_

src/JsonApiDotNetCore.Annotations/Resources/Annotations/HasManyAttribute.cs

@@ -50,6 +50,18 @@ public HasManyCapabilities Capabilities
         set => _capabilities = value;
     }
 
+    /// <summary>
+    /// When set to <c>true</c>, overrules the default page size, the page size from a resource definition, and the
+    /// <c>
+    /// page[size]
+    /// </c>
+    /// query string parameter by forcibly turning off pagination on the related resources for this relationship.
+    /// </summary>
+    /// <remarks>
+    /// Caution: only use this when the number of related resources (along with their nested includes) is known to always be small.
+    /// </remarks>
+    public bool DisablePagination { get; set; }
+
     public HasManyAttribute()
     {
         _lazyIsManyToMany = new Lazy<bool>(EvaluateIsManyToMany, LazyThreadSafetyMode.PublicationOnly);

src/JsonApiDotNetCore.Annotations/Resources/Annotations/HasManyAttribute.netstandard.cs

@@ -11,4 +11,7 @@ public sealed class HasManyAttribute : RelationshipAttribute
 {
     /// <summary />
     public HasManyCapabilities Capabilities { get; set; }
+
+    /// <summary />
+    public bool DisablePagination { get; set; }
 }

src/JsonApiDotNetCore/Configuration/IJsonApiOptions.cs

@@ -105,7 +105,8 @@ public interface IJsonApiOptions
     bool IncludeTotalResourceCount { get; }
 
     /// <summary>
-    /// The page size (10 by default) that is used when not specified in query string. Set to <c>null</c> to not use pagination by default.
+    /// The page size (10 by default) that is used when not specified in query string. Set to <c>null</c> to not use pagination by default. This setting can
+    /// be overruled per relationship by setting <see cref="HasManyAttribute.DisablePagination" /> to <c>true</c>.
     /// </summary>
     PageSize? DefaultPageSize { get; }
 

src/JsonApiDotNetCore/Queries/Expressions/QueryExpressionRewriter.cs

@@ -124,7 +124,7 @@ public override QueryExpression VisitIsType(IsTypeExpression expression, TArgume
 
         if (newElements.Count != 0)
         {
-            var newExpression = new SortExpression(newElements);
+            var newExpression = new SortExpression(newElements, expression.IsAutoGenerated);
             return newExpression.Equals(expression) ? expression : newExpression;
         }
 

src/JsonApiDotNetCore/Queries/Expressions/SortExpression.cs

@@ -13,16 +13,27 @@ namespace JsonApiDotNetCore.Queries.Expressions;
 [PublicAPI]
 public class SortExpression : QueryExpression
 {
+    /// <summary>
+    /// Indicates whether this expression was generated by JsonApiDotNetCore to ensure a deterministic order.
+    /// </summary>
+    internal bool IsAutoGenerated { get; }
+
     /// <summary>
     /// One or more elements to sort on.
     /// </summary>
     public IImmutableList<SortElementExpression> Elements { get; }
 
     public SortExpression(IImmutableList<SortElementExpression> elements)
+        : this(elements, false)
+    {
+    }
+
+    internal SortExpression(IImmutableList<SortElementExpression> elements, bool isAutoGenerated)
     {
         ArgumentGuard.NotNullNorEmpty(elements);
 
         Elements = elements;
+        IsAutoGenerated = isAutoGenerated;
     }
 
     public override TResult Accept<TArgument, TResult>(QueryExpressionVisitor<TArgument, TResult> visitor, TArgument argument)
@@ -37,7 +48,7 @@ public override string ToString()
 
     public override string ToFullString()
     {
-        return string.Join(",", Elements.Select(child => child.ToFullString()));
+        return $"{string.Join(",", Elements.Select(child => child.ToFullString()))}{(IsAutoGenerated ? " (auto-generated)" : "")}";
     }
 
     public override bool Equals(object? obj)
@@ -54,12 +65,13 @@ public override bool Equals(object? obj)
 
         var other = (SortExpression)obj;
 
-        return Elements.SequenceEqual(other.Elements);
+        return IsAutoGenerated == other.IsAutoGenerated && Elements.SequenceEqual(other.Elements);
     }
 
     public override int GetHashCode()
     {
         var hashCode = new HashCode();
+        hashCode.Add(IsAutoGenerated);
 
         foreach (SortElementExpression element in Elements)
         {

src/JsonApiDotNetCore/Queries/QueryLayerComposer.cs

@@ -243,12 +243,13 @@ private IImmutableSet<IncludeElementExpression> ProcessIncludeSet(IImmutableSet<
 
                 ResourceType resourceType = includeElement.Relationship.RightType;
                 bool isToManyRelationship = includeElement.Relationship is HasManyAttribute;
+                bool allowPagination = includeElement.Relationship is HasManyAttribute { DisablePagination: false };
 
                 var subLayer = new QueryLayer(resourceType)
                 {
                     Filter = isToManyRelationship ? GetFilter(expressionsInCurrentScope, resourceType) : null,
                     Sort = isToManyRelationship ? GetSort(expressionsInCurrentScope, resourceType) : null,
-                    Pagination = isToManyRelationship ? GetPagination(expressionsInCurrentScope, resourceType) : null,
+                    Pagination = allowPagination ? GetPagination(expressionsInCurrentScope, resourceType) : null,
                     Selection = GetSelectionForSparseAttributeSet(resourceType)
                 };
 
@@ -384,12 +385,26 @@ public QueryLayer WrapLayerForSecondaryEndpoint<TId>(QueryLayer secondaryLayer,
         FilterExpression? primaryFilter = GetFilter(Array.Empty<QueryExpression>(), primaryResourceType);
         AttrAttribute primaryIdAttribute = GetIdAttribute(primaryResourceType);
 
-        return new QueryLayer(primaryResourceType)
+        var primaryLayer = new QueryLayer(primaryResourceType)
         {
             Include = RewriteIncludeForSecondaryEndpoint(innerInclude, relationship),
             Filter = CreateFilterByIds([primaryId], primaryIdAttribute, primaryFilter),
             Selection = primarySelection
         };
+
+        if (relationship is HasManyAttribute { DisablePagination: true } && secondaryLayer.Pagination != null)
+        {
+            // Undo pagination/sort. At the time secondaryLayer was being built, we were not yet aware that it needed to be turned off.
+            secondaryLayer.Pagination = null;
+            _paginationContext.PageSize = null;
+
+            if (secondaryLayer.Sort is { IsAutoGenerated: true })
+            {
+                secondaryLayer.Sort = null;
+            }
+        }
+
+        return primaryLayer;
     }
 
     private IncludeExpression RewriteIncludeForSecondaryEndpoint(IncludeExpression? relativeInclude, RelationshipAttribute secondaryRelationship)
@@ -554,7 +569,7 @@ private SortExpression CreateSortById(ResourceType resourceType)
     {
         AttrAttribute idAttribute = GetIdAttribute(resourceType);
         var idAscendingSort = new SortElementExpression(new ResourceFieldChainExpression(idAttribute), true);
-        return new SortExpression(ImmutableArray.Create(idAscendingSort));
+        return new SortExpression(ImmutableArray.Create(idAscendingSort), true);
     }
 
     protected virtual PaginationExpression GetPagination(IReadOnlyCollection<QueryExpression> expressionsInScope, ResourceType resourceType)