Add cursor-based pagination with composite Page Token implementation and unified async API

README.md

@@ -9,7 +9,8 @@
 - **Dynamic Query Building**: Generate queries dynamically using expression trees.
 - **Filtering**: Apply flexible filtering logic to refine query results.
 - **Field Projection**: Return only the specified fields to optimize API responses.
-- **Pagination and Sorting**: Built-in support for pagination and sorting.
+- **Pagination and Sorting**: Built-in support for both offset-based and cursor-based pagination, plus sorting.
+- **Cursor-Based Pagination**: Efficient pagination using opaque page tokens for large datasets.
 - **ASP.NET Core Integration**: Middleware support for easy integration into ASP.NET Core projects.
 
 ## Benchmark
@@ -192,6 +193,126 @@ GET /Users?filter[ids]=1&filter[ids]=3&fields=Id,Name&sort=-Id&page=1&pageSize=2
 }
 ```
 
+## Cursor-Based Pagination
+
+AutoQuery also supports cursor-based pagination, which is more efficient for large datasets and provides consistent results even when data is being modified. Unlike offset-based pagination, cursor-based pagination uses opaque page tokens to track position.
+
+### Benefits of Cursor-Based Pagination
+
+- **Consistent Results**: No duplicate or skipped items when data changes between requests
+- **Better Performance**: More efficient for large datasets as it doesn't require counting or skipping rows
+- **Scalability**: Works well with real-time data and high-volume scenarios
+- **Flexible Sorting**: Supports sorting by any field using composite cursors
+
+### How It Works
+
+Cursor-based pagination uses **composite cursors** that encode all sort field values along with the cursor key. This allows accurate pagination regardless of which fields you sort by:
+
+- When sorting by the cursor key (e.g., `sort=id`): The cursor encodes just the ID
+- When sorting by other fields (e.g., `sort=name`): The cursor encodes both the name and ID values
+- Multi-field sorts (e.g., `sort=name,-dateOfBirth,id`): All field values are encoded
+
+The cursor key is automatically added as a tie-breaker if not already in the sort expression, ensuring deterministic ordering.
+
+### Using Cursor-Based Pagination
+
+1. Define a query options class implementing `IQueryCursorOptions`:
+    ```csharp
+    public class UserCursorQueryOptions : IQueryCursorOptions
+    {
+        [FromQuery(Name = "filter[name]")]
+        public string? FilterName { get; set; }
+        [FromQuery(Name = "fields")]
+        public string? Fields { get; set; }
+        [FromQuery(Name = "sort")]
+        public string? Sort { get; set; }
+        [FromQuery(Name = "pageToken")]
+        public string? PageToken { get; set; }
+        [FromQuery(Name = "pageSize")]
+        public int? PageSize { get; set; }
+    }
+    ```
+
+2. Configure the cursor key in your filter configuration:
+    ```csharp
+    public class UserCursorQueryConfiguration : IFilterQueryConfiguration<UserCursorQueryOptions, User>
+    {
+        public void Configure(FilterQueryBuilder<UserCursorQueryOptions, User> builder)
+        {
+            // Configure cursor key for pagination
+            builder.HasCursorKey(d => d.Id);
+
+            // Configure filter properties
+            builder.Property(q => q.FilterName, d => d.Name)
+                .HasEqual();
+        }
+    }
+    ```
+
+3. Create a controller endpoint using cursor pagination:
+    ```csharp
+    [HttpGet("cursor")]
+    [EnableFieldProjection]
+    public IActionResult GetWithCursor(UserCursorQueryOptions queryOptions)
+    {
+        var result = users.AsQueryable()
+                          .ApplyQueryCursorPaged(_queryProcessor, queryOptions);
+        return Ok(result);
+    }
+    ```
+
+4. Example Request (First Page):
+```http
+GET /Users/cursor?pageSize=2&sort=id
+```
+
+5. Example Response (First Page):
+```json
+{
+    "datas": [
+        {
+            "id": 1,
+            "name": "John Doe",
+            "email": "john.doe@example.com"
+        },
+        {
+            "id": 2,
+            "name": "Jane Smith",
+            "email": "jane.smith@example.com"
+        }
+    ],
+    "nextPageToken": "Mg==",
+    "count": 2
+}
+```
+
+6. Example Request (Next Page):
+```http
+GET /Users/cursor?pageSize=2&sort=id&pageToken=Mg==
+```
+
+7. Example Response (Next Page):
+```json
+{
+    "datas": [
+        {
+            "id": 3,
+            "name": "Alice Johnson",
+            "email": "alice.johnson@example.com"
+        },
+        {
+            "id": 4,
+            "name": "Bob Brown",
+            "email": "bob.brown@example.com"
+        }
+    ],
+    "nextPageToken": "NA==",
+    "count": 2
+}
+```
+
+**Note**: When `nextPageToken` is `null`, there are no more results to fetch.
+
 ## Contribution
 
 Contributions are welcome! Feel free to submit issues or pull requests to improve the project.

sample/AutoQueryApiDemo/Configurations/UserCursorQueryConfiguration.cs

@@ -0,0 +1,19 @@
+using AutoQuery;
+using AutoQuery.Abstractions;
+using AutoQuery.Extensions;
+using AutoQueryApiDemo.Models;
+
+namespace AutoQueryApiDemo.Configurations;
+
+public class UserCursorQueryConfiguration : IFilterQueryConfiguration<UserCursorQueryOptions, User>
+{
+    public void Configure(FilterQueryBuilder<UserCursorQueryOptions, User> builder)
+    {
+        builder.HasCursorKey(d => d.Id);
+
+        builder.Property(q => q.FilterIds, d => d.Id)
+            .HasCollectionContains();
+        builder.Property(q => q.FilterName, d => d.Name)
+            .HasEqual();
+    }
+}

sample/AutoQueryApiDemo/Controllers/UsersController.cs

@@ -34,4 +34,13 @@ public IActionResult Get(UserQueryOptions queryOptions)
                           .ApplyQueryPagedResult(_queryProcessor, queryOptions);
         return Ok(result);
     }
+
+    [HttpGet("cursor")]
+    [EnableFieldProjection]
+    public IActionResult GetWithCursor(UserCursorQueryOptions queryOptions)
+    {
+        var result = users.AsQueryable()
+                          .ApplyQueryCursorPagedResult(_queryProcessor, queryOptions);
+        return Ok(result);
+    }
 }

sample/AutoQueryApiDemo/Models/UserCursorQueryOptions.cs

@@ -0,0 +1,20 @@
+using AutoQuery.Abstractions;
+using Microsoft.AspNetCore.Mvc;
+
+namespace AutoQueryApiDemo.Models;
+
+public class UserCursorQueryOptions : IQueryCursorOptions
+{
+    [FromQuery(Name = "filter[ids]")]
+    public int[]? FilterIds { get; set; }
+    [FromQuery(Name = "filter[name]")]
+    public string? FilterName { get; set; }
+    [FromQuery(Name = "fields")]
+    public string? Fields { get; set; }
+    [FromQuery(Name = "sort")]
+    public string? Sort { get; set; }
+    [FromQuery(Name = "pageToken")]
+    public string? PageToken { get; set; }
+    [FromQuery(Name = "pageSize")]
+    public int? PageSize { get; set; }
+}

src/AutoQuery/Abstractions/IQueryCursorOptions.cs

@@ -0,0 +1,17 @@
+namespace AutoQuery.Abstractions;
+
+/// <summary>
+/// Query parameters for cursor-based pagination.
+/// </summary>
+public interface IQueryCursorOptions : IQueryOptions
+{
+    /// <summary>
+    /// Page token representing the cursor position for pagination.
+    /// </summary>
+    string? PageToken { get; set; }
+
+    /// <summary>
+    /// Number of items to return.
+    /// </summary>
+    int? PageSize { get; set; }
+}

src/AutoQuery/Abstractions/IQueryProcessor.cs

@@ -26,5 +26,12 @@ public interface IQueryProcessor
     /// <returns>The selector expression, or null if no selection conditions exist.</returns>
     Expression<Func<TData, TData>>? BuildSelectorExpression<TData, TQueryOptions>(TQueryOptions queryOptions)
         where TQueryOptions : IQueryOptions;
-}
 
+    /// <summary>
+    /// Gets the cursor key selector for cursor-based pagination.
+    /// </summary>
+    /// <typeparam name="TQueryOptions">The type of the query options.</typeparam>
+    /// <typeparam name="TData">The type of the data.</typeparam>
+    /// <returns>The cursor key selector expression, or null if not configured.</returns>
+    LambdaExpression? GetCursorKeySelector<TQueryOptions, TData>();
+}

src/AutoQuery/CursorPagedResult.cs

@@ -0,0 +1,13 @@
+namespace AutoQuery;
+
+/// <summary>
+/// Represents a cursor-based paginated result.
+/// </summary>
+/// <typeparam name="TData">The type of data contained in the result set.</typeparam>
+/// <param name="Datas">The data collection of the paginated result, represented as <see cref="IQueryable{T}"/> for API consistency with other paged results.</param>
+/// <param name="NextPageToken">The page token for the next page, or null if there are no more results.</param>
+/// <param name="Count">The number of items in the current result set.</param>
+/// <remarks>
+/// Note: The data is materialized during pagination but exposed as IQueryable for consistency with <see cref="PagedResult{TData}"/>.
+/// </remarks>
+public record CursorPagedResult<TData>(IQueryable<TData> Datas, string? NextPageToken, int Count);