Add support for cursor pagination

Author: tobyzerner

CHANGELOG.md

@@ -8,17 +8,37 @@ and this project adheres to
 
 ## [Unreleased]
 
+### ⚠️ Breaking Changes
+
+- Change `Resource\Paginatable::paginate()` to accept the resolved offset and
+  limit integers (plus the request context) and return the page of results
+  instead of mutating the query in place
+- New contract for custom `Pagination` implementations:
+    - Return results from the `paginate(object $query, Context $context): Page`
+    - Add `meta` and `links` via the `Context` object
+
+### Added
+
+- Add cursor pagination support via `Endpoint\Index::cursorPaginate()` and the
+  `Resource\CursorPaginatable` contract, following the
+  `ethanresnick/cursor-pagination` profile
+- Introduce `MaxPageSizeExceededException` and
+  `RangePaginationNotSupportedException` with JSON:API profile links for cursor
+  pagination errors
+- Allow exceptions to attach `meta` and `links` members to the error response
+- Add `Context::$meta` and `Context::$links` as `ArrayObject` instances to allow
+  callbacks to add meta information to the response document
+
 ## [1.0.0-beta.5] - 2025-09-27
 
 ### ⚠️ Breaking Changes
 
-- `Tobyz\\JsonApiServer\\Laravel\\Filter\\EloquentFilter` renamed to
-  `ColumnFilter`.
-- Remove the `Has` Laravel filter; use `WhereExists` instead.
+- `Tobyz\JsonApiServer\Laravel\Filter\EloquentFilter` renamed to `ColumnFilter`
+- Remove the `Has` Laravel filter; use `WhereExists` instead
 - Remove the `WhereDoesntHave` Laravel filter; use the operator support on
-  `WhereHas` instead.
+  `WhereHas` instead
 - Remove `Where::asNumber()`; express numeric comparisons with operators such as
-  `filter[score][gt]=...` or `filter[score][lte]=...`.
+  `filter[score][gt]=...` or `filter[score][lte]=...`
 
 ### Added
 

docs/list.md

@@ -288,9 +288,11 @@ The JSON:API specification reserves the `page` query parameter for
 [paginating collections](https://jsonapi.org/format/#fetching-pagination). The
 specification is agnostic about the pagination strategy used by the server.
 
-Currently json-api-server supports an offset pagination strategy, using the
-`page[limit]` and `page[offset]` query parameters. Support for cursor pagination
-is planned.
+json-api-server supports both offset and cursor pagination strategies. Offset
+pagination uses the `page[limit]` and `page[offset]` query parameters, while
+cursor pagination follows the
+[`ethanresnick/cursor-pagination` profile](https://jsonapi.org/profiles/ethanresnick/cursor-pagination/)
+and relies on the `page[size]`, `page[after]`, and `page[before]` parameters.
 
 ### Offset Pagination
 
@@ -306,25 +308,83 @@ is 50. If you would like to use different values, pass them as arguments to the
 `paginate` method:
 
 ```php
-Index::make()->paginate(10, 100);
+Index::make()->paginate(defaultLimit: 10, maxLimit: 100);
 ```
 
 You will also need to implement the `Tobyz\JsonApiServer\Resource\Paginatable`
-interface on your resource and specify how the limit and offset values should be
-applied to your query:
+interface on your resource and return a page of results:
 
 ```php
 use Tobyz\JsonApiServer\Context;
 use Tobyz\JsonApiServer\Pagination\OffsetPagination;
+use Tobyz\JsonApiServer\Pagination\Page;
 use Tobyz\JsonApiServer\Resource\{Listable, Paginatable, AbstractResource};
 
 class PostsResource extends AbstractResource implements Listable, Paginatable
 {
-    // ...
+    public function paginate(
+        object $query,
+        int $offset,
+        int $limit,
+        Context $context,
+    ): Page {
+        return new Page(
+            results: $this->results(
+                $query->offset($offset)->limit($limit + 1),
+                $context,
+            ),
+            isLastPage: count($results) <= $limit,
+        );
+    }
+}
+```
+
+### Cursor Pagination
+
+Cursor pagination is enabled by calling the `cursorPaginate` method on the
+`Index` endpoint:
+
+```php
+Index::make()->cursorPaginate();
+```
+
+By default the page size is 20 with a maximum of 50. You can customise these
+values by passing arguments:
+
+```php
+Index::make()->cursorPaginate(defaultSize: 25, maxSize: 100);
+```
+
+Cursor pagination requires implementing the
+`Tobyz\JsonApiServer\Resource\CursorPaginatable` interface on the resource. The
+`cursorPaginate` method must return page of results, while the `itemCursor`
+method must return a cursor for the given model/query.
+
+```php
+use Tobyz\JsonApiServer\Context;
+use Tobyz\JsonApiServer\Pagination\CursorPagination;
+use Tobyz\JsonApiServer\Pagination\Page;
+use Tobyz\JsonApiServer\Resource\CursorPaginatable;
+
+class PostsResource extends AbstractResource implements
+    Listable,
+    CursorPaginatable
+{
+    public function cursorPaginate(
+        object $query,
+        int $size,
+        ?string $after,
+        ?string $before,
+        Context $context,
+    ): Page {
+        // ...
+
+        return new Page($results, $isFirstPage, $isLastPage);
+    }
 
-    public function paginate(object $query, OffsetPagination $pagination): void
+    public function itemCursor($model, object $query, Context $context): string
     {
-        $query->offset($pagination->offset)->limit($pagination->limit);
+        // ...
     }
 }
 ```

src/Context.php

@@ -2,6 +2,7 @@
 
 namespace Tobyz\JsonApiServer;
 
+use ArrayObject;
 use Psr\Http\Message\ServerRequestInterface;
 use Tobyz\JsonApiServer\Endpoint\Endpoint;
 use Tobyz\JsonApiServer\Resource\Collection;
@@ -19,6 +20,9 @@ class Context
     public mixed $model = null;
     public ?Field $field = null;
     public ?array $include = null;
+    public ArrayObject $documentMeta;
+    public ArrayObject $documentLinks;
+    public WeakMap $resourceMeta;
 
     private ?array $body;
     private ?string $path;
@@ -30,6 +34,11 @@ public function __construct(public JsonApi $api, public ServerRequestInterface $
     {
         $this->fields = new WeakMap();
         $this->sparseFields = new WeakMap();
+
+        $this->documentMeta = new ArrayObject();
+        $this->documentLinks = new ArrayObject();
+
+        $this->resourceMeta = new WeakMap();
     }
 
     /**
@@ -219,4 +228,11 @@ public function withInclude(?array $include): static
         $new->include = $include;
         return $new;
     }
+
+    public function resourceMeta($model, array $meta): static
+    {
+        $this->resourceMeta[$model] = array_merge($this->resourceMeta[$model] ?? [], $meta);
+
+        return $this;
+    }
 }

src/Endpoint/Index.php

@@ -2,7 +2,6 @@
 
 namespace Tobyz\JsonApiServer\Endpoint;
 
-use Closure;
 use Psr\Http\Message\ResponseInterface as Response;
 use RuntimeException;
 use Tobyz\JsonApiServer\Context;
@@ -13,7 +12,9 @@
 use Tobyz\JsonApiServer\Exception\MethodNotAllowedException;
 use Tobyz\JsonApiServer\Exception\Sourceable;
 use Tobyz\JsonApiServer\OpenApi\OpenApiPathsProvider;
+use Tobyz\JsonApiServer\Pagination\CursorPagination;
 use Tobyz\JsonApiServer\Pagination\OffsetPagination;
+use Tobyz\JsonApiServer\Pagination\Pagination;
 use Tobyz\JsonApiServer\Resource\Collection;
 use Tobyz\JsonApiServer\Resource\Countable;
 use Tobyz\JsonApiServer\Resource\Listable;
@@ -34,26 +35,24 @@ class Index implements Endpoint, OpenApiPathsProvider
     use HasDescription;
     use BuildsOpenApiPaths;
 
-    public Closure $paginationResolver;
+    public ?Pagination $pagination = null;
     public ?string $defaultSort = null;
 
-    public function __construct()
+    public static function make(): static
     {
-        $this->paginationResolver = fn() => null;
+        return new static();
     }
 
-    public static function make(): static
+    public function paginate(int $defaultLimit = 20, ?int $maxLimit = 50): static
     {
-        return new static();
+        $this->pagination = new OffsetPagination($defaultLimit, $maxLimit);
+
+        return $this;
     }
 
-    public function paginate(int $defaultLimit = 20, int $maxLimit = 50): static
+    public function cursorPaginate(int $defaultSize = 20, ?int $maxSize = 50): static
     {
-        $this->paginationResolver = fn(Context $context) => new OffsetPagination(
-            $context,
-            $defaultLimit,
-            $maxLimit,
-        );
+        $this->pagination = new CursorPagination($defaultSize, $maxSize);
 
         return $this;
     }
@@ -94,22 +93,19 @@ public function handle(Context $context): ?Response
         $this->applySorts($query, $context);
         $this->applyFilters($query, $context);
 
-        $meta = $this->serializeMeta($context);
-        $links = [];
-
         if (
             $collection instanceof Countable &&
             !is_null($total = $collection->count($query, $context))
         ) {
-            $meta['page']['total'] = $collection->count($query, $context);
+            $context->documentMeta['page']['total'] = $total;
         }
 
-        if ($pagination = ($this->paginationResolver)($context)) {
-            $pagination->apply($query);
+        if ($this->pagination) {
+            $models = $this->pagination->paginate($query, $context);
+        } else {
+            $models = $collection->results($query, $context);
         }
 
-        $models = $collection->results($query, $context);
-
         $serializer = new Serializer($context);
 
         $include = $this->getInclude($context);
@@ -124,11 +120,14 @@ public function handle(Context $context): ?Response
 
         [$data, $included] = $serializer->serialize();
 
-        if ($pagination) {
-            $meta['page'] = array_merge($meta['page'] ?? [], $pagination->meta());
-            $links = array_merge($links, $pagination->links(count($data), $total ?? null));
+        $meta = $context->documentMeta;
+
+        foreach ($this->serializeMeta($context) as $key => $value) {
+            $meta[$key] = $value;
         }
 
+        $links = $context->documentLinks;
+
         return json_api_response(compact('data', 'included', 'meta', 'links'));
     }
 

src/Exception/Concerns/SingleError.php

@@ -7,6 +7,8 @@
 trait SingleError
 {
     protected ?array $source = null;
+    protected ?array $meta = null;
+    protected ?array $links = null;
 
     public function setSource(?array $source): static
     {
@@ -24,6 +26,20 @@ public function prependSource(array $source): static
         return $this;
     }
 
+    public function setMeta(?array $meta): static
+    {
+        $this->meta = $meta;
+
+        return $this;
+    }
+
+    public function setLinks(?array $links): static
+    {
+        $this->links = $links;
+
+        return $this;
+    }
+
     public function getJsonApiErrors(): array
     {
         $members = [];
@@ -36,6 +52,14 @@ public function getJsonApiErrors(): array
             $members['source'] = $this->source;
         }
 
+        if ($this->meta) {
+            $members['meta'] = $this->meta;
+        }
+
+        if ($this->links) {
+            $members['links'] = $this->links;
+        }
+
         return [
             [
                 'status' => $this->getJsonApiStatus(),

src/Laravel/EloquentCollection.php

@@ -4,7 +4,7 @@
 
 use RuntimeException;
 use Tobyz\JsonApiServer\Context;
-use Tobyz\JsonApiServer\Pagination\OffsetPagination;
+use Tobyz\JsonApiServer\Pagination\Page;
 use Tobyz\JsonApiServer\Resource\Collection;
 use Tobyz\JsonApiServer\Resource\Countable;
 use Tobyz\JsonApiServer\Resource\Listable;
@@ -95,9 +95,11 @@ public function sorts(): array
         return [];
     }
 
-    public function paginate(object $query, OffsetPagination $pagination): void
+    public function paginate(object $query, int $offset, int $limit, Context $context): Page
     {
-        $query->take($pagination->limit)->skip($pagination->offset);
+        $results = $this->results($query->take($limit + 1)->skip($offset), $context);
+
+        return new Page(array_slice($results, 0, $limit), isLastPage: count($results) <= $limit);
     }
 
     public function count(object $query, Context $context): ?int