Cursor pagnation for resolvespec

README.md

@@ -45,7 +45,7 @@ Documentation Generated by LLMs
 * **Relationship Preloading**: Load related entities with custom column selection and filters
 * **Complex Filtering**: Apply multiple filters with various operators
 * **Sorting**: Multi-column sort support
-* **Pagination**: Built-in limit/offset and cursor-based pagination
+* **Pagination**: Built-in limit/offset and cursor-based pagination (both ResolveSpec and RestHeadSpec)
 * **Computed Columns**: Define virtual columns for complex calculations
 * **Custom Operators**: Add custom SQL conditions when needed
 * **🆕 Recursive CRUD Handler**: Automatically handle nested object graphs with foreign key resolution and per-record operation control via `_request` field
@@ -465,6 +465,82 @@ POST /core/users
 }
 ```
 
+### Cursor Pagination (ResolveSpec)
+
+ResolveSpec now supports cursor-based pagination for efficient traversal of large datasets:
+
+```JSON
+POST /core/posts
+{
+  "operation": "read",
+  "options": {
+    "sort": [
+      {
+        "column": "created_at",
+        "direction": "desc"
+      },
+      {
+        "column": "id",
+        "direction": "asc"
+      }
+    ],
+    "limit": 50,
+    "cursor_forward": "12345"
+  }
+}
+```
+
+**How it works**:
+1. First request returns results + cursor token (last record's ID)
+2. Subsequent requests use `cursor_forward` or `cursor_backward` in options
+3. Cursor maintains consistent ordering even when data changes
+4. Supports complex multi-column sorting
+
+**Benefits over offset pagination**:
+- Consistent results when data changes between requests
+- Better performance for large offsets
+- Prevents "skipped" or duplicate records
+- Works with complex sort expressions
+
+**Example request sequence**:
+
+```JSON
+// First request - no cursor
+POST /core/posts
+{
+  "operation": "read",
+  "options": {
+    "sort": [{"column": "created_at", "direction": "desc"}],
+    "limit": 50
+  }
+}
+
+// Response includes data + last record ID
+// Use the last record's ID as cursor_forward for next page
+
+// Second request - with cursor
+POST /core/posts
+{
+  "operation": "read",
+  "options": {
+    "sort": [{"column": "created_at", "direction": "desc"}],
+    "limit": 50,
+    "cursor_forward": "12345"  // ID of last record from previous page
+  }
+}
+
+// For backward pagination
+POST /core/posts
+{
+  "operation": "read",
+  "options": {
+    "sort": [{"column": "created_at", "direction": "desc"}],
+    "limit": 50,
+    "cursor_backward": "12300"  // ID of first record from current page
+  }
+}
+```
+
 ### Recursive CRUD Operations (🆕)
 
 ResolveSpec now supports automatic handling of nested object graphs with intelligent foreign key resolution. This allows you to create, update, or delete entire object hierarchies in a single request.
@@ -1059,6 +1135,14 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ### v2.1
 
+**Cursor Pagination for ResolveSpec (🆕 Dec 9, 2025)**:
+
+* **Cursor-Based Pagination**: Efficient cursor pagination now available in ResolveSpec (body-based API)
+* **Consistent with RestHeadSpec**: Both APIs now support cursor pagination for feature parity
+* **Multi-Column Sort Support**: Works seamlessly with complex sorting requirements
+* **Better Performance**: Improved performance for large datasets compared to offset pagination
+* **SQL Safety**: Proper SQL sanitization for cursor values
+
 **Recursive CRUD Handler (🆕 Nov 11, 2025)**:
 
 * **Nested Object Graphs**: Automatically handle complex object hierarchies with parent-child relationships