Changes PaginationExpression.PageSize to be non-nullable. It doesn't make sense to expose a page number without a size.

Note this subtly breaks IResourceDefinition.OnApplyPagination, whose return value used to distinguish between "no pagination" and "give me the default page size from options". The latter is odd, because option defaults have already been applied when entering this method.

Author: bkoelman

Diff for: docs/usage/options.md

@@ -22,7 +22,7 @@ options.AllowClientGeneratedIds = true;
 
 ## Pagination
 
-The default page size used for all resources can be overridden in options (10 by default). To disable paging, set it to `null`.
+The default page size used for all resources can be overridden in options (10 by default). To disable pagination, set it to `null`.
 The maximum page size and number allowed from client requests can be set too (unconstrained by default).
 
 You can also include the total number of resources in each response.

Diff for: src/JsonApiDotNetCore.Annotations/Resources/Annotations/LinkTypes.shared.cs

@@ -5,8 +5,8 @@ public enum LinkTypes
 {
     Self = 1 << 0,
     Related = 1 << 1,
-    Paging = 1 << 2,
+    Pagination = 1 << 2,
     NotConfigured = 1 << 3,
     None = 1 << 4,
-    All = Self | Related | Paging
+    All = Self | Related | Pagination
 }

Diff for: src/JsonApiDotNetCore/Configuration/IJsonApiOptions.cs

@@ -99,7 +99,7 @@ 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 paging 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.
     /// </summary>
     PageSize? DefaultPageSize { get; }
 

Diff for: src/JsonApiDotNetCore/Queries/Expressions/PaginationExpression.cs

@@ -10,11 +10,12 @@ namespace JsonApiDotNetCore.Queries.Expressions;
 public class PaginationExpression : QueryExpression
 {
     public PageNumber PageNumber { get; }
-    public PageSize? PageSize { get; }
+    public PageSize PageSize { get; }
 
-    public PaginationExpression(PageNumber pageNumber, PageSize? pageSize)
+    public PaginationExpression(PageNumber pageNumber, PageSize pageSize)
     {
         ArgumentGuard.NotNull(pageNumber);
+        ArgumentGuard.NotNull(pageSize);
 
         PageNumber = pageNumber;
         PageSize = pageSize;
@@ -27,7 +28,7 @@ public override TResult Accept<TArgument, TResult>(QueryExpressionVisitor<TArgum
 
     public override string ToString()
     {
-        return PageSize != null ? $"Page number: {PageNumber}, size: {PageSize}" : "(none)";
+        return $"Page number: {PageNumber}, size: {PageSize}";
     }
 
     public override string ToFullString()
@@ -49,7 +50,7 @@ public override bool Equals(object? obj)
 
         var other = (PaginationExpression)obj;
 
-        return PageNumber.Equals(other.PageNumber) && Equals(PageSize, other.PageSize);
+        return PageNumber.Equals(other.PageNumber) && PageSize.Equals(other.PageSize);
     }
 
     public override int GetHashCode()

Diff for: src/JsonApiDotNetCore/Queries/IPaginationContext.cs

@@ -3,18 +3,19 @@
 namespace JsonApiDotNetCore.Queries;
 
 /// <summary>
-/// Tracks values used for pagination, which is a combined effort from options, query string parsing and fetching the total number of rows.
+/// Tracks values used for pagination, which is a combined effort from options, query string parsing, resource definition callbacks and fetching the
+/// total number of rows.
 /// </summary>
 public interface IPaginationContext
 {
     /// <summary>
-    /// The value 1, unless specified from query string. Never null. Cannot be higher than options.MaximumPageNumber.
+    /// The value 1, unless overridden from query string or resource definition. Should not be higher than <see cref="IJsonApiOptions.MaximumPageNumber" />.
     /// </summary>
     PageNumber PageNumber { get; set; }
 
     /// <summary>
-    /// The default page size from options, unless specified in query string. Can be <c>null</c>, which means no paging. Cannot be higher than
-    /// options.MaximumPageSize.
+    /// The default page size from options, unless overridden from query string or resource definition. Should not be higher than
+    /// <see cref="IJsonApiOptions.MaximumPageSize" />. Can be <c>null</c>, which means pagination is disabled.
     /// </summary>
     PageSize? PageSize { get; set; }
 
@@ -25,12 +26,12 @@ public interface IPaginationContext
     bool IsPageFull { get; set; }
 
     /// <summary>
-    /// The total number of resources. <c>null</c> when <see cref="IJsonApiOptions.IncludeTotalResourceCount" /> is set to <c>false</c>.
+    /// The total number of resources, or <c>null</c> when <see cref="IJsonApiOptions.IncludeTotalResourceCount" /> is set to <c>false</c>.
     /// </summary>
     int? TotalResourceCount { get; set; }
 
     /// <summary>
-    /// The total number of resource pages. <c>null</c> when <see cref="IJsonApiOptions.IncludeTotalResourceCount" /> is set to <c>false</c> or
+    /// The total number of resource pages, or <c>null</c> when <see cref="IJsonApiOptions.IncludeTotalResourceCount" /> is set to <c>false</c> or
     /// <see cref="PageSize" /> is <c>null</c>.
     /// </summary>
     int? TotalPageCount { get; }

Diff for: src/JsonApiDotNetCore/Queries/Internal/QueryLayerComposer.cs

@@ -156,9 +156,13 @@ private QueryLayer ComposeTopLayer(IEnumerable<ExpressionInScope> constraints, R
         // @formatter:keep_existing_linebreaks restore
         // @formatter:wrap_chained_method_calls restore
 
-        PaginationExpression topPagination = GetPagination(expressionsInTopScope, resourceType);
-        _paginationContext.PageSize = topPagination.PageSize;
-        _paginationContext.PageNumber = topPagination.PageNumber;
+        PaginationExpression? topPagination = GetPagination(expressionsInTopScope, resourceType);
+
+        if (topPagination != null)
+        {
+            _paginationContext.PageSize = topPagination.PageSize;
+            _paginationContext.PageNumber = topPagination.PageNumber;
+        }
 
         return new QueryLayer(resourceType)
         {
@@ -509,18 +513,13 @@ protected virtual SortExpression GetSort(IReadOnlyCollection<QueryExpression> ex
         return sort;
     }
 
-    protected virtual PaginationExpression GetPagination(IReadOnlyCollection<QueryExpression> expressionsInScope, ResourceType resourceType)
+    protected virtual PaginationExpression? GetPagination(IReadOnlyCollection<QueryExpression> expressionsInScope, ResourceType resourceType)
     {
         ArgumentGuard.NotNull(expressionsInScope);
         ArgumentGuard.NotNull(resourceType);
 
         PaginationExpression? pagination = expressionsInScope.OfType<PaginationExpression>().FirstOrDefault();
-
-        pagination = _resourceDefinitionAccessor.OnApplyPagination(resourceType, pagination);
-
-        pagination ??= new PaginationExpression(PageNumber.ValueOne, _options.DefaultPageSize);
-
-        return pagination;
+        return _resourceDefinitionAccessor.OnApplyPagination(resourceType, pagination);
     }
 
 #pragma warning disable AV1130 // Return type in method signature should be an interface to an unchangeable collection

Diff for: src/JsonApiDotNetCore/Queries/Internal/QueryableBuilding/SkipTakeClauseBuilder.cs

@@ -35,18 +35,15 @@ public override Expression VisitPagination(PaginationExpression expression, obje
     {
         Expression skipTakeExpression = _source;
 
-        if (expression.PageSize != null)
-        {
-            int skipValue = (expression.PageNumber.OneBasedValue - 1) * expression.PageSize.Value;
-
-            if (skipValue > 0)
-            {
-                skipTakeExpression = ExtensionMethodCall(skipTakeExpression, "Skip", skipValue);
-            }
+        int skipValue = (expression.PageNumber.OneBasedValue - 1) * expression.PageSize.Value;
 
-            skipTakeExpression = ExtensionMethodCall(skipTakeExpression, "Take", expression.PageSize.Value);
+        if (skipValue > 0)
+        {
+            skipTakeExpression = ExtensionMethodCall(skipTakeExpression, "Skip", skipValue);
         }
 
+        skipTakeExpression = ExtensionMethodCall(skipTakeExpression, "Take", expression.PageSize.Value);
+
         return skipTakeExpression;
     }
 

Diff for: src/JsonApiDotNetCore/QueryStrings/Internal/PaginationQueryStringParameterReader.cs

@@ -73,7 +73,7 @@ public virtual void Read(string parameterName, StringValues parameterValue)
         }
         catch (QueryParseException exception)
         {
-            throw new InvalidQueryStringParameterException(parameterName, "The specified paging is invalid.", exception.Message, exception);
+            throw new InvalidQueryStringParameterException(parameterName, "The specified pagination is invalid.", exception.Message, exception);
         }
     }
 
@@ -103,7 +103,6 @@ protected virtual void ValidatePageSize(PaginationQueryStringValueExpression con
         }
     }
 
-    [AssertionMethod]
     protected virtual void ValidatePageNumber(PaginationQueryStringValueExpression constraint)
     {
         if (_options.MaximumPageNumber != null && constraint.Elements.Any(element => element.Value > _options.MaximumPageNumber.OneBasedValue))
@@ -154,11 +153,7 @@ public MutablePaginationEntry ResolveEntryInScope(ResourceFieldChainExpression?
                 return _globalScope;
             }
 
-            if (!_nestedScopes.ContainsKey(scope))
-            {
-                _nestedScopes.Add(scope, new MutablePaginationEntry());
-            }
-
+            _nestedScopes.TryAdd(scope, new MutablePaginationEntry());
             return _nestedScopes[scope];
         }
 
@@ -189,11 +184,17 @@ public IReadOnlyCollection<ExpressionInScope> GetExpressionsInScope()
 
         private IEnumerable<ExpressionInScope> EnumerateExpressionsInScope()
         {
-            yield return new ExpressionInScope(null, new PaginationExpression(_globalScope.PageNumber!, _globalScope.PageSize));
+            if (_globalScope.PageSize != null)
+            {
+                yield return new ExpressionInScope(null, new PaginationExpression(_globalScope.PageNumber!, _globalScope.PageSize));
+            }
 
             foreach ((ResourceFieldChainExpression scope, MutablePaginationEntry entry) in _nestedScopes)
             {
-                yield return new ExpressionInScope(scope, new PaginationExpression(entry.PageNumber!, entry.PageSize));
+                if (entry.PageSize != null)
+                {
+                    yield return new ExpressionInScope(scope, new PaginationExpression(entry.PageNumber!, entry.PageSize));
+                }
             }
         }
     }

Diff for: src/JsonApiDotNetCore/Resources/IResourceDefinition.cs

@@ -1,5 +1,6 @@
 using System.Collections.Immutable;
 using JetBrains.Annotations;
+using JsonApiDotNetCore.Configuration;
 using JsonApiDotNetCore.Middleware;
 using JsonApiDotNetCore.Queries.Expressions;
 using JsonApiDotNetCore.Resources.Annotations;
@@ -57,11 +58,10 @@ public interface IResourceDefinition<TResource, in TId>
     /// Enables to extend, replace or remove pagination that is being applied on a set of this resource type.
     /// </summary>
     /// <param name="existingPagination">
-    /// An optional existing pagination, coming from query string. Can be <c>null</c>.
+    /// An optional existing pagination, coming from query string and <see cref="IJsonApiOptions" /> defaults. Can be <c>null</c>.
     /// </param>
     /// <returns>
-    /// The changed pagination, or <c>null</c> to use the first page with default size from options. To disable paging, set
-    /// <see cref="PaginationExpression.PageSize" /> to <c>null</c>.
+    /// The changed pagination, or <c>null</c> to disable pagination.
     /// </returns>
     PaginationExpression? OnApplyPagination(PaginationExpression? existingPagination);
 

Diff for: src/JsonApiDotNetCore/Serialization/Response/LinkBuilder.cs

@@ -85,7 +85,7 @@ private static string NoAsyncSuffix(string actionName)
             links.Related = GetLinkForRelationshipRelated(_request.PrimaryId!, _request.Relationship);
         }
 
-        if (_request.IsCollection && _paginationContext.PageSize != null && ShouldIncludeTopLevelLink(LinkTypes.Paging, resourceType))
+        if (_request.IsCollection && _paginationContext.PageSize != null && ShouldIncludeTopLevelLink(LinkTypes.Pagination, resourceType))
         {
             SetPaginationInTopLevelLinks(resourceType!, links);
         }

Diff for: src/JsonApiDotNetCore/Services/JsonApiResourceService.cs

@@ -76,7 +76,7 @@ public virtual async Task<IReadOnlyCollection<TResource>> GetAsync(CancellationT
         QueryLayer queryLayer = _queryLayerComposer.ComposeFromConstraints(_request.PrimaryResourceType);
         IReadOnlyCollection<TResource> resources = await _repositoryAccessor.GetAsync<TResource>(queryLayer, cancellationToken);
 
-        if (queryLayer.Pagination?.PageSize?.Value == resources.Count)
+        if (queryLayer.Pagination?.PageSize.Value == resources.Count)
         {
             _paginationContext.IsPageFull = true;
         }
@@ -128,7 +128,7 @@ public virtual async Task<TResource> GetAsync(TId id, CancellationToken cancella
 
         object? rightValue = _request.Relationship.GetValue(primaryResource);
 
-        if (rightValue is ICollection rightResources && secondaryLayer.Pagination?.PageSize?.Value == rightResources.Count)
+        if (rightValue is ICollection rightResources && secondaryLayer.Pagination?.PageSize.Value == rightResources.Count)
         {
             _paginationContext.IsPageFull = true;
         }
@@ -169,7 +169,7 @@ public virtual async Task<TResource> GetAsync(TId id, CancellationToken cancella
 
         object? rightValue = _request.Relationship.GetValue(primaryResource);
 
-        if (rightValue is ICollection rightResources && secondaryLayer.Pagination?.PageSize?.Value == rightResources.Count)
+        if (rightValue is ICollection rightResources && secondaryLayer.Pagination?.PageSize.Value == rightResources.Count)
         {
             _paginationContext.IsPageFull = true;
         }

Diff for: test/JsonApiDotNetCoreTests/IntegrationTests/QueryStrings/Pagination/PaginationWithTotalCountTests.cs

@@ -88,7 +88,7 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
 
         ErrorObject error = responseDocument.Errors[0];
         error.StatusCode.Should().Be(HttpStatusCode.BadRequest);
-        error.Title.Should().Be("The specified paging is invalid.");
+        error.Title.Should().Be("The specified pagination is invalid.");
         error.Detail.Should().Be("This query string parameter can only be used on a collection of resources (not on a single resource).");
         error.Source.ShouldNotBeNull();
         error.Source.Parameter.Should().Be("page[number]");
@@ -185,7 +185,7 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
 
         ErrorObject error = responseDocument.Errors[0];
         error.StatusCode.Should().Be(HttpStatusCode.BadRequest);
-        error.Title.Should().Be("The specified paging is invalid.");
+        error.Title.Should().Be("The specified pagination is invalid.");
         error.Detail.Should().Be("This query string parameter can only be used on a collection of resources (not on a single resource).");
         error.Source.ShouldNotBeNull();
         error.Source.Parameter.Should().Be("page[size]");
@@ -463,7 +463,7 @@ public async Task Cannot_paginate_in_unknown_scope()
 
         ErrorObject error = responseDocument.Errors[0];
         error.StatusCode.Should().Be(HttpStatusCode.BadRequest);
-        error.Title.Should().Be("The specified paging is invalid.");
+        error.Title.Should().Be("The specified pagination is invalid.");
         error.Detail.Should().Be($"Relationship '{Unknown.Relationship}' does not exist on resource type 'webAccounts'.");
         error.Source.ShouldNotBeNull();
         error.Source.Parameter.Should().Be("page[number]");
@@ -485,7 +485,7 @@ public async Task Cannot_paginate_in_unknown_nested_scope()
 
         ErrorObject error = responseDocument.Errors[0];
         error.StatusCode.Should().Be(HttpStatusCode.BadRequest);
-        error.Title.Should().Be("The specified paging is invalid.");
+        error.Title.Should().Be("The specified pagination is invalid.");
         error.Detail.Should().Be($"Relationship '{Unknown.Relationship}' in 'posts.{Unknown.Relationship}' does not exist on resource type 'blogPosts'.");
         error.Source.ShouldNotBeNull();
         error.Source.Parameter.Should().Be("page[size]");
@@ -528,7 +528,7 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
     }
 
     [Fact]
-    public async Task Returns_all_resources_when_paging_is_disabled()
+    public async Task Returns_all_resources_when_pagination_is_disabled()
     {
         // Arrange
         var options = (JsonApiOptions)_testContext.Factory.Services.GetRequiredService<IJsonApiOptions>();

Diff for: test/JsonApiDotNetCoreTests/IntegrationTests/QueryStrings/Pagination/RangeValidationTests.cs

@@ -42,7 +42,7 @@ public async Task Cannot_use_negative_page_number()
 
         ErrorObject error = responseDocument.Errors[0];
         error.StatusCode.Should().Be(HttpStatusCode.BadRequest);
-        error.Title.Should().Be("The specified paging is invalid.");
+        error.Title.Should().Be("The specified pagination is invalid.");
         error.Detail.Should().Be("Page number cannot be negative or zero.");
         error.Source.ShouldNotBeNull();
         error.Source.Parameter.Should().Be("page[number]");
@@ -64,7 +64,7 @@ public async Task Cannot_use_zero_page_number()
 
         ErrorObject error = responseDocument.Errors[0];
         error.StatusCode.Should().Be(HttpStatusCode.BadRequest);
-        error.Title.Should().Be("The specified paging is invalid.");
+        error.Title.Should().Be("The specified pagination is invalid.");
         error.Detail.Should().Be("Page number cannot be negative or zero.");
         error.Source.ShouldNotBeNull();
         error.Source.Parameter.Should().Be("page[number]");
@@ -123,7 +123,7 @@ public async Task Cannot_use_negative_page_size()
 
         ErrorObject error = responseDocument.Errors[0];
         error.StatusCode.Should().Be(HttpStatusCode.BadRequest);
-        error.Title.Should().Be("The specified paging is invalid.");
+        error.Title.Should().Be("The specified pagination is invalid.");
         error.Detail.Should().Be("Page size cannot be negative.");
         error.Source.ShouldNotBeNull();
         error.Source.Parameter.Should().Be("page[size]");

Diff for: test/JsonApiDotNetCoreTests/IntegrationTests/QueryStrings/Pagination/RangeValidationWithMaximumTests.cs

@@ -71,7 +71,7 @@ public async Task Cannot_use_page_number_over_maximum()
 
         ErrorObject error = responseDocument.Errors[0];
         error.StatusCode.Should().Be(HttpStatusCode.BadRequest);
-        error.Title.Should().Be("The specified paging is invalid.");
+        error.Title.Should().Be("The specified pagination is invalid.");
         error.Detail.Should().Be($"Page number cannot be higher than {MaximumPageNumber}.");
         error.Source.ShouldNotBeNull();
         error.Source.Parameter.Should().Be("page[number]");
@@ -93,7 +93,7 @@ public async Task Cannot_use_zero_page_size()
 
         ErrorObject error = responseDocument.Errors[0];
         error.StatusCode.Should().Be(HttpStatusCode.BadRequest);
-        error.Title.Should().Be("The specified paging is invalid.");
+        error.Title.Should().Be("The specified pagination is invalid.");
         error.Detail.Should().Be("Page size cannot be unconstrained.");
         error.Source.ShouldNotBeNull();
         error.Source.Parameter.Should().Be("page[size]");
@@ -144,7 +144,7 @@ public async Task Cannot_use_page_size_over_maximum()
 
         ErrorObject error = responseDocument.Errors[0];
         error.StatusCode.Should().Be(HttpStatusCode.BadRequest);
-        error.Title.Should().Be("The specified paging is invalid.");
+        error.Title.Should().Be("The specified pagination is invalid.");
         error.Detail.Should().Be($"Page size cannot be higher than {MaximumPageSize}.");
         error.Source.ShouldNotBeNull();
         error.Source.Parameter.Should().Be("page[size]");

Diff for: test/JsonApiDotNetCoreTests/IntegrationTests/ResourceDefinitions/Reading/StarDefinition.cs

@@ -41,7 +41,7 @@ public override PaginationExpression OnApplyPagination(PaginationExpression? exi
 
         if (existingPagination != null)
         {
-            PageSize pageSize = existingPagination.PageSize?.Value <= maxPageSize.Value ? existingPagination.PageSize : maxPageSize;
+            PageSize pageSize = existingPagination.PageSize.Value <= maxPageSize.Value ? existingPagination.PageSize : maxPageSize;
             return new PaginationExpression(existingPagination.PageNumber, pageSize);
         }