minotor 12.0.1 → 13.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -2,6 +2,7 @@ import { StopId } from '../stops/stops.js';
2
2
  import { Duration, Time } from '../timetable/time.js';
3
3
  import { Result } from './result.js';
4
4
  import { Route } from './route.js';
5
+ import type { RoutingResult, StopArrival } from './routingResult.js';
5
6
  import { Arrival } from './state.js';
6
7
  /**
7
8
  * A single departure-time iteration that produced at least one Pareto-optimal
@@ -39,37 +40,34 @@ export type ArrivalWithDuration = Arrival & {
39
40
  * strictly earlier *and* arrives strictly earlier than the previous one,
40
41
  * forming the classic staircase Pareto frontier.
41
42
  *
42
- * **Full-network mode** (empty `destinations`): when no destinations are
43
+ * **Full-network mode** (no query destinations): when no destinations are
43
44
  * supplied to the range query every departure slot in the window becomes its
44
45
  * own run, because destination-based Pareto pruning cannot be applied.
45
- * In this mode the destination-specific helpers ({@link getRoutes},
46
+ * In this mode the destination-specific helpers ({@link routes},
46
47
  * {@link bestRoute}, {@link latestDepartureRoute}, {@link fastestRoute})
47
- * return empty results; use {@link allEarliestArrivals},
48
- * {@link allShortestDurations}, {@link earliestArrivalAt}, or
48
+ * return empty results; use {@link arrivals},
49
+ * {@link shortestDurations}, {@link arrivalAt}, or
49
50
  * {@link shortestDurationTo} instead.
50
51
  *
51
52
  * Destination handling is delegated to {@link Result}, which expands
52
53
  * equivalent stops when reconstructing routes or looking up arrivals.
53
54
  */
54
- export declare class RangeResult {
55
+ export declare class RangeResult implements RoutingResult {
55
56
  private readonly _runs;
56
- private readonly _destinations;
57
- constructor(runs: ParetoRun[], destinations: ReadonlySet<StopId>);
58
- /** The resolved destination stop IDs for this result. */
59
- get destinations(): ReadonlySet<StopId>;
57
+ constructor(runs: ParetoRun[]);
60
58
  private normalizeTargets;
61
59
  /**
62
- * Returns all non-dominated routes to this result's default destination set,
60
+ * Lazily yields all non-dominated routes to this result's default destination set,
63
61
  * ordered from the earliest departure to the latest departure.
64
62
  *
65
- * Each route in the list departs strictly earlier *and* arrives strictly
66
- * earlier than its predecessor.
63
+ * Each route in the list departs strictly later *and* arrives strictly
64
+ * later than its predecessor.
67
65
  *
68
- * Returns an empty array when no destinations were provided (full-network
69
- * mode). Use {@link allEarliestArrivals} or {@link allShortestDurations}
66
+ * Yields nothing when no destinations were provided (full-network
67
+ * mode). Use {@link arrivals} or {@link shortestDurations}
70
68
  * to query individual stops in that case.
71
69
  */
72
- getRoutes(): Route[];
70
+ routes(): Generator<Route>;
73
71
  /**
74
72
  * The route that arrives **earliest** at the given stop(s) across all
75
73
  * Pareto-optimal runs.
@@ -83,10 +81,11 @@ export declare class RangeResult {
83
81
  * (no destinations), otherwise `undefined` is returned.
84
82
  *
85
83
  * @param to Optional destination stop ID or set of stop IDs.
84
+ * @param maxTransfers Optional transfer limit within retained data.
86
85
  * @returns The reconstructed {@link Route} with the earliest arrival,
87
86
  * or `undefined` if the target is unreachable in every run.
88
87
  */
89
- bestRoute(to?: StopId | Set<StopId>): Route | undefined;
88
+ bestRoute(to?: StopId | Set<StopId>, maxTransfers?: number): Route | undefined;
90
89
  /**
91
90
  * The route with the **latest possible departure** from the origin among all
92
91
  * Pareto-optimal journeys in the window.
@@ -101,10 +100,11 @@ export declare class RangeResult {
101
100
  * (no destinations), otherwise `undefined` is returned.
102
101
  *
103
102
  * @param to Optional destination stop ID or set of stop IDs.
103
+ * @param maxTransfers Optional transfer limit within retained data.
104
104
  * @returns The reconstructed {@link Route} with the latest departure,
105
105
  * or `undefined` if the target is unreachable in every run.
106
106
  */
107
- latestDepartureRoute(to?: StopId | Set<StopId>): Route | undefined;
107
+ latestDepartureRoute(to?: StopId | Set<StopId>, maxTransfers?: number): Route | undefined;
108
108
  /**
109
109
  * Reconstructs the **fastest** route to the given stop(s) — the journey with
110
110
  * the shortest travel duration (arrival time − origin departure time) across
@@ -119,10 +119,11 @@ export declare class RangeResult {
119
119
  * (no destinations), otherwise `undefined` is returned.
120
120
  *
121
121
  * @param to Optional destination stop ID or set of stop IDs.
122
+ * @param maxTransfers Optional transfer limit within retained data.
122
123
  * @returns The reconstructed fastest {@link Route}, or `undefined` if the
123
124
  * target is unreachable in every run.
124
125
  */
125
- fastestRoute(to?: StopId | Set<StopId>): Route | undefined;
126
+ fastestRoute(to?: StopId | Set<StopId>, maxTransfers?: number): Route | undefined;
126
127
  /** Number of Pareto-optimal journeys found. */
127
128
  get size(): number;
128
129
  /**
@@ -135,9 +136,9 @@ export declare class RangeResult {
135
136
  * Equivalent stops are handled by {@link Result.arrivalAt}.
136
137
  *
137
138
  * @param stop The target stop ID.
138
- * @param maxTransfers Optional upper bound on the number of transfers.
139
+ * @param maxTransfers Optional transfer limit within retained data.
139
140
  */
140
- earliestArrivalAt(stop: StopId, maxTransfers?: number): Arrival | undefined;
141
+ arrivalAt(stop: StopId, maxTransfers?: number): Arrival | undefined;
141
142
  /**
142
143
  * Shortest travel duration to reach a stop across all Pareto-optimal runs.
143
144
  *
@@ -154,19 +155,27 @@ export declare class RangeResult {
154
155
  * Returns `undefined` if `stop` is unreachable in every run.
155
156
  *
156
157
  * @param stop The target stop ID.
157
- * @param maxTransfers Optional upper bound on the number of transfers.
158
+ * @param maxTransfers Optional transfer limit within retained data.
158
159
  */
159
160
  shortestDurationTo(stop: StopId, maxTransfers?: number): ArrivalWithDuration | undefined;
160
161
  /**
161
162
  * Shortest travel duration to **every reachable stop** across all
162
- * Pareto-optimal runs, as a single `Map<StopId, DurationArrival>`.
163
+ * Pareto-optimal runs, yielding the stop ID and arrival with duration.
164
+ * All runs are aggregated before the first value is yielded. Ties retain
165
+ * the first run's arrival and leg count.
166
+ * @param maxTransfers Optional transfer limit within retained data.
163
167
  */
164
- allShortestDurations(): Map<StopId, ArrivalWithDuration>;
168
+ shortestDurations(maxTransfers?: number): Generator<StopArrival & {
169
+ duration: Duration;
170
+ }>;
165
171
  /**
166
172
  * Earliest achievable arrival at **every reachable stop** across all
167
- * Pareto-optimal runs, as a single `Map<StopId, Arrival>`.
173
+ * Pareto-optimal runs, yielding the stop ID and arrival.
174
+ * All runs are aggregated before the first value is yielded. Ties retain
175
+ * the first run's arrival and leg count.
176
+ * @param maxTransfers Optional transfer limit within retained data.
168
177
  */
169
- allEarliestArrivals(): Map<StopId, Arrival>;
178
+ arrivals(maxTransfers?: number): Generator<StopArrival>;
170
179
  /**
171
180
  * Iterates over all Pareto-optimal `(departureTime, result)` pairs,
172
181
  * ordered from the latest departure to the earliest departure.
@@ -1,19 +1,36 @@
1
1
  import { Timetable } from '../router.js';
2
2
  import { SourceStopId, StopId } from '../stops/stops.js';
3
3
  import { StopsIndex } from '../stops/stopsIndex.js';
4
+ import { resultDestinations, resultGraph } from './resultInternals.js';
4
5
  import { Route } from './route.js';
5
6
  import { Arrival, RoutingState } from './router.js';
6
- export declare class Result {
7
- private readonly destinations;
8
- readonly routingState: RoutingState;
7
+ import type { RoutingResult, StopArrival } from './routingResult.js';
8
+ /**
9
+ * A single-departure routing result.
10
+ */
11
+ export declare class Result implements RoutingResult {
12
+ #private;
9
13
  readonly stopsIndex: StopsIndex;
10
14
  readonly timetable: Timetable;
11
- constructor(destinations: ReadonlySet<StopId>, routingState: RoutingState, stopsIndex: StopsIndex, timetable: Timetable);
15
+ constructor(routingState: RoutingState, stopsIndex: StopsIndex, timetable: Timetable);
16
+ /** @internal Default query destinations for range result selection. */
17
+ [resultDestinations](): readonly StopId[];
18
+ /** @internal Routing graph and destination metadata for the graph plotter. */
19
+ [resultGraph](): Pick<RoutingState, 'graph' | 'destinations'>;
20
+ /**
21
+ * Iterates over reached stops, yielding each concrete stop ID, its earliest
22
+ * arrival time, and the number of legs taken to reach it. Unreached stops
23
+ * are omitted. Destination pruning may limit which stops were reached.
24
+ * @param maxTransfers Optional transfer limit within retained data.
25
+ */
26
+ arrivals(maxTransfers?: number): Generator<StopArrival>;
27
+ /** Looks up one concrete stop without expanding equivalent stops. */
28
+ private concreteArrivalAt;
12
29
  /**
13
30
  * Expands a target stop or stop set to all equivalent concrete stop IDs.
14
31
  *
15
- * When `to` is omitted, defaults to the resolved destinations stored on this
16
- * result.
32
+ * When `to` is omitted, defaults to the resolved destinations in the
33
+ * query.
17
34
  *
18
35
  * Equivalent stops are expanded here so destination handling has a single
19
36
  * source of truth shared by route reconstruction and arrival lookups.
@@ -25,9 +42,10 @@ export declare class Result {
25
42
  * destination set)
26
43
  *
27
44
  * @param to The destination stop by SourceStopId.
45
+ * @param maxTransfers Optional transfer limit within retained data.
28
46
  * @returns a route to the destination stop if it exists.
29
47
  */
30
- bestRouteToSourceStopId(to: SourceStopId | Set<SourceStopId>): Route | undefined;
48
+ bestRouteToSourceStopId(to: SourceStopId | Set<SourceStopId>, maxTransfers?: number): Route | undefined;
31
49
  /**
32
50
  * Reconstructs the best route to a stop.
33
51
  * (to any stop reachable in less time / transfers than this result's
@@ -35,9 +53,10 @@ export declare class Result {
35
53
  *
36
54
  * @param to The destination stop. Defaults to this result's resolved
37
55
  * destinations.
56
+ * @param maxTransfers Optional transfer limit within retained data.
38
57
  * @returns a route to the destination stop if it exists.
39
58
  */
40
- bestRoute(to?: StopId | Set<StopId>): Route | undefined;
59
+ bestRoute(to?: StopId | Set<StopId>, maxTransfers?: number): Route | undefined;
41
60
  private buildServiceRouteInfo;
42
61
  /**
43
62
  * Builds a vehicle leg from a chain of vehicle edges.
@@ -76,7 +95,7 @@ export declare class Result {
76
95
  * than this result's destination set.
77
96
  *
78
97
  * @param stop The target stop for which to return the arrival time.
79
- * @param maxTransfers The optional maximum number of transfers allowed.
98
+ * @param maxTransfers Optional transfer limit within retained data.
80
99
  * @returns The arrival time if the target stop is reachable, otherwise undefined.
81
100
  */
82
101
  arrivalAt(stop: StopId, maxTransfers?: number): Arrival | undefined;
@@ -0,0 +1,4 @@
1
+ /** Internal plotter access; deliberately not exported from the package entry point. */
2
+ export declare const resultGraph: unique symbol;
3
+ /** Internal access to query destinations for range result selection. */
4
+ export declare const resultDestinations: unique symbol;
@@ -0,0 +1,29 @@
1
+ import type { StopId } from '../stops/stops.js';
2
+ import type { Route } from './route.js';
3
+ import type { Arrival } from './state.js';
4
+ export type StopArrival = Arrival & {
5
+ stop: StopId;
6
+ };
7
+ /**
8
+ * Common earliest-arrival operations for single-departure and range results.
9
+ */
10
+ export interface RoutingResult {
11
+ /**
12
+ * Earliest arrival at a stop or an equivalent stop, optionally limited by
13
+ * transfer count. Returns undefined when no matching stop was reached.
14
+ */
15
+ arrivalAt(stop: StopId, maxTransfers?: number): Arrival | undefined;
16
+ /**
17
+ * Iterates once over each reached concrete stop and its earliest arrival.
18
+ * Destination pruning may limit coverage. Each call returns a fresh iterator.
19
+ * @param maxTransfers Optional transfer limit within retained data.
20
+ */
21
+ arrivals(maxTransfers?: number): IterableIterator<StopArrival>;
22
+ /**
23
+ * Reconstructs the earliest-arriving route to the given or default
24
+ * destinations. Returns undefined when none
25
+ * were reached or when no destinations were provided.
26
+ * @param maxTransfers Optional transfer limit within retained data.
27
+ */
28
+ bestRoute(to?: StopId | Set<StopId>, maxTransfers?: number): Route | undefined;
29
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "minotor",
3
- "version": "12.0.1",
3
+ "version": "13.0.0",
4
4
  "description": "A lightweight client-side transit routing library.",
5
5
  "keywords": [
6
6
  "minotor",
@@ -243,7 +243,7 @@ program
243
243
  );
244
244
  prettyPrintPerformanceResults(
245
245
  rangeResultResults,
246
- 'Range queries — rangeResult.getRoutes() (reconstruction only)',
246
+ 'Range queries — rangeResult.routes() (reconstruction only)',
247
247
  );
248
248
  },
249
249
  );
package/src/cli/perf.ts CHANGED
@@ -349,18 +349,18 @@ export const testRangeRouterPerformance = (
349
349
  };
350
350
 
351
351
  /**
352
- * Benchmarks {@link RangeResult.getRoutes} — the full Pareto-frontier
352
+ * Benchmarks {@link RangeResult.routes} — the full Pareto-frontier
353
353
  * reconstruction phase — independently of the range routing phase.
354
354
  *
355
355
  * @param router - The router instance used to produce the range results that
356
- * are then fed into `getRoutes`.
356
+ * are then fed into `routes`.
357
357
  * @param tasks - The list of range queries to benchmark. One
358
358
  * {@link PerformanceResult} is produced per query.
359
- * @param iterations - Number of times `getRoutes` is called per query.
359
+ * @param iterations - Number of times `routes` is fully consumed per query.
360
360
  * @param stopsIndex - Used to resolve stop names for result labels.
361
361
  * @returns An array of {@link PerformanceResult} objects, one per query, each
362
362
  * containing the mean wall-clock time (µs) and mean heap and ArrayBuffer deltas (MiB) for the
363
- * `getRoutes` call alone.
363
+ * full `routes` iteration alone.
364
364
  */
365
365
  export const testRangeResultPerformance = (
366
366
  router: Router,
@@ -375,7 +375,7 @@ export const testRangeResultPerformance = (
375
375
 
376
376
  results.push({
377
377
  label: buildQueryLabel(task, stopsIndex),
378
- ...measurePerformance(() => rangeResult.getRoutes(), iterations),
378
+ ...measurePerformance(() => [...rangeResult.routes()], iterations),
379
379
  });
380
380
  }
381
381
 
package/src/cli/repl.ts CHANGED
@@ -173,7 +173,7 @@ export const startRepl = (stopsPath: string, timetablePath: string) => {
173
173
  `from ${fromStop.name} to ${toStop.name} ` +
174
174
  `(window ${atTime}–${beforeTime}):`,
175
175
  );
176
- const routes = result.getRoutes();
176
+ const routes = [...result.routes()];
177
177
  routes.forEach((route, index) => {
178
178
  const journeyNumber = index + 1;
179
179
  console.log(`\nJourney ${journeyNumber}:`);
package/src/router.ts CHANGED
@@ -15,6 +15,7 @@ import type {
15
15
  ParetoRun,
16
16
  } from './routing/router.js';
17
17
  import { RangeResult, Router } from './routing/router.js';
18
+ import type { RoutingResult, StopArrival } from './routing/routingResult.js';
18
19
  import type { LocationType, SourceStopId, StopId } from './stops/stops.js';
19
20
  import type { Stop } from './stops/stops.js';
20
21
  import { StopsIndex } from './stops/stopsIndex.js';
@@ -63,9 +64,11 @@ export type {
63
64
  QueryOptions,
64
65
  RangeQueryOptions,
65
66
  RouteType,
67
+ RoutingResult,
66
68
  ServiceRouteInfo,
67
69
  SourceStopId,
68
70
  Stop,
71
+ StopArrival,
69
72
  StopId,
70
73
  Transfer,
71
74
  TransferType,
@@ -13,7 +13,6 @@ import {
13
13
  TransferTypes,
14
14
  } from '../../timetable/timetable.js';
15
15
  import { Plotter } from '../plotter.js';
16
- import { Query } from '../query.js';
17
16
  import { Result } from '../result.js';
18
17
  import { RoutingState } from '../router.js';
19
18
 
@@ -71,16 +70,10 @@ describe('Plotter', () => {
71
70
 
72
71
  const mockStopsIndex = new StopsIndex([stop1, stop2]);
73
72
  const mockTimetable = new Timetable(stopsAdjacency, routesAdjacency, routes);
74
- const mockQuery = new Query.Builder()
75
- .from(0)
76
- .to(new Set([1]))
77
- .departureTime(timeFromHMS(8, 0, 0))
78
- .build();
79
73
 
80
74
  describe('plotDotGraph', () => {
81
75
  it('should generate valid DOT graph structure', () => {
82
76
  const result = new Result(
83
- mockQuery.to,
84
77
  RoutingState.fromTestData({ nbStops: NB_STOPS }),
85
78
  mockStopsIndex,
86
79
  mockTimetable,
@@ -97,7 +90,6 @@ describe('Plotter', () => {
97
90
 
98
91
  it('should include station nodes', () => {
99
92
  const result = new Result(
100
- mockQuery.to,
101
93
  RoutingState.fromTestData({
102
94
  nbStops: NB_STOPS,
103
95
  origins: [0],
@@ -118,7 +110,6 @@ describe('Plotter', () => {
118
110
 
119
111
  it('should handle empty graph gracefully', () => {
120
112
  const result = new Result(
121
- mockQuery.to,
122
113
  RoutingState.fromTestData({ nbStops: NB_STOPS }),
123
114
  mockStopsIndex,
124
115
  mockTimetable,
@@ -146,7 +137,6 @@ describe('Plotter', () => {
146
137
  const specialStopsIndex = new StopsIndex([stop1, stop2, specialStop]);
147
138
 
148
139
  const result = new Result(
149
- mockQuery.to,
150
140
  RoutingState.fromTestData({
151
141
  nbStops: NB_STOPS,
152
142
  origins: [2],
@@ -171,7 +161,6 @@ describe('Plotter', () => {
171
161
 
172
162
  it('should use correct colors', () => {
173
163
  const result = new Result(
174
- mockQuery.to,
175
164
  RoutingState.fromTestData({
176
165
  nbStops: NB_STOPS,
177
166
  origins: [0],