@voltro/plugin-leaderboards 0.0.0-stage → 0.87.0

package/dist/ports.js

@@ -0,0 +1,7 @@
+import { TournamentBracketPort as e } from "./bracketMatchPorts.js";
+import { TournamentStagePort as t } from "./tournamentStagePorts.js";
+import { Context as n } from "effect";
+//#region src/bracketPorts.ts
+var r = class extends n.Service()("@voltro/BracketAdmissionPort") {};
+//#endregion
+export { r as BracketAdmissionPort, e as TournamentBracketPort, t as TournamentStagePort };

package/dist/rankQuery.js

@@ -0,0 +1,24 @@
+import { LeaderboardError as e, leaderboardError as t } from "./errors.js";
+import { rankLeaderboardRecords as n } from "./ranking.js";
+import { Effect as r } from "effect";
+//#region src/rankQuery.ts
+var i = (i) => r.try({
+	try: () => Object.freeze(n(i.records, {
+		sort: i.sort,
+		maxRecords: i.maxRecords,
+		tiebreak: i.tiebreak
+	}).map((e) => e.id)),
+	catch: (n) => n instanceof e ? n : t("unavailable")
+}), a = (e, n) => {
+	if (!Array.isArray(e) || e.length !== n.length) throw t("invalid_record");
+	let r = new Set(n.map((e) => e.id)), i = /* @__PURE__ */ new Set(), a = [];
+	if (r.size !== n.length) throw t("invalid_record");
+	for (let n = 0; n < e.length; n++) {
+		let o = Object.getOwnPropertyDescriptor(e, String(n));
+		if (!o || !("value" in o) || typeof o.value != "string" || !r.has(o.value) || i.has(o.value)) throw t("invalid_record");
+		i.add(o.value), a.push(o.value);
+	}
+	return Object.freeze(a);
+};
+//#endregion
+export { a as admitLeaderboardRankOrder, i as defaultLeaderboardRankQuery };

package/dist/ranking.d.ts

@@ -0,0 +1,42 @@
+/** Equal primary score: higher subscore, then earlier submission, then binary owner/record ID. */
+export declare const defaultLeaderboardTiebreak: LeaderboardTiebreak;
+
+export declare const defaultPeriodSummary: (records: ReadonlyArray<RankedLeaderboardRecord>, top?: number) => Readonly<{
+    participants: number;
+    top: readonly RankedLeaderboardRecord[];
+}>;
+
+/** Stable FNV-1a UTF-8 partition helper. Does not enforce fixed-size cohort admission. */
+export declare const hashBucket: (tenantId: string, periodId: string, ownerId: string, bucketCount: number) => number;
+
+export declare const leaderboardAround: (records: ReadonlyArray<RankedLeaderboardRecord>, ownerId: string, radius?: number) => ReadonlyArray<RankedLeaderboardRecord>;
+
+export declare interface LeaderboardRankRecord {
+    readonly id: string;
+    readonly tenantId: string;
+    readonly board: string;
+    readonly periodId: string;
+    readonly ownerId: string;
+    readonly score: string;
+    readonly subscore: string;
+    readonly updatedAt: number;
+}
+
+declare type LeaderboardSort = 'asc' | 'desc';
+
+export declare type LeaderboardTiebreak = (left: LeaderboardRankRecord, right: LeaderboardRankRecord) => number;
+
+export declare interface RankedLeaderboardRecord extends LeaderboardRankRecord {
+    readonly rank: number;
+}
+
+/** Whole supplied board/period snapshot. No SQL/window-query or million-row capacity claim. */
+export declare const rankLeaderboardRecords: (input: ReadonlyArray<LeaderboardRankRecord>, options?: RankOptions) => ReadonlyArray<RankedLeaderboardRecord>;
+
+export declare interface RankOptions {
+    readonly sort?: LeaderboardSort;
+    readonly tiebreak?: LeaderboardTiebreak;
+    readonly maxRecords?: number;
+}
+
+export { }

package/dist/ranking.js

@@ -0,0 +1,71 @@
+import { leaderboardError as e } from "./errors.js";
+import { leaderboardIdentifier as t } from "./leaderboard.js";
+import { scoreString as n, scoreValue as r } from "./score.js";
+//#region src/ranking.ts
+var i = (e, t) => e < t ? -1 : +(e > t), a = (e, t) => {
+	let n = r(e.subscore), a = r(t.subscore);
+	return n > a ? -1 : n < a ? 1 : e.updatedAt - t.updatedAt || i(e.ownerId, t.ownerId) || i(e.id, t.id);
+}, o = (o, s = {}) => {
+	let c = s.sort ?? "desc", l = s.tiebreak ?? a, u = s.maxRecords ?? 1e4;
+	if (!Array.isArray(o) || !Number.isSafeInteger(u) || u < 1 || u > 1e5 || o.length > u || !["asc", "desc"].includes(c) || typeof l != "function") throw e("invalid_input");
+	for (let t = 0; t < o.length; t++) if (!Object.hasOwn(o, t)) throw e("invalid_record");
+	let d = /* @__PURE__ */ new Set(), f = /* @__PURE__ */ new Set(), p = o[0], m = o.map((r) => {
+		if (!r || ![
+			"id",
+			"tenantId",
+			"board",
+			"periodId",
+			"ownerId"
+		].every((e) => t(r[e])) || p && (r.tenantId !== p.tenantId || r.board !== p.board || r.periodId !== p.periodId) || !Number.isSafeInteger(r.updatedAt) || r.updatedAt < 0 || r.updatedAt > 864e13 || d.has(r.id) || f.has(r.ownerId)) throw e("invalid_record");
+		return d.add(r.id), f.add(r.ownerId), Object.freeze({
+			id: r.id,
+			tenantId: r.tenantId,
+			board: r.board,
+			periodId: r.periodId,
+			ownerId: r.ownerId,
+			score: n(r.score),
+			subscore: n(r.subscore),
+			updatedAt: r.updatedAt
+		});
+	});
+	return m.sort((t, n) => {
+		let a = r(t.score), o = r(n.score);
+		if (a !== o) return c === "desc" ? a > o ? -1 : 1 : a < o ? -1 : 1;
+		let s;
+		try {
+			s = l(t, n);
+		} catch {
+			throw e("invalid_record");
+		}
+		if (!Number.isFinite(s)) throw e("invalid_record");
+		return s || i(t.ownerId, n.ownerId) || i(t.id, n.id);
+	}), Object.freeze(m.map((e, t) => Object.freeze({
+		...e,
+		rank: t + 1
+	})));
+}, s = (n, r, i = 5) => {
+	if (!t(r) || !Number.isSafeInteger(i) || i < 0 || i > 500) throw e("invalid_input");
+	let a = n.findIndex((e) => e.ownerId === r);
+	return Object.freeze(a < 0 ? [] : n.slice(Math.max(0, a - i), a + i + 1));
+}, c = (t, n = 10) => {
+	if (!Number.isSafeInteger(n) || n < 0 || n > 1e3) throw e("invalid_input");
+	return Object.freeze({
+		participants: t.length,
+		top: Object.freeze(t.slice(0, n))
+	});
+}, l = (n, r, i, a) => {
+	if (![
+		n,
+		r,
+		i
+	].every(t) || !Number.isSafeInteger(a) || a < 1 || a > 1e6) throw e("invalid_input");
+	let o = 14695981039346656037n;
+	for (let e of new TextEncoder().encode(JSON.stringify([
+		n,
+		r,
+		i
+	]))) o = BigInt.asUintN(64, (o ^ BigInt(e)) * 1099511628211n);
+	return Number(o % BigInt(a));
+};
+//#endregion
+export { a as defaultLeaderboardTiebreak, c as defaultPeriodSummary, l as hashBucket, s as leaderboardAround, o as rankLeaderboardRecords };

package/dist/rating.d.ts

@@ -0,0 +1,103 @@
+/** Pairwise mean Elo; each team's delta is split by participation weight. */
+export declare const elo: (options?: EloOptions) => EloRate;
+
+export declare interface EloInput {
+    readonly teams: ReadonlyArray<ReadonlyArray<EloPlayer>>;
+    readonly ranks: ReadonlyArray<number>;
+}
+
+export declare interface EloOptions {
+    readonly k?: number;
+    readonly scale?: number;
+}
+
+export declare interface EloPlayer {
+    readonly id: string;
+    readonly rating: number;
+    readonly weight?: number;
+}
+
+export declare type EloRate = (input: EloInput) => ReadonlyArray<ReadonlyArray<EloResult>>;
+
+export declare interface EloResult {
+    readonly id: string;
+    readonly previous: number;
+    readonly rating: number;
+    readonly delta: number;
+}
+
+/** Glickman's revised Illinois procedure; one complete simultaneous rating period.
+ * https://glicko.net/glicko/glicko2.pdf — independently implemented equations. */
+export declare const glicko2: (options?: Glicko2Options) => Glicko2Rate;
+
+export declare interface Glicko2Input {
+    readonly player: Glicko2Rating;
+    /** All opponents carry their pre-period ratings, not sequentially updated ones. */
+    readonly opponents: ReadonlyArray<Glicko2Opponent>;
+}
+
+export declare interface Glicko2Opponent {
+    readonly rating: number;
+    readonly deviation: number;
+    readonly score: 0 | 0.5 | 1;
+}
+
+export declare interface Glicko2Options {
+    readonly tau?: number;
+    readonly epsilon?: number;
+    readonly maxIterations?: number;
+    readonly maxOpponents?: number;
+}
+
+export declare type Glicko2Rate = (input: Glicko2Input) => Glicko2Result;
+
+export declare interface Glicko2Rating {
+    readonly rating: number;
+    readonly deviation: number;
+    readonly volatility: number;
+}
+
+export declare interface Glicko2Result extends Glicko2Rating {
+    readonly previous: Glicko2Rating;
+}
+
+/** Weng–Lin Plackett–Luce, Algorithm4 (2011), with linear Gaussian partial play.
+ * https://jmlr.org/papers/volume12/weng11a/weng11a.pdf
+ * Fractional weights enter the team mean linearly and variance quadratically;
+ * they are not the OpenSkill library's contribution/weight-normalization API. */
+export declare const openskill: (options?: OpenSkillOptions) => OpenSkillRate;
+
+export declare interface OpenSkillInput {
+    readonly teams: ReadonlyArray<ReadonlyArray<OpenSkillPlayer>>;
+    readonly ranks: ReadonlyArray<number>;
+}
+
+export declare interface OpenSkillOptions {
+    readonly beta?: number;
+    readonly tau?: number;
+    readonly kappa?: number;
+    readonly ordinalZ?: number;
+}
+
+export declare interface OpenSkillPlayer {
+    readonly id: string;
+    readonly mu: number;
+    readonly sigma: number;
+    /** Fraction of participation. Zero retains the exact prior. */
+    readonly weight?: number;
+}
+
+export declare type OpenSkillRate = (input: OpenSkillInput) => ReadonlyArray<ReadonlyArray<OpenSkillResult>>;
+
+export declare interface OpenSkillResult {
+    readonly id: string;
+    readonly previous: {
+        readonly mu: number;
+        readonly sigma: number;
+    };
+    readonly mu: number;
+    readonly sigma: number;
+    readonly ordinal: number;
+}
+
+export { }

package/dist/rating.js

@@ -0,0 +1,50 @@
+import { leaderboardError as e } from "./errors.js";
+import { leaderboardIdentifier as t } from "./leaderboard.js";
+import { glicko2 as n } from "./glicko2.js";
+import { openskill as r } from "./openskill.js";
+//#region src/rating.ts
+var i = (n = {}) => {
+	let r = n.k ?? 32, i = n.scale ?? 400;
+	if (!Number.isFinite(r) || r <= 0 || r > 1e6 || !Number.isFinite(i) || i <= 0 || i > 1e6) throw e("invalid_input");
+	return (n) => {
+		if (!n || !Array.isArray(n.teams) || n.teams.length < 2 || n.teams.length > 64 || !Array.isArray(n.ranks) || n.ranks.length !== n.teams.length || n.ranks.some((e) => !Number.isSafeInteger(e) || e < 1 || e > n.teams.length)) throw e("invalid_input");
+		for (let t = 0; t < n.teams.length; t++) if (!Object.hasOwn(n.teams, t) || !Object.hasOwn(n.ranks, t)) throw e("invalid_input");
+		let a = /* @__PURE__ */ new Set(), o = n.teams.map((n) => {
+			if (!Array.isArray(n) || n.length < 1 || n.length > 256) throw e("invalid_input");
+			for (let t = 0; t < n.length; t++) if (!Object.hasOwn(n, t) || !n[t]) throw e("invalid_input");
+			let r = n.map((n) => {
+				let r = n.weight ?? 1;
+				if (!t(n.id) || a.has(n.id) || !Number.isFinite(n.rating) || Math.abs(n.rating) > 1e9 || !Number.isFinite(r) || r < 0 || r > 1) throw e("invalid_input");
+				return a.add(n.id), Object.freeze({
+					id: n.id,
+					rating: n.rating,
+					weight: r
+				});
+			}), i = r.reduce((e, t) => e + t.weight, 0);
+			if (i === 0) throw e("invalid_input");
+			return {
+				members: r,
+				weight: i,
+				mean: r.reduce((e, t) => e + t.rating * t.weight / i, 0)
+			};
+		});
+		if (a.size > 4096) throw e("limit_exceeded");
+		let s = o.map(() => 0), c = r / (o.length - 1);
+		for (let e = 0; e < o.length; e++) for (let t = e + 1; t < o.length; t++) {
+			let r = o[e], a = (o[t].mean - r.mean) / i, l = a >= 0 ? 1 / (1 + 10 ** a) : 1 - 1 / (1 + 10 ** -a), u = c * ((n.ranks[e] < n.ranks[t] ? 1 : n.ranks[e] === n.ranks[t] ? .5 : 0) - l);
+			s[e] += u, s[t] -= u;
+		}
+		return Object.freeze(o.map((t, n) => Object.freeze(t.members.map((r) => {
+			let i = s[n] * r.weight / t.weight, a = r.rating + i;
+			if (!Number.isFinite(a) || Math.abs(a) > 1e9) throw e("overflow");
+			return Object.freeze({
+				id: r.id,
+				previous: r.rating,
+				rating: a,
+				delta: i
+			});
+		}))));
+	};
+};
+//#endregion
+export { i as elo, n as glicko2, r as openskill };

package/dist/ratingPools.js

@@ -0,0 +1,134 @@
+import { leaderboardError as e } from "./errors.js";
+import { leaderboardIdentifier as t } from "./leaderboard.js";
+import { canonicalLeaderboardJson as n, captureLeaderboardJson as r } from "./json.js";
+import { glicko2 as i } from "./glicko2.js";
+import { openskill as a } from "./openskill.js";
+import { elo as o } from "./rating.js";
+import { Schema as s } from "effect";
+//#region src/ratingPools.ts
+var c = s.Number.pipe(s.check(s.isFinite()), s.check(s.isBetween({
+	minimum: -1e9,
+	maximum: 1e9
+}))), l = s.Number.pipe(s.check(s.isFinite()), s.check(s.isBetween({
+	minimum: 1e-12,
+	maximum: 1e9
+}))), u = s.Union([
+	s.Struct({
+		algorithm: s.Literal("elo"),
+		rating: c
+	}),
+	s.Struct({
+		algorithm: s.Literal("openskill"),
+		mu: c,
+		sigma: l
+	}),
+	s.Struct({
+		algorithm: s.Literal("glicko2"),
+		rating: c,
+		deviation: l,
+		volatility: l
+	})
+]), d = (t, i) => {
+	let a = r(t, 1024), o = s.decodeUnknownSync(u)(a);
+	if (o.algorithm !== i || n(o) !== n(a)) throw e("invalid_record");
+	return Object.freeze(o);
+}, f = (n = []) => {
+	if (!Array.isArray(n) || n.length > 256) throw e("invalid_input");
+	let s = /* @__PURE__ */ new Set(), c = n.map((n) => {
+		if (!n || !t(n.name) || s.has(n.name)) throw e("invalid_input");
+		s.add(n.name);
+		let c = Object.freeze(r(n.options ?? {}, 1024));
+		if (!c || typeof c != "object" || Array.isArray(c)) throw e("invalid_input");
+		let l, u;
+		switch (n.algorithm) {
+			case "elo":
+				if (u = ["k", "scale"], l = d({
+					algorithm: "elo",
+					...n.initial ?? { rating: 1e3 }
+				}, "elo"), l.algorithm !== "elo") throw e("invalid_input");
+				o(c)({
+					teams: [[{
+						id: "a",
+						rating: l.rating
+					}], [{
+						id: "b",
+						rating: l.rating
+					}]],
+					ranks: [1, 1]
+				});
+				break;
+			case "openskill":
+				if (u = [
+					"beta",
+					"tau",
+					"kappa",
+					"ordinalZ"
+				], l = d({
+					algorithm: "openskill",
+					...n.initial ?? {
+						mu: 25,
+						sigma: 25 / 3
+					}
+				}, "openskill"), l.algorithm !== "openskill") throw e("invalid_input");
+				a(c)({
+					teams: [[{
+						id: "a",
+						mu: l.mu,
+						sigma: l.sigma
+					}], [{
+						id: "b",
+						mu: l.mu,
+						sigma: l.sigma
+					}]],
+					ranks: [1, 1]
+				});
+				break;
+			case "glicko2":
+				if (u = [
+					"tau",
+					"epsilon",
+					"maxIterations",
+					"maxOpponents"
+				], l = d({
+					algorithm: "glicko2",
+					...n.initial ?? {
+						rating: 1500,
+						deviation: 350,
+						volatility: .06
+					}
+				}, "glicko2"), l.algorithm !== "glicko2") throw e("invalid_input");
+				i(c)({
+					player: l,
+					opponents: []
+				});
+				break;
+			default: throw e("invalid_input");
+		}
+		if (Object.keys(c).some((e) => !u.includes(e))) throw e("invalid_input");
+		return Object.freeze({
+			name: n.name,
+			algorithm: n.algorithm,
+			initial: l,
+			options: c
+		});
+	});
+	for (let t = 0; t < n.length; t++) if (!Object.hasOwn(n, t)) throw e("invalid_input");
+	return Object.freeze(c);
+}, p = s.NonEmptyString.pipe(s.check(s.isMaxLength(256))), m = s.Struct({
+	tenantId: p,
+	pool: p,
+	matchId: p,
+	teams: s.Array(s.Array(s.Struct({
+		ownerId: p,
+		weight: s.optional(s.Number.pipe(s.check(s.isFinite()), s.check(s.isBetween({
+			minimum: 0,
+			maximum: 1
+		}))))
+	})).pipe(s.check(s.isMinLength(1)), s.check(s.isMaxLength(256)))).pipe(s.check(s.isMinLength(2)), s.check(s.isMaxLength(64))),
+	ranks: s.Array(s.Number.pipe(s.check(s.isInt()), s.check(s.isBetween({
+		minimum: 1,
+		maximum: 64
+	})))).pipe(s.check(s.isMinLength(2)), s.check(s.isMaxLength(64)))
+});
+//#endregion
+export { m as PrepareRatingMatchSchema, u as RatingStateSchema, d as exactRatingState, f as resolveRatingPools };