@opndev/tennis-match-center 0.0.1

package/lib/plan-placement.mjs

@@ -0,0 +1,219 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/**
+ * Places generated matches into the cells Planning booked for them.
+ *
+ * This deliberately contains no scheduling logic. Planning already
+ * decided which division and round occupies each court and slot; the
+ * only job here is to bind those decisions to concrete matches and
+ * report anything left over. When Planning and Scheduling each ran
+ * their own layout they disagreed, and cells were reserved that no
+ * match could be placed into.
+ */
+
+import { templateMatches } from './group-schedule.mjs'
+
+function fixtureKey(divisionId, round) {
+  return `${divisionId}:${round}`
+}
+
+/**
+ * Whether a bracket row is a bye: one side filled, the other empty.
+ * Both empty is a fixture awaiting winners, and does need a cell.
+ *
+ * @param {{home_team_id: ?number, visitor_team_id: ?number}} match
+ * @returns {boolean}
+ */
+export function isBye(match) {
+  return (match.home_team_id == null) !== (match.visitor_team_id == null)
+}
+
+/**
+ * @param {Object} params
+ * @param {Array<{date: string, court_id: number, slot: string, division_id: ?number, round: ?string}>} params.cells
+ *   Planning's cells, in the order Planning saved them.
+ * @param {Array<{rounds: Array<{name: string, matches: Array<Object>}>}>} params.brackets
+ *   The saved bracket shells, grouped by round.
+ * @returns {{matches: Array<Object>, unplaced: Array<Object>, unusedCells: Array<Object>}}
+ *   unplaced is a match Planning reserved no cell for - a planning
+ *   error. unusedCells is a cell with no match to put in it, which is
+ *   expected: Planning reserves full capacity, Scheduling fills actual.
+ */
+export function placeKnockoutIntoCells({ cells, brackets }) {
+  const pool = new Map()
+
+  for (const bracket of brackets) {
+    for (const round of bracket.rounds) {
+      for (const match of round.matches) {
+        // A bye advances a team without being played, so it takes no
+        // cell. Planning counts a round's court time the same way -
+        // see knockout-waves.mjs - and counting it here instead would
+        // report the difference as capacity Planning failed to book.
+        if (isBye(match)) {
+          continue
+        }
+
+        const key = fixtureKey(match.division_id, round.name)
+
+        if (!pool.has(key)) {
+          pool.set(key, [])
+        }
+
+        pool.get(key).push({ ...match, round: round.name })
+      }
+    }
+  }
+
+  const matches = []
+  const unusedCells = []
+
+  for (const cell of cells) {
+    if (cell.division_id == null || !cell.round) {
+      unusedCells.push(cell)
+      continue
+    }
+
+    const shell = pool.get(fixtureKey(cell.division_id, cell.round))?.shift()
+
+    if (!shell) {
+      unusedCells.push(cell)
+      continue
+    }
+
+    matches.push({
+      id: shell.id,
+      division_id: cell.division_id,
+      group_id: null,
+      round: cell.round,
+      slot: null,
+      court_id: cell.court_id,
+      date: cell.date,
+      hour: cell.slot,
+      home_team_id: shell.home_team_id,
+      visitor_team_id: shell.visitor_team_id,
+    })
+  }
+
+  return {
+    matches,
+    unplaced: [...pool.values()].flat(),
+    unusedCells,
+  }
+}
+
+/**
+ * Places a group's matches into the cells Planning booked for them.
+ *
+ * A cell names one fixture - a group and an index into that group's
+ * fixed template - so there is nothing to work out here. The template
+ * gives the pair of seed positions and the group gives the teams
+ * sitting in them.
+ *
+ * @param {Object} params
+ * @param {Array<{date: string, court_id: number, slot: string, group_id: ?number, match_slot: ?number}>} params.cells
+ *   Planning's cells, in the order Planning saved them.
+ * @param {Array<{id: number, divisionId: number, teamIds: number[], groupSize: 4|5}>} params.groups
+ * @returns {{matches: Array<Object>, unplaced: Array<Object>, unusedCells: Array<Object>}}
+ *   unplaced is a match Planning booked no cell for - a planning
+ *   error. unusedCells is a booked cell with no match to put in it,
+ *   which is expected: Planning reserves full capacity while
+ *   Scheduling fills what actually exists.
+ */
+/**
+ * A group's fixtures, in template order, with the seats resolved.
+ *
+ * Planning books a short group's cells against the size it is played
+ * at, padding the seats nobody filled, so the template is that one.
+ * A fixture with one seat empty is a bye and is played; one with both
+ * empty is no fixture at all, and says so.
+ *
+ * @param {{teamIds: number[], groupSize: number}} group
+ * @returns {Array<{slot: number, homeId: ?number, visitorId: ?number,
+ *   playable: boolean}>}
+ */
+export function groupFixtures(group) {
+  const seats = [...group.teamIds]
+
+  while (seats.length < (group.groupSize ?? seats.length)) {
+    seats.push(null)
+  }
+
+  return templateMatches({ teamIds: seats, groupSize: group.groupSize })
+    .map(entry => {
+      const homeId = seats[entry.pair[0] - 1] ?? null
+      const visitorId = seats[entry.pair[1] - 1] ?? null
+
+      return {
+        slot: entry.slot,
+        homeId,
+        visitorId,
+        playable: homeId !== null || visitorId !== null,
+      }
+    })
+}
+
+export function placeGroupsIntoCells({ cells, groups }) {
+  const byId = new Map(groups.map(group => [group.id, group]))
+  const templates = new Map(
+    groups.map(group => [group.id, groupFixtures(group)])
+  )
+
+  const matches = []
+  const unusedCells = []
+  const taken = new Set()
+
+  for (const cell of cells) {
+    if (cell.group_id == null || cell.match_slot == null) {
+      unusedCells.push(cell)
+      continue
+    }
+
+    const group = byId.get(cell.group_id)
+    const entry = templates.get(cell.group_id)?.[cell.match_slot]
+    const key = `${cell.group_id}:${cell.match_slot}`
+
+    // A group that has since been resized can leave a cell pointing at
+    // a match its template no longer has.
+    if (!group || !entry || taken.has(key)) {
+      unusedCells.push(cell)
+      continue
+    }
+
+    taken.add(key)
+
+    if (!entry.playable) {
+      unusedCells.push(cell)
+      continue
+    }
+
+    matches.push({
+      id: null,
+      round: 'group',
+      division_id: group.divisionId,
+      group_id: group.id,
+      // Which fixture of the group this is, not which round of it: a
+      // four team group plays two fixtures a round, and a match is one
+      // per (group, slot).
+      slot: cell.match_slot,
+      court_id: cell.court_id,
+      date: cell.date,
+      hour: cell.slot,
+      home_team_id: entry.homeId,
+      visitor_team_id: entry.visitorId,
+    })
+  }
+
+  const unplaced = []
+
+  for (const group of groups) {
+    templates.get(group.id).forEach((entry, index) => {
+      if (entry.playable && !taken.has(`${group.id}:${index}`)) {
+        unplaced.push({ group_id: group.id, match_slot: index, slot: entry.slot })
+      }
+    })
+  }
+
+  return { matches, unplaced, unusedCells }
+}

package/lib/plan.mjs

@@ -0,0 +1,133 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/**
+ * The plan being built: the cells that landed, the cells that were
+ * taken back, and everything the day could not honour.
+ *
+ * Every count that ends up in the shortfall report is registered here
+ * as it is discovered, rather than gathered from half a dozen maps at
+ * the end. A caller asks it for the finished result once.
+ */
+export class Plan {
+
+  constructor() {
+    this.blocks = []
+    this.warnings = []
+
+    this.refusedCells = new Map()
+    this.dropped = new Set()
+    this.missing = new Map()
+  }
+
+  /**
+   * Books a cell.
+   *
+   * @param {Object} block
+   */
+  place(block) {
+    this.blocks.push(block)
+  }
+
+  /**
+   * Every cell a competition holds for one date and phase.
+   *
+   * @param {Object} competition
+   * @param {string} date
+   * @param {string} phase
+   * @returns {Array}
+   */
+  cellsFor(competition, date, phase) {
+    return this.blocks.filter(block =>
+      block.competition_id === competition.id
+        && block.date === date
+        && block.phase === phase
+    )
+  }
+
+  /**
+   * Takes a competition's cells back off it, counting them as capacity
+   * it did not get. The cells are left for whoever can use them.
+   *
+   * @param {Object} competition
+   * @param {string} phase
+   * @param {Array} blocks The cells to withdraw.
+   */
+  refuse(competition, phase, blocks) {
+    this.short(competition, phase, blocks.length)
+
+    for (const block of blocks) {
+      this.dropped.add(block)
+    }
+  }
+
+  /**
+   * Records matches a competition needed and did not get.
+   *
+   * @param {Object|number} competition The competition or its id.
+   * @param {string} phase 'group' or 'knockout'.
+   * @param {number} count
+   */
+  short(competition, phase, count) {
+    if (count <= 0) {
+      return
+    }
+
+    const id = typeof competition === 'object' ? competition.id : competition
+    const key = `${id}:${phase}`
+
+    this.missing.set(key, (this.missing.get(key) ?? 0) + count)
+  }
+
+  /**
+   * How much a competition is short in one phase.
+   *
+   * @param {Object|number} competition
+   * @param {string} phase
+   * @returns {number}
+   */
+  shortfallFor(competition, phase) {
+    const id = typeof competition === 'object' ? competition.id : competition
+
+    return this.missing.get(`${id}:${phase}`) ?? 0
+  }
+
+  /**
+   * Notes something the plan had to guess at or could not honour.
+   *
+   * @param {Object} warning
+   */
+  warn(warning) {
+    this.warnings.push(warning)
+  }
+
+  /**
+   * The finished plan: the cells that survived, what each competition
+   * is short by, and the warnings raised along the way.
+   *
+   * @param {Array} competitions In the order they should be reported.
+   * @returns {{blocks: Array, shortfall: Array, warnings: Array}}
+   */
+  result(competitions) {
+    const blocks = this.dropped.size === 0
+      ? this.blocks
+      : this.blocks.filter(block => !this.dropped.has(block))
+
+    const shortfall = []
+
+    for (const competition of competitions) {
+      for (const phase of ['group', 'knockout']) {
+        const missing = this.shortfallFor(competition, phase)
+
+        if (missing > 0) {
+          shortfall.push({
+            competition_id: competition.id, phase, missing,
+          })
+        }
+      }
+    }
+
+    return { blocks, shortfall, warnings: this.warnings }
+  }
+}

package/lib/planning-day.mjs

@@ -0,0 +1,177 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import { courtUsableAt, runFits } from './court-runs.mjs'
+
+/**
+ * How long before dark an unlit court stops taking new play.
+ *
+ * A match that ends exactly as the light goes is pushing it: matches
+ * overrun, and the overrun trickles through the rest of the evening
+ * with nowhere to finish. An unlit court is left out of the last hour
+ * of daylight rather than relied on for it.
+ */
+const LIGHT_BUFFER_MINUTES = 60
+
+/**
+ * One date of the event as the planner works through it: the courts it
+ * has, the slots each competition runs on it, what is already booked,
+ * and the plan the cells go into.
+ *
+ * Everything the placers used to be handed field by field is asked of
+ * this instead - which courts a lane may use, what is free at a given
+ * slot, whether a court could hold a whole run - so a placer needs the
+ * day and nothing else.
+ */
+export class PlanningDay {
+
+  /**
+   * @param {Object} params
+   * @param {string} params.date Y-m-d.
+   * @param {Array} params.proCourts Courts reserved for pro play.
+   * @param {Array} params.openCourts Courts anyone may use, already
+   *   carrying any per-day override (see openCourtsFor).
+   * @param {Map<number, Array>} params.slotsByCompetition Each
+   *   competition's own slots for this date.
+   * @param {Object} params.occupancy What is already booked.
+   * @param {Plan} params.plan Where cells are placed.
+   * @param {?number} [params.darkFromMinutes] When the light goes, if
+   *   the event says. Without it a slot's own flag is all there is.
+   */
+  constructor({
+    date, proCourts, openCourts, slotsByCompetition, occupancy, plan,
+    darkFromMinutes = null,
+  }) {
+    this.date = date
+    this.proCourts = proCourts
+    this.openCourts = openCourts
+    this.slotsByCompetition = slotsByCompetition
+    this.occupancy = occupancy
+    this.plan = plan
+    this.darkFromMinutes = darkFromMinutes
+  }
+
+  /**
+   * Whether this slot has to be played under lights.
+   *
+   * Its own flag says whether it runs past dark. The buffer says the
+   * hour before that is no place to start on an unlit court either.
+   *
+   * @param {Object} slot
+   * @returns {boolean}
+   */
+  needsLight(slot) {
+    if (slot.lit_required) {
+      return true
+    }
+
+    if (this.darkFromMinutes == null) {
+      return false
+    }
+
+    return slot.start_minutes >= this.darkFromMinutes - LIGHT_BUFFER_MINUTES
+  }
+
+  /**
+   * The courts one lane of play may use.
+   *
+   * @param {boolean} pro
+   * @returns {Array}
+   */
+  courtsFor(pro) {
+    return pro ? this.proCourts : this.openCourts
+  }
+
+  /**
+   * A competition's slots for this date.
+   *
+   * @param {number} competitionId
+   * @returns {Array}
+   */
+  slotsFor(competitionId) {
+    return this.slotsByCompetition.get(competitionId) ?? []
+  }
+
+  /**
+   * Whether a court has nothing on it for this slot.
+   *
+   * @param {Object} court
+   * @param {Object} slot
+   * @returns {boolean}
+   */
+  isFree(court, slot) {
+    if (this.needsLight(slot) && !court.lit) {
+      return false
+    }
+
+    return courtUsableAt(court, slot) && this.occupancy.free(
+      this.date, court.id, slot.start_minutes, slot.end_minutes
+    )
+  }
+
+  /**
+   * Which of these courts may be played on in this slot at all,
+   * whether or not anything is on them.
+   *
+   * The venue's capacity at that hour, as against what is going spare
+   * - a round asking whether it could ever finish today measures
+   * itself against this, not against whoever happens to hold a court
+   * this minute.
+   *
+   * @param {Array} courts
+   * @param {Object} slot
+   * @returns {Array}
+   */
+  usable(courts, slot) {
+    return courts.filter(court =>
+      courtUsableAt(court, slot) && !(this.needsLight(slot) && !court.lit)
+    )
+  }
+
+  /**
+   * Which of these courts are going spare for this slot.
+   *
+   * @param {Array} courts
+   * @param {Object} slot
+   * @returns {Array}
+   */
+  free(courts, slot) {
+    return courts.filter(court => this.isFree(court, slot))
+  }
+
+  /**
+   * Which of these courts could hold a run of consecutive slots end to
+   * end - the question a court has to answer before it is taken.
+   *
+   * @param {Array} courts
+   * @param {Object} where Its slots and where the run starts.
+   * @param {number} runLength
+   * @returns {Array}
+   */
+  fitting(courts, { slots, slotIndex }, runLength) {
+    const context = {
+      slots, slotIndex, date: this.date, taken: this.occupancy,
+    }
+
+    const window = slots.slice(slotIndex, slotIndex + runLength)
+
+    return courts.filter(court =>
+      runFits(court, context, runLength)
+        && window.every(slot => this.isFree(court, slot))
+    )
+  }
+
+  /**
+   * Books a cell: onto the plan, and against the court's own time.
+   *
+   * @param {Object} block
+   * @param {Object} slot The slot it runs in.
+   */
+  place(block, slot) {
+    this.plan.place(block)
+    this.occupancy.take(
+      this.date, block.court_id, slot.start_minutes, slot.end_minutes
+    )
+  }
+}

package/lib/roster-seeding.mjs

@@ -0,0 +1,65 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/**
+ * Country-spread + age-balancing seeding algorithm - "Group Assignment
+ * (Seeding)" in spec.md. Pure function so it can run client-side ahead
+ * of any save and be unit tested without a DOM.
+ *
+ * @param {Array<{id: number, country: ?string, aruba_resident: boolean, age: ?number}>} teams
+ * @param {number} groupCount
+ * @returns {number[][]} team ids, one array per group, in seed order
+ */
+export function seedGroups(teams, groupCount) {
+  if (groupCount <= 0) {
+    return []
+  }
+
+  const buckets = new Map()
+
+  for (const team of teams) {
+    const key = team.aruba_resident ? '__ARUBA__' : (team.country ?? '__UNKNOWN__')
+
+    if (!buckets.has(key)) {
+      buckets.set(key, [])
+    }
+
+    buckets.get(key).push(team)
+  }
+
+  // Largest bucket first, so the most numerous country/resident group is
+  // spread across groups before smaller ones fill in the gaps.
+  const orderedBuckets = [...buckets.values()]
+    .sort((a, b) => b.length - a.length)
+
+  const sortedTeams = orderedBuckets.flatMap(bucket => {
+    return [...bucket].sort((a, b) => (a.age ?? 0) - (b.age ?? 0))
+  })
+
+  const groups = Array.from({ length: groupCount }, () => [])
+
+  sortedTeams.forEach((team, index) => {
+    groups[index % groupCount].push(team.id)
+  })
+
+  return groups
+}
+
+/**
+ * A, B, C, ... Z, AA, AB, ... for group naming.
+ *
+ * @param {number} index zero-based
+ * @returns {string}
+ */
+export function groupName(index) {
+  let name = ''
+  let n = index
+
+  do {
+    name = String.fromCharCode(65 + (n % 26)) + name
+    n = Math.floor(n / 26) - 1
+  } while (n >= 0)
+
+  return name
+}