Table of Contents

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

cursor string

The opaque cursor string, or null/Empty for the first page.

Returns

object[]

An array of sort values (strings, numbers, booleans, or nulls), or null if 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

sortValues object[]

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 sortValues is null.

ArgumentException

Thrown when sortValues is empty.