Class CursorEncoder
- Namespace
- Excalibur.EventSourcing
- Assembly
- Excalibur.EventSourcing.Abstractions.dll
Encodes and decodes opaque cursor strings for cursor-based (keyset) pagination.
public static class CursorEncoder
- Inheritance
-
CursorEncoder
- Inherited Members
Remarks
Cursors are Base64url-encoded JSON arrays of sort values from the boundary item in a paged result set. They are safe to pass as URL query parameters without additional encoding.
The cursor format is opaque to consumers — they should not parse or construct it. The encoding is an implementation detail that may change between versions.
This encoder is backend-agnostic. It works with any data store that supports
keyset pagination (Elasticsearch search_after, SQL Server keyset queries,
Cosmos DB continuation tokens, etc.). Backend-specific packages provide helpers
that convert native sort values to/from the object[] format
expected by this encoder.
Methods
Decode(string?)
Decodes a Base64url cursor string back into an array of sort values.
public static object?[]? Decode(string? cursor)
Parameters
Returns
- object[]
An array of sort values (strings, numbers, booleans, or nulls), or
nullif the cursor is empty, whitespace, or invalid.
Remarks
Invalid cursors (malformed Base64, corrupt JSON) are treated as "no cursor"
and return null, causing the query to start from the beginning.
This is intentional — a corrupt cursor should not fail the request.
Encode(params object?[])
Encodes an array of sort values into an opaque Base64url cursor string.
public static string Encode(params object?[] sortValues)
Parameters
sortValuesobject[]The sort values from the boundary item (e.g., the last item on the current page). Supported types: string, long, int, double, float, decimal, DateTimeOffset, DateTime, DateOnly, TimeOnly, bool, and
null. DateTimeOffset and DateTime values are stored as Unix epoch milliseconds for reliable round-tripping. DateOnly and TimeOnly values are stored as ISO 8601 strings which sort lexicographically.
Returns
- string
A Base64url-encoded cursor string.
Exceptions
- ArgumentNullException
Thrown when
sortValuesisnull.- ArgumentException
Thrown when
sortValuesis empty.