Pagination
Trellis separates pagination into three responsibilities:
- Validate request controls with
PageRequest.TryCreate, orHttpRequest.TryCreatePageRequestat an ASP.NET Core boundary. - Continue the query using typed state: an EF
SeekDefinition, an application-owned algorithm, or a provider's own continuation token. - Assemble and project the result with
PageBuilder,Page<T>, andPage<T>.Map.
Core has no storage or HTTP dependency. Trellis.EntityFrameworkCore supplies
provider-translatable seek pagination. Trellis.Asp maps Result<Page<T>> to
200 OK, a JSON envelope, and an RFC 8288 Link header. Collection pagination
does not use 206 Partial Content, which belongs to byte-range transfer.
Why use a cursor?
Offset pagination can skip or repeat rows when concurrent changes shift their
positions. A seek cursor instead identifies a boundary in a deterministic
ordering, such as (CreatedAt descending, Id ascending). With suitable indexes,
the database can avoid scanning a growing offset.
This is not a universal performance or consistency guarantee. Provider support, indexes, filters, and comparison semantics determine the query plan. Mutable sort values and concurrent writes can still change results between pages. Trellis does not create a snapshot.
Building blocks
| Type | Package | Responsibility |
|---|---|---|
Cursor |
Core | Opaque token; clients echo Token unchanged. |
PageSize |
Core | Validated Requested, Applied, and WasCapped. |
PageRequest |
Core | Validates nullable cursor text and an already-parsed limit; Decode(codec) produces Result<Maybe<TState>>. |
HttpRequestPaginationExtensions |
ASP | Reads raw cursor/limit query values, preserves missing versus empty, rejects repeats, parses the limit invariantly, and produces a query-located Result<PageRequest>. |
ICursorCodec<TState> / CursorCodec |
Core | Typed encoding, parsing, and validation of continuation state. |
PageBuilder |
Core | Pure assembly from an already ordered, sought, over-fetched batch. |
Page<T> |
Core | Immutable item sequence, adjacent cursors, and observable limit metadata; Map preserves that metadata. |
SeekDefinition<T,TState> |
EF Core | Owns ordering, state extraction, and the matching lexicographic seek predicate together. |
ToPageAsync |
EF Core | Decode, seek, over-fetch, and assemble a forward page. |
Cursor, PageSize, PageRequest, and Page<T> are sealed record classes.
Their default value is null, not an empty valid struct. Use Page.Empty<T>(...)
for empty results and null only for an absent cursor.
Validate raw input once
Use the non-throwing factory at an untrusted boundary:
Result<PageRequest> request = PageRequest.TryCreate(
cursor, limit, max: 100, defaultSize: 50,
policy: PageSizeLimitPolicy.Clamp,
cursorFieldName: "cursor", limitFieldName: "limit");
At an ASP.NET Core boundary, parse the raw query collection rather than binding cursor and limit handler parameters:
Result<PageRequest> request = httpRequest.TryCreatePageRequest(
max: 100, defaultSize: 50,
policy: PageSizeLimitPolicy.Clamp);
| Input | Outcome |
|---|---|
Missing cursor (null) |
First page: no continuation boundary. |
| Empty or whitespace-only cursor | Failed result, reason cursor.malformed. Never silently restarts at page one. |
| Missing limit | Uses defaultSize, capped to max if necessary. |
| Zero or negative limit | Failed result, reason page-size.out-of-range. |
Explicit limit above max, Clamp policy |
Keeps the original requested limit; caps the applied limit. |
Explicit limit above max, Reject policy |
Failed result, reason page-size.out-of-range. |
PageRequest defaults field names to "cursor" and "limit". A custom cursor
field name must also be passed to Decode / ToPageAsync; it is not stored in
the request.
TryCreatePageRequest preserves the transport distinction too. MVC string binding can convert a
present-but-empty query value to null, and host integer binding can return 400 before a Trellis
failure is created. The extension reads Request.Query directly: ?cursor= remains present,
each parameter may occur only once, malformed/overflowing limits report format.integer, and
every field failure is located at the configured query parameter. It deliberately adds no
ApiExplorer/OpenAPI parameter metadata, so document cursor and limit separately.
A nonblank opaque cursor can pass request parsing and fail later during Decode / ToPageAsync.
Core cannot attach an HTTP location to that failure. For a query-only pagination endpoint, use
.WithInputOrigin(InputLocation.Query) in a Minimal API or
[InputOrigin(InputLocation.Query)] in MVC so the downstream /cursor violation still projects
as the cursor query parameter.
PageSize.TryCreate(limit, ...) offers the same policy when only a size is
needed (its default field name is "pageSize"). PageSize.FromRequested
is a trusted, throwing convenience, not a lenient query-string parser:
non-positive input throws. Missing input defaults; above-cap input clamps.
Bad server configuration also throws: max must be positive and at most
PageSize.MaxApplied (int.MaxValue - 1), defaultSize must be positive,
and the policy must be defined. That bound makes Applied + 1 safe.
EF Core: keep ordering and seek together
The source must already carry the application's authorization, tenant, and
business filters. This function assumes authorizedOrders is appropriately scoped:
using Microsoft.EntityFrameworkCore;
using Trellis;
using Trellis.EntityFrameworkCore;
static Task<Result<Page<Order>>> ListOrders(
IQueryable<Order> authorizedOrders, string? cursor, int? limit,
CancellationToken ct)
{
var seek = SeekDefinition.Descending<Order, DateTimeOffset>(o => o.CreatedAt)
.ThenAscending(o => o.Id.Value);
return PageRequest.TryCreate(cursor, limit)
.BindAsync(request => authorizedOrders.AsNoTracking()
.ToPageAsync(request, seek, cursorFieldName: "cursor",
cancellationToken: ct));
}
BindAsync prevents database execution when request validation fails. The
helper decodes through seek.Codec, applies the matching order and boundary,
fetches Applied + 1 rows, and emits a next cursor from the last retained row
only when another row exists.
Boundary values are projected alongside the rows in the database query using
the same key expressions as ordering and seeking. The helper does not compile
selectors or recompute their values after materialization. Provider-translated
functions such as EF.Functions.Collate can therefore participate when the
provider translates the complete query; equivalent-looking C# recomputation
is not assumed to match SQL semantics.
For descending time / ascending ID, the predicate is equivalent to:
time < boundaryTime OR (time == boundaryTime AND id > boundaryId)
Use ThenAscending / ThenDescending for additional keys, ending with a
stable unique tie-breaker. Tuple state nests as keys are added: (time, id),
then ((time, id), thirdKey). Null keys are unsupported. Do not add a competing
OrderBy upstream; the definition owns the complete ordering.
The single-key convenience remains:
await authorizedOrders.ToPageAsync(
pageSize, cursor, o => o.Id.Value, cancellationToken: ct);
Here cursor is already a Cursor? and pageSize is validated. This overload
wraps a single ascending definition, so the key must itself be unique.
Provider comparison is part of correctness
Numeric/date-like keys use relational expressions; other comparable keys,
including GUID and string, use CompareTo. Verify provider translation and
agreement between ORDER BY, equality, and the seek comparison. Database
collations and GUID ordering need not match .NET in-memory ordering.
There is no automatic client-side fallback. A value converter alone cannot
guarantee translation of an arbitrary comparison method. Projections through
Trellis value objects (o.Id.Value) require AddTrellisInterceptors() on the
context options. Verify boundary projection as well as ordering and seek
translation when using provider-specific expressions.
Ascending / Descending and their Then counterparts accept an explicit
key codec when the scalar codec is unsuitable. seek.WithCodec(codec) replaces
the complete state codec without changing ordering or extraction; use it for
context binding or a caller-owned protection wrapper.
Typed codecs: opaque, versioned, not signed
ICursorCodec<Guid> ids = CursorCodec.Scalar<Guid>();
ICursorCodec<(DateTimeOffset Primary, Guid Secondary)> events =
CursorCodec.Composite<DateTimeOffset, Guid>();
Cursor token = events.Encode((createdAt, id));
Result<(DateTimeOffset Primary, Guid Secondary)> decoded = events.TryDecode(token);
Scalar codecs require IParsable<T> plus invariant IFormattable support (or
string); unsupported formatting fails at factory creation. Generated scalar
IDs satisfying both interfaces can be used directly. For other value objects,
project their primitive or provide an explicit codec.
Built-in frames are URL-safe base64 of 1:s:... (scalar), 1:c:...
(composite), or 1:x-<schema>:... (explicit codec). Composites length-prefix
the first component token and can nest arbitrary codecs without delimiter
ambiguity. The entire encoded token is limited to 1,024 characters on both
encoding and decoding. Old unversioned tokens are deliberately rejected.
CursorCodec.Create(schema, format, parse) supplies an explicit serializer
and validating parser. CursorCodec.Map(wireCodec, toWire, fromWire) instead
maps a composed wire representation to named validated state. There is no
implicit JSON fallback. Encode validates parsing and state equality, so a lossy
formatter or invalid server boundary throws rather than issuing an unusable
cursor. Floating-point state must be finite; dates use round-trip "O" format
to preserve ticks and kind/offset.
Built-in tokens are not encrypted or signed. Bind tenant/filter/origin/sort/
algorithm context in the application codec when tokens must not be reused
across different queries. A context hash is not authentication; use a
caller-owned ICursorCodec<TState> protection wrapper for anti-tamper needs.
Authorization must still filter every request.
Computed distance or score
Spherical distance over numeric latitude/longitude columns has a translated EF Core path.
Validate the search with GeoBounds, use WithinRadius for the conservative box prefilter
plus exact distance, and reuse the same distance expression as the first seek key:
var bounds = GeoBounds.Create(origin, radiusMeters);
var withinRadius = GeoCoordinateExpressions.WithinRadius<Store>(
store => store.Latitude, store => store.Longitude, bounds);
var distance = GeoCoordinateExpressions.DistanceMetersTo<Store>(
store => store.Latitude, store => store.Longitude, bounds.Center);
var seek = SeekDefinition.Ascending(distance)
.ThenAscending(store => store.Id)
.WithCodec(queryBoundCodec);
Result<Page<Store>> page = await db.Stores
.Where(withinRadius)
.ToPageAsync(request, seek, cancellationToken: cancellationToken);
The database applies the prefilter, exact predicate, ordering, boundary projection, and
seek. The default (distance, id) codec is not sufficient across requests:
queryBoundCodec must bind canonical identity for the origin, radius, every other filter,
sort directions, and an algorithm version. Translation failures propagate; Trellis does
not switch to client evaluation. The helpers use spherical arithmetic over ordinary
numeric columns, not a spatial index. Origins, radii, and box endpoints are parameterized,
so values within the same one-box or two-box structural case reuse one query shape.
Provider trigonometric functions can round differently from the in-memory calculation at
an exact boundary; include an application tolerance in the radius when that distinction matters.
For a computation that cannot be translated, the application still owns the algorithm and its candidate bounds. Use:
- An authorized, appropriately bounded candidate source.
PageRequest.Decode(codec)to validate optional typed continuation state.- A deterministic computed value plus a stable unique tie-breaker.
- The matching boundary predicate before
Take(Applied + 1). PageBuilder.FromOverFetchwith a callback that encodes the last retained boundary.
The computed pagination recipe shows both paths, including finite nonnegative state, canonical query-context binding, translated spherical filtering, and a bounded in-memory fallback with a GUID tie-breaker. The fallback deliberately uses a complete bounded snapshot; it is not a reason to materialize an unbounded database table.
Pure page assembly and provider tokens
PageBuilder has only one overload; the callback returns a Cursor, not a key:
var codec = CursorCodec.Composite<DateTimeOffset, Guid>();
var page = PageBuilder.FromOverFetch(orderedAndSoughtRows, pageSize,
last => codec.Encode((last.CreatedAt, last.Id)));
The caller has already sought and ordered the rows using those same keys. For an applied size of 25, 26 fetched rows means 25 retained rows and a next cursor from row 25; exactly 25, fewer rows, or no rows means no next cursor. The callback runs exactly once if there is more data, otherwise never.
For stores that supply opaque continuation tokens, construct Page<T> directly:
var page = new Page<Order>(
providerItems,
providerNextToken is null ? null : new Cursor(providerNextToken),
providerPreviousToken is null ? null : new Cursor(providerPreviousToken),
pageSize.Requested, pageSize.Applied);
Do not decode provider tokens with CursorCodec or infer completion solely
from item count. Some providers return an empty batch with a continuation.
The page constructor snapshots the item sequence; value equality includes
sequence contents, both cursors, and both limits.
Page<T>.Map preserves both cursors and limits while projecting items:
Result<Page<OrderListItem>> response = result.Map(page => page.Map(order =>
new OrderListItem(order.Id.Value, order.Total.Amount, order.Total.Currency.Value)));
The EF helper and PageBuilder are forward-only (Previous is null).
Descending ordering does not implement previous-page navigation. A direct
Page<T> can carry a provider-supplied previous token when the provider really
supports that operation.
What fails how?
| Failure | Behavior |
|---|---|
| Missing/empty distinction, repeated query values, invalid raw limit | HttpRequest.TryCreatePageRequest returns a query-located Error.InvalidInput; non-HTTP adapters use their own parser and then PageRequest.TryCreate. |
| Bad token version/base64/UTF-8/framing, oversized or invalid state | Built-in codecs return Error.InvalidInput with reason cursor.malformed. |
| Invalid server size configuration, null required arguments | Throws: a configuration/programming error, not invalid client input. |
| Encoding invalid or non-round-tripping server state | Throws ArgumentException. |
| A custom codec/parser returns successful null continuation state | Throws InvalidOperationException, including through CursorCodec.TryDecodeOptional / PageRequest.Decode; never restarts at the first page. |
| Cancellation, query translation, database/connection failures | Propagate; pagination does not relabel infrastructure faults as malformed cursors. |
Expected invalid input maps to HTTP 422 through Trellis ASP mapping; successful
pages map to 200. See the ASP reference
for response-envelope and link-builder overloads. Do not serialize a raw
Result<Page<T>> directly.
Upgrading existing pagination code
- At ASP.NET Core boundaries, replace bound cursor/limit parameters and manual raw-query handling
with
Request.TryCreatePageRequest(). At other boundaries, parse transport text and then callPageRequest.TryCreate; do not treat empty cursors or non-positive limits as absence. - Replace raw-key / timestamp-selector
PageBuilderlambdas withlast => codec.Encode(state); there is no key-selector overload. - Replace separately maintained ordering and seek predicates with an EF
SeekDefinitionwhere translation is supported. - Treat cursors as nullable references, not nullable structs (
cursor.Token, notcursor.Value.Tokenafter a presence check). - Expect outstanding old unversioned tokens to fail validation; clients must restart pagination. No legacy migration decoder is shipped.