@pickleball/expo-sdk 0.1.1

package/src/match/validation.ts

@@ -0,0 +1,375 @@
+import type {
+  CourtSide,
+  MatchEvent,
+  MatchFormat,
+  MatchInputSource,
+  MatchScoringMode,
+  MatchSnapshot,
+  MatchTeamId,
+} from "./contracts";
+
+const TEAM_IDS = ["A", "B"] as const;
+const COURT_SIDES = ["left", "right"] as const;
+const INPUT_SOURCES = ["local", "remote", "voice", "ble", "system"] as const;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function assertRecord(value: unknown, label: string): asserts value is Record<string, unknown> {
+  if (!isRecord(value)) throw new TypeError(`${label} must be an object`);
+}
+
+function assertNonEmptyString(value: unknown, label: string): asserts value is string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new TypeError(`${label} must be a non-empty string`);
+  }
+}
+
+function assertInteger(value: unknown, minimum: number, maximum: number, label: string) {
+  if (!Number.isInteger(value) || (value as number) < minimum || (value as number) > maximum) {
+    throw new TypeError(`${label} must be an integer from ${minimum} to ${maximum}`);
+  }
+}
+
+function isTeamId(value: unknown): value is MatchTeamId {
+  return value === "A" || value === "B";
+}
+
+function isCourtSide(value: unknown): value is CourtSide {
+  return value === "left" || value === "right";
+}
+
+function isFormat(value: unknown): value is MatchFormat {
+  return value === "singles" || value === "doubles";
+}
+
+function isScoringMode(value: unknown): value is MatchScoringMode {
+  return value === "rally" || value === "sideOut";
+}
+
+function isSource(value: unknown): value is MatchInputSource {
+  return INPUT_SOURCES.some((source) => source === value);
+}
+
+function assertRecordKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+  label: string,
+) {
+  if (Object.keys(value).some((key) => !allowed.includes(key))) {
+    throw new TypeError(`${label} contains an unknown field`);
+  }
+}
+
+function assertPendingSwitch(
+  value: unknown,
+): asserts value is
+  | { reason: "gameEnd"; game: 1 | 2 }
+  | { reason: "gameThreeMidpoint"; game: 3 } {
+  assertRecord(value, "Pending court switch");
+  if (value.reason === "gameEnd") {
+    if (value.game !== 1 && value.game !== 2) {
+      throw new TypeError("Game-end switch must follow game one or two");
+    }
+  } else if (value.reason === "gameThreeMidpoint") {
+    if (value.game !== 3) throw new TypeError("Midpoint switch must be in game three");
+  } else {
+    throw new TypeError("Invalid pending court switch reason");
+  }
+}
+
+export function assertRuntimeMatchSnapshot(
+  value: unknown,
+): asserts value is MatchSnapshot {
+  assertRecord(value, "Match snapshot");
+  assertNonEmptyString(value.id, "Match id");
+  if (!isFormat(value.format)) throw new TypeError("Invalid match format");
+  if (!isScoringMode(value.scoringMode)) throw new TypeError("Invalid scoring mode");
+  assertInteger(value.targetScore, 1, 99, "Target score");
+  if (value.bestOf !== 3) throw new TypeError("Match must be best-of-three");
+  if (!isTeamId(value.initialServingTeam)) {
+    throw new TypeError("Invalid initial serving team");
+  }
+  assertInteger(value.sequence, 0, Number.MAX_SAFE_INTEGER, "Match sequence");
+
+  assertRecord(value.teams, "Teams");
+  assertRecordKeys(value.teams, TEAM_IDS, "Teams");
+  const expectedPlayers = value.format === "singles" ? 1 : 2;
+  const playerIds = new Set<string>();
+  const teamPlayerIds: Record<MatchTeamId, string[]> = { A: [], B: [] };
+  for (const teamId of TEAM_IDS) {
+    const team = value.teams[teamId];
+    assertRecord(team, `Team ${teamId}`);
+    if (team.id !== teamId || !Array.isArray(team.players) || team.players.length !== expectedPlayers) {
+      throw new TypeError(`Team ${teamId} roster is invalid`);
+    }
+    if (team.name !== undefined) assertNonEmptyString(team.name, `Team ${teamId} name`);
+    for (const rawPlayer of team.players) {
+      assertRecord(rawPlayer, "Player");
+      assertNonEmptyString(rawPlayer.id, "Player id");
+      assertNonEmptyString(rawPlayer.name, "Player name");
+      if (playerIds.has(rawPlayer.id)) throw new TypeError("Player ids must be unique");
+      playerIds.add(rawPlayer.id);
+      teamPlayerIds[teamId].push(rawPlayer.id);
+    }
+    if (
+      team.initialServerId !== undefined &&
+      !teamPlayerIds[teamId].includes(team.initialServerId as string)
+    ) {
+      throw new TypeError(`Team ${teamId} initial server is invalid`);
+    }
+  }
+
+  assertRecord(value.designatedServerByTeam, "Designated servers");
+  for (const teamId of TEAM_IDS) {
+    if (!teamPlayerIds[teamId].includes(value.designatedServerByTeam[teamId] as string)) {
+      throw new TypeError(`Team ${teamId} designated server is invalid`);
+    }
+  }
+
+  assertRecord(value.courtSides, "Display court mapping");
+  if (
+    !isTeamId(value.courtSides.left) ||
+    !isTeamId(value.courtSides.right) ||
+    value.courtSides.left === value.courtSides.right
+  ) {
+    throw new TypeError("Display court mapping must contain both teams");
+  }
+
+  assertRecord(value.playerCourts, "Player court mapping");
+  assertRecordKeys(value.playerCourts, [...playerIds], "Player court mapping");
+  if (Object.keys(value.playerCourts).length !== playerIds.size) {
+    throw new TypeError("Every player must have a court mapping");
+  }
+  for (const playerId of playerIds) {
+    if (!isCourtSide(value.playerCourts[playerId])) {
+      throw new TypeError("Player court mapping contains an invalid side");
+    }
+  }
+  if (value.format === "doubles") {
+    for (const teamId of TEAM_IDS) {
+      const [first, second] = teamPlayerIds[teamId];
+      if (value.playerCourts[first] === value.playerCourts[second]) {
+        throw new TypeError(`Team ${teamId} players must occupy different courts`);
+      }
+    }
+  }
+
+  if (!Array.isArray(value.games) || value.games.length < 1 || value.games.length > 3) {
+    throw new TypeError("Match games are invalid");
+  }
+  const games = value.games;
+  if (value.currentGame !== games.length) {
+    throw new TypeError("Current game must be the final game snapshot");
+  }
+  const winnerCounts = { A: 0, B: 0 };
+  games.forEach((rawGame, index) => {
+    assertRecord(rawGame, "Game snapshot");
+    if (rawGame.number !== index + 1 || !isTeamId(rawGame.startingServingTeam)) {
+      throw new TypeError("Game identity is invalid");
+    }
+    assertRecord(rawGame.score, "Game score");
+    for (const teamId of TEAM_IDS) {
+      assertInteger(rawGame.score[teamId], 0, value.targetScore as number, "Game score");
+    }
+    if (rawGame.winner !== null && !isTeamId(rawGame.winner)) {
+      throw new TypeError("Game winner is invalid");
+    }
+    if (
+      isTeamId(rawGame.winner) &&
+      rawGame.score[rawGame.winner] !== value.targetScore
+    ) {
+      throw new TypeError("Winning game must reach target score");
+    }
+    if (rawGame.winner === null) {
+      if (
+        rawGame.score.A === value.targetScore ||
+        rawGame.score.B === value.targetScore
+      ) {
+        throw new TypeError("A game at target score must have a winner");
+      }
+    } else {
+      const losingTeam = rawGame.winner === "A" ? "B" : "A";
+      if ((rawGame.score[losingTeam] as number) >= (value.targetScore as number)) {
+        throw new TypeError("The losing team must remain below target score");
+      }
+    }
+    if (isTeamId(rawGame.winner)) winnerCounts[rawGame.winner] += 1;
+    if (typeof rawGame.midGameSwitchCompleted !== "boolean") {
+      throw new TypeError("Game midpoint switch flag is invalid");
+    }
+    if (rawGame.midGameSwitchCompleted && rawGame.number !== 3) {
+      throw new TypeError("Only game three has a midpoint switch");
+    }
+    if (index < games.length - 1 && rawGame.winner === null) {
+      throw new TypeError("Previous games must have a winner");
+    }
+  });
+
+  assertRecord(value.gamesWon, "Games won");
+  for (const teamId of TEAM_IDS) {
+    if (value.gamesWon[teamId] !== winnerCounts[teamId]) {
+      throw new TypeError("Games-won total does not match game history");
+    }
+  }
+
+  assertRecord(value.serve, "Serve state");
+  if (
+    !isTeamId(value.serve.teamId) ||
+    !teamPlayerIds[value.serve.teamId].includes(value.serve.playerId as string) ||
+    (value.serve.serverNumber !== 1 && value.serve.serverNumber !== 2) ||
+    !isCourtSide(value.serve.court)
+  ) {
+    throw new TypeError("Serve state is invalid");
+  }
+  if (
+    (value.format === "singles" || value.scoringMode === "rally") &&
+    value.serve.serverNumber !== 1
+  ) {
+    throw new TypeError("This match mode has one server");
+  }
+  const currentScore = (games[(value.currentGame as number) - 1] as Record<string, unknown>)
+    .score as Record<MatchTeamId, number>;
+  const parityCourt = currentScore[value.serve.teamId] % 2 === 0 ? "right" : "left";
+  if (
+    (value.format === "singles" ||
+      value.scoringMode === "rally" ||
+      value.serve.serverNumber === 1) &&
+    value.serve.court !== parityCourt
+  ) {
+    throw new TypeError("Server court does not match score parity");
+  }
+  if (
+    value.format === "doubles" &&
+    value.playerCourts[value.serve.playerId as string] !== value.serve.court
+  ) {
+    throw new TypeError("Server court does not match player position");
+  }
+
+  const currentGame = games[games.length - 1] as Record<string, unknown>;
+  if (value.pendingCourtSwitch !== null) {
+    assertPendingSwitch(value.pendingCourtSwitch);
+    const pending = value.pendingCourtSwitch;
+    if (pending.game !== value.currentGame) {
+      throw new TypeError("Pending switch must belong to the current game");
+    }
+    if (pending.reason === "gameEnd" && currentGame.winner === null) {
+      throw new TypeError("Game-end switch requires a game winner");
+    }
+    if (pending.reason === "gameThreeMidpoint") {
+      const score = currentGame.score as Record<MatchTeamId, number>;
+      if (
+        currentGame.winner !== null ||
+        currentGame.midGameSwitchCompleted !== false ||
+        Math.max(score.A, score.B) < Math.ceil((value.targetScore as number) / 2)
+      ) {
+        throw new TypeError("Game-three midpoint switch state is invalid");
+      }
+    }
+  }
+
+  if (value.status === "inProgress") {
+    if (winnerCounts.A >= 2 || winnerCounts.B >= 2) {
+      throw new TypeError("In-progress match cannot already have a match winner");
+    }
+    if (value.winner !== null || value.endReason !== null) {
+      throw new TypeError("In-progress match cannot have terminal metadata");
+    }
+    if (currentGame.winner !== null && value.pendingCourtSwitch === null) {
+      throw new TypeError("Completed game must await a court switch");
+    }
+  } else if (value.status === "completed") {
+    const matchWinners = TEAM_IDS.filter((teamId) => winnerCounts[teamId] === 2);
+    if (
+      matchWinners.length !== 1 ||
+      !isTeamId(value.winner) ||
+      matchWinners[0] !== value.winner ||
+      value.gamesWon[value.winner] !== 2 ||
+      currentGame.winner !== value.winner ||
+      value.endReason !== null ||
+      value.pendingCourtSwitch !== null
+    ) {
+      throw new TypeError("Completed match state is invalid");
+    }
+  } else if (value.status === "ended") {
+    if (
+      winnerCounts.A >= 2 ||
+      winnerCounts.B >= 2 ||
+      value.winner !== null ||
+      typeof value.endReason !== "string" ||
+      value.endReason.trim().length === 0 ||
+      value.pendingCourtSwitch !== null
+    ) {
+      throw new TypeError("Explicitly ended match state is invalid");
+    }
+  } else {
+    throw new TypeError("Match status is invalid");
+  }
+}
+
+function assertCorrection(value: unknown) {
+  assertRecord(value, "Match correction");
+  assertRecordKeys(value, ["score", "serve", "playerCourts"], "Match correction");
+  if (value.score === undefined && value.serve === undefined && value.playerCourts === undefined) {
+    throw new TypeError("Match correction is empty");
+  }
+  if (value.score !== undefined) {
+    assertRecord(value.score, "Corrected score");
+    assertRecordKeys(value.score, TEAM_IDS, "Corrected score");
+    for (const score of Object.values(value.score)) {
+      if (!Number.isInteger(score)) throw new TypeError("Corrected score must be an integer");
+    }
+  }
+  if (value.serve !== undefined) {
+    assertRecord(value.serve, "Corrected serve");
+    if (
+      !isTeamId(value.serve.teamId) ||
+      typeof value.serve.playerId !== "string" ||
+      (value.serve.serverNumber !== 1 && value.serve.serverNumber !== 2) ||
+      !isCourtSide(value.serve.court)
+    ) {
+      throw new TypeError("Corrected serve is malformed");
+    }
+  }
+  if (value.playerCourts !== undefined) {
+    assertRecord(value.playerCourts, "Corrected player courts");
+    for (const court of Object.values(value.playerCourts)) {
+      if (!isCourtSide(court)) throw new TypeError("Corrected player court is malformed");
+    }
+  }
+}
+
+export function assertRuntimeMatchEvent(value: unknown): asserts value is MatchEvent {
+  assertRecord(value, "Match event");
+  if (value.schemaVersion !== 1) throw new TypeError("Unsupported match event schema");
+  assertNonEmptyString(value.id, "Match event id");
+  assertInteger(value.sequence, 0, Number.MAX_SAFE_INTEGER, "Match event sequence");
+  if (!isSource(value.source)) throw new TypeError("Invalid match event source");
+
+  switch (value.type) {
+    case "matchCreated":
+      assertRuntimeMatchSnapshot(value.snapshot);
+      break;
+    case "rallyAwarded":
+      if (!isCourtSide(value.displaySide) || !isTeamId(value.winnerTeamId)) {
+        throw new TypeError("Rally event payload is invalid");
+      }
+      break;
+    case "courtSwitchConfirmed":
+      assertPendingSwitch(value.pending);
+      break;
+    case "matchCorrected":
+      assertCorrection(value.correction);
+      break;
+    case "matchEnded":
+      assertNonEmptyString(value.reason, "Match end reason");
+      break;
+    case "matchEventUndone":
+      assertNonEmptyString(value.targetEventId, "Undo target event id");
+      assertRuntimeMatchSnapshot(value.restoredSnapshot);
+      break;
+    default:
+      throw new TypeError("Unknown match event type");
+  }
+}