Add cursor pagination range truncation support

Author: tobyzerner

CHANGELOG.md

@@ -38,6 +38,8 @@ and this project adheres to
   (including `describedby`)
 - Add `Schema\Link` class for defining rich link objects with metadata
 - Add `JsonApiError::id(string $id)` method for setting error IDs
+- Add `Page::$rangeTruncated` parameter for cursor pagination range truncation
+  support
 - Add full support for JSON:API profiles:
     - Parse profile URIs from `Accept` header
     - `Context::profileRequested(string $uri): bool` - check if a profile was

docs/pagination.md

@@ -118,7 +118,11 @@ class PostsResource extends AbstractResource implements
     ): Page {
         // ...
 
-        return new Page($results, $isFirstPage, $isLastPage);
+        return new Page(
+            results: $results,
+            isFirstPage: $isFirstPage,
+            isLastPage: $isLastPage,
+        );
     }
 
     public function itemCursor($model, object $query, Context $context): string
@@ -128,6 +132,24 @@ class PostsResource extends AbstractResource implements
 }
 ```
 
+### Range Pagination
+
+When both `after` and `before` cursors are provided, implementations can support
+range-based pagination. If the results were truncated to fit within the
+specified range, set the `rangeTruncated` parameter:
+
+```php
+return new Page(
+    results: $results,
+    isFirstPage: false,
+    isLastPage: false,
+    rangeTruncated: true,
+);
+```
+
+This will add `{"page": {"rangeTruncated": true}}` to the document's `meta`
+object to inform clients that not all items in the range were returned.
+
 ## Countability
 
 By default, offset pagination won't include a `last` link because there is no

src/Pagination/CursorPagination.php

@@ -70,6 +70,10 @@ public function paginate(object $query, Context $context): array
             ]);
         }
 
+        if ($page->rangeTruncated !== null) {
+            $context->documentMeta['page']['rangeTruncated'] = $page->rangeTruncated;
+        }
+
         return $page->results;
     }
 

src/Pagination/Page.php

@@ -8,6 +8,7 @@ public function __construct(
         public array $results,
         public ?bool $isFirstPage = null,
         public ?bool $isLastPage = null,
+        public ?bool $rangeTruncated = null,
     ) {
     }
 }

tests/specification/CursorPaginationTest.php

@@ -163,4 +163,19 @@ public function test_unknown_cursor_returns_invalid_parameter_error(): void
             $this->assertStringContainsString('after', $error['source']['parameter'] ?? '');
         }
     }
+
+    public function test_range_truncation_meta_is_included_when_results_truncated(): void
+    {
+        $response = $this->api->handle(
+            $this->buildRequest('GET', '/articles')->withQueryParams([
+                'page' => ['before' => '5', 'size' => '2'],
+            ]),
+        );
+
+        $data = json_decode($response->getBody(), true);
+
+        $this->assertArrayHasKey('meta', $data);
+        $this->assertArrayHasKey('page', $data['meta']);
+        $this->assertTrue($data['meta']['page']['rangeTruncated']);
+    }
 }