minotor 11.1.2 → 11.2.0

package/.cspell.json

@@ -17,9 +17,12 @@
     "Dolderbahn",
     "dolmuş",
     "dropoff",
+    "dests",
     "Dymchurch",
+    "empts",
     "Engadin",
     "Eurostar",
+    "ffbt",
     "fontname",
     "Francey",
     "funi",
@@ -58,6 +61,7 @@
     "nodesep",
     "Olten",
     "penwidth",
+    "platz",
     "protoc",
     "rankdir",
     "ranksep",
@@ -76,7 +80,9 @@
     "Tilleul",
     "Tpng",
     "Tsvg",
-    "Wokingham"
+    "Wokingham",
+    "τdep",
+    "τarr"
   ],
   "flagWords": [],
   "ignorePaths": [

package/CHANGELOG.md

@@ -1,6 +1,6 @@
-## [11.1.2](https://github.com/aubryio/minotor/compare/v11.1.1...v11.1.2) (2026-04-18)
+# [11.2.0](https://github.com/aubryio/minotor/compare/v11.1.3...v11.2.0) (2026-04-27)
 
 
-### Performance Improvements
+### Features
 
-* easy performance wins with minor refactorings ([#65](https://github.com/aubryio/minotor/issues/65)) ([b3cfc62](https://github.com/aubryio/minotor/commit/b3cfc62b56cd754aff964333f4296301185e2a87))
+* range queries support ([#67](https://github.com/aubryio/minotor/issues/67)) ([39d1dd3](https://github.com/aubryio/minotor/commit/39d1dd3ecd17070a1e49bfded3bbb0888594a77b)), closes [#31](https://github.com/aubryio/minotor/issues/31) [#62](https://github.com/aubryio/minotor/issues/62)

package/README.md

@@ -10,10 +10,10 @@ Unlike most transit planners out there, **minotor** can store all the transit da
 This is particularly useful for highly dynamic applications or complex visualizations for research purposes where the user needs to query the data in real-time.
 Privacy-conscious applications where the user does not want to share their location data with a server can also benefit from this model.
 
-The transit router and the stops index of **minotor** can run in the browser, on react-native or in a Node.js environment.
-Transit data (GTFS) parsing runs on Node.js, and the resulting data is serialized as a protobuf binary that can be loaded from the router.
+The transit router and the stops index of **minotor** can run in the browser, on React Native or in a Node.js environment.
+Transit data (GTFS) parsing runs on Node.js, and the resulting data is serialized as a protobuf binary that can be loaded by the router.
 
-Minotor routing algorithm is mostly based on RAPTOR. See [Round-Based Public Transit Routing, D. Delling et al. 2012](https://www.microsoft.com/en-us/research/wp-content/uploads/2012/01/raptor_alenex.pdf).
+Minotor's routing algorithm is mostly based on RAPTOR. See [Round-Based Public Transit Routing, D. Delling et al. 2012](https://www.microsoft.com/en-us/research/wp-content/uploads/2012/01/raptor_alenex.pdf).
 
 ## Examples
 
@@ -34,15 +34,16 @@ A more complete isochrone map showcase can be found on [isochrone.ch](https://is
 ## Features
 
 - GTFS feed parsing (standard and extended)
-- Geographic and textual stops search
-- Transit routing from origin(s) stop(s) to destination(s) stop(s) at a given time
-- Computation for arrival times at all stops given a destination and start time
+- Geographic and textual stop search
+- **Point queries** — earliest-arrival journey from an origin to a destination at a given time
+- **Range queries** — all Pareto-optimal journeys within a departure-time window
+- Isochrone computation — earliest arrival times / fastest routes to every reachable stop
 
 ### Tested GTFS feeds
 
-| Feed                                                                                       | Parsing time | Timetable Size for a Day (Compressed) |
+| Feed                                                                                       | Parsing time | Timetable size for a day (compressed) |
 | ------------------------------------------------------------------------------------------ | ------------ | ------------------------------------- |
-| [Swiss GTFS feed](https://data.opentransportdata.swiss/en/dataset/timetable-2026-gtfs2020) | ~2 minutes   | 20 MB (5MB)                           |
+| [Swiss GTFS feed](https://data.opentransportdata.swiss/en/dataset/timetable-2026-gtfs2020) | ~2 minutes   | 20 MB (5 MB)                          |
 
 ## Get started
 
@@ -50,11 +51,11 @@ A more complete isochrone map showcase can be found on [isochrone.ch](https://is
 
 `npm i minotor`
 
-### Typescript API Usage example
+### TypeScript API
 
-#### GTFS Feed parsing (Node.js only)
+#### GTFS feed parsing (Node.js only)
 
-```
+```ts
 import { GtfsParser, extendedGtfsProfile } from 'minotor/parser';
 
 const parser = new GtfsParser('gtfs-feed.zip', extendedGtfsProfile);
@@ -62,87 +63,125 @@ const timetable = await parser.parseTimetable(new Date());
 const stopsIndex = await parser.parseStops();
 ```
 
-Note that times are only represented at the minute level so they can fit on 16 bits.
+Times are represented at the minute level (16-bit integers). Parsing can take a few minutes for large feeds.
 
-This operation can take a few minutes for large GTFS feeds.
+#### Stop search (browser or Node.js)
 
-#### Stop Search (Browser or Node.js)
+```ts
+// Text search (supports partial names and accents)
+const results = stopsIndex.findStopsByName('Fribourg');
 
-```
-const origins = stopsIndex.findStopsByName('Fribourg');
-const destinations = stopsIndex.findStopsByName('Moles'); // Partial name search
+// Lookup by source ID from the GTFS feed
+const platform = stopsIndex.findStopBySourceStopId('8504100:0:2');
+
+// Nearest stops within 500 m
+const nearby = stopsIndex.findStopsByLocation(46.803, 7.151, 5, 0.5);
 ```
 
-Query stops by ID:
+#### Point query (browser or Node.js)
 
-`const stopFromId = stopsIndex.findStopBySourceId('8592374:0:A');`
+Find the earliest-arrival journey departing at a specific time:
 
-Or by location:
+```ts
+import { Query, Router } from 'minotor';
 
-`const nearbyStops = stopsIndex.findStopsByLocation(46.80314924, 7.1510478, 5, 0.5);`
+const router = new Router(timetable, stopsIndex);
 
-#### Routing (Browser or Node.js)
+const [origin] = stopsIndex.findStopsByName('Fribourg/Freiburg');
+const [destination] = stopsIndex.findStopsByName('Moléson-sur-Gruyères');
 
-```
-import { Query, Router } from 'minotor';
+const result = router.route(
+  new Query.Builder()
+    .from(origin.id)
+    .to(destination.id)
+    .departureTime(8 * 60 + 30) // 08:30 in minutes from midnight
+    .maxTransfers(3)
+    .build(),
+);
 
-const router = new Router(timetable, stopsIndex);
+const route = result.bestRoute(); // Route | undefined
 
-const query = new Query.Builder()
-  .from('Parent8504100')
-  .to('Parent8504748')
-  .departureTime(8*60)
-  .maxTransfers(5)
-  .build();
-const result = router.route(query);
+// Earliest arrival at any individual stop (useful for isochrone computation)
+const arrival = result.arrivalAt(stop.id); // { arrival: Time, legNumber: number } | undefined
 ```
 
-Get the route between origin and the closest destination (optionally provide another destination stop than the one in the query, the resulting route will be found if it's reachable before the first query destination reached).
+Query options:
 
-`const bestRoute = result.bestRoute();`
+| Option                  | Default   | Description                                                            |
+| ----------------------- | --------- | ---------------------------------------------------------------------- |
+| `maxTransfers`          | `5`       | Maximum number of transfers                                            |
+| `minTransferTime`       | `2 min`   | Fallback minimum transfer time                                         |
+| `maxInitialWaitingTime` | unlimited | Maximum wait for the first vehicle after arriving at the boarding stop |
+| `transportModes`        | all       | Restrict to a subset of GTFS route types                               |
 
-Get the arrival time to any stop (optionally provide the max number of transfers if you're interested in a lower one than the one provided in the query).
-This time will be correct for any stop reachable before the first query destination reached.
+#### Range query (browser or Node.js)
 
-`const arrivalTime = result.arrivalAt(toStop.id);`
+Find all Pareto-optimal journeys within a departure-time window — no journey in the result is dominated by another (i.e. no journey departs later _and_ arrives earlier):
 
-### CLI Usage example
+```ts
+import { RangeQuery, Router } from 'minotor';
 
-Parse GTFS data for a day and output the timetable and stops index (`minotor parse-gtfs -h` for more options):
+const rangeResult = router.rangeRoute(
+  new RangeQuery.Builder()
+    .from(origin.id)
+    .to(destination.id)
+    .departureTime(8 * 60) // window start: 08:00
+    .lastDepartureTime(10 * 60) // window end:   10:00
+    .maxTransfers(3)
+    .build(),
+);
 
-`minotor parse-gtfs gtfs_feed.zip`
+console.log(rangeResult.size); // number of Pareto-optimal journeys
+
+// Iterate runs latest-departure-first
+for (const { departureTime, result } of rangeResult) {
+  const route = result.bestRoute();
+}
+
+// Or pick a specific journey
+const earliest = rangeResult.bestRoute(); // earliest arrival
+const latest = rangeResult.latestDepartureRoute(); // latest possible departure
+const fastest = rangeResult.fastestRoute(); // shortest travel duration
+const all = rangeResult.getRoutes(); // all routes, earliest-departure-first
+
+// Earliest arrival at every reachable stop across all runs
+const arrivals = rangeResult.allEarliestArrivals(); // Map<StopId, Arrival>
+const durations = rangeResult.allShortestDurations(); // Map<StopId, DurationArrival>
+```
+
+### CLI Usage
 
-Note that this operation can take a few minutes for very large GTFS feeds.
-Without extra parameters it saves the timetable and stopsIndex for the current day in `/tmp` as binary protobufs.
+Parse GTFS data for today and save the timetable and stops index to `/tmp`:
+
+`minotor parse-gtfs gtfs_feed.zip`
 
-Run the REPL to query the router or the stop index (`minotor repl -h` for more options):
+Start the interactive REPL:
 
 `minotor repl`
 
-Search stops (`minotor> .find -h for more options`):
+Search stops:
 
 `minotor> .find moleson`
 
-Query routes (`minotor> .route -h for more options`):
+Query a route:
 
 `minotor> .route from fribourg to moleson at 08:00`
 
+Run `minotor parse-gtfs -h` and `minotor repl -h` for all available options.
+
 ## Development
 
 ### Requirements
 
-Make sure you have a working [node](https://nodejs.org) environment.
-
-`protoc` also needs to be available on the build system.
+A working [Node.js](https://nodejs.org) environment and `protoc`:
 
 Ubuntu: `apt install -y protobuf-compiler` |
 Fedora: `dnf install -y protobuf-compiler` |
-MacOS: `brew install protobuf`
+macOS: `brew install protobuf`
 
 ### Debugging
 
-Using the npm script `repl`, or `minotor repl` if the project is installed globally, it is possible to inspect the internals
-of the router.
+The REPL (`minotor repl`) exposes several inspection tools.
 
 #### Inspect a stop
 
@@ -154,48 +193,34 @@ of the router.
 
 #### Plot the routing graph
 
-Make sure you have `graphviz` installed.
+Requires [Graphviz](https://graphviz.org):
 
 Ubuntu: `apt install -y graphviz` |
 Fedora: `dnf install -y graphviz` |
-MacOS: `brew install graphviz`
-
-`minotor> .plot from <stationId> to <stationId> at <HH:mm> [with <N> transfers] [to <graph.dot>]`
-
-`dot -Ksfdp -Tsvg graph.dot -o graph.svg`
-
-### Build
-
-- `build`: builds the project in the `dist/` directory
-- `clean`: removes the `dist/` directory
-
-### Unit Tests
-
-- `test`: runs unit tests
-- `test:coverage`: runs unit test runner with coverage reports
+macOS: `brew install graphviz`
 
-### End-to-End Tests
-
-- `e2e`: runs end-to-end tests, using a real data from a day in the Swiss GTFS dataset
-
-### Performance Tests
-
-- `perf`: runs a basic performance test, using a real data from a day in the Swiss GTFS dataset
-
-Note that performance tests are not included in the CI pipeline and must be run manually.
-
-### Formatting & linting
-
-- `lint`: ESLint with automatic fixing
-- `format`: Prettier with automatic fixing
-- `spell:check`: Spell checker
+```
+minotor> .plot from <station> to <station> at <HH:mm> [with <N> transfers] [to <graph.dot>]
+dot -Ksfdp -Tsvg graph.dot -o graph.svg
+```
 
-### Releasing
+### Scripts
 
-- `cz`: generates a valid git commit message (See [Commitizen](https://github.com/commitizen/cz-cli))
+| Script          | Description                                   |
+| --------------- | --------------------------------------------- |
+| `build`         | Compile to `dist/`                            |
+| `clean`         | Remove `dist/`                                |
+| `test`          | Run unit tests                                |
+| `test:coverage` | Unit tests with coverage                      |
+| `e2e`           | End-to-end tests against real Swiss GTFS data |
+| `perf`          | Performance benchmark (not in CI)             |
+| `lint`          | ESLint with auto-fix                          |
+| `format`        | Prettier with auto-fix                        |
+| `spell:check`   | Spell checker                                 |
+| `cz`            | Generate a Commitizen commit message          |
 
-Releases are automatically published to npm when merging to the `main` or `beta` (pre-release) branch.
+Releases are automatically published to npm on merge to `main` (stable) or `beta` (pre-release).
 
 ## Roadmap and requests
 
-The project is under active development, use github issues for reporting bugs and requesting features. For custom development, consulting, integrations, or other special requests, feel free to contact [the author](https://aubry.io/).
+The project is under active development. Use GitHub issues for bug reports and feature requests. For custom development, consulting, integrations, or other inquiries, feel free to contact [the author](https://aubry.io/).

package/dist/cli/perf.d.ts

@@ -1,6 +1,6 @@
-import { Query, Router, StopsIndex } from '../router.js';
+import { Query, RangeQuery, Router, StopsIndex } from '../router.js';
 type PerformanceResult = {
-    task: Query;
+    label: string;
     meanTimeUs: number;
     meanMemoryMb: number;
 };
@@ -8,11 +8,8 @@ type PerformanceResult = {
  * Loads a list of routing queries from a JSON file and resolves the
  * human-readable stop IDs to the internal numeric IDs used by the router.
  *
- * The file must contain a JSON array whose elements each have the shape:
- * ```json
- * { "from": "STOP_A", "to": ["STOP_B", "STOP_C"], "departureTime": "08:30:00" }
- * ```
- * An optional `maxTransfers` integer field is also supported.
+ * Only entries that do **not** carry a `lastDepartureTime` field are loaded —
+ * range-query entries are silently skipped.
  *
  * @param filePath - Path to the JSON file containing the serialized queries.
  * @param stopsIndex - The stops index used to resolve source stop IDs to the
@@ -23,6 +20,22 @@ type PerformanceResult = {
  *   referenced in the file cannot be found in the stops index.
  */
 export declare const loadQueriesFromJson: (filePath: string, stopsIndex: StopsIndex) => Query[];
+/**
+ * Loads a list of range routing queries from a JSON file and resolves the
+ * human-readable stop IDs to the internal numeric IDs used by the router.
+ *
+ * Only entries that carry a `lastDepartureTime` field are loaded — plain
+ * point-query entries are silently skipped.
+ *
+ * @param filePath - Path to the JSON file containing the serialized queries.
+ * @param stopsIndex - The stops index used to resolve source stop IDs to the
+ *   internal numeric IDs expected by the router.
+ * @returns An array of fully constructed {@link RangeQuery} objects ready to
+ *   be passed to {@link Router.rangeRoute}.
+ * @throws If the file cannot be read, the JSON is malformed, or any stop ID
+ *   referenced in the file cannot be found in the stops index.
+ */
+export declare const loadRangeQueriesFromJson: (filePath: string, stopsIndex: StopsIndex) => RangeQuery[];
 /**
  * Benchmarks {@link Router.route} across a set of queries.
  *
@@ -31,10 +44,11 @@ export declare const loadQueriesFromJson: (filePath: string, stopsIndex: StopsIn
  *   produced per query.
  * @param iterations - Number of times each query is repeated. Higher values
  *   yield a more stable mean at the cost of longer wall-clock time.
+ * @param stopsIndex - Used to resolve stop names for result labels.
  * @returns An array of {@link PerformanceResult} objects, one per query, each
  *   containing the mean wall-clock time (µs) and mean heap delta (MB).
  */
-export declare const testRouterPerformance: (router: Router, tasks: Query[], iterations: number) => PerformanceResult[];
+export declare const testRouterPerformance: (router: Router, tasks: Query[], iterations: number, stopsIndex: StopsIndex) => PerformanceResult[];
 /**
  * Benchmarks {@link Result.bestRoute} — the path-reconstruction phase —
  * independently of the routing phase.
@@ -44,23 +58,48 @@ export declare const testRouterPerformance: (router: Router, tasks: Query[], ite
  * @param tasks - The list of queries to benchmark. One {@link PerformanceResult}
  *   is produced per query.
  * @param iterations - Number of times `bestRoute` is called per query.
+ * @param stopsIndex - Used to resolve stop names for result labels.
  * @returns An array of {@link PerformanceResult} objects, one per query, each
  *   containing the mean wall-clock time (µs) and mean heap delta (MB) for the
  *   `bestRoute` call alone.
  */
-export declare const testBestRoutePerformance: (router: Router, tasks: Query[], iterations: number) => PerformanceResult[];
+export declare const testBestRoutePerformance: (router: Router, tasks: Query[], iterations: number, stopsIndex: StopsIndex) => PerformanceResult[];
+/**
+ * Benchmarks {@link Router.rangeRoute} across a set of range queries.
+ *
+ * @param router - The router instance to benchmark.
+ * @param tasks - The list of range queries to run. One {@link PerformanceResult}
+ *   is produced per query.
+ * @param iterations - Number of times each query is repeated.
+ * @param stopsIndex - Used to resolve stop names for result labels.
+ * @returns An array of {@link PerformanceResult} objects, one per query, each
+ *   containing the mean wall-clock time (µs) and mean heap delta (MB).
+ */
+export declare const testRangeRouterPerformance: (router: Router, tasks: RangeQuery[], iterations: number, stopsIndex: StopsIndex) => PerformanceResult[];
+/**
+ * Benchmarks {@link RangeResult.getRoutes} — the full Pareto-frontier
+ * reconstruction phase — independently of the range routing phase.
+ *
+ * @param router - The router instance used to produce the range results that
+ *   are then fed into `getRoutes`.
+ * @param tasks - The list of range queries to benchmark. One
+ *   {@link PerformanceResult} is produced per query.
+ * @param iterations - Number of times `getRoutes` is called per query.
+ * @param stopsIndex - Used to resolve stop names for result labels.
+ * @returns An array of {@link PerformanceResult} objects, one per query, each
+ *   containing the mean wall-clock time (µs) and mean heap delta (MB) for the
+ *   `getRoutes` call alone.
+ */
+export declare const testRangeResultPerformance: (router: Router, tasks: RangeQuery[], iterations: number, stopsIndex: StopsIndex) => PerformanceResult[];
 /**
- * Prints a human-readable summary of performance results to stdout.
+ * Prints a table summary of performance results to stdout.
  *
- * Displays an overall mean across all tasks followed by a per-task breakdown.
- * An optional {@link label} is printed as a section header so that results
- * from different benchmark phases (e.g. routing vs. reconstruction) can be
- * told apart when several calls appear in the same run.
+ * Each row corresponds to one task, identified by a human-readable query label
+ * (origin → destination + departure time). A footer row shows the mean across
+ * all tasks. An optional `label` is printed as a section header above the table.
  *
- * @param results - The performance results to display, as returned by
- *   {@link testRouterPerformance} or {@link testBestRoutePerformance}.
- * @param label - Optional heading printed above the results block.
- *   Defaults to `'Performance Results'`.
+ * @param results - The performance results to display.
+ * @param label - Heading printed above the table. Defaults to `'Performance Results'`.
  */
 export declare const prettyPrintPerformanceResults: (results: PerformanceResult[], label?: string) => void;
 export {};