@leaguesolver/round-robin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ren Fujii
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# @leaguesolver/round-robin
+
+A dependency-free, deterministic single/double round-robin schedule generator for
+TypeScript and JavaScript. Given a list of team names, it produces a full circle-method
+schedule: every pair of teams meets exactly once (single) or twice with home/away swapped
+(double), with automatic byes for odd team counts and balanced home/away counts per team.
+
+No `Date`, `Math.random`, or I/O of any kind: the same input always produces the exact
+same output, and the input array is never mutated.
+
+## Install
+
+```bash
+npm install @leaguesolver/round-robin
+```
+
+Requires Node.js >= 22. Ships as ESM only.
+
+## Usage
+
+```ts
+import { generateRoundRobin } from "@leaguesolver/round-robin";
+
+const rounds = generateRoundRobin(["Tigers", "Lions", "Bears", "Sharks"], "single");
+
+console.log(rounds);
+// [
+//   { round: 1, matches: [{ home: "Tigers", away: "Sharks" }, { home: "Bears", away: "Lions" }], byeTeam: null },
+//   { round: 2, matches: [{ home: "Bears", away: "Tigers" }, { home: "Sharks", away: "Lions" }], byeTeam: null },
+//   { round: 3, matches: [{ home: "Lions", away: "Tigers" }, { home: "Sharks", away: "Bears" }], byeTeam: null },
+// ]
+```
+
+An odd team count adds a bye each round:
+
+```ts
+generateRoundRobin(["Tigers", "Lions", "Bears"], "single");
+// 3 rounds, one match plus one byeTeam per round.
+```
+
+Use `"double"` to play every pair twice, with home/away swapped in the return leg:
+
+```ts
+generateRoundRobin(["Tigers", "Lions", "Bears", "Sharks"], "double");
+// 6 rounds: the first 3 as above, followed by the same 3 rounds with home/away reversed.
+```
+
+## API
+
+```ts
+type RoundRobinFormat = "single" | "double";
+
+interface RoundRobinMatch {
+  readonly home: string;
+  readonly away: string;
+}
+
+interface RoundRobinRound {
+  readonly round: number;
+  readonly matches: readonly RoundRobinMatch[];
+  readonly byeTeam: string | null;
+}
+
+function generateRoundRobin(
+  teams: readonly string[],
+  format: RoundRobinFormat,
+): readonly RoundRobinRound[];
+```
+
+## Scope
+
+This library only generates the simple round-robin pairing structure. It does not handle
+venue availability, blackout dates, rest-day constraints, or infeasibility diagnostics --
+that is a constraint-optimization problem, not a scheduling-pattern one.
+
+Need venue availability, rest days, home/away balance, or infeasibility diagnostics? Use
+the LeagueSolver API: https://leaguesolver.slipway-studio.com
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Pure circle-method round-robin schedule generator. No Date, Math.random, or IO of any
+ * kind: the same teams and format always produce the exact same schedule, and inputs are
+ * never mutated.
+ *
+ * The circle method fixes one seat and rotates every other seat around it each round,
+ * which guarantees every pair of teams meets exactly once per leg with no repeats and no
+ * team ever missing a round. An odd team count gets one extra "bye" seat so the algorithm
+ * always works on an even seat count; whichever team lands opposite the bye seat in a
+ * given round sits that round out instead of playing a match.
+ *
+ * Home/away is assigned per pairing (not per round): each match's home team is whichever
+ * of the two teams has played fewer home games so far, with a deterministic round/slot
+ * tiebreak when both are equal. Since every team plays exactly n - 1 games in a single
+ * leg, this keeps every team's home-game count within 1 of its away-game count for any
+ * team count, even or odd.
+ */
+export type RoundRobinFormat = "single" | "double";
+export interface RoundRobinMatch {
+    readonly home: string;
+    readonly away: string;
+}
+export interface RoundRobinRound {
+    readonly round: number;
+    readonly matches: readonly RoundRobinMatch[];
+    readonly byeTeam: string | null;
+}
+/**
+ * Generates a full round-robin schedule. `single` plays every pair once; `double` appends
+ * a mirrored second leg (home/away swapped) so every pair plays twice.
+ */
+export declare function generateRoundRobin(teams: readonly string[], format: RoundRobinFormat): readonly RoundRobinRound[];

package/dist/index.js

@@ -0,0 +1,103 @@
+/**
+ * Pure circle-method round-robin schedule generator. No Date, Math.random, or IO of any
+ * kind: the same teams and format always produce the exact same schedule, and inputs are
+ * never mutated.
+ *
+ * The circle method fixes one seat and rotates every other seat around it each round,
+ * which guarantees every pair of teams meets exactly once per leg with no repeats and no
+ * team ever missing a round. An odd team count gets one extra "bye" seat so the algorithm
+ * always works on an even seat count; whichever team lands opposite the bye seat in a
+ * given round sits that round out instead of playing a match.
+ *
+ * Home/away is assigned per pairing (not per round): each match's home team is whichever
+ * of the two teams has played fewer home games so far, with a deterministic round/slot
+ * tiebreak when both are equal. Since every team plays exactly n - 1 games in a single
+ * leg, this keeps every team's home-game count within 1 of its away-game count for any
+ * team count, even or odd.
+ */
+// Internal sentinel occupying the extra seat when the team count is odd. Never appears in
+// any returned match or bye value -- a pairing against it becomes that round's bye instead.
+const BYE_SEAT = Symbol("round-robin-bye-seat");
+/**
+ * Generates a full round-robin schedule. `single` plays every pair once; `double` appends
+ * a mirrored second leg (home/away swapped) so every pair plays twice.
+ */
+export function generateRoundRobin(teams, format) {
+    const firstLeg = generateSingleLeg(teams);
+    return format === "single" ? firstLeg : [...firstLeg, ...mirrorLeg(firstLeg)];
+}
+function generateSingleLeg(teams) {
+    const seats = teams.length % 2 === 0 ? [...teams] : [...teams, BYE_SEAT];
+    const seatCount = seats.length;
+    const roundCount = seatCount - 1;
+    const half = seatCount / 2;
+    // Local mutable accumulator, not shared/passed-in state: tracks each team's running
+    // home-game count across rounds so buildRound can balance home/away per pairing. Never
+    // mutates `teams` itself.
+    const homeCounts = new Map(teams.map((team) => [team, 0]));
+    const rounds = [];
+    let current = seats;
+    for (let roundIndex = 0; roundIndex < roundCount; roundIndex++) {
+        rounds.push(buildRound(roundIndex, current, half, seatCount, homeCounts));
+        current = rotate(current);
+    }
+    return rounds;
+}
+/** Builds one round's matches (and bye, if any) from the current seating arrangement,
+ * assigning home/away per pairing via `assignHomeAway` (see its docstring) and updating
+ * `homeCounts` in place as each match is decided. */
+function buildRound(roundIndex, seats, half, seatCount, homeCounts) {
+    const matches = [];
+    let byeTeam = null;
+    for (let i = 0; i < half; i++) {
+        const seatA = seats[i];
+        const seatB = seats[seatCount - 1 - i];
+        if (seatA === BYE_SEAT || seatB === BYE_SEAT) {
+            byeTeam = seatA === BYE_SEAT ? seatB : seatA;
+            continue;
+        }
+        const match = assignHomeAway(seatA, seatB, roundIndex, i, homeCounts);
+        homeCounts.set(match.home, (homeCounts.get(match.home) ?? 0) + 1);
+        matches.push(match);
+    }
+    return { round: roundIndex + 1, matches, byeTeam };
+}
+/**
+ * Decides which of `teamA`/`teamB` hosts this match: whichever has played fewer home
+ * games so far. When both are tied, breaks the tie by round/slot parity rather than
+ * always favoring the same side of the pairing -- always preferring one side is exactly
+ * the bug this replaces (see the module docstring), since it would still bias whichever
+ * team happens to stay tied with its opponent across multiple rounds.
+ */
+function assignHomeAway(teamA, teamB, roundIndex, slotIndex, homeCounts) {
+    const homeCountA = homeCounts.get(teamA) ?? 0;
+    const homeCountB = homeCounts.get(teamB) ?? 0;
+    if (homeCountA < homeCountB) {
+        return { home: teamA, away: teamB };
+    }
+    if (homeCountB < homeCountA) {
+        return { home: teamB, away: teamA };
+    }
+    return (roundIndex + slotIndex) % 2 === 0
+        ? { home: teamA, away: teamB }
+        : { home: teamB, away: teamA };
+}
+/** Standard circle-method rotation: seat 0 stays fixed, every other seat advances one
+ * position, with the last seat wrapping around to position 1. Returns a new array. */
+function rotate(seats) {
+    if (seats.length <= 1) {
+        return [...seats];
+    }
+    const [first, ...rest] = seats;
+    const lastSeat = rest[rest.length - 1];
+    return [first, lastSeat, ...rest.slice(0, -1)];
+}
+/** The return leg of a double round-robin: same rounds, home/away swapped, renumbered to
+ * continue after the first leg. */
+function mirrorLeg(firstLeg) {
+    return firstLeg.map((round) => ({
+        round: round.round + firstLeg.length,
+        matches: round.matches.map((match) => ({ home: match.away, away: match.home })),
+        byeTeam: round.byeTeam,
+    }));
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@leaguesolver/round-robin",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Dependency-free, deterministic single/double round-robin schedule generator.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.1",
+    "@vitest/coverage-v8": "4.1.10",
+    "typescript": "5.9.3",
+    "vitest": "4.1.10"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}