Enable to enforce pagination disabled per relationship

bkoelman · bkoelman · commit b4835afd8225 · 2025-08-02T02:39:50.000+02:00
diff --git a/src/JsonApiDotNetCore.Annotations/Resources/Annotations/HasManyAttribute.cs b/src/JsonApiDotNetCore.Annotations/Resources/Annotations/HasManyAttribute.cs
@@ -50,6 +50,12 @@ public HasManyCapabilities Capabilities
         set => _capabilities = value;
     }
 
+    /// <summary>
+    /// When set to <c>true</c>, disables pagination for this relationship, which overrules global options, resource definitions, and the <c>page</c> query
+    /// string parameter. Only use this when the number of related resources is known to always be small.
+    /// </summary>
+    public bool DisablePagination { get; set; }
+
     public HasManyAttribute()
     {
         _lazyIsManyToMany = new Lazy<bool>(EvaluateIsManyToMany, LazyThreadSafetyMode.PublicationOnly);
diff --git a/src/JsonApiDotNetCore.Annotations/Resources/Annotations/HasManyAttribute.netstandard.cs b/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; }
 }
diff --git a/src/JsonApiDotNetCore/Queries/Expressions/QueryExpressionRewriter.cs b/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;
         }
 
diff --git a/src/JsonApiDotNetCore/Queries/Expressions/SortExpression.cs b/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)
         {
diff --git a/src/JsonApiDotNetCore/Queries/QueryLayerComposer.cs b/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 = isToManyRelationship && allowPagination ? GetPagination(expressionsInCurrentScope, resourceType) : null,
                     Selection = GetSelectionForSparseAttributeSet(resourceType)
                 };
 
@@ -384,12 +385,25 @@ 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)
+        {
+            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 +568,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)
diff --git a/test/AnnotationTests/Models/TreeNode.cs b/test/AnnotationTests/Models/TreeNode.cs
@@ -17,6 +17,7 @@ public sealed class TreeNode : Identifiable<long>
     [HasOne(PublicName = "orders", Capabilities = HasOneCapabilities.AllowView | HasOneCapabilities.AllowInclude, Links = LinkTypes.All)]
     public TreeNode? Parent { get; set; }
 
-    [HasMany(PublicName = "orders", Capabilities = HasManyCapabilities.AllowView | HasManyCapabilities.AllowFilter, Links = LinkTypes.All)]
+    [HasMany(PublicName = "orders", Capabilities = HasManyCapabilities.AllowView | HasManyCapabilities.AllowFilter, Links = LinkTypes.All,
+        DisablePagination = true)]
     public ISet<TreeNode> Children { get; set; } = new HashSet<TreeNode>();
 }
diff --git a/test/JsonApiDotNetCoreTests/IntegrationTests/QueryStrings/Appointment.cs b/test/JsonApiDotNetCoreTests/IntegrationTests/QueryStrings/Appointment.cs
@@ -20,6 +20,9 @@ public sealed class Appointment : Identifiable<int>
     [Attr]
     public DateTimeOffset EndTime { get; set; }
 
-    [HasMany]
+    [HasOne]
+    public Calendar? Calendar { get; set; }
+
+    [HasMany(DisablePagination = true)]
     public IList<Reminder> Reminders { get; set; } = new List<Reminder>();
 }
diff --git a/test/JsonApiDotNetCoreTests/IntegrationTests/QueryStrings/Includes/DisablePaginationOnRelationshipTests.cs b/test/JsonApiDotNetCoreTests/IntegrationTests/QueryStrings/Includes/DisablePaginationOnRelationshipTests.cs
@@ -0,0 +1,238 @@
+using System.Net;
+using FluentAssertions;
+using JetBrains.Annotations;
+using JsonApiDotNetCore.Configuration;
+using JsonApiDotNetCore.Queries.Expressions;
+using JsonApiDotNetCore.Resources;
+using JsonApiDotNetCore.Serialization.Objects;
+using Microsoft.Extensions.DependencyInjection;
+using TestBuildingBlocks;
+using Xunit;
+
+namespace JsonApiDotNetCoreTests.IntegrationTests.QueryStrings.Includes;
+
+public sealed class DisablePaginationOnRelationshipTests : IClassFixture<IntegrationTestContext<TestableStartup<QueryStringDbContext>, QueryStringDbContext>>
+{
+    private readonly IntegrationTestContext<TestableStartup<QueryStringDbContext>, QueryStringDbContext> _testContext;
+    private readonly QueryStringFakers _fakers = new();
+
+    public DisablePaginationOnRelationshipTests(IntegrationTestContext<TestableStartup<QueryStringDbContext>, QueryStringDbContext> testContext)
+    {
+        _testContext = testContext;
+
+        testContext.UseController<AppointmentsController>();
+        testContext.UseController<CalendarsController>();
+
+        testContext.ConfigureServices(services =>
+        {
+            services.AddResourceDefinition<ReminderDefinition>();
+            services.AddSingleton<PaginationToggle>();
+        });
+
+        var paginationToggle = testContext.Factory.Services.GetRequiredService<PaginationToggle>();
+        paginationToggle.IsEnabled = false;
+        paginationToggle.IsCalled = false;
+
+        var options = (JsonApiOptions)testContext.Factory.Services.GetRequiredService<IJsonApiOptions>();
+        options.DefaultPageSize = new PageSize(5);
+        options.UseRelativeLinks = true;
+        options.IncludeTotalResourceCount = true;
+    }
+
+    [Fact]
+    public async Task Can_include_in_primary_resources()
+    {
+        // Arrange
+        Appointment appointment = _fakers.Appointment.GenerateOne();
+        appointment.Reminders = _fakers.Reminder.GenerateList(7);
+
+        await _testContext.RunOnDatabaseAsync(async dbContext =>
+        {
+            await dbContext.ClearTableAsync<Appointment>();
+            dbContext.Appointments.Add(appointment);
+            await dbContext.SaveChangesAsync();
+        });
+
+        const string route = "appointments?include=reminders";
+
+        // Act
+        (HttpResponseMessage httpResponse, Document responseDocument) = await _testContext.ExecuteGetAsync<Document>(route);
+
+        // Assert
+        httpResponse.ShouldHaveStatusCode(HttpStatusCode.OK);
+
+        responseDocument.Data.ManyValue.Should().HaveCount(1);
+        responseDocument.Data.ManyValue[0].Type.Should().Be("appointments");
+        responseDocument.Data.ManyValue[0].Id.Should().Be(appointment.StringId);
+
+        responseDocument.Data.ManyValue[0].Relationships.Should().ContainKey("reminders").WhoseValue.With(value =>
+        {
+            value.Should().NotBeNull();
+            value.Data.ManyValue.Should().HaveCount(7);
+
+            value.Links.Should().NotBeNull();
+            value.Links.Self.Should().Be($"/appointments/{appointment.StringId}/relationships/reminders");
+            value.Links.Related.Should().Be($"/appointments/{appointment.StringId}/reminders");
+        });
+
+        responseDocument.Included.Should().HaveCount(7);
+        responseDocument.Included.Should().AllSatisfy(resource => resource.Type.Should().Be("reminders"));
+
+        responseDocument.Meta.Should().ContainTotal(1);
+    }
+
+    [Fact]
+    public async Task Can_get_all_secondary_resources()
+    {
+        // Arrange
+        Appointment appointment = _fakers.Appointment.GenerateOne();
+        appointment.Reminders = _fakers.Reminder.GenerateList(7);
+
+        await _testContext.RunOnDatabaseAsync(async dbContext =>
+        {
+            dbContext.Appointments.Add(appointment);
+            await dbContext.SaveChangesAsync();
+        });
+
+        string route = $"appointments/{appointment.StringId}/reminders";
+
+        // Act
+        (HttpResponseMessage httpResponse, Document responseDocument) = await _testContext.ExecuteGetAsync<Document>(route);
+
+        // Assert
+        httpResponse.ShouldHaveStatusCode(HttpStatusCode.OK);
+
+        responseDocument.Data.ManyValue.Should().HaveCount(7);
+        responseDocument.Data.ManyValue.Should().AllSatisfy(resource => resource.Type.Should().Be("reminders"));
+
+        responseDocument.Links.Should().NotBeNull();
+        responseDocument.Links.First.Should().BeNull();
+        responseDocument.Links.Next.Should().BeNull();
+        responseDocument.Links.Last.Should().BeNull();
+
+        responseDocument.Meta.Should().ContainTotal(7);
+    }
+
+    [Fact]
+    public async Task Can_get_ToMany_relationship()
+    {
+        // Arrange
+        Appointment appointment = _fakers.Appointment.GenerateOne();
+        appointment.Reminders = _fakers.Reminder.GenerateList(7);
+
+        await _testContext.RunOnDatabaseAsync(async dbContext =>
+        {
+            dbContext.Appointments.Add(appointment);
+            await dbContext.SaveChangesAsync();
+        });
+
+        string route = $"appointments/{appointment.StringId}/relationships/reminders";
+
+        // Act
+        (HttpResponseMessage httpResponse, Document responseDocument) = await _testContext.ExecuteGetAsync<Document>(route);
+
+        // Assert
+        httpResponse.ShouldHaveStatusCode(HttpStatusCode.OK);
+
+        responseDocument.Data.ManyValue.Should().HaveCount(7);
+        responseDocument.Data.ManyValue.Should().AllSatisfy(resource => resource.Type.Should().Be("reminders"));
+
+        responseDocument.Links.Should().NotBeNull();
+        responseDocument.Links.First.Should().BeNull();
+        responseDocument.Links.Next.Should().BeNull();
+        responseDocument.Links.Last.Should().BeNull();
+
+        responseDocument.Meta.Should().ContainTotal(7);
+    }
+
+    [Fact]
+    public async Task Ignores_pagination_from_query_string()
+    {
+        // Arrange
+        Calendar calendar = _fakers.Calendar.GenerateOne();
+        calendar.Appointments = _fakers.Appointment.GenerateSet(3);
+        calendar.Appointments.ElementAt(0).Reminders = _fakers.Reminder.GenerateList(7);
+
+        await _testContext.RunOnDatabaseAsync(async dbContext =>
+        {
+            dbContext.Calendars.Add(calendar);
+            await dbContext.SaveChangesAsync();
+        });
+
+        string route = $"calendars/{calendar.StringId}/appointments?include=reminders&page[size]=2,reminders:4";
+
+        // Act
+        (HttpResponseMessage httpResponse, Document responseDocument) = await _testContext.ExecuteGetAsync<Document>(route);
+
+        // Assert
+        httpResponse.ShouldHaveStatusCode(HttpStatusCode.OK);
+
+        responseDocument.Data.ManyValue.Should().HaveCount(2);
+        responseDocument.Data.ManyValue.Should().AllSatisfy(resource => resource.Type.Should().Be("appointments"));
+
+        ResourceObject firstAppointment = responseDocument.Data.ManyValue.Single(resource => resource.Id == calendar.Appointments.ElementAt(0).StringId);
+
+        firstAppointment.Relationships.Should().ContainKey("reminders").WhoseValue.With(value =>
+        {
+            value.Should().NotBeNull();
+            value.Data.ManyValue.Should().HaveCount(7);
+        });
+
+        responseDocument.Included.Should().HaveCount(7);
+        responseDocument.Included.Should().AllSatisfy(resource => resource.Type.Should().Be("reminders"));
+
+        responseDocument.Meta.Should().ContainTotal(3);
+    }
+
+    [Fact]
+    public async Task Ignores_pagination_from_resource_definition()
+    {
+        // Arrange
+        var paginationToggle = _testContext.Factory.Services.GetRequiredService<PaginationToggle>();
+        paginationToggle.IsEnabled = true;
+
+        Appointment appointment = _fakers.Appointment.GenerateOne();
+        appointment.Reminders = _fakers.Reminder.GenerateList(7);
+
+        await _testContext.RunOnDatabaseAsync(async dbContext =>
+        {
+            dbContext.Appointments.Add(appointment);
+            await dbContext.SaveChangesAsync();
+        });
+
+        string route = $"appointments/{appointment.StringId}/reminders";
+
+        // Act
+        (HttpResponseMessage httpResponse, Document responseDocument) = await _testContext.ExecuteGetAsync<Document>(route);
+
+        // Assert
+        httpResponse.ShouldHaveStatusCode(HttpStatusCode.OK);
+
+        responseDocument.Data.ManyValue.Should().HaveCount(7);
+        responseDocument.Data.ManyValue.Should().AllSatisfy(resource => resource.Type.Should().Be("reminders"));
+
+        responseDocument.Meta.Should().ContainTotal(7);
+
+        paginationToggle.IsCalled.Should().BeTrue();
+    }
+
+    [UsedImplicitly(ImplicitUseKindFlags.InstantiatedNoFixedConstructorSignature)]
+    private sealed class ReminderDefinition(PaginationToggle paginationToggle, IResourceGraph resourceGraph)
+        : JsonApiResourceDefinition<Reminder, int>(resourceGraph)
+    {
+        private readonly PaginationToggle _paginationToggle = paginationToggle;
+
+        public override PaginationExpression? OnApplyPagination(PaginationExpression? existingPagination)
+        {
+            _paginationToggle.IsCalled = true;
+            return _paginationToggle.IsEnabled ? new PaginationExpression(PageNumber.ValueOne, new PageSize(4)) : existingPagination;
+        }
+    }
+
+    [UsedImplicitly(ImplicitUseKindFlags.InstantiatedNoFixedConstructorSignature)]
+    private sealed class PaginationToggle
+    {
+        public bool IsEnabled { get; set; }
+        public bool IsCalled { get; set; }
+    }
+}
diff --git a/test/JsonApiDotNetCoreTests/IntegrationTests/QueryStrings/QueryStringDbContext.cs b/test/JsonApiDotNetCoreTests/IntegrationTests/QueryStrings/QueryStringDbContext.cs
diff --git a/test/JsonApiDotNetCoreTests/IntegrationTests/QueryStrings/Reminder.cs b/test/JsonApiDotNetCoreTests/IntegrationTests/QueryStrings/Reminder.cs

Original file line number	Diff line number	Diff line change
`@@ -50,6 +50,12 @@ public HasManyCapabilities Capabilities`
`50`	`50`	`set => _capabilities = value;`
`51`	`51`	`}`
`52`	`52`
	`53`	`+ /// <summary>`
	`54`	`+ /// When set to <c>true</c>, disables pagination for this relationship, which overrules global options, resource definitions, and the <c>page</c> query`
	`55`	`+ /// string parameter. Only use this when the number of related resources is known to always be small.`
	`56`	`+ /// </summary>`
	`57`	`+ public bool DisablePagination { get; set; }`
	`58`	`+`
`53`	`59`	`public HasManyAttribute()`
`54`	`60`	`{`
`55`	`61`	`_lazyIsManyToMany = new Lazy<bool>(EvaluateIsManyToMany, LazyThreadSafetyMode.PublicationOnly);`
Original file line number	Diff line number	Diff line change
`@@ -11,4 +11,7 @@ public sealed class HasManyAttribute : RelationshipAttribute`
`11`	`11`	`{`
`12`	`12`	`/// <summary />`
`13`	`13`	`public HasManyCapabilities Capabilities { get; set; }`
	`14`	`+`
	`15`	`+ /// <summary />`
	`16`	`+ public bool DisablePagination { get; set; }`
`14`	`17`	`}`
Original file line number	Diff line number	Diff line change
`@@ -124,7 +124,7 @@ public override QueryExpression VisitIsType(IsTypeExpression expression, TArgume`
`124`	`124`
`125`	`125`	`if (newElements.Count != 0)`
`126`	`126`	`{`
`127`		`- var newExpression = new SortExpression(newElements);`
	`127`	`+ var newExpression = new SortExpression(newElements, expression.IsAutoGenerated);`
`128`	`128`	`return newExpression.Equals(expression) ? expression : newExpression;`
`129`	`129`	`}`
`130`	`130`
Original file line number	Diff line number	Diff line change
`@@ -13,16 +13,27 @@ namespace JsonApiDotNetCore.Queries.Expressions;`
`13`	`13`	`[PublicAPI]`
`14`	`14`	`public class SortExpression : QueryExpression`
`15`	`15`	`{`
	`16`	`+ /// <summary>`
	`17`	`+ /// Indicates whether this expression was generated by JsonApiDotNetCore to ensure a deterministic order.`
	`18`	`+ /// </summary>`
	`19`	`+ internal bool IsAutoGenerated { get; }`
	`20`	`+`
`16`	`21`	`/// <summary>`
`17`	`22`	`/// One or more elements to sort on.`
`18`	`23`	`/// </summary>`
`19`	`24`	`public IImmutableList<SortElementExpression> Elements { get; }`
`20`	`25`
`21`	`26`	`public SortExpression(IImmutableList<SortElementExpression> elements)`
	`27`	`+ : this(elements, false)`
	`28`	`+ {`
	`29`	`+ }`
	`30`	`+`
	`31`	`+ internal SortExpression(IImmutableList<SortElementExpression> elements, bool isAutoGenerated)`
`22`	`32`	`{`
`23`	`33`	`ArgumentGuard.NotNullNorEmpty(elements);`
`24`	`34`
`25`	`35`	`Elements = elements;`
	`36`	`+ IsAutoGenerated = isAutoGenerated;`
`26`	`37`	`}`
`27`	`38`
`28`	`39`	`public override TResult Accept<TArgument, TResult>(QueryExpressionVisitor<TArgument, TResult> visitor, TArgument argument)`
`@@ -37,7 +48,7 @@ public override string ToString()`
`37`	`48`
`38`	`49`	`public override string ToFullString()`
`39`	`50`	`{`
`40`		`- return string.Join(",", Elements.Select(child => child.ToFullString()));`
	`51`	`+ return $"{string.Join(",", Elements.Select(child => child.ToFullString()))}{(IsAutoGenerated ? " (auto-generated)" : "")}";`
`41`	`52`	`}`
`42`	`53`
`43`	`54`	`public override bool Equals(object? obj)`
`@@ -54,12 +65,13 @@ public override bool Equals(object? obj)`
`54`	`65`
`55`	`66`	`var other = (SortExpression)obj;`
`56`	`67`
`57`		`- return Elements.SequenceEqual(other.Elements);`
	`68`	`+ return IsAutoGenerated == other.IsAutoGenerated && Elements.SequenceEqual(other.Elements);`
`58`	`69`	`}`
`59`	`70`
`60`	`71`	`public override int GetHashCode()`
`61`	`72`	`{`
`62`	`73`	`var hashCode = new HashCode();`
	`74`	`+ hashCode.Add(IsAutoGenerated);`
`63`	`75`
`64`	`76`	`foreach (SortElementExpression element in Elements)`
`65`	`77`	`{`
Original file line number	Diff line number	Diff line change
`@@ -17,6 +17,7 @@ public sealed class TreeNode : Identifiable<long>`
`17`	`17`	`[HasOne(PublicName = "orders", Capabilities = HasOneCapabilities.AllowView \| HasOneCapabilities.AllowInclude, Links = LinkTypes.All)]`
`18`	`18`	`public TreeNode? Parent { get; set; }`
`19`	`19`
`20`		`- [HasMany(PublicName = "orders", Capabilities = HasManyCapabilities.AllowView \| HasManyCapabilities.AllowFilter, Links = LinkTypes.All)]`
	`20`	`+ [HasMany(PublicName = "orders", Capabilities = HasManyCapabilities.AllowView \| HasManyCapabilities.AllowFilter, Links = LinkTypes.All,`
	`21`	`+ DisablePagination = true)]`
`21`	`22`	`public ISet<TreeNode> Children { get; set; } = new HashSet<TreeNode>();`
`22`	`23`	`}`