SeekKit.EntityFramework 1.0.0

<p align="center"> <img src="icon.png" alt="SeekKit logo" width="110" /> </p>

<h1 align="center">SeekKit.EntityFramework</h1>

<p align="center"> High-performance cursor (keyset) pagination for Entity Framework Core.<br/> Constant-time page navigation on any table size — SQL Server, PostgreSQL, MySQL, Oracle, and SQLite. </p>

<p align="center"> <a href="https://github.com/lttruc1402/SeekKit.EntityFramework/actions/workflows/ci.yml"><img src="https://github.com/lttruc1402/SeekKit.EntityFramework/actions/workflows/ci.yml/badge.svg" alt="CI" /></a> <a href="https://www.nuget.org/packages/SeekKit.EntityFramework"><img src="https://img.shields.io/nuget/v/SeekKit.EntityFramework.svg" alt="NuGet" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a> </p>

What is SeekKit?

SeekKit replaces slow Skip/Take (offset) pagination with keyset pagination (also called cursor or seek pagination). Instead of asking the database to count and discard rows, it remembers where the last page ended and continues from that exact position:

-- Offset: scans and throws away 100,000 rows to get page 10,001
SELECT * FROM Products ORDER BY Id OFFSET 100000 ROWS FETCH NEXT 10 ROWS ONLY;

-- Keyset (SeekKit): jumps straight to the position via the index
SELECT TOP 10 * FROM Products WHERE Id > @lastSeenId ORDER BY Id;

The client only sees an opaque token — no leaking of internal keys, no fragile page numbers:

GET /api/products                        → first page + nextToken
GET /api/products?token=eyJ0eXBlIjo...   → next page

Why cursor pagination?

Use SeekKit for infinite scroll, activity feeds, data exports, sync APIs, admin tables — anywhere users walk through data page by page.

Features

• ⚡ Constant-time paging — no OFFSET, purely index-driven seeks
• 🔀 Bidirectional — navigate forward and backward with NextToken / PreviousToken
• 🗄️ Database-tuned strategies — tuple comparison, UNION ALL, or OR-predicates, chosen per engine
• 📇 Multi-column sorting — mixed ascending/descending directions supported
• 🔐 Opaque tokens — clients never see your key values
• 🧩 Pure LINQ — no raw SQL; EF Core translates everything to provider-native queries
• 🛠️ Extensible — custom type converters, custom serializers, custom filter strategies
• ✅ Targets .NET 8, 9, 10 (EF Core 8/9/10) and .NET Standard 2.1 (EF Core 5)

Installation

dotnet add package SeekKit.EntityFramework

You also need the EF Core provider for your database (e.g. Microsoft.EntityFrameworkCore.SqlServer).

Quick start

1. Register the service

// Program.cs
using SeekKit.EntityFramework;
using SeekKit.EntityFramework.Core;

builder.Services.AddSeekKit(options =>
{
    // Pick the strategy matching your database:
    // ForSqlServer() | ForPostgreSql() | ForMySql() | ForOracle() | ForSqlite()
    options.Strategy        = DatabaseStrategy.ForSqlServer();
    options.DefaultPageSize = 20;
    options.MaxPageSize     = 100;
});

2. Paginate a query

Inject ISeekService and paginate any IQueryable<T>:

public class ProductService(ISeekService seek, AppDbContext db)
{
    public async Task<SeekResult<Product>> GetPageAsync(SeekRequest request)
    {
        return await seek.SeekAsync(
            db.Products.Where(p => p.IsActive),   // any filtered query
            request,
            b => b.OrderByDescending(p => p.CreatedAt)
                  .OrderBy(p => p.Id));           // unique column LAST — required
    }
}

Rule: the last OrderBy column must be unique (typically the primary key). This guarantees the cursor always points to an exact row, so pages never skip or duplicate items.

3. Expose it from a controller

[HttpGet]
public Task<SeekResult<Product>> Get([FromQuery] string? token, [FromQuery] int? pageSize)
    => _service.GetPageAsync(new SeekRequest { Token = token, PageSize = pageSize });

4. Response shape

{
  "items": [ /* 20 products */ ],
  "nextToken": "eyJ0eXBlIjoiTmV4dCIsInZhbHVlcy...",
  "previousToken": null,
  "hasNext": true,
  "hasPrevious": false,
  "count": 20,
  "pageMetadata": { "pageSize": 20, "requestedAt": "2026-07-06T10:00:00Z" }
}

The client passes nextToken back as token to get the next page — that's the whole protocol.

Usage guide

Fluent builder

For more control, build the query step by step with CreateBuilder:

SeekResult<Product> result = await seek
    .CreateBuilder(db.Products)
    .WithRequest(request)
    .OrderByDescending(p => p.CreatedAt)
    .OrderBy(p => p.Id)
    .ToSeekResultAsync(cancellationToken);

Multi-column sort (mixed directions)

Column order determines sort priority. Mixed directions are fully supported:

b => b.OrderBy(p => p.Status)              // 1st: status ascending
      .OrderByDescending(p => p.Priority)  // 2nd: priority descending
      .OrderBy(p => p.Id)                  // 3rd: unique tie-breaker

Map entities to DTOs

Map projects items while preserving all tokens and metadata:

SeekResult<Product> page = await seek.SeekAsync(db.Products, request,
    b => b.OrderBy(p => p.Id));

SeekResult<ProductDto> dto = page.Map(p => new ProductDto
{
    Id    = p.Id,
    Name  = p.Name,
    Price = p.Price
});

Bidirectional navigation

Every page carries tokens in both directions:

Page 1            Page 2            Page 3
[items] ──next──▶ [items] ──next──▶ [items]
        ◀──prev──         ◀──prev──

// Forward
var page2 = await GetPageAsync(new SeekRequest { Token = page1.NextToken });

// Backward
var page1Again = await GetPageAsync(new SeekRequest { Token = page2.PreviousToken });

• First page: PreviousToken == null, HasPrevious == false
• Last page: NextToken == null, HasNext == false

Override options per request

Global options stay untouched; the override applies to this call only:

await seek.SeekAsync(
    query, request,
    b => b.OrderBy(p => p.Id),
    options => options.Strategy = DatabaseStrategy.ForPostgreSql(PostgreSqlStrategy.Tuple));

Force a specific query strategy

The builder can pin a strategy regardless of configuration:

await seek.CreateBuilder(db.Products)
    .WithRequest(request)
    .OrderBy(p => p.Id)
    .WithUnionAll()          // or .WithOrPredicate() / .WithTupleComparison()
    .ToSeekResultAsync();

Attach extra data to the response

var result = await seek.SeekAsync(db.Products, request, b => b.OrderBy(p => p.Id));
result.WithValue("totalActive", await db.Products.CountAsync(p => p.IsActive));
// serialized as an extra top-level JSON property

Custom type converter

Keyset values are serialized to strings inside the token. Built-in converters cover all primitives, Guid, DateTime, DateTimeOffset, DateOnly, TimeOnly, TimeSpan, and their nullable variants. For custom value types, register a converter:

builder.Services.AddSeekKit(
    options => options.Strategy = DatabaseStrategy.ForPostgreSql(),
    config  => config.AddConverter<Money>(
        toString:   m => m.ToInvariantString(),
        fromString: s => Money.Parse(s)));

Or implement TypeConverter<T> and pass an instance to config.AddConverter(...).

Signed tokens (tamper-proof)

By default tokens are opaque but not signed — a client could craft one by hand. Enable HMAC-SHA256 signing to reject tampered or forged tokens (they fall back to the first page):

builder.Services.AddSeekKit(
    options => options.Strategy = DatabaseStrategy.ForSqlServer(),
    config  => config.UseHmacSigning(builder.Configuration["SeekKit:TokenKey"]!));

The key must be at least 16 bytes (use a 32-byte random secret) and must be the same across all instances serving the same clients. Keep it in configuration or a secret store, not in source code.

Custom token serializer

Replace the default JSON+Base64 token format (e.g. to add encryption):

builder.Services.AddSeekKit(
    options => options.Strategy = DatabaseStrategy.ForSqlServer(),
    config  => config.UseSeekSerializer<MyEncryptedSerializer>());  // implements ISeekSerializer

Custom filter strategy

For full control over how the seek predicate is built, implement ISeekFilterStrategy and pin it on the builder:

await seek.CreateBuilder(db.Products)
    .WithRequest(request)
    .OrderBy(p => p.Id)
    .WithStrategy(new MyFilterStrategy())
    .ToSeekResultAsync();

Query strategies

SeekKit builds pure LINQ; your EF Core provider translates it to native SQL. Each engine gets a tuned default, configurable via DatabaseStrategy.ForXxx(strategy, fallback).

PostgreSQL — DatabaseStrategy.ForPostgreSql(...)

SQL Server — DatabaseStrategy.ForSqlServer(...)

MySQL / Oracle / SQLite

_{*Indicative timings measured on a mid-size table with a proper composite index; your numbers will vary.}

Fallback

When the primary strategy cannot run (e.g. Tuple with mixed sort directions), the fallback takes over:

options.Strategy = DatabaseStrategy.ForPostgreSql(
    strategy: PostgreSqlStrategy.Tuple,
    fallback: FallbackStrategy.UnionAll);   // OrLogic (default) | UnionAll | None (throw)

API reference

AddSeekKit(configureOptions, configure?)

Registers ISeekService and friends as singletons.

SeekKitOptions

SeekRequest

SeekResult<T>

ISeekBuilder<T>

Requirements

• An EF Core provider for your database:

Example project

A runnable end-to-end demo — .NET 10 minimal API, SQL Server 2022 via Docker Compose, and a bulk seed script for benchmarking seek vs offset on billions of rows — lives in examples/SeekKit.Example.Api.

cd examples/SeekKit.Example.Api
docker compose up -d sqlserver        # start SQL Server
# seed data (see examples README for row-count options), then:
docker compose up -d --build api      # http://localhost:8080/products

Contributing

Issues and pull requests are welcome! Run the test suite before submitting:

dotnet test SeekKit.EntityFramework.slnx

License

This project is licensed under the MIT License.