Errand Chain — a trip planner that does the math
String your stops, leave when it fits. A route planner that solves stop ordering against store closing times, appointment windows, and time-of-day traffic, then compares candidate leave times so you pick the best one.
- System
- A constraint solver over the Google Maps Distance Matrix. Brute-force stop-order optimization per candidate departure time, with hard deadlines (closing times), soft windows (pickups), dwell times, and traffic-dependent edge costs.
- Stack
- JavaScript (no framework)Google Maps APIsDistance Matrixnode:test
- Validation
- The solver has unit tests for candidate generation, return-home composition, and the drive-vs-wait comparison bar. Features were written as specs before implementation, and the design docs ship in the repo.
- Outcome
- A real constraint-satisfaction problem (ordering × deadlines × windows × time-dependent costs) solved in dependency-free vanilla JavaScript, spec-first, with tests. Live demo coming.
The loop
human checkpoint
- define
Set a home base and up to 7 stops, each with a dwell time, an optional hard "closes at" deadline, and an optional time window (a daycare pickup that must happen between 4:45 and 5:00).
- candidates
The planner proposes 2–3 candidate leave times, because "leave now" is rarely the only option worth checking.
- solve
For each candidate, brute-force the stop orderings with traffic-aware drive times for that departure, since the optimal order at 2pm is often wrong at 5pm. Infeasible plans degrade gracefully, preserving deadline-bound stops and reporting what was dropped.
Distance Matrix API
- choose
The comparison view shows each leave time's total trip, drive-vs-wait composition, and what fits. The human picks.
why a human here The solver optimizes what's quantifiable. Whether leaving 40 minutes later is worth it depends on what those 40 minutes are for, and that's the user's call. So the tool presents trade-offs instead of a single answer.
- hand off
The chosen plan opens in Google Maps for turn-by-turn navigation.
Google Maps
Why this project is here
Multi-stop routing with hard deadlines and time-dependent travel costs is a combinatorial problem, and the interesting engineering is in the solver: per-departure-time optimization, graceful degradation when not everything fits, and honest reporting of what was dropped and why.
Design decisions worth explaining
Brute force, on purpose. With ≤7 stops, exhaustive search over orderings is a few thousand evaluations: trivially fast, provably optimal, and zero heuristic complexity to debug. The real constraint was API call budget (the Distance Matrix charges per element), not compute, so the effort went into batching and caching matrix requests instead of a fancier search.
Leave-time comparison as the product. Route optimizers answer “what order?” The more useful question is “when should I leave?” Solving the full ordering problem per candidate departure and comparing the results (total time, drive-vs-wait split, what makes it in) is the feature that makes it a planner rather than a router.
Spec-then-build. Both major features (adaptive leave candidates and the drive-vs-wait comparison) were written as design specs before code, and both live in the repo alongside the tests. Same discipline as the client work, applied to a Saturday problem.