pinewood-derby-scheduler 1.0.0 → 1.0.2

package/README.md

@@ -2,7 +2,9 @@
 
 [![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.
+A lane assignment scheduler for pinewood derby races. Generates fair race schedules that optimize for lane diversity, opponent variety, and fast race setup.
+
+Live demo: [https://pinewood.tomlee.space](https://pinewood.tomlee.space/)
 
 ## Installation
 
@@ -36,18 +38,63 @@ raceSchedule.forEach((heat, i) => {
 });
 ```
 
-### Prioritizing Opponents Over Lanes
+## Scheduling Criteria
+
+The scheduler optimizes for three criteria, which you can prioritize in any order:
+
+| Criterion | Description |
+|-----------|-------------|
+| `'lanes'` | **Lane diversity** — Each racer uses different lanes across their heats |
+| `'opponents'` | **Opponent diversity** — Each racer faces different opponents |
+| `'turnover'` | **Turnover** — Minimize cars appearing in consecutive heats (faster race setup) |
+
+### Setting Priorities
 
-By default, the scheduler prioritizes lane diversity (each racer uses different lanes). You can switch to prioritize opponent diversity instead:
+Pass an array to `prioritize` to control the relative importance of each criterion. The first item has highest priority:
+
+```ts
+// Prioritize fast race setup, then opponent variety, then lane diversity
+const raceSchedule = schedule(racers, {
+  numLanes: 4,
+  heatsPerRacer: 4,
+  prioritize: ['turnover', 'opponents', 'lanes'],
+});
+```
 
 ```ts
+// Prioritize lane diversity (default behavior)
 const raceSchedule = schedule(racers, {
   numLanes: 4,
   heatsPerRacer: 4,
-  prioritize: 'opponents', // maximize unique matchups
+  prioritize: ['lanes', 'opponents', 'turnover'],
 });
 ```
 
+```ts
+// Prioritize opponent variety above all else
+const raceSchedule = schedule(racers, {
+  numLanes: 4,
+  heatsPerRacer: 4,
+  prioritize: ['opponents', 'lanes', 'turnover'],
+});
+```
+
+All three criteria are always considered; the priority order controls their relative weights (first = 1000, second = 100, third = 10).
+
+### Backward Compatibility
+
+The old single-string format still works:
+
+```ts
+// These are equivalent:
+prioritize: 'lanes'
+prioritize: ['lanes', 'opponents', 'turnover']
+
+// These are equivalent:
+prioritize: 'opponents'
+prioritize: ['opponents', 'lanes', 'turnover']
+```
+
 ## API
 
 ### `schedule<T>(racers: T[], options: ScheduleOptions): Schedule<T>`
@@ -58,10 +105,28 @@ Generates a race schedule.
 - `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'`
+- `options.prioritize` — Priority order for scheduling criteria
+  - Single criterion: `'lanes'` | `'opponents'` (backward compatible)
+  - Array of criteria: `['lanes', 'opponents', 'turnover']` (any order)
+  - Default: `['lanes', 'opponents', 'turnover']`
 
 **Returns:** A 2D array where `result[heatIndex][laneIndex]` is a racer or `null` (empty lane).
 
+### Types
+
+```ts
+type ScheduleCriterion = 'lanes' | 'opponents' | 'turnover';
+
+interface ScheduleOptions {
+  numLanes: number;
+  heatsPerRacer: number;
+  prioritize?: ScheduleCriterion | ScheduleCriterion[];
+}
+
+type Heat<T> = (T | null)[];
+type Schedule<T> = Heat<T>[];
+```
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pinewood-derby-scheduler",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Lane assignment scheduler for pinewood derby races",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,7 +19,9 @@
     }
   },
   "files": [
-    "dist", "README.md", "LICENSE"
+    "dist",
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts",
@@ -45,4 +47,3 @@
     "vitest": "^1.1.3"
   }
 }
-