Class CursorCodec

Namespace

Trellis

Assembly

Trellis.Core.dll

AOT-friendly, versioned continuation codecs. Tokens are opaque, not signed. Existing unversioned tokens are deliberately rejected. Authorization must still filter every query.

public static class CursorCodec

Inheritance

object

CursorCodec

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Fields

MaxEncodedTokenLength

Maximum encoded token size for built-in codecs, enforced on both paths.

public const int MaxEncodedTokenLength = 1024

Field Value

int

Methods

Composite<TPrimary, TSecondary>()

Creates a two-component codec using built-in scalar codecs.

public static ICursorCodec<(TPrimary Primary, TSecondary Secondary)> Composite<TPrimary, TSecondary>() where TPrimary : notnull, IParsable<TPrimary> where TSecondary : notnull, IParsable<TSecondary>

Returns

ICursorCodec<(TPrimary Primary, TSecondary Secondary)>

Type Parameters

TPrimary

TSecondary

Composite<TPrimary, TSecondary>(ICursorCodec<TPrimary>, ICursorCodec<TSecondary>)

Composes arbitrary component codecs using unambiguous length-prefixed framing.

public static ICursorCodec<(TPrimary Primary, TSecondary Secondary)> Composite<TPrimary, TSecondary>(ICursorCodec<TPrimary> primary, ICursorCodec<TSecondary> secondary) where TPrimary : notnull where TSecondary : notnull

Parameters

primary ICursorCodec<TPrimary>

secondary ICursorCodec<TSecondary>

Returns

ICursorCodec<(TPrimary Primary, TSecondary Secondary)>

Type Parameters

TPrimary

TSecondary

Create<TState>(string, Func<TState, string>, Func<string, string?, Result<TState>>)

Creates a codec with an explicit schema identifier and round-trip formatter/parser. The parser must validate domain bounds and context and return InvalidInput for bad client state. It also runs during encoding to reject server state that cannot round-trip.

public static ICursorCodec<TState> Create<TState>(string schema, Func<TState, string> format, Func<string, string?, Result<TState>> parse) where TState : notnull

Parameters

schema string

format Func<TState, string>

parse Func<string, string, Result<TState>>

Returns

ICursorCodec<TState>

Type Parameters

TState

Encode<T>(T)

Encodes a scalar using the built-in codec.

public static Cursor Encode<T>(T id) where T : notnull, IParsable<T>

Parameters

id T

Returns

Cursor

Type Parameters

T

Encode<TPrimary, TSecondary>(TPrimary, TSecondary)

Encodes arbitrary primary and secondary scalar keys.

public static Cursor Encode<TPrimary, TSecondary>(TPrimary primary, TSecondary secondary) where TPrimary : notnull, IParsable<TPrimary> where TSecondary : notnull, IParsable<TSecondary>

Parameters

primary TPrimary

secondary TSecondary

Returns

Cursor

Type Parameters

TPrimary

TSecondary

Map<TWire, TState>(ICursorCodec<TWire>, Func<TState, TWire>, Func<TWire, string?, Result<TState>>)

Maps a wire codec to named validated state without hand-writing serialization. Validation runs on inbound state and on the round-trip of every encoded boundary.

public static ICursorCodec<TState> Map<TWire, TState>(ICursorCodec<TWire> wireCodec, Func<TState, TWire> toWire, Func<TWire, string?, Result<TState>> fromWire) where TWire : notnull where TState : notnull

Parameters

wireCodec ICursorCodec<TWire>

toWire Func<TState, TWire>

fromWire Func<TWire, string, Result<TState>>

Returns

ICursorCodec<TState>

Type Parameters

TWire

TState

Scalar<T>()

Creates an invariant scalar codec. Custom types must implement invariant formatting and parsing.

public static ICursorCodec<T> Scalar<T>() where T : notnull, IParsable<T>

Returns

ICursorCodec<T>

Type Parameters

T

TryDecodeComposite<TKey>(Cursor?, string?)

Convenience decoder for timestamp and ID state, using the versioned composite codec.

public static Result<(DateTimeOffset CreatedAt, TKey Id)> TryDecodeComposite<TKey>(Cursor? cursor, string? fieldName = null) where TKey : notnull, IParsable<TKey>

Parameters

cursor Cursor

fieldName string

Returns

Result<(DateTimeOffset CreatedAt, TKey Id)>

Type Parameters

TKey

TryDecodeComposite<TPrimary, TSecondary>(Cursor?, string?)

Decodes arbitrary primary and secondary scalar keys.

public static Result<(TPrimary Primary, TSecondary Secondary)> TryDecodeComposite<TPrimary, TSecondary>(Cursor? cursor, string? fieldName = null) where TPrimary : notnull, IParsable<TPrimary> where TSecondary : notnull, IParsable<TSecondary>

Parameters

cursor Cursor

fieldName string

Returns

Result<(TPrimary Primary, TSecondary Secondary)>

Type Parameters

TPrimary

TSecondary

TryDecodeOptional<TState>(Cursor?, ICursorCodec<TState>, string?)

Decodes optional continuation state. Only an absent token means the first page. A codec returning successful null state violates its contract and throws InvalidOperationException.

public static Result<Maybe<TState>> TryDecodeOptional<TState>(Cursor? cursor, ICursorCodec<TState> codec, string? fieldName = null) where TState : notnull

Parameters

cursor Cursor

codec ICursorCodec<TState>

fieldName string

Returns

Result<Maybe<TState>>

Type Parameters

TState

TryDecode<T>(Cursor?, string?)

Decodes a scalar using the built-in codec.

public static Result<T> TryDecode<T>(Cursor? cursor, string? fieldName = null) where T : notnull, IParsable<T>

Parameters

cursor Cursor

fieldName string

Returns

Result<T>

Type Parameters

T