@babylonjs-toolkit/server 0.0.0-stage → 9.35.0

package/lib/leaderboards/FileLeaderboardRankStore.d.ts

@@ -0,0 +1,293 @@
+import type { LeaderboardSortOrder } from "../admin/AdminApiTypes.js";
+import type { LeaderboardDurability, LeaderboardPlayerRecord, LeaderboardRankKey, LeaderboardRankStore, LeaderboardWriteRequest, LeaderboardWriteResult, RankedLeaderboardEntry, RemovedLeaderboardEntry } from "./LeaderboardRankStore.js";
+/** Rankings in files (D1, DR §8). */
+export declare class FileLeaderboardRankStore implements LeaderboardRankStore {
+    /** Always "file". */
+    readonly kind: "file";
+    /** The store's folder (<admin.dataDir>/leaderboards). */
+    private readonly folder;
+    /** Whether the folder survives a redeploy (D20). */
+    private readonly isFolderPersistent;
+    /** Loaded season files by file key (`<boardId>/<seasonId>`). */
+    private readonly seasons;
+    /** Season loads in flight, so two callers share one read. */
+    private readonly seasonLoads;
+    /** Player records. */
+    private players;
+    /** Player id → rank key texts. */
+    private playerKeys;
+    /** Dedupe id → remembered result. */
+    private dedupe;
+    /** Rate bucket → counter (memory only). */
+    private readonly rates;
+    /** `<sessionName>\n<subject>` → presence (memory only). */
+    private readonly presence;
+    /** File keys changed since the last flush. */
+    private readonly dirtyFiles;
+    /** The pending flush timer, or null. */
+    private flushTimer;
+    /** Pending writes per file key, so a file's writes never interleave. */
+    private readonly writeChains;
+    /** The latest caller time seen (prunes expired dedupe records on flush). */
+    private latestNowMs;
+    /**
+     * Creates the store; open() loads the shared files.
+     * @param folder The store's folder.
+     * @param isFolderPersistent Whether the folder survives a redeploy.
+     */
+    private constructor();
+    /**
+     * Opens the store, loading players, player keys and dedupe records (season files load on first use).
+     * @param folder The store's folder (created on the first write).
+     * @param isFolderPersistent Whether the folder survives a redeploy (the admin store's isPersistent).
+     * @returns The store.
+     */
+    static open(folder: string, isFolderPersistent: boolean): Promise<FileLeaderboardRankStore>;
+    /**
+     * Writes one score: dedupe, keep policy (applyKeepPolicy, the Lua's semantics), overflow, ranking and indexes.
+     * @param request The write.
+     * @returns What the write did.
+     */
+    write(request: LeaderboardWriteRequest): Promise<LeaderboardWriteResult>;
+    /**
+     * Reads a page of a ranking.
+     * @param key The ranking.
+     * @param offset Zero-based index of the first entry.
+     * @param limit Most entries.
+     * @returns The ranked entries.
+     */
+    readRange(key: LeaderboardRankKey, offset: number, limit: number): Promise<RankedLeaderboardEntry[]>;
+    /**
+     * Counts the live entries.
+     * @param key The ranking.
+     * @returns The count.
+     */
+    count(key: LeaderboardRankKey): Promise<number>;
+    /**
+     * Reads one player's live entry and rank.
+     * @param key The ranking.
+     * @param playerId The player.
+     * @returns The entry, or null.
+     */
+    readEntry(key: LeaderboardRankKey, playerId: string): Promise<RankedLeaderboardEntry | null>;
+    /**
+     * Reads the window around a player's entry, clamped to the ranking.
+     * @param key The ranking.
+     * @param playerId The player.
+     * @param window Entries above and below.
+     * @returns The entries, or [] when the player has none.
+     */
+    readAround(key: LeaderboardRankKey, playerId: string, window: number): Promise<RankedLeaderboardEntry[]>;
+    /**
+     * Finds entries by display name or player id (case-insensitive), in rank order.
+     * @param key The ranking.
+     * @param text The text.
+     * @param limit Most entries.
+     * @returns The matches.
+     */
+    searchEntries(key: LeaderboardRankKey, text: string, limit: number): Promise<RankedLeaderboardEntry[]>;
+    /**
+     * Reads the removed entries, newest removal first.
+     * @param key The ranking.
+     * @returns The removed entries.
+     */
+    readRemoved(key: LeaderboardRankKey): Promise<RemovedLeaderboardEntry[]>;
+    /**
+     * Moves a live entry to the removed set.
+     * @param key The ranking.
+     * @param playerId The player.
+     * @param reason Why.
+     * @param removedBy Who.
+     * @param removedAt ISO time.
+     * @returns True when there was a live entry.
+     */
+    removeEntry(key: LeaderboardRankKey, playerId: string, reason: string, removedBy: string, removedAt: string): Promise<boolean>;
+    /**
+     * Moves a removed entry back into the ranking.
+     * @param key The ranking.
+     * @param playerId The player.
+     * @param sortOrder The board's sort order.
+     * @returns "restored", "missing" or "liveEntryExists".
+     */
+    restoreEntry(key: LeaderboardRankKey, playerId: string, sortOrder: LeaderboardSortOrder): Promise<"restored" | "missing" | "liveEntryExists">;
+    /**
+     * Lists the variant keys of a season, sorted.
+     * @param boardId The board.
+     * @param seasonId The season.
+     * @returns The variant keys.
+     */
+    listVariantKeys(boardId: string, seasonId: number): Promise<string[]>;
+    /**
+     * Reads a board's last accepted write time across its season files.
+     * @param boardId The board.
+     * @returns ISO time, or null.
+     */
+    readLastSubmissionAt(boardId: string): Promise<string | null>;
+    /**
+     * Empties a season (its file keeps only the last submission time) and unlinks it from its players.
+     * @param boardId The board.
+     * @param seasonId The season.
+     * @returns How many entries were deleted.
+     */
+    deleteSeason(boardId: string, seasonId: number): Promise<number>;
+    /**
+     * Deletes a board's folder after emptying its seasons.
+     * @param boardId The board.
+     * @param seasonIds Its seasons.
+     */
+    deleteBoard(boardId: string, seasonIds: number[]): Promise<void>;
+    /**
+     * Lists the rankings a player has an entry in.
+     * @param playerId The player.
+     * @returns The rank keys, sorted by their text.
+     */
+    listPlayerRankKeys(playerId: string): Promise<LeaderboardRankKey[]>;
+    /**
+     * Renames every entry of a player, live and removed.
+     * @param playerId The player.
+     * @param displayName The new name.
+     * @returns How many entries changed.
+     */
+    renamePlayerEntries(playerId: string, displayName: string): Promise<number>;
+    /**
+     * Deletes every entry of a player, live and removed, and the player's rank keys.
+     * @param playerId The player.
+     * @returns How many entries were deleted.
+     */
+    deletePlayerEntries(playerId: string): Promise<number>;
+    /**
+     * Reads a player.
+     * @param playerId The player.
+     * @returns A copy of the record, or null.
+     */
+    getPlayer(playerId: string): Promise<LeaderboardPlayerRecord | null>;
+    /**
+     * Writes a player.
+     * @param record The record.
+     */
+    putPlayer(record: LeaderboardPlayerRecord): Promise<void>;
+    /**
+     * Deletes a player record.
+     * @param playerId The player.
+     * @returns True when it existed.
+     */
+    deletePlayer(playerId: string): Promise<boolean>;
+    /**
+     * Finds players by display name or id (case-insensitive).
+     * @param text The text ("" matches any).
+     * @param limit Most players.
+     * @returns Copies of the matching records.
+     */
+    searchPlayers(text: string, limit: number): Promise<LeaderboardPlayerRecord[]>;
+    /**
+     * Counts every player.
+     * @returns The count.
+     */
+    countPlayers(): Promise<number>;
+    /**
+     * Counts one use in a fixed window, in memory.
+     * @param bucket What is limited.
+     * @param limit Most uses per window.
+     * @param windowMs The window, in milliseconds.
+     * @param nowMs The caller's clock.
+     * @returns True while within the limit.
+     */
+    consumeRate(bucket: string, limit: number, windowMs: number, nowMs: number): Promise<boolean>;
+    /**
+     * Records a session join per subject, in memory; an earlier join that still counts wins.
+     * @param sessionName The session.
+     * @param subjects The subjects.
+     * @param joinedAtMs The join time.
+     * @param ttlMs How long it counts.
+     */
+    recordSessionPresence(sessionName: string, subjects: string[], joinedAtMs: number, ttlMs: number): Promise<void>;
+    /**
+     * Reads a subject's join time, if it still counts.
+     * @param sessionName The session.
+     * @param subject The subject.
+     * @param nowMs The caller's clock.
+     * @returns The join time, or null.
+     */
+    readSessionPresence(sessionName: string, subject: string, nowMs: number): Promise<number | null>;
+    /**
+     * Durability of the folder (D20): durable when the admin store says it persists.
+     * @returns The durability and advice.
+     */
+    measureDurability(): Promise<LeaderboardDurability>;
+    /** Writes every changed file and waits for the writes. */
+    close(): Promise<void>;
+    /**
+     * Applies one write to a loaded season (no dedupe).
+     * @param season The season.
+     * @param request The write.
+     * @returns What the write did.
+     */
+    private applyWrite;
+    /**
+     * Finds a loaded ranking without creating it.
+     * @param key The ranking.
+     * @returns The ranking, or null.
+     */
+    private findRanking;
+    /**
+     * Loads a season file once (an empty season when it does not exist).
+     * @param boardId The board.
+     * @param seasonId The season.
+     * @returns The season held in memory.
+     */
+    private loadSeason;
+    /**
+     * Reads a season file into memory form.
+     * @param fileKey The season's file key.
+     * @returns The season.
+     */
+    private readSeasonFile;
+    /**
+     * Lists the season ids that have a file for a board.
+     * @param boardId The board.
+     * @returns The season ids, plus those loaded in memory.
+     */
+    private listSeasonIds;
+    /** Loads the players, player keys and dedupe files. */
+    private loadSharedFiles;
+    /**
+     * Adds a rank key to a player's index.
+     * @param playerId The player.
+     * @param keyText The rank key text.
+     */
+    private addPlayerKey;
+    /**
+     * Removes a rank key from a player's index.
+     * @param playerId The player.
+     * @param keyText The rank key text.
+     */
+    private removePlayerKey;
+    /**
+     * Marks a file changed and schedules a flush after LEADERBOARD_FILE_FLUSH_DELAY_MS.
+     * @param fileKey The file key (a season key or a shared file name).
+     */
+    private markDirty;
+    /**
+     * Writes every changed file, each after its own pending write.
+     * @returns Resolves once the writes are queued and done.
+     */
+    private flush;
+    /**
+     * Writes one file from memory (an empty, never-submitted season file is deleted instead).
+     * @param fileKey The file key.
+     */
+    private writeFileOf;
+    /**
+     * Runs a task after the pending writes of one file.
+     * @param fileKey The file.
+     * @param task The task.
+     * @returns The task's result.
+     */
+    private serialize;
+    /**
+     * The path of a file key.
+     * @param fileKey A season key (`<boardId>/<seasonId>`) or a shared file name.
+     * @returns The absolute path.
+     */
+    private filePath;
+}