Interface ILeaderboardStore

Application port for persisting and querying leaderboard entries.

Namespace: Serenity.Leaderboard.Application.Interfaces.Repositories

Assembly: Serenity.Leaderboard.Application.dll

Syntax

public interface ILeaderboardStore

Remarks

Implementations decide how and where leaderboard data is stored (in-memory, cloud backend, etc.). The business layer depends on this abstraction, never on a concrete backend. Read-operation contract: every read operation (GetTopAsync(BoardId, int, LeaderboardSortDirection, CancellationToken), GetAroundAsync(BoardId, PlayerId, int, LeaderboardSortDirection, CancellationToken), GetRankAsync(BoardId, PlayerId, LeaderboardSortDirection, CancellationToken), CountAsync(BoardId, CancellationToken)) ranks over each player's best entry, regardless of the board's retention mode.

Methods

ClearAsync(BoardId, CancellationToken)

Removes every entry for a board.

Declaration

Task ClearAsync(BoardId board, CancellationToken cancellationToken)

Parameters

Type	Name	Description
BoardId	board	The board to clear.
CancellationToken	cancellationToken	Token used to cancel the operation.

Returns

Type	Description
Task

CountAsync(BoardId, CancellationToken)

Counts the number of distinct players ranked on a board, regardless of the board's retention mode (in FullHistory retention this is NOT the raw submission count).

Declaration

Task<int> CountAsync(BoardId board, CancellationToken cancellationToken)

Parameters

Type	Name	Description
BoardId	board	The board to query.
CancellationToken	cancellationToken	Token used to cancel the operation.

Returns

Type	Description
Task<int>

GetAroundAsync(BoardId, PlayerId, int, LeaderboardSortDirection, CancellationToken)

Gets the entries surrounding a player's position on a board, ordered per the given direction. Ranks over each player's best entry, regardless of the board's retention mode.

Declaration

Task<IReadOnlyList<LeaderboardEntry>> GetAroundAsync(BoardId board, PlayerId player, int radius, LeaderboardSortDirection direction, CancellationToken cancellationToken)

Parameters

Type	Name	Description
BoardId	board	The board to query.
PlayerId	player	The player to center the window on.
int	radius	The number of entries to include on each side of the player. Must be zero or greater; negative values are clamped to zero.
LeaderboardSortDirection	direction	The ordering to apply.
CancellationToken	cancellationToken	Token used to cancel the operation.

Returns

Type	Description
Task<IReadOnlyList<LeaderboardEntry>>

GetPlayerBestAsync(BoardId, PlayerId, CancellationToken)

Gets a player's best entry on a board.

Declaration

Task<LeaderboardEntry?> GetPlayerBestAsync(BoardId board, PlayerId player, CancellationToken cancellationToken)

Parameters

Type	Name	Description
BoardId	board	The board to query.
PlayerId	player	The player to look up.
CancellationToken	cancellationToken	Token used to cancel the operation.

Returns

Type	Description
Task<LeaderboardEntry?>	The player's best entry, or null when the player has no entry on the board.

GetRankAsync(BoardId, PlayerId, LeaderboardSortDirection, CancellationToken)

Gets a player's 1-based competition rank on a board, ordered per the given direction. Ranks over each player's best entry, regardless of the board's retention mode.

Declaration

Task<int> GetRankAsync(BoardId board, PlayerId player, LeaderboardSortDirection direction, CancellationToken cancellationToken)

Parameters

Type	Name	Description
BoardId	board	The board to query.
PlayerId	player	The player to look up.
LeaderboardSortDirection	direction	The ordering to apply.
CancellationToken	cancellationToken	Token used to cancel the operation.

Returns

Type	Description
Task<int>	The player's 1-based rank, or zero when the player has no entry on the board.

GetTopAsync(BoardId, int, LeaderboardSortDirection, LeaderboardRankingMode, CancellationToken)

Gets the top entries for a board, ordered per the given direction.

Declaration

Task<IReadOnlyList<LeaderboardEntry>> GetTopAsync(BoardId board, int count, LeaderboardSortDirection direction, LeaderboardRankingMode rankingMode, CancellationToken cancellationToken)

Parameters

Type	Name	Description
BoardId	board	The board to query.
int	count	The maximum number of entries to return.
LeaderboardSortDirection	direction	The ordering to apply.
LeaderboardRankingMode	rankingMode	BestPerPlayer ranks over each player's best entry, regardless of the board's retention mode. AllEntries returns every stored row, unmerged — a player may occupy more than one row.
CancellationToken	cancellationToken	Token used to cancel the operation.

Returns

Type	Description
Task<IReadOnlyList<LeaderboardEntry>>

GetTopAsync(BoardId, int, LeaderboardSortDirection, CancellationToken)

Gets the top entries for a board, ordered per the given direction, ranked over each player's best entry regardless of the board's retention mode. Equivalent to calling the four-argument overload with BestPerPlayer.

Declaration

Task<IReadOnlyList<LeaderboardEntry>> GetTopAsync(BoardId board, int count, LeaderboardSortDirection direction, CancellationToken cancellationToken)

Parameters

Type	Name	Description
BoardId	board	The board to query.
int	count	The maximum number of entries to return.
LeaderboardSortDirection	direction	The ordering to apply.
CancellationToken	cancellationToken	Token used to cancel the operation.

Returns

Type	Description
Task<IReadOnlyList<LeaderboardEntry>>

HealthCheckAsync(CancellationToken)

Checks whether the backing store is reachable and healthy.

Declaration

Task<bool> HealthCheckAsync(CancellationToken cancellationToken)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	Token used to cancel the operation.

Returns

Type	Description
Task<bool>

SubmitAsync(LeaderboardEntry, LeaderboardDefinition, CancellationToken)

Submits a new entry to the store for the given board.

Declaration

Task SubmitAsync(LeaderboardEntry entry, LeaderboardDefinition board, CancellationToken cancellationToken)

Parameters

Type	Name	Description
LeaderboardEntry	entry	The entry to submit.
LeaderboardDefinition	board	The board configuration the entry is submitted against.
CancellationToken	cancellationToken	Token used to cancel the operation.

Returns

Type	Description
Task

Remarks

When the board defines MaxEntries (greater than zero), implementations trim the raw stored entries to the best MaxEntries ENTRIES in ranking order after each submission — a literal per-entry cap, so under FullHistory retention it bounds the stored history itself. Zero means unbounded.