Rename cursorPaginate() to cursor() and add comparison docs (#24)

Shorter, cleaner API for cursor-based pagination. Also replaces the
comparison table with a more readable list format and updates all
docs to reference cursor() instead of cursorPaginate().

Author: brunogaspar

docs/1.basics/3.query-builder.md

@@ -127,7 +127,7 @@ class ProductController
 ->paginate()
 
 // Cursor pagination: ?page[cursor]=eyJpZCI6MTB9&page[size]=20
-->cursorPaginate()
+->cursor()
 
 // No pagination, returns all results
 ->get()

docs/1.index.md

@@ -19,6 +19,22 @@ API Toolkit is a Laravel package that gives you everything you need to build [JS
 - **Testing Utilities** - Chainable assertions purpose-built for JSON:API responses
 - **Middleware** - Force JSON:API content type on all responses
 
+## Why API Toolkit?
+
+Laravel 12.45 introduced `JsonApiResource` for basic JSON:API serialization, covering type/id/attributes structure, relationships, included resources, and sparse fieldsets.
+
+API Toolkit builds on top of that with:
+
+- **Type-safe resources** - Typed model parameters instead of magic `$this->name` via `__get`
+- **Non-Eloquent support** - Works with any object: DTOs, Carbon, stdClass, and more
+- **Filtering** - Exact, partial, date, and scope-based filters via `?filter[status]=active`
+- **Sorting** - `?sort=-created_at` parsed and applied automatically
+- **Pagination** - Offset and cursor-based with meta and links
+- **Query validation** - Strict rejection of unknown parameters
+- **Error responses** - JSON:API errors with source pointers for validation failures
+- **OpenAPI 3.1** - Auto-generated from your routes and resources
+- **Testing** - Chainable assertions for Pest and PHPUnit
+
 ## Requirements
 
 - PHP 8.4+

docs/2.filtering-and-sorting/3.pagination.md

@@ -47,12 +47,12 @@ GET /api/products?page[number]=2&page[size]=20
 
 ## Cursor Pagination
 
-More efficient for large datasets. Use `->cursorPaginate()`.
+More efficient for large datasets. Use `->cursor()`.
 
 ```php
 return QueryBuilder::for(Product::class, $request)
     ->fromResource(ProductResource::class)
-    ->cursorPaginate();
+    ->cursor();
 ```
 
 ### Query Parameters

src/OpenApi/RouteScanner.php

@@ -169,12 +169,12 @@ private function resolveClassName(string $shortName, string $controllerClass): s
     }
 
     /**
-     * Determine if this endpoint returns a collection (uses paginate/cursorPaginate/get on QueryBuilder).
+     * Determine if this endpoint returns a collection (uses paginate/cursor/get on QueryBuilder).
      */
     private function isListEndpoint(string $source): bool
     {
         return str_contains($source, '->paginate(')
-            || str_contains($source, '->cursorPaginate(')
+            || str_contains($source, '->cursor(')
             || str_contains($source, 'QueryBuilder::for(');
     }
 

src/QueryBuilder.php

@@ -117,7 +117,7 @@ public function paginate(): SuccessResponse
         return $this->toSuccessResponse($data);
     }
 
-    public function cursorPaginate(): SuccessResponse
+    public function cursor(): SuccessResponse
     {
         $this->applyAll();
 

tests/Feature/OpenApi/RouteScannerTest.php

@@ -101,7 +101,7 @@
     expect($endpoints)->toBe([]);
 });
 
-it('detects cursorPaginate as list endpoint', function () {
+it('detects cursor as list endpoint', function () {
     Route::get('/api/v1/products', [ScannerStubCursorController::class, '__invoke']);
 
     $scanner = app(RouteScanner::class);

tests/Feature/QueryBuilderTest.php

@@ -169,7 +169,7 @@
     expect($array)->toHaveKey('links');
 });
 
-it('returns a SuccessResponse from cursorPaginate', function () {
+it('returns a SuccessResponse from cursor', function () {
     Product::create([
         'public_id' => 'prod-1',
         'name' => 'Widget',
@@ -182,7 +182,7 @@
 
     $result = QueryBuilder::for(Product::class, $request)
         ->fromResource(ProductResource::class)
-        ->cursorPaginate()
+        ->cursor()
     ;
 
     expect($result)->toBeInstanceOf(SuccessResponse::class);

tests/Fixtures/Controllers/ScannerStubCursorController.php

@@ -17,7 +17,7 @@ public function __invoke(Request $request, Response $response): JsonResponse
     {
         return QueryBuilder::for(Product::class, $request)
             ->fromResource(ProductResource::class)
-            ->cursorPaginate()
+            ->cursor()
             ->respond()
         ;
     }