feat: add double elimination match mode

This commit is contained in:
dahyeon committed 2026-06-26 05:00:08 -07:00
1 parent b9aaf55193
commit e12f182e7f
19 files changed
+3415 -58

No files matched your search

@@ -0,0 +1,672 @@
import type mongoose from 'mongoose';
export type DoubleEliminationBracketSide =
| 'winner'
| 'loser'
| 'grand-final'
| 'reset-final';
export type DoubleEliminationBracketMatchState =
| 'pending'
| 'ready'
| 'completed';
export type DoubleEliminationCompletionType = 'riot-result' | 'walkover';
export interface DoubleEliminationSeed {
seedNumber: number;
teamIndex: number;
}
export interface DoubleEliminationBracketMatchSource {
type: 'seed' | 'winner' | 'loser';
seedNumber?: number;
bracketMatchId?: string;
}
export interface DoubleEliminationBracketMatchDestination {
bracketMatchId: string;
position: 'A' | 'B';
}
export interface DoubleEliminationWalkover {
winnerTeamIndex: number;
reason?: string;
awardedBy?: mongoose.Types.ObjectId;
awardedAt: Date;
cancelledBy?: mongoose.Types.ObjectId;
cancelledAt?: Date;
cancelReason?: string;
active: boolean;
}
export interface DoubleEliminationBracketMatch {
bracketMatchId: string;
gameNumber: number;
bracketSide: DoubleEliminationBracketSide;
roundNumber: number;
matchNumber: number;
state: DoubleEliminationBracketMatchState;
teamAIndex?: number;
teamBIndex?: number;
teamASource?: DoubleEliminationBracketMatchSource;
teamBSource?: DoubleEliminationBracketMatchSource;
winnerAdvancesTo?: DoubleEliminationBracketMatchDestination;
loserAdvancesTo?: DoubleEliminationBracketMatchDestination;
winnerTeamIndex?: number;
loserTeamIndex?: number;
completedBy?: DoubleEliminationCompletionType;
completedAt?: Date;
walkover?: DoubleEliminationWalkover;
}
export interface DoubleEliminationPlacements {
firstTeamIndex?: number;
secondTeamIndex?: number;
thirdTeamIndex?: number;
}
export interface DoubleEliminationEvent {
type:
| 'bracket-created'
| 'seeds-reshuffled'
| 'seeds-swapped'
| 'bracket-match-completed'
| 'bracket-match-cancelled'
| 'walkover-awarded'
| 'walkover-cancelled'
| 'reset-final-created'
| 'riot-result-cancelled';
bracketMatchId?: string;
actorUserId?: mongoose.Types.ObjectId;
reason?: string;
createdAt: Date;
}
export interface DoubleEliminationBracket {
teamCount: 4 | 8;
resetFinalEnabled: boolean;
resetFinalCreated: boolean;
seeds: DoubleEliminationSeed[];
bracketMatches: DoubleEliminationBracketMatch[];
placements: DoubleEliminationPlacements;
events: DoubleEliminationEvent[];
}
export interface BuildDoubleEliminationBracketOptions {
resetFinalEnabled: boolean;
}
export interface CompleteDoubleEliminationBracketMatchParams {
bracketMatchId: string;
winnerTeamIndex: number;
completedBy: DoubleEliminationCompletionType;
completedAt?: Date;
walkover?: DoubleEliminationWalkover;
}
export interface CancelDoubleEliminationBracketMatchParams {
bracketMatchId: string;
cancelledBy?: mongoose.Types.ObjectId;
cancelReason?: string;
}
export function buildDoubleEliminationBracket(
seededTeamIndexes: number[],
options: BuildDoubleEliminationBracketOptions,
): DoubleEliminationBracket {
assertSupportedTeamCount(seededTeamIndexes.length);
const seeds = seededTeamIndexes.map((teamIndex, index) => ({
seedNumber: index + 1,
teamIndex,
}));
const bracket: DoubleEliminationBracket = {
teamCount: seededTeamIndexes.length as 4 | 8,
resetFinalEnabled: options.resetFinalEnabled,
resetFinalCreated: false,
seeds,
bracketMatches:
seededTeamIndexes.length === 4
? buildFourTeamBracketMatches()
: buildEightTeamBracketMatches(),
placements: {},
events: [
{
type: 'bracket-created',
createdAt: new Date(),
},
],
};
applySeedTeams(bracket);
refreshBracketMatchStates(bracket);
return bracket;
}
export function reshuffleDoubleEliminationSeeds(
bracket: DoubleEliminationBracket,
rng: () => number = Math.random,
): DoubleEliminationBracket {
assertSeedChangeAllowed(bracket);
const teamIndexes = shuffleInPlace(
bracket.seeds.map((seed) => seed.teamIndex),
rng,
);
return rebuildWithSeeds(bracket, teamIndexes, 'seeds-reshuffled');
}
export function swapDoubleEliminationSeeds(
bracket: DoubleEliminationBracket,
params: { leftSeedNumber: number; rightSeedNumber: number },
): DoubleEliminationBracket {
assertSeedChangeAllowed(bracket);
const teamIndexes = [...bracket.seeds]
.sort((left, right) => left.seedNumber - right.seedNumber)
.map((seed) => seed.teamIndex);
const leftIndex = params.leftSeedNumber - 1;
const rightIndex = params.rightSeedNumber - 1;
if (!teamIndexes[leftIndex] || !teamIndexes[rightIndex]) {
throw new Error('Invalid seed number.');
}
[teamIndexes[leftIndex], teamIndexes[rightIndex]] = [
teamIndexes[rightIndex],
teamIndexes[leftIndex],
];
return rebuildWithSeeds(bracket, teamIndexes, 'seeds-swapped');
}
export function completeDoubleEliminationBracketMatch(
bracket: DoubleEliminationBracket,
params: CompleteDoubleEliminationBracketMatchParams,
): DoubleEliminationBracket {
const next = cloneBracket(bracket);
const bracketMatch = requireBracketMatch(next, params.bracketMatchId);
if (bracketMatch.state !== 'ready') {
throw new Error('Bracket match is not ready.');
}
if (
bracketMatch.teamAIndex !== params.winnerTeamIndex &&
bracketMatch.teamBIndex !== params.winnerTeamIndex
) {
throw new Error('Winner team is not assigned to this bracket match.');
}
const loserTeamIndex =
bracketMatch.teamAIndex === params.winnerTeamIndex
? bracketMatch.teamBIndex
: bracketMatch.teamAIndex;
if (!loserTeamIndex) throw new Error('Loser team is missing.');
bracketMatch.state = 'completed';
bracketMatch.winnerTeamIndex = params.winnerTeamIndex;
bracketMatch.loserTeamIndex = loserTeamIndex;
bracketMatch.completedBy = params.completedBy;
bracketMatch.completedAt = params.completedAt ?? new Date();
if (params.walkover) {
bracketMatch.walkover = params.walkover;
}
advanceTeam(next, bracketMatch.winnerAdvancesTo, params.winnerTeamIndex);
advanceTeam(next, bracketMatch.loserAdvancesTo, loserTeamIndex);
if (bracketMatch.bracketMatchId === 'LB_FINAL') {
next.placements.thirdTeamIndex = loserTeamIndex;
}
if (bracketMatch.bracketMatchId === 'GF') {
completeGrandFinal(next, bracketMatch);
}
if (bracketMatch.bracketMatchId === 'GF_RESET') {
next.placements.firstTeamIndex = params.winnerTeamIndex;
next.placements.secondTeamIndex = loserTeamIndex;
}
refreshBracketMatchStates(next);
next.events.push({
type:
params.completedBy === 'walkover'
? 'walkover-awarded'
: 'bracket-match-completed',
bracketMatchId: bracketMatch.bracketMatchId,
createdAt: bracketMatch.completedAt,
});
return next;
}
export function cancelDoubleEliminationBracketMatch(
bracket: DoubleEliminationBracket,
params: CancelDoubleEliminationBracketMatchParams,
): DoubleEliminationBracket {
const next = cloneBracket(bracket);
const bracketMatch = requireBracketMatch(next, params.bracketMatchId);
if (bracketMatch.state !== 'completed') {
throw new Error('Bracket match is not completed.');
}
const descendants = collectDescendantBracketMatchIds(
next,
bracketMatch.bracketMatchId,
);
const completedDescendant = next.bracketMatches.find(
(match) => descendants.has(match.bracketMatchId) && match.state === 'completed',
);
if (completedDescendant) {
throw new Error('Cannot cancel because a downstream bracket match is completed.');
}
if (bracketMatch.bracketMatchId === 'GF') {
next.bracketMatches = next.bracketMatches.filter(
(match) => match.bracketMatchId !== 'GF_RESET',
);
next.resetFinalCreated = false;
}
for (const descendantId of descendants) {
const descendant = next.bracketMatches.find(
(match) => match.bracketMatchId === descendantId,
);
if (!descendant) continue;
if (referencesBracketMatch(descendant.teamASource, bracketMatch.bracketMatchId)) {
descendant.teamAIndex = undefined;
}
if (referencesBracketMatch(descendant.teamBSource, bracketMatch.bracketMatchId)) {
descendant.teamBIndex = undefined;
}
descendant.winnerTeamIndex = undefined;
descendant.loserTeamIndex = undefined;
descendant.completedBy = undefined;
descendant.completedAt = undefined;
}
bracketMatch.winnerTeamIndex = undefined;
bracketMatch.loserTeamIndex = undefined;
bracketMatch.completedBy = undefined;
bracketMatch.completedAt = undefined;
if (bracketMatch.walkover?.active) {
bracketMatch.walkover = {
...bracketMatch.walkover,
active: false,
cancelledBy: params.cancelledBy,
cancelledAt: new Date(),
cancelReason: params.cancelReason,
};
}
next.placements = {};
refreshBracketMatchStates(next);
next.events.push({
type:
bracketMatch.walkover && !bracketMatch.walkover.active
? 'walkover-cancelled'
: 'bracket-match-cancelled',
bracketMatchId: bracketMatch.bracketMatchId,
actorUserId: params.cancelledBy,
reason: params.cancelReason,
createdAt: new Date(),
});
return next;
}
export function findNextReadyDoubleEliminationBracketMatches(
bracket: DoubleEliminationBracket | undefined,
): DoubleEliminationBracketMatch[] {
return (bracket?.bracketMatches ?? []).filter(
(bracketMatch) => bracketMatch.state === 'ready',
);
}
export function hasCompletedDoubleEliminationBracketMatches(
bracket: DoubleEliminationBracket | undefined,
): boolean {
return Boolean(
bracket?.bracketMatches.some(
(bracketMatch) => bracketMatch.state === 'completed',
),
);
}
function rebuildWithSeeds(
bracket: DoubleEliminationBracket,
teamIndexes: number[],
eventType: DoubleEliminationEvent['type'],
): DoubleEliminationBracket {
const next = buildDoubleEliminationBracket(teamIndexes, {
resetFinalEnabled: bracket.resetFinalEnabled,
});
next.events = [
...bracket.events,
{
type: eventType,
createdAt: new Date(),
},
];
return next;
}
function completeGrandFinal(
bracket: DoubleEliminationBracket,
grandFinal: DoubleEliminationBracketMatch,
): void {
if (!grandFinal.winnerTeamIndex || !grandFinal.loserTeamIndex) return;
const winnerBracketTeamIndex = grandFinal.teamAIndex;
if (
bracket.resetFinalEnabled &&
!bracket.resetFinalCreated &&
grandFinal.winnerTeamIndex !== winnerBracketTeamIndex
) {
bracket.resetFinalCreated = true;
bracket.bracketMatches.push({
bracketMatchId: 'GF_RESET',
gameNumber: nextGameNumber(bracket),
bracketSide: 'reset-final',
roundNumber: 1,
matchNumber: 1,
state: 'ready',
teamAIndex: grandFinal.teamAIndex,
teamBIndex: grandFinal.teamBIndex,
teamASource: { type: 'winner', bracketMatchId: 'GF' },
teamBSource: { type: 'loser', bracketMatchId: 'GF' },
});
bracket.events.push({
type: 'reset-final-created',
bracketMatchId: 'GF_RESET',
createdAt: new Date(),
});
return;
}
bracket.placements.firstTeamIndex = grandFinal.winnerTeamIndex;
bracket.placements.secondTeamIndex = grandFinal.loserTeamIndex;
}
function advanceTeam(
bracket: DoubleEliminationBracket,
destination: DoubleEliminationBracketMatchDestination | undefined,
teamIndex: number,
): void {
if (!destination) return;
const target = requireBracketMatch(bracket, destination.bracketMatchId);
if (destination.position === 'A') {
target.teamAIndex = teamIndex;
} else {
target.teamBIndex = teamIndex;
}
}
function refreshBracketMatchStates(bracket: DoubleEliminationBracket): void {
for (const bracketMatch of bracket.bracketMatches) {
if (bracketMatch.winnerTeamIndex) {
bracketMatch.state = 'completed';
continue;
}
bracketMatch.state =
bracketMatch.teamAIndex && bracketMatch.teamBIndex ? 'ready' : 'pending';
}
}
function applySeedTeams(bracket: DoubleEliminationBracket): void {
const bySeedNumber = new Map(
bracket.seeds.map((seed) => [seed.seedNumber, seed.teamIndex]),
);
for (const bracketMatch of bracket.bracketMatches) {
if (bracketMatch.teamASource?.type === 'seed') {
bracketMatch.teamAIndex = bySeedNumber.get(
bracketMatch.teamASource.seedNumber ?? 0,
);
}
if (bracketMatch.teamBSource?.type === 'seed') {
bracketMatch.teamBIndex = bySeedNumber.get(
bracketMatch.teamBSource.seedNumber ?? 0,
);
}
}
}
function buildFourTeamBracketMatches(): DoubleEliminationBracketMatch[] {
return [
bracketMatch('WB_R1_M1', 1, 'winner', 1, 1, {
teamASource: seedSource(1),
teamBSource: seedSource(4),
winnerAdvancesTo: destination('WB_FINAL', 'A'),
loserAdvancesTo: destination('LB_R1_M1', 'A'),
}),
bracketMatch('WB_R1_M2', 2, 'winner', 1, 2, {
teamASource: seedSource(2),
teamBSource: seedSource(3),
winnerAdvancesTo: destination('WB_FINAL', 'B'),
loserAdvancesTo: destination('LB_R1_M1', 'B'),
}),
bracketMatch('WB_FINAL', 3, 'winner', 2, 1, {
teamASource: winnerSource('WB_R1_M1'),
teamBSource: winnerSource('WB_R1_M2'),
winnerAdvancesTo: destination('GF', 'A'),
loserAdvancesTo: destination('LB_FINAL', 'B'),
}),
bracketMatch('LB_R1_M1', 4, 'loser', 1, 1, {
teamASource: loserSource('WB_R1_M1'),
teamBSource: loserSource('WB_R1_M2'),
winnerAdvancesTo: destination('LB_FINAL', 'A'),
}),
bracketMatch('LB_FINAL', 5, 'loser', 2, 1, {
teamASource: winnerSource('LB_R1_M1'),
teamBSource: loserSource('WB_FINAL'),
winnerAdvancesTo: destination('GF', 'B'),
}),
bracketMatch('GF', 6, 'grand-final', 1, 1, {
teamASource: winnerSource('WB_FINAL'),
teamBSource: winnerSource('LB_FINAL'),
}),
];
}
function buildEightTeamBracketMatches(): DoubleEliminationBracketMatch[] {
return [
bracketMatch('WB_R1_M1', 1, 'winner', 1, 1, {
teamASource: seedSource(1),
teamBSource: seedSource(8),
winnerAdvancesTo: destination('WB_R2_M1', 'A'),
loserAdvancesTo: destination('LB_R1_M1', 'A'),
}),
bracketMatch('WB_R1_M2', 2, 'winner', 1, 2, {
teamASource: seedSource(4),
teamBSource: seedSource(5),
winnerAdvancesTo: destination('WB_R2_M1', 'B'),
loserAdvancesTo: destination('LB_R1_M1', 'B'),
}),
bracketMatch('WB_R1_M3', 3, 'winner', 1, 3, {
teamASource: seedSource(2),
teamBSource: seedSource(7),
winnerAdvancesTo: destination('WB_R2_M2', 'A'),
loserAdvancesTo: destination('LB_R1_M2', 'A'),
}),
bracketMatch('WB_R1_M4', 4, 'winner', 1, 4, {
teamASource: seedSource(3),
teamBSource: seedSource(6),
winnerAdvancesTo: destination('WB_R2_M2', 'B'),
loserAdvancesTo: destination('LB_R1_M2', 'B'),
}),
bracketMatch('WB_R2_M1', 5, 'winner', 2, 1, {
teamASource: winnerSource('WB_R1_M1'),
teamBSource: winnerSource('WB_R1_M2'),
winnerAdvancesTo: destination('WB_FINAL', 'A'),
loserAdvancesTo: destination('LB_R2_M2', 'B'),
}),
bracketMatch('WB_R2_M2', 6, 'winner', 2, 2, {
teamASource: winnerSource('WB_R1_M3'),
teamBSource: winnerSource('WB_R1_M4'),
winnerAdvancesTo: destination('WB_FINAL', 'B'),
loserAdvancesTo: destination('LB_R2_M1', 'B'),
}),
bracketMatch('WB_FINAL', 7, 'winner', 3, 1, {
teamASource: winnerSource('WB_R2_M1'),
teamBSource: winnerSource('WB_R2_M2'),
winnerAdvancesTo: destination('GF', 'A'),
loserAdvancesTo: destination('LB_FINAL', 'B'),
}),
bracketMatch('LB_R1_M1', 8, 'loser', 1, 1, {
teamASource: loserSource('WB_R1_M1'),
teamBSource: loserSource('WB_R1_M2'),
winnerAdvancesTo: destination('LB_R2_M1', 'A'),
}),
bracketMatch('LB_R1_M2', 9, 'loser', 1, 2, {
teamASource: loserSource('WB_R1_M3'),
teamBSource: loserSource('WB_R1_M4'),
winnerAdvancesTo: destination('LB_R2_M2', 'A'),
}),
bracketMatch('LB_R2_M1', 10, 'loser', 2, 1, {
teamASource: winnerSource('LB_R1_M1'),
teamBSource: loserSource('WB_R2_M2'),
winnerAdvancesTo: destination('LB_R3_M1', 'A'),
}),
bracketMatch('LB_R2_M2', 11, 'loser', 2, 2, {
teamASource: winnerSource('LB_R1_M2'),
teamBSource: loserSource('WB_R2_M1'),
winnerAdvancesTo: destination('LB_R3_M1', 'B'),
}),
bracketMatch('LB_R3_M1', 12, 'loser', 3, 1, {
teamASource: winnerSource('LB_R2_M1'),
teamBSource: winnerSource('LB_R2_M2'),
winnerAdvancesTo: destination('LB_FINAL', 'A'),
}),
bracketMatch('LB_FINAL', 13, 'loser', 4, 1, {
teamASource: winnerSource('LB_R3_M1'),
teamBSource: loserSource('WB_FINAL'),
winnerAdvancesTo: destination('GF', 'B'),
}),
bracketMatch('GF', 14, 'grand-final', 1, 1, {
teamASource: winnerSource('WB_FINAL'),
teamBSource: winnerSource('LB_FINAL'),
}),
];
}
function bracketMatch(
bracketMatchId: string,
gameNumber: number,
bracketSide: DoubleEliminationBracketSide,
roundNumber: number,
matchNumber: number,
params: Partial<DoubleEliminationBracketMatch>,
): DoubleEliminationBracketMatch {
return {
bracketMatchId,
gameNumber,
bracketSide,
roundNumber,
matchNumber,
state: 'pending',
...params,
};
}
function seedSource(seedNumber: number): DoubleEliminationBracketMatchSource {
return { type: 'seed', seedNumber };
}
function winnerSource(
bracketMatchId: string,
): DoubleEliminationBracketMatchSource {
return { type: 'winner', bracketMatchId };
}
function loserSource(
bracketMatchId: string,
): DoubleEliminationBracketMatchSource {
return { type: 'loser', bracketMatchId };
}
function destination(
bracketMatchId: string,
position: 'A' | 'B',
): DoubleEliminationBracketMatchDestination {
return { bracketMatchId, position };
}
function collectDescendantBracketMatchIds(
bracket: DoubleEliminationBracket,
bracketMatchId: string,
): Set<string> {
const descendants = new Set<string>();
let changed = true;
while (changed) {
changed = false;
for (const match of bracket.bracketMatches) {
const sourceIds = [
match.teamASource?.bracketMatchId,
match.teamBSource?.bracketMatchId,
].filter((id): id is string => Boolean(id));
if (
sourceIds.some((id) => id === bracketMatchId || descendants.has(id)) &&
!descendants.has(match.bracketMatchId)
) {
descendants.add(match.bracketMatchId);
changed = true;
}
}
}
return descendants;
}
function referencesBracketMatch(
source: DoubleEliminationBracketMatchSource | undefined,
bracketMatchId: string,
): boolean {
return source?.bracketMatchId === bracketMatchId;
}
function requireBracketMatch(
bracket: DoubleEliminationBracket,
bracketMatchId: string,
): DoubleEliminationBracketMatch {
const bracketMatch = bracket.bracketMatches.find(
(match) => match.bracketMatchId === bracketMatchId,
);
if (!bracketMatch) throw new Error('Bracket match not found.');
return bracketMatch;
}
function assertSeedChangeAllowed(bracket: DoubleEliminationBracket): void {
if (hasCompletedDoubleEliminationBracketMatches(bracket)) {
throw new Error('Cannot change seeds after a bracket match is completed.');
}
}
function assertSupportedTeamCount(teamCount: number): asserts teamCount is 4 | 8 {
if (teamCount !== 4 && teamCount !== 8) {
throw new Error('Double elimination supports only 4 or 8 teams.');
}
}
function nextGameNumber(bracket: DoubleEliminationBracket): number {
return Math.max(...bracket.bracketMatches.map((match) => match.gameNumber)) + 1;
}
function cloneBracket(
bracket: DoubleEliminationBracket,
): DoubleEliminationBracket {
return {
...bracket,
seeds: bracket.seeds.map((seed) => ({ ...seed })),
bracketMatches: bracket.bracketMatches.map((match) => ({
...match,
teamASource: match.teamASource ? { ...match.teamASource } : undefined,
teamBSource: match.teamBSource ? { ...match.teamBSource } : undefined,
winnerAdvancesTo: match.winnerAdvancesTo
? { ...match.winnerAdvancesTo }
: undefined,
loserAdvancesTo: match.loserAdvancesTo
? { ...match.loserAdvancesTo }
: undefined,
walkover: match.walkover ? { ...match.walkover } : undefined,
})),
placements: { ...bracket.placements },
events: bracket.events.map((event) => ({ ...event })),
};
}
function shuffleInPlace<T>(
items: T[],
rng: () => number = Math.random,
): T[] {
for (let index = items.length - 1; index > 0; index -= 1) {
const swapIndex = Math.floor(rng() * (index + 1));
[items[index], items[swapIndex]] = [items[swapIndex], items[index]];
}
return items;
}