pinewood-derby-scheduler 1.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Thomas Lee
+
+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,67 @@
+# pinewood-derby-scheduler
+
+[![Node.js CI](https://github.com/sbma44/pinewood-derby-scheduler/actions/workflows/node.js.yml/badge.svg)](https://github.com/sbma44/pinewood-derby-scheduler/actions/workflows/node.js.yml)
+
+A lane assignment scheduler for pinewood derby races. Generates fair race schedules that maximize lane diversity and opponent variety.
+
+## Installation
+
+```bash
+npm install pinewood-derby-scheduler
+```
+
+## Usage
+
+```ts
+import { schedule } from 'pinewood-derby-scheduler';
+
+// Define your racers (can be any shape)
+const racers = [
+  { id: 1, name: 'Lightning' },
+  { id: 2, name: 'Thunder' },
+  { id: 3, name: 'Rocket' },
+  { id: 4, name: 'Blaze' },
+  { id: 5, name: 'Storm' },
+];
+
+// Generate a schedule
+const raceSchedule = schedule(racers, {
+  numLanes: 4,      // 4-lane track
+  heatsPerRacer: 3, // each car races 3 times
+});
+
+// raceSchedule is a 2D array: [heat][lane]
+raceSchedule.forEach((heat, i) => {
+  console.log(`Heat ${i + 1}:`, heat.map(r => r?.name ?? '(empty)'));
+});
+```
+
+### Prioritizing Opponents Over Lanes
+
+By default, the scheduler prioritizes lane diversity (each racer uses different lanes). You can switch to prioritize opponent diversity instead:
+
+```ts
+const raceSchedule = schedule(racers, {
+  numLanes: 4,
+  heatsPerRacer: 4,
+  prioritize: 'opponents', // maximize unique matchups
+});
+```
+
+## API
+
+### `schedule<T>(racers: T[], options: ScheduleOptions): Schedule<T>`
+
+Generates a race schedule.
+
+**Parameters:**
+- `racers` — Array of racer objects (any shape)
+- `options.numLanes` — Number of lanes on the track
+- `options.heatsPerRacer` — How many heats each racer participates in
+- `options.prioritize` — `'lanes'` (default) or `'opponents'`
+
+**Returns:** A 2D array where `result[heatIndex][laneIndex]` is a racer or `null` (empty lane).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Scheduling criteria that can be prioritized.
+ * - 'lanes': Lane diversity (each racer uses different lanes)
+ * - 'opponents': Opponent diversity (each racer faces different opponents)
+ * - 'turnover': Minimize cars appearing in consecutive heats (faster race setup)
+ */
+type ScheduleCriterion = 'lanes' | 'opponents' | 'turnover';
+/**
+ * Options for generating a race schedule.
+ */
+interface ScheduleOptions {
+    /** Number of lanes on the track */
+    numLanes: number;
+    /** Number of heats each racer should participate in */
+    heatsPerRacer: number;
+    /**
+     * Priority ordering for scheduling criteria.
+     * Can be specified as:
+     * - A single criterion string (backward compatible): 'lanes' | 'opponents'
+     * - An array of criteria in priority order (first = highest priority)
+     *
+     * Default: ['lanes', 'opponents', 'turnover']
+     *
+     * All criteria are always considered; this controls their relative weights.
+     * First criterion gets weight 1000, second gets 100, third gets 10.
+     *
+     * @example
+     * // Prioritize turnover (fast setup), then opponents, then lanes
+     * prioritize: ['turnover', 'opponents', 'lanes']
+     */
+    prioritize?: ScheduleCriterion | ScheduleCriterion[];
+}
+/**
+ * A single heat in the schedule, where each index represents a lane.
+ * Contains the racer object or null if the lane is empty.
+ */
+type Heat<T> = (T | null)[];
+/**
+ * The complete race schedule as a 2D array.
+ * First dimension is heats, second dimension is lanes.
+ */
+type Schedule<T> = Heat<T>[];
+/**
+ * Generates a race schedule assigning racers to lanes across multiple heats.
+ *
+ * @param racers - Array of racer objects (can be any shape)
+ * @param options - Scheduling options (numLanes, heatsPerRacer)
+ * @returns A 2D array where result[heatIndex][laneIndex] is a racer or null
+ * @throws Error if inputs are invalid (e.g., numLanes < 1, empty racers)
+ *
+ * @example
+ * ```ts
+ * const racers = [{ id: 1, name: 'Car A' }, { id: 2, name: 'Car B' }];
+ * const schedule = schedule(racers, { numLanes: 4, heatsPerRacer: 3 });
+ * // schedule[0] is the first heat: [racer, racer, null, null]
+ * ```
+ */
+declare function schedule<T>(racers: T[], options: ScheduleOptions): Schedule<T>;
+
+export { type Heat, type Schedule, type ScheduleCriterion, type ScheduleOptions, schedule };

package/dist/index.js

@@ -0,0 +1,208 @@
+// src/index.ts
+function schedule(racers, options) {
+  const { numLanes, heatsPerRacer, prioritize = ["lanes", "opponents", "turnover"] } = options;
+  const priorityList = Array.isArray(prioritize) ? prioritize : prioritize === "lanes" ? ["lanes", "opponents", "turnover"] : ["opponents", "lanes", "turnover"];
+  const weights = { lanes: 1, opponents: 1, turnover: 1 };
+  const weightValues = [1e3, 100, 10];
+  for (let i = 0; i < priorityList.length; i++) {
+    weights[priorityList[i]] = weightValues[i] ?? 1;
+  }
+  const allCriteria = ["lanes", "opponents", "turnover"];
+  for (const criterion of allCriteria) {
+    if (!priorityList.includes(criterion)) {
+      weights[criterion] = 1;
+    }
+  }
+  if (!Array.isArray(racers)) {
+    throw new Error("racers must be an array");
+  }
+  if (racers.length === 0) {
+    throw new Error("racers array cannot be empty");
+  }
+  if (!Number.isInteger(numLanes) || numLanes < 1) {
+    throw new Error("numLanes must be a positive integer");
+  }
+  if (!Number.isInteger(heatsPerRacer) || heatsPerRacer < 1) {
+    throw new Error("heatsPerRacer must be a positive integer");
+  }
+  const totalSlots = racers.length * heatsPerRacer;
+  const numHeats = Math.max(heatsPerRacer, Math.ceil(totalSlots / numLanes));
+  const result = [];
+  for (let i = 0; i < numHeats; i++) {
+    const heat = new Array(numLanes).fill(null);
+    result.push(heat);
+  }
+  const necessaryByes = numHeats * numLanes - totalSlots;
+  const byeSlots = /* @__PURE__ */ new Set();
+  function getLanePriority(n) {
+    const priority = [];
+    let left = 0, right = n - 1;
+    while (left <= right) {
+      if (left === right) {
+        priority.push(left);
+      } else {
+        priority.push(left, right);
+      }
+      left++;
+      right--;
+    }
+    return priority;
+  }
+  const laneLeft = 0;
+  const laneRight = numLanes - 1;
+  let leftByes = 0, rightByes = 0;
+  let heatIdx = result.length - 1;
+  let byesPlaced = 0;
+  const laneOrder = getLanePriority(numLanes);
+  while (byesPlaced < necessaryByes) {
+    let chooseEdge;
+    if (leftByes < rightByes) {
+      chooseEdge = laneLeft;
+    } else if (rightByes < leftByes) {
+      chooseEdge = laneRight;
+    } else {
+      chooseEdge = byesPlaced % 2 === 0 ? laneLeft : laneRight;
+    }
+    let assigned = false;
+    for (const idx of laneOrder) {
+      if (chooseEdge === laneLeft && idx !== laneLeft || chooseEdge === laneRight && idx !== laneRight) {
+        continue;
+      }
+      const key = `${heatIdx},${idx}`;
+      if (!byeSlots.has(key)) {
+        byeSlots.add(key);
+        if (idx === laneLeft) leftByes++;
+        if (idx === laneRight) rightByes++;
+        byesPlaced++;
+        assigned = true;
+        break;
+      }
+    }
+    if (!assigned) {
+      for (const idx of laneOrder) {
+        const key = `${heatIdx},${idx}`;
+        if (!byeSlots.has(key)) {
+          byeSlots.add(key);
+          if (idx === laneLeft) leftByes++;
+          if (idx === laneRight) rightByes++;
+          byesPlaced++;
+          assigned = true;
+          break;
+        }
+      }
+    }
+    heatIdx--;
+    if (heatIdx < 0) heatIdx = result.length - 1;
+  }
+  const isByeSlot = (heat, lane) => byeSlots.has(`${heat},${lane}`);
+  const heatsRemaining = new Array(racers.length).fill(heatsPerRacer);
+  const lanesUsed = racers.map(() => /* @__PURE__ */ new Set());
+  const racedTogether = /* @__PURE__ */ new Set();
+  const pairKey = (a, b) => a < b ? `${a},${b}` : `${b},${a}`;
+  let previousHeatRacers = /* @__PURE__ */ new Set();
+  const availableLanesPerHeat = [];
+  for (let heat = 0; heat < numHeats; heat++) {
+    const lanes = [];
+    for (let lane = 0; lane < numLanes; lane++) {
+      if (!isByeSlot(heat, lane)) {
+        lanes.push(lane);
+      }
+    }
+    availableLanesPerHeat.push(lanes);
+  }
+  for (let heat = 0; heat < numHeats; heat++) {
+    const slotsInHeat = availableLanesPerHeat[heat].length;
+    const selectedRacers = [];
+    for (let slot = 0; slot < slotsInHeat; slot++) {
+      const candidates = [];
+      for (let r = 0; r < racers.length; r++) {
+        if (heatsRemaining[r] > 0 && !selectedRacers.includes(r)) {
+          candidates.push(r);
+        }
+      }
+      if (candidates.length === 0) break;
+      let bestCandidate = candidates[0];
+      let bestScore = -Infinity;
+      const availableLanesNow = availableLanesPerHeat[heat];
+      for (const candidate of candidates) {
+        let newOpponents = 0;
+        let repeatOpponents = 0;
+        for (const alreadySelected of selectedRacers) {
+          if (racedTogether.has(pairKey(candidate, alreadySelected))) {
+            repeatOpponents++;
+          } else {
+            newOpponents++;
+          }
+        }
+        let unusedLanesAvailable = 0;
+        for (const lane of availableLanesNow) {
+          if (!lanesUsed[candidate].has(lane)) {
+            unusedLanesAvailable++;
+          }
+        }
+        const hasUnusedLane = unusedLanesAvailable > 0 ? 1 : 0;
+        const wasInPreviousHeat = previousHeatRacers.has(candidate) ? 1 : 0;
+        const turnoverScore = wasInPreviousHeat ? -1 : 1;
+        const laneScore = (hasUnusedLane * 10 + unusedLanesAvailable) * weights.lanes;
+        const opponentScore = (newOpponents * 2 - repeatOpponents * 5) * weights.opponents;
+        const turnoverScoreWeighted = turnoverScore * weights.turnover;
+        const score = laneScore + opponentScore + turnoverScoreWeighted + heatsRemaining[candidate] * 0.1;
+        if (score > bestScore || score === bestScore && candidate < bestCandidate) {
+          bestScore = score;
+          bestCandidate = candidate;
+        }
+      }
+      selectedRacers.push(bestCandidate);
+      heatsRemaining[bestCandidate]--;
+    }
+    for (let i = 0; i < selectedRacers.length; i++) {
+      for (let j = i + 1; j < selectedRacers.length; j++) {
+        racedTogether.add(pairKey(selectedRacers[i], selectedRacers[j]));
+      }
+    }
+    previousHeatRacers = new Set(selectedRacers);
+    const availableLanes = [...availableLanesPerHeat[heat]];
+    const racerLanePrefs = selectedRacers.map((r) => {
+      for (let offset = 0; offset < numLanes; offset++) {
+        const tryLane = (r + lanesUsed[r].size + offset) % numLanes;
+        if (!lanesUsed[r].has(tryLane)) {
+          return { racer: r, preferredLane: tryLane };
+        }
+      }
+      return { racer: r, preferredLane: (r + lanesUsed[r].size) % numLanes };
+    });
+    racerLanePrefs.sort((a, b) => {
+      if (a.preferredLane !== b.preferredLane) return a.preferredLane - b.preferredLane;
+      return a.racer - b.racer;
+    });
+    for (const { racer, preferredLane } of racerLanePrefs) {
+      let assignedLane;
+      const prefIdx = availableLanes.indexOf(preferredLane);
+      if (prefIdx >= 0) {
+        assignedLane = preferredLane;
+        availableLanes.splice(prefIdx, 1);
+      } else if (availableLanes.length > 0) {
+        let foundUnused = false;
+        for (let i = 0; i < availableLanes.length; i++) {
+          if (!lanesUsed[racer].has(availableLanes[i])) {
+            assignedLane = availableLanes[i];
+            availableLanes.splice(i, 1);
+            foundUnused = true;
+            break;
+          }
+        }
+        if (!foundUnused) {
+          assignedLane = availableLanes.shift();
+        }
+      } else {
+        continue;
+      }
+      result[heat][assignedLane] = racers[racer];
+      lanesUsed[racer].add(assignedLane);
+    }
+  }
+  return result;
+}
+export {
+  schedule
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "pinewood-derby-scheduler",
+  "version": "1.0.0",
+  "description": "Lane assignment scheduler for pinewood derby races",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sbma44/pinewood-derby-scheduler.git"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist", "README.md", "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "site:dev": "vite site",
+    "site:build": "vite build site",
+    "site:preview": "vite preview site",
+    "prepublishOnly": "npm run build  && npm run test:run"
+  },
+  "keywords": [
+    "pinewood-derby",
+    "racing",
+    "scheduler",
+    "lane-assignment"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.10",
+    "vitest": "^1.1.3"
+  }
+}
+