@pickleball/expo-sdk 0.1.1

package/src/match/engine.ts

@@ -0,0 +1,702 @@
+import type {
+  CourtSide,
+  CourtSwitchConfirmedEvent,
+  GameSnapshot,
+  MatchCorrectedEvent,
+  MatchCorrection,
+  MatchCreateInput,
+  MatchCreatedEvent,
+  MatchCreation,
+  MatchEndedEvent,
+  MatchEvent,
+  MatchInputSource,
+  MatchSnapshot,
+  MatchTeam,
+  MatchTeamId,
+  PendingCourtSwitch,
+  RallyAwardedEvent,
+  ServeState,
+  TeamScore,
+} from "./contracts";
+import { cloneSnapshot, cloneTeam } from "./state";
+import {
+  assertRuntimeMatchEvent,
+  assertRuntimeMatchSnapshot,
+} from "./validation";
+
+const DEFAULT_TARGET_SCORE = 11;
+
+function oppositeTeam(teamId: MatchTeamId): MatchTeamId {
+  return teamId === "A" ? "B" : "A";
+}
+
+function oppositeSide(side: CourtSide): CourtSide {
+  return side === "left" ? "right" : "left";
+}
+
+function serviceSide(score: number): CourtSide {
+  return score % 2 === 0 ? "right" : "left";
+}
+
+function assertNonEmpty(value: string, label: string) {
+  if (value.trim().length === 0) throw new TypeError(`${label} must not be empty`);
+}
+
+function assertCreateInput(input: MatchCreateInput) {
+  assertNonEmpty(input.id, "Match id");
+  if (input.format !== "singles" && input.format !== "doubles") {
+    throw new TypeError("Invalid match format");
+  }
+  if (input.scoringMode !== "rally" && input.scoringMode !== "sideOut") {
+    throw new TypeError("Invalid scoring mode");
+  }
+  const target = input.targetScore ?? DEFAULT_TARGET_SCORE;
+  if (!Number.isInteger(target) || target < 1 || target > 99) {
+    throw new TypeError("Target score must be an integer from 1 to 99");
+  }
+  const expectedPlayers = input.format === "singles" ? 1 : 2;
+  const playerIds = new Set<string>();
+  for (const teamId of ["A", "B"] as const) {
+    const team = input.teams[teamId];
+    if (!team || team.id !== teamId || team.players.length !== expectedPlayers) {
+      throw new TypeError(`Team ${teamId} must have ${expectedPlayers} player(s)`);
+    }
+    if (team.name !== undefined) assertNonEmpty(team.name, `Team ${teamId} name`);
+    for (const player of team.players) {
+      assertNonEmpty(player.id, "Player id");
+      assertNonEmpty(player.name, "Player name");
+      if (playerIds.has(player.id)) throw new TypeError("Player ids must be unique");
+      playerIds.add(player.id);
+    }
+    if (
+      team.initialServerId !== undefined &&
+      !team.players.some((player) => player.id === team.initialServerId)
+    ) {
+      throw new TypeError(`Team ${teamId} initial server must belong to the team`);
+    }
+  }
+  if (
+    input.initialServingTeam !== undefined &&
+    input.initialServingTeam !== "A" &&
+    input.initialServingTeam !== "B"
+  ) {
+    throw new TypeError("Invalid initial serving team");
+  }
+}
+
+function initialPlayerCourts(
+  teams: Readonly<Record<MatchTeamId, MatchTeam>>,
+  designatedServerByTeam: Readonly<Record<MatchTeamId, string>>,
+): Record<string, CourtSide> {
+  const courts: Record<string, CourtSide> = {};
+  for (const teamId of ["A", "B"] as const) {
+    teams[teamId].players.forEach((player) => {
+      courts[player.id] =
+        player.id === designatedServerByTeam[teamId] ? "right" : "left";
+    });
+  }
+  return courts;
+}
+
+function gameNumber(value: number): 1 | 2 | 3 {
+  if (value !== 1 && value !== 2 && value !== 3) {
+    throw new TypeError("A best-of-three match cannot have another game");
+  }
+  return value;
+}
+
+function makeGame(
+  number: 1 | 2 | 3,
+  startingServingTeam: MatchTeamId,
+): GameSnapshot {
+  return {
+    number,
+    score: { A: 0, B: 0 },
+    startingServingTeam,
+    winner: null,
+    midGameSwitchCompleted: false,
+  };
+}
+
+function initialServe(
+  snapshot: Pick<
+    MatchSnapshot,
+    | "format"
+    | "scoringMode"
+    | "teams"
+    | "designatedServerByTeam"
+    | "playerCourts"
+  >,
+  teamId: MatchTeamId,
+): ServeState {
+  const playerId = snapshot.designatedServerByTeam[teamId];
+  return {
+    teamId,
+    playerId,
+    serverNumber:
+      snapshot.format === "doubles" && snapshot.scoringMode === "sideOut" ? 2 : 1,
+    court: snapshot.playerCourts[playerId],
+  };
+}
+
+function eventIdentity(snapshot: MatchSnapshot) {
+  const sequence = snapshot.sequence + 1;
+  return { schemaVersion: 1 as const, id: `${snapshot.id}:${sequence}`, sequence };
+}
+
+export function createMatch(
+  input: MatchCreateInput,
+  source: MatchInputSource = "system",
+): MatchCreation {
+  assertCreateInput(input);
+  const teams = { A: cloneTeam(input.teams.A), B: cloneTeam(input.teams.B) };
+  const designatedServerByTeam = {
+    A: teams.A.initialServerId ?? teams.A.players[0].id,
+    B: teams.B.initialServerId ?? teams.B.players[0].id,
+  };
+  const playerCourts = initialPlayerCourts(teams, designatedServerByTeam);
+  const initialServingTeam = input.initialServingTeam ?? "A";
+  const base = {
+    id: input.id,
+    format: input.format,
+    scoringMode: input.scoringMode,
+    targetScore: input.targetScore ?? DEFAULT_TARGET_SCORE,
+    bestOf: 3 as const,
+    teams,
+    designatedServerByTeam,
+    initialServingTeam,
+    courtSides: { left: "A", right: "B" } as const,
+    playerCourts,
+    games: [makeGame(1, initialServingTeam)],
+    currentGame: 1 as const,
+    gamesWon: { A: 0, B: 0 },
+    pendingCourtSwitch: null,
+    status: "inProgress" as const,
+    winner: null,
+    endReason: null,
+    sequence: 0,
+  };
+  const snapshot: MatchSnapshot = {
+    ...base,
+    serve: initialServe(base, initialServingTeam),
+  };
+  const event: MatchCreatedEvent = {
+    type: "matchCreated",
+    schemaVersion: 1,
+    id: `${snapshot.id}:0`,
+    sequence: 0,
+    source,
+    input,
+    snapshot: cloneSnapshot(snapshot),
+  };
+  return { snapshot, events: [event] };
+}
+
+function assertNextEvent(snapshot: MatchSnapshot, event: MatchEvent) {
+  if (event.sequence !== snapshot.sequence + 1) {
+    throw new TypeError("Match event sequence is not contiguous");
+  }
+  if (event.id !== `${snapshot.id}:${event.sequence}`) {
+    throw new TypeError("Match event id does not match its sequence");
+  }
+}
+
+function currentGame(snapshot: MatchSnapshot): GameSnapshot {
+  const game = snapshot.games[snapshot.currentGame - 1];
+  if (!game) throw new TypeError("Current game is missing");
+  return game;
+}
+
+function updateCurrentGame(
+  snapshot: MatchSnapshot,
+  update: (game: GameSnapshot) => GameSnapshot,
+): MatchSnapshot {
+  const games = snapshot.games.map((game, index) =>
+    index === snapshot.currentGame - 1 ? update(game) : game,
+  );
+  return { ...snapshot, games };
+}
+
+function playerOnCourt(
+  snapshot: MatchSnapshot,
+  teamId: MatchTeamId,
+  court: CourtSide,
+): string {
+  const player = snapshot.teams[teamId].players.find(
+    (candidate) => snapshot.playerCourts[candidate.id] === court,
+  );
+  if (!player) throw new TypeError(`Team ${teamId} has no player on ${court}`);
+  return player.id;
+}
+
+function swapTeamPlayers(
+  snapshot: MatchSnapshot,
+  teamId: MatchTeamId,
+): MatchSnapshot {
+  if (snapshot.format === "singles") return snapshot;
+  const playerCourts = { ...snapshot.playerCourts };
+  for (const player of snapshot.teams[teamId].players) {
+    playerCourts[player.id] = oppositeSide(playerCourts[player.id]);
+  }
+  return { ...snapshot, playerCourts };
+}
+
+function serveForPossession(
+  snapshot: MatchSnapshot,
+  teamId: MatchTeamId,
+  serverNumber: 1 | 2 = 1,
+): ServeState {
+  const score = currentGame(snapshot).score[teamId];
+  const court = serviceSide(score);
+  if (snapshot.format === "singles") {
+    return {
+      teamId,
+      playerId: snapshot.teams[teamId].players[0].id,
+      serverNumber: 1,
+      court,
+    };
+  }
+  return {
+    teamId,
+    playerId: playerOnCourt(snapshot, teamId, court),
+    serverNumber,
+    court,
+  };
+}
+
+function finishPoint(
+  snapshot: MatchSnapshot,
+  scoringTeam: MatchTeamId | null,
+): MatchSnapshot {
+  if (!scoringTeam) return snapshot;
+  const game = currentGame(snapshot);
+  if (game.score[scoringTeam] < snapshot.targetScore) {
+    if (
+      snapshot.currentGame === 3 &&
+      !game.midGameSwitchCompleted &&
+      game.score[scoringTeam] >= Math.ceil(snapshot.targetScore / 2)
+    ) {
+      return {
+        ...snapshot,
+        pendingCourtSwitch: { reason: "gameThreeMidpoint", game: 3 },
+      };
+    }
+    return snapshot;
+  }
+
+  let next = updateCurrentGame(snapshot, (value) => ({
+    ...value,
+    winner: scoringTeam,
+  }));
+  const gamesWon: TeamScore = {
+    ...next.gamesWon,
+    [scoringTeam]: next.gamesWon[scoringTeam] + 1,
+  };
+  next = { ...next, gamesWon };
+  if (gamesWon[scoringTeam] === 2) {
+    return {
+      ...next,
+      status: "completed",
+      winner: scoringTeam,
+      pendingCourtSwitch: null,
+    };
+  }
+  return {
+    ...next,
+    pendingCourtSwitch: {
+      reason: "gameEnd",
+      game: next.currentGame as 1 | 2,
+    },
+  };
+}
+
+function scorePoint(snapshot: MatchSnapshot, teamId: MatchTeamId): MatchSnapshot {
+  return updateCurrentGame(snapshot, (game) => ({
+    ...game,
+    score: { ...game.score, [teamId]: game.score[teamId] + 1 },
+  }));
+}
+
+function applyRally(
+  snapshot: MatchSnapshot,
+  winnerTeamId: MatchTeamId,
+): MatchSnapshot {
+  const servingTeam = snapshot.serve.teamId;
+  let next = snapshot;
+  let scoringTeam: MatchTeamId | null = null;
+
+  if (snapshot.scoringMode === "rally") {
+    scoringTeam = winnerTeamId;
+    next = scorePoint(next, winnerTeamId);
+    if (winnerTeamId === servingTeam) {
+      next = swapTeamPlayers(next, winnerTeamId);
+      next = {
+        ...next,
+        serve:
+          next.format === "singles"
+            ? serveForPossession(next, winnerTeamId)
+            : {
+                ...next.serve,
+                court: next.playerCourts[next.serve.playerId],
+              },
+      };
+    } else {
+      next = { ...next, serve: serveForPossession(next, winnerTeamId) };
+    }
+  } else if (winnerTeamId === servingTeam) {
+    scoringTeam = winnerTeamId;
+    next = scorePoint(next, winnerTeamId);
+    next = swapTeamPlayers(next, winnerTeamId);
+    next = {
+      ...next,
+      serve:
+        next.format === "singles"
+          ? serveForPossession(next, winnerTeamId)
+          : {
+              ...next.serve,
+              court: next.playerCourts[next.serve.playerId],
+            },
+    };
+  } else if (snapshot.format === "singles") {
+    next = { ...next, serve: serveForPossession(next, winnerTeamId) };
+  } else if (snapshot.serve.serverNumber === 1) {
+    const partner = snapshot.teams[servingTeam].players.find(
+      (player) => player.id !== snapshot.serve.playerId,
+    );
+    if (!partner) throw new TypeError("Doubles serving partner is missing");
+    next = {
+      ...next,
+      serve: {
+        teamId: servingTeam,
+        playerId: partner.id,
+        serverNumber: 2,
+        court: snapshot.playerCourts[partner.id],
+      },
+    };
+  } else {
+    next = { ...next, serve: serveForPossession(next, winnerTeamId, 1) };
+  }
+
+  return finishPoint(next, scoringTeam);
+}
+
+function assertPlayerCourts(snapshot: MatchSnapshot) {
+  const knownIds = new Set(
+    (["A", "B"] as const).flatMap((teamId) =>
+      snapshot.teams[teamId].players.map((player) => player.id),
+    ),
+  );
+  for (const [playerId, court] of Object.entries(snapshot.playerCourts)) {
+    if (!knownIds.has(playerId) || (court !== "left" && court !== "right")) {
+      throw new TypeError("Correction contains an invalid player court");
+    }
+  }
+  if (Object.keys(snapshot.playerCourts).length !== knownIds.size) {
+    throw new TypeError("Every player must have a court mapping");
+  }
+  if (snapshot.format === "doubles") {
+    for (const teamId of ["A", "B"] as const) {
+      const [first, second] = snapshot.teams[teamId].players;
+      if (snapshot.playerCourts[first.id] === snapshot.playerCourts[second.id]) {
+        throw new TypeError(`Team ${teamId} players must occupy different courts`);
+      }
+    }
+  }
+}
+
+function assertServe(snapshot: MatchSnapshot, serve: ServeState) {
+  const teamPlayerIds = snapshot.teams[serve.teamId].players.map((player) => player.id);
+  if (!teamPlayerIds.includes(serve.playerId)) {
+    throw new TypeError("Server must belong to the serving team");
+  }
+  if (serve.serverNumber !== 1 && serve.serverNumber !== 2) {
+    throw new TypeError("Server number must be one or two");
+  }
+  if (
+    snapshot.format === "singles" ||
+    (snapshot.format === "doubles" && snapshot.scoringMode === "rally")
+  ) {
+    if (serve.serverNumber !== 1) throw new TypeError("This mode has one server");
+  }
+  const expectedCourt =
+    snapshot.format === "singles"
+      ? serviceSide(currentGame(snapshot).score[serve.teamId])
+      : snapshot.playerCourts[serve.playerId];
+  if (serve.court !== expectedCourt) {
+    throw new TypeError("Service court does not match score/player position");
+  }
+  if (
+    snapshot.format === "doubles" &&
+    (snapshot.scoringMode === "rally" || serve.serverNumber === 1) &&
+    serve.court !== serviceSide(currentGame(snapshot).score[serve.teamId])
+  ) {
+    throw new TypeError("First server court does not match the serving team score");
+  }
+}
+
+function applyCorrection(
+  snapshot: MatchSnapshot,
+  correction: MatchCorrection,
+): MatchSnapshot {
+  const correctionKeys = Object.keys(correction);
+  if (
+    correctionKeys.length === 0 ||
+    correctionKeys.some(
+      (key) => key !== "score" && key !== "serve" && key !== "playerCourts",
+    ) ||
+    (correction.score === undefined &&
+      correction.serve === undefined &&
+      correction.playerCourts === undefined)
+  ) {
+    throw new TypeError("Correction must contain a supported patch");
+  }
+  if (snapshot.status !== "inProgress" || snapshot.pendingCourtSwitch) {
+    throw new TypeError("Only an active, unpaused match can be corrected");
+  }
+  let next = cloneSnapshot(snapshot);
+  const previousScore = currentGame(snapshot).score;
+  if (correction.playerCourts) {
+    next = {
+      ...next,
+      playerCourts: { ...next.playerCourts, ...correction.playerCourts },
+    };
+    assertPlayerCourts(next);
+  }
+  if (correction.score) {
+    if (Object.keys(correction.score).some((teamId) => teamId !== "A" && teamId !== "B")) {
+      throw new TypeError("Correction contains an invalid team score");
+    }
+    for (const value of Object.values(correction.score)) {
+      if (!Number.isInteger(value) || value! < 0 || value! > next.targetScore) {
+        throw new TypeError("Corrected scores must be non-negative integers up to target");
+      }
+    }
+    next = updateCurrentGame(next, (game) => ({
+      ...game,
+      score: { ...game.score, ...correction.score },
+    }));
+    const score = currentGame(next).score;
+    if (score.A === next.targetScore && score.B === next.targetScore) {
+      throw new TypeError("Both teams cannot have a winning score");
+    }
+  }
+  const correctedServingScore = correction.score?.[snapshot.serve.teamId];
+  const servingTeamCourtsPatched = snapshot.teams[snapshot.serve.teamId].players.some(
+    (player) => correction.playerCourts?.[player.id] !== undefined,
+  );
+  if (
+    next.format === "doubles" &&
+    correctedServingScore !== undefined &&
+    correctedServingScore % 2 !== previousScore[snapshot.serve.teamId] % 2
+  ) {
+    if (servingTeamCourtsPatched) {
+      const hasExpectedRotation = snapshot.teams[snapshot.serve.teamId].players.every(
+        (player) =>
+          next.playerCourts[player.id] === oppositeSide(snapshot.playerCourts[player.id]),
+      );
+      if (!hasExpectedRotation) {
+        throw new TypeError("Corrected serving positions do not match the score change");
+      }
+    } else {
+      next = swapTeamPlayers(next, snapshot.serve.teamId);
+      next = {
+        ...next,
+        serve: { ...next.serve, court: next.playerCourts[next.serve.playerId] },
+      };
+    }
+  }
+  if (correction.serve) {
+    assertServe(next, correction.serve);
+    next = { ...next, serve: { ...correction.serve } };
+  } else if (correction.playerCourts?.[next.serve.playerId]) {
+    next = {
+      ...next,
+      serve: { ...next.serve, court: next.playerCourts[next.serve.playerId] },
+    };
+  } else if (correction.score && next.format === "singles") {
+    next = { ...next, serve: serveForPossession(next, next.serve.teamId) };
+  }
+  assertServe(next, next.serve);
+
+  const score = currentGame(next).score;
+  const winningTeam =
+    score.A === next.targetScore ? "A" : score.B === next.targetScore ? "B" : null;
+  const midpoint = Math.ceil(next.targetScore / 2);
+  const midpointTeam = score.A >= midpoint ? "A" : score.B >= midpoint ? "B" : null;
+  return finishPoint(next, winningTeam ?? midpointTeam);
+}
+
+export function applyMatchEvent(
+  snapshot: MatchSnapshot,
+  event: MatchEvent,
+): MatchSnapshot {
+  assertRuntimeMatchSnapshot(snapshot);
+  assertRuntimeMatchEvent(event);
+  if (event.type === "matchCreated") {
+    throw new TypeError("A creation event can only begin an event log");
+  }
+  assertNextEvent(snapshot, event);
+  let next: MatchSnapshot;
+  switch (event.type) {
+    case "rallyAwarded":
+      if (snapshot.status !== "inProgress" || snapshot.pendingCourtSwitch) {
+        throw new TypeError("A paused or terminal match cannot accept a rally");
+      }
+      if (snapshot.courtSides[event.displaySide] !== event.winnerTeamId) {
+        throw new TypeError("Rally display side does not map to its winning team");
+      }
+      next = applyRally(cloneSnapshot(snapshot), event.winnerTeamId);
+      break;
+    case "courtSwitchConfirmed": {
+      if (
+        snapshot.status !== "inProgress" ||
+        !snapshot.pendingCourtSwitch ||
+        JSON.stringify(snapshot.pendingCourtSwitch) !== JSON.stringify(event.pending)
+      ) {
+        throw new TypeError("No matching court switch is pending");
+      }
+      next = {
+        ...cloneSnapshot(snapshot),
+        courtSides: {
+          left: snapshot.courtSides.right,
+          right: snapshot.courtSides.left,
+        },
+        pendingCourtSwitch: null,
+      };
+      if (event.pending.reason === "gameThreeMidpoint") {
+        next = updateCurrentGame(next, (game) => ({
+          ...game,
+          midGameSwitchCompleted: true,
+        }));
+      } else {
+        const nextNumber = gameNumber(snapshot.currentGame + 1);
+        const startingServingTeam =
+          nextNumber % 2 === 1
+            ? snapshot.initialServingTeam
+            : oppositeTeam(snapshot.initialServingTeam);
+        const playerCourts = initialPlayerCourts(
+          snapshot.teams,
+          snapshot.designatedServerByTeam,
+        );
+        const withoutServe = {
+          ...next,
+          playerCourts,
+          games: [...next.games, makeGame(nextNumber, startingServingTeam)],
+          currentGame: nextNumber,
+        };
+        next = {
+          ...withoutServe,
+          serve: initialServe(withoutServe, startingServingTeam),
+        };
+      }
+      break;
+    }
+    case "matchCorrected":
+      next = applyCorrection(snapshot, event.correction);
+      break;
+    case "matchEnded":
+      if (snapshot.status !== "inProgress") {
+        throw new TypeError("Match is already terminal");
+      }
+      next = {
+        ...cloneSnapshot(snapshot),
+        status: "ended",
+        winner: null,
+        endReason: event.reason,
+        pendingCourtSwitch: null,
+      };
+      break;
+    case "matchEventUndone":
+      if (
+        event.restoredSnapshot.id !== snapshot.id ||
+        !event.targetEventId.startsWith(`${snapshot.id}:`)
+      ) {
+        throw new TypeError("Undo payload belongs to a different match");
+      }
+      const targetSequence = Number(event.targetEventId.slice(snapshot.id.length + 1));
+      if (
+        !Number.isInteger(targetSequence) ||
+        targetSequence < 1 ||
+        targetSequence >= event.sequence ||
+        event.restoredSnapshot.sequence !== targetSequence - 1
+      ) {
+        throw new TypeError("Undo payload has an invalid target lineage");
+      }
+      next = cloneSnapshot(event.restoredSnapshot);
+      break;
+    default:
+      throw new TypeError("Unknown match event type");
+  }
+  const result = { ...next, sequence: event.sequence };
+  assertRuntimeMatchSnapshot(result);
+  return result;
+}
+
+export function awardRally(
+  snapshot: MatchSnapshot,
+  displaySide: CourtSide,
+  source: MatchInputSource = "local",
+): RallyAwardedEvent | null {
+  if (snapshot.status !== "inProgress" || snapshot.pendingCourtSwitch) return null;
+  if (displaySide !== "left" && displaySide !== "right") {
+    throw new TypeError("Invalid display side");
+  }
+  return {
+    type: "rallyAwarded",
+    ...eventIdentity(snapshot),
+    source,
+    displaySide,
+    winnerTeamId: snapshot.courtSides[displaySide],
+  };
+}
+
+export function confirmCourtSwitch(
+  snapshot: MatchSnapshot,
+  source: MatchInputSource = "local",
+): CourtSwitchConfirmedEvent {
+  if (snapshot.status !== "inProgress" || !snapshot.pendingCourtSwitch) {
+    throw new TypeError("No court switch is pending");
+  }
+  return {
+    type: "courtSwitchConfirmed",
+    ...eventIdentity(snapshot),
+    source,
+    pending: { ...snapshot.pendingCourtSwitch } as PendingCourtSwitch,
+  };
+}
+
+export function correctMatch(
+  snapshot: MatchSnapshot,
+  correction: MatchCorrection,
+  source: MatchInputSource = "local",
+): MatchCorrectedEvent {
+  const event: MatchCorrectedEvent = {
+    type: "matchCorrected",
+    ...eventIdentity(snapshot),
+    source,
+    correction: {
+      ...(correction.score ? { score: { ...correction.score } } : {}),
+      ...(correction.serve ? { serve: { ...correction.serve } } : {}),
+      ...(correction.playerCourts
+        ? { playerCourts: { ...correction.playerCourts } }
+        : {}),
+    },
+  };
+  applyMatchEvent(snapshot, event);
+  return event;
+}
+
+export function endMatch(
+  snapshot: MatchSnapshot,
+  reason: string,
+  source: MatchInputSource = "local",
+): MatchEndedEvent {
+  assertNonEmpty(reason, "End reason");
+  if (snapshot.status !== "inProgress") throw new TypeError("Match is already terminal");
+  return {
+    type: "matchEnded",
+    ...eventIdentity(snapshot),
+    source,
+    reason,
+  };
+}