minotor 11.5.2 → 12.0.1

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.
Files changed (41) hide show
  1. package/CHANGELOG.md +3 -3
  2. package/README.md +1 -1
  3. package/dist/cli/perf.d.ts +15 -5
  4. package/dist/cli.mjs +139 -151
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/parser.cjs.js +37 -19
  7. package/dist/parser.cjs.js.map +1 -1
  8. package/dist/parser.esm.js +37 -19
  9. package/dist/parser.esm.js.map +1 -1
  10. package/dist/router.cjs.js +1 -1
  11. package/dist/router.cjs.js.map +1 -1
  12. package/dist/router.d.ts +6 -5
  13. package/dist/router.esm.js +1 -1
  14. package/dist/router.esm.js.map +1 -1
  15. package/dist/router.umd.js +1 -1
  16. package/dist/router.umd.js.map +1 -1
  17. package/dist/routing/route.d.ts +6 -9
  18. package/dist/routing/state.d.ts +2 -2
  19. package/dist/stops/stopsIndex.d.ts +1 -1
  20. package/dist/timetable/route.d.ts +7 -4
  21. package/package.json +2 -2
  22. package/src/__e2e__/router.test.ts +55 -56
  23. package/src/cli/minotor.ts +19 -2
  24. package/src/cli/perf.ts +94 -107
  25. package/src/cli/repl.ts +9 -5
  26. package/src/router.ts +21 -8
  27. package/src/routing/__tests__/plainRouter.test.ts +2 -2
  28. package/src/routing/__tests__/result.test.ts +1 -1
  29. package/src/routing/__tests__/route.test.ts +8 -7
  30. package/src/routing/__tests__/router.test.ts +21 -1
  31. package/src/routing/__tests__/state.test.ts +29 -0
  32. package/src/routing/result.ts +11 -45
  33. package/src/routing/route.ts +11 -13
  34. package/src/routing/state.ts +11 -3
  35. package/src/stops/__tests__/stopFinder.test.ts +13 -0
  36. package/src/stops/stopsIndex.ts +13 -19
  37. package/src/timetable/__tests__/io.test.ts +27 -0
  38. package/src/timetable/__tests__/route.test.ts +30 -0
  39. package/src/timetable/io.ts +15 -1
  40. package/src/timetable/route.ts +40 -12
  41. package/src/timetable/timetable.ts +1 -1
@@ -1,17 +1,9 @@
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 {
5
- PickUpDropOffTypeString,
6
- RawPickUpDropOffType,
7
- Route as TimetableRoute,
8
- } from '../timetable/route.js';
4
+ import { Route as TimetableRoute } from '../timetable/route.js';
9
5
  import { Time } from '../timetable/time.js';
10
- import {
11
- routeTypeToString,
12
- TransferTypes,
13
- transferTypeToString,
14
- } from '../timetable/timetable.js';
6
+ import { TransferTypes } from '../timetable/timetable.js';
15
7
  import {
16
8
  Access,
17
9
  Leg,
@@ -23,34 +15,6 @@ import {
23
15
  import { Arrival, RoutingState, TransferEdge, VehicleEdge } from './router.js';
24
16
  import { AccessEdge } from './state.js';
25
17
 
26
- /**
27
- * Details about the pickup and drop-off modalities at each stop in each trip of a route.
28
- */
29
- const pickUpDropOffTypeMap: PickUpDropOffTypeString[] = [
30
- 'REGULAR',
31
- 'NOT_AVAILABLE',
32
- 'MUST_PHONE_AGENCY',
33
- 'MUST_COORDINATE_WITH_DRIVER',
34
- ];
35
-
36
- /**
37
- * Converts a numerical representation of a pick-up/drop-off type
38
- * into its corresponding string representation.
39
- *
40
- * @param numericalType - The numerical value representing the pick-up/drop-off type.
41
- * @returns The corresponding PickUpDropOffTypeString as a string.
42
- * @throws An error if the numerical type is invalid.
43
- */
44
- const toPickupDropOffType = (
45
- rawType: RawPickUpDropOffType,
46
- ): PickUpDropOffTypeString => {
47
- const type = pickUpDropOffTypeMap[rawType];
48
- if (!type) {
49
- throw new Error(`Invalid pickup/drop-off type ${rawType}`);
50
- }
51
- return type;
52
- };
53
-
54
18
  export class Result {
55
19
  private readonly destinations: ReadonlySet<StopId>;
56
20
  public readonly routingState: RoutingState;
@@ -225,7 +189,7 @@ export class Result {
225
189
  private buildServiceRouteInfo(route: TimetableRoute): ServiceRouteInfo {
226
190
  const serviceRouteInfo = this.timetable.getServiceRouteInfo(route);
227
191
  return {
228
- type: routeTypeToString(serviceRouteInfo.type),
192
+ type: serviceRouteInfo.type,
229
193
  name: serviceRouteInfo.name,
230
194
  };
231
195
  }
@@ -267,11 +231,13 @@ export class Result {
267
231
  firstEdge.tripIndex,
268
232
  ),
269
233
  arrivalTime: lastEdge.arrival,
270
- pickUpType: toPickupDropOffType(
271
- firstRoute.pickUpTypeFrom(firstEdge.stopIndex, firstEdge.tripIndex),
234
+ pickUpType: firstRoute.pickUpTypeFrom(
235
+ firstEdge.stopIndex,
236
+ firstEdge.tripIndex,
272
237
  ),
273
- dropOffType: toPickupDropOffType(
274
- lastRoute.dropOffTypeAt(lastEdge.hopOffStopIndex, lastEdge.tripIndex),
238
+ dropOffType: lastRoute.dropOffTypeAt(
239
+ lastEdge.hopOffStopIndex,
240
+ lastEdge.tripIndex,
275
241
  ),
276
242
  };
277
243
  }
@@ -289,7 +255,7 @@ export class Result {
289
255
  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
290
256
  to: this.stopsIndex.findStopById(edge.to)!,
291
257
  minTransferTime: edge.minTransferTime,
292
- type: transferTypeToString(edge.type),
258
+ type: edge.type,
293
259
  };
294
260
  }
295
261
 
@@ -332,7 +298,7 @@ export class Result {
332
298
  from: this.stopsIndex.findStopById(fromStopId)!,
333
299
  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
334
300
  to: this.stopsIndex.findStopById(toStopId)!,
335
- type: transferTypeToString(TransferTypes.GUARANTEED),
301
+ type: TransferTypes.GUARANTEED,
336
302
  };
337
303
  }
338
304
 
@@ -1,5 +1,5 @@
1
1
  import { Stop } from '../stops/stops.js';
2
- import type { PickUpDropOffTypeString } from '../timetable/route.js';
2
+ import type { PickUpDropOffType } from '../timetable/route.js';
3
3
  import {
4
4
  Duration,
5
5
  DURATION_ZERO,
@@ -7,15 +7,13 @@ import {
7
7
  Time,
8
8
  timeToString,
9
9
  } from '../timetable/time.js';
10
- import type {
11
- RouteTypeString,
12
- TransferTypeString,
10
+ import type { ServiceRouteInfo, TransferType } from '../timetable/timetable.js';
11
+ import {
12
+ routeTypeToString,
13
+ transferTypeToString,
13
14
  } from '../timetable/timetable.js';
14
15
 
15
- export type ServiceRouteInfo = {
16
- type: RouteTypeString;
17
- name: string;
18
- };
16
+ export type { ServiceRouteInfo } from '../timetable/timetable.js';
19
17
 
20
18
  export type BaseLeg = {
21
19
  from: Stop;
@@ -28,15 +26,15 @@ export type Access = BaseLeg & {
28
26
 
29
27
  export type Transfer = BaseLeg & {
30
28
  minTransferTime?: Duration;
31
- type: TransferTypeString;
29
+ type: TransferType;
32
30
  };
33
31
 
34
32
  export type VehicleLeg = BaseLeg & {
35
33
  route: ServiceRouteInfo;
36
34
  departureTime: Time;
37
35
  arrivalTime: Time;
38
- pickUpType: PickUpDropOffTypeString;
39
- dropOffType: PickUpDropOffTypeString;
36
+ pickUpType: PickUpDropOffType;
37
+ dropOffType: PickUpDropOffType;
40
38
  };
41
39
 
42
40
  export type Leg = Transfer | Access | VehicleLeg;
@@ -119,7 +117,7 @@ export class Route {
119
117
  const toStop = `To: ${leg.to.name}${leg.to.platform ? ` (Pl. ${leg.to.platform})` : ''}`;
120
118
  const transferDetails =
121
119
  'type' in leg && !('route' in leg)
122
- ? `Transfer: ${leg.type}${leg.minTransferTime ? `, Minimum Transfer Time: ${durationToString(leg.minTransferTime)}` : ''}`
120
+ ? `Transfer: ${transferTypeToString(leg.type)}${leg.minTransferTime ? `, Minimum Transfer Time: ${durationToString(leg.minTransferTime)}` : ''}`
123
121
  : '';
124
122
  const accessDetails =
125
123
  'duration' in leg
@@ -127,7 +125,7 @@ export class Route {
127
125
  : '';
128
126
  const travelDetails =
129
127
  'route' in leg && 'departureTime' in leg && 'arrivalTime' in leg
130
- ? `Route: ${leg.route.type} ${leg.route.name}, Departure: ${timeToString(leg.departureTime)}, Arrival: ${timeToString(leg.arrivalTime)}`
128
+ ? `Route: ${routeTypeToString(leg.route.type)} ${leg.route.name}, Departure: ${timeToString(leg.departureTime)}, Arrival: ${timeToString(leg.arrivalTime)}`
131
129
  : '';
132
130
 
133
131
  return [
@@ -111,8 +111,8 @@ export class RoutingState implements IRaptorState {
111
111
  private readonly maxDuration?: Duration;
112
112
 
113
113
  /**
114
- * Every stop that has received an arrival improvement during the current run,
115
- * in the order the improvements occurred. Used by {@link resetFor} to clear
114
+ * Every stop reached during the current run, recorded once in first-reached
115
+ * order. Used by {@link resetFor} to clear
116
116
  * only the touched entries instead of scanning the entire array.
117
117
  */
118
118
  private readonly reachedStops: StopId[] = [];
@@ -219,7 +219,9 @@ export class RoutingState implements IRaptorState {
219
219
  * @param leg The round number (number of transit legs taken so far).
220
220
  */
221
221
  updateArrival(stop: StopId, time: Time, leg: number): void {
222
- this.reachedStops.push(stop);
222
+ if (this.earliestArrivalTimes[stop] === UNREACHED_TIME) {
223
+ this.reachedStops.push(stop);
224
+ }
223
225
  this.earliestArrivalTimes[stop] = time;
224
226
  this.earliestArrivalLegs[stop] = leg;
225
227
  if (this.destinationSet.has(stop) && time < this._destinationBest) {
@@ -382,6 +384,12 @@ export class RoutingState implements IRaptorState {
382
384
  return arr;
383
385
  });
384
386
  state.graph.splice(0, state.graph.length, ...denseRounds);
387
+ state.reachedStops.length = 0;
388
+ const touched = new Set(arrivals.map(([stop]) => stop));
389
+ for (const round of graph) {
390
+ for (const [stop] of round) touched.add(stop);
391
+ }
392
+ state.reachedStops.push(...touched);
385
393
 
386
394
  return state;
387
395
  }
@@ -112,6 +112,19 @@ describe('Stop Finder', () => {
112
112
  });
113
113
 
114
114
  describe('findStopsByLocation', () => {
115
+ it('maps spatial IDs correctly when some stops have no coordinates', () => {
116
+ const stops = mockStops.map((stop, id) =>
117
+ id === 0 || id === 2
118
+ ? { ...stop, lat: undefined, lon: undefined }
119
+ : stop,
120
+ );
121
+ const index = new StopsIndex(stops);
122
+ assert.deepStrictEqual(
123
+ index.findStopsByLocation(46.8, 7.16, 10, 0.75).map((stop) => stop.id),
124
+ [1],
125
+ );
126
+ });
127
+
115
128
  it('should find stops by geographic location', () => {
116
129
  const results = stopFinder.findStopsByLocation(46.8061, 7.1614, 1);
117
130
  assert.strictEqual(results.length, 1);
@@ -8,8 +8,6 @@ import { deserializeStopsMap, serializeStopsMap } from './io.js';
8
8
  import { StopsMap as ProtoStopsMap } from './proto/v1/stops.js';
9
9
  import { SourceStopId, SourceStopsMap, Stop, StopId } from './stops.js';
10
10
 
11
- type StopPoint = { id: StopId; lat: number; lon: number };
12
-
13
11
  /**
14
12
  * The StopsIndex class provides functionality to search for public transport stops
15
13
  * by name or geographic location. It leverages text search and geospatial indexing
@@ -20,13 +18,13 @@ export class StopsIndex {
20
18
  private readonly sourceStopsMap: SourceStopsMap;
21
19
  private readonly textIndex;
22
20
  private readonly geoIndex: KDTree;
23
- private readonly stopPoints: StopPoint[];
21
+ private readonly geoStopIds: StopId[];
24
22
 
25
23
  constructor(stops: Stop[]) {
26
24
  this.stops = stops;
27
25
  this.sourceStopsMap = new Map<SourceStopId, StopId>();
28
26
  const stopsSet = new Map<StopId, { id: StopId; name: string }>();
29
- this.stopPoints = [];
27
+ this.geoStopIds = [];
30
28
  for (let id = 0; id < stops.length; id++) {
31
29
  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
32
30
  const stop = stops[id]!;
@@ -45,11 +43,7 @@ export class StopsIndex {
45
43
  }
46
44
 
47
45
  if (stop.lat && stop.lon) {
48
- this.stopPoints.push({
49
- id: id,
50
- lat: stop.lat,
51
- lon: stop.lon,
52
- });
46
+ this.geoStopIds.push(id);
53
47
  }
54
48
  }
55
49
  this.textIndex = createIndex({
@@ -60,11 +54,12 @@ export class StopsIndex {
60
54
  });
61
55
  const stopsArray = Array.from(stopsSet.values());
62
56
  addAll(this.textIndex, stopsArray);
63
- this.geoIndex = new KDTree(this.stopPoints.length);
64
- for (let i = 0; i < this.stopPoints.length; i++) {
57
+ this.geoIndex = new KDTree(this.geoStopIds.length);
58
+ for (let i = 0; i < this.geoStopIds.length; i++) {
65
59
  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
66
- const { lat, lon } = this.stopPoints[i]!;
67
- this.geoIndex.add(lon, lat);
60
+ const stop = this.stops[this.geoStopIds[i]!]!;
61
+ // Coordinates were checked when collecting geoStopIds.
62
+ this.geoIndex.add(stop.lon as number, stop.lat as number);
68
63
  }
69
64
  this.geoIndex.finish();
70
65
  }
@@ -112,10 +107,9 @@ export class StopsIndex {
112
107
  * @returns An array of Stop objects that match the search query.
113
108
  */
114
109
  findStopsByName(query: string, maxResults = 5): Stop[] {
115
- const results = search(this.textIndex, query).map(
116
- (result: SearchResult) => this.stops[result.id as number] as Stop,
117
- );
118
- return results.slice(0, maxResults);
110
+ return search(this.textIndex, query)
111
+ .slice(0, maxResults)
112
+ .map((result: SearchResult) => this.stops[result.id as number] as Stop);
119
113
  }
120
114
 
121
115
  /**
@@ -140,8 +134,8 @@ export class StopsIndex {
140
134
  maxResults,
141
135
  radius,
142
136
  ).map((id) => {
143
- const stopPoint = this.stopPoints[id] as StopPoint;
144
- return this.stops[stopPoint.id] as Stop;
137
+ const stopId = this.geoStopIds[id] as StopId;
138
+ return this.stops[stopId] as Stop;
145
139
  });
146
140
  return nearestStops;
147
141
  }
@@ -169,3 +169,30 @@ describe('Timetable IO', () => {
169
169
  assert.deepStrictEqual(deserializedData, routes);
170
170
  });
171
171
  });
172
+
173
+ it('owns compact pickup/drop-off bytes independently of input views', () => {
174
+ const input = Buffer.alloc(128);
175
+ input[17] = 0x12;
176
+ input[29] = 0x34;
177
+ const proto = [17, 29].map((offset) => ({
178
+ stopTimes: new Uint8Array(new Uint16Array([10, 11]).buffer),
179
+ pickupDropOffTypes: input.subarray(offset, offset + 1),
180
+ stops: new Uint8Array(new Uint32Array([0]).buffer),
181
+ serviceRouteId: 0,
182
+ }));
183
+ assert.ok(proto[0]);
184
+ proto.push({ ...proto[0], pickupDropOffTypes: input.subarray(40, 40) });
185
+ const routes = deserializeRoutesAdjacency(proto);
186
+ const [firstRoute, secondRoute, emptyRoute] = routes;
187
+ assert.ok(firstRoute && secondRoute && emptyRoute);
188
+ const first = firstRoute.serialize().pickupDropOffTypes;
189
+ const second = secondRoute.serialize().pickupDropOffTypes;
190
+ assert.notStrictEqual(first.buffer, input.buffer);
191
+ assert.strictEqual(first.buffer, second.buffer);
192
+ assert.strictEqual(first.buffer.byteLength, 2);
193
+ input.fill(0);
194
+ assert.deepStrictEqual([...first], [0x12]);
195
+ assert.deepStrictEqual([...second], [0x34]);
196
+ assert.strictEqual(emptyRoute.serialize().pickupDropOffTypes.length, 0);
197
+ assert.deepStrictEqual(deserializeRoutesAdjacency([]), []);
198
+ });
@@ -279,3 +279,33 @@ describe('Route', () => {
279
279
  });
280
280
  });
281
281
  });
282
+
283
+ it('keeps first-index lookup and stable arrays consistent for unique and repeated stops', () => {
284
+ const route = Route.of({
285
+ id: 0,
286
+ serviceRouteId: 0,
287
+ trips: [
288
+ {
289
+ stops: [5, 7, 5, 9, 5].map((id, index) => ({
290
+ id,
291
+ arrivalTime: index,
292
+ departureTime: index,
293
+ })),
294
+ },
295
+ ],
296
+ });
297
+ assert.strictEqual(route.firstStopRouteIndex(5), 0);
298
+ assert.strictEqual(route.firstStopRouteIndex(7), 1);
299
+ assert.strictEqual(route.firstStopRouteIndex(99), undefined);
300
+ assert.deepStrictEqual(route.stopRouteIndices(99), []);
301
+ assert.deepStrictEqual(route.stopRouteIndices(5), [0, 2, 4]);
302
+ const unique = route.stopRouteIndices(7);
303
+ assert.deepStrictEqual(unique, [1]);
304
+ assert.strictEqual(route.stopRouteIndices(7), unique);
305
+ unique[0] = 3;
306
+ assert.strictEqual(route.firstStopRouteIndex(7), 3);
307
+ const repeated = route.stopRouteIndices(5);
308
+ assert.strictEqual(route.stopRouteIndices(5), repeated);
309
+ repeated.shift();
310
+ assert.strictEqual(route.firstStopRouteIndex(5), 2);
311
+ });
@@ -215,16 +215,30 @@ export const deserializeRoutesAdjacency = (
215
215
  protoRoutesAdjacency: ProtoRoute[],
216
216
  ): Route[] => {
217
217
  const routesAdjacency: Route[] = [];
218
+ // Own the compact payload so small protobuf views do not retain the input file.
219
+ const pickupDropOffStorage = new Uint8Array(
220
+ protoRoutesAdjacency.reduce(
221
+ (size, route) => size + route.pickupDropOffTypes.byteLength,
222
+ 0,
223
+ ),
224
+ );
225
+ let pickupOffset = 0;
218
226
 
219
227
  for (let i = 0; i < protoRoutesAdjacency.length; i++) {
220
228
  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
221
229
  const value = protoRoutesAdjacency[i]!;
222
230
  const stops = bytesToUint32Array(value.stops);
231
+ pickupDropOffStorage.set(value.pickupDropOffTypes, pickupOffset);
232
+ const pickupDropOffTypes = pickupDropOffStorage.subarray(
233
+ pickupOffset,
234
+ pickupOffset + value.pickupDropOffTypes.byteLength,
235
+ );
236
+ pickupOffset += value.pickupDropOffTypes.byteLength;
223
237
  routesAdjacency.push(
224
238
  new Route(
225
239
  i,
226
240
  bytesToUint16Array(value.stopTimes),
227
- value.pickupDropOffTypes,
241
+ pickupDropOffTypes,
228
242
  stops,
229
243
  value.serviceRouteId,
230
244
  ),
@@ -23,7 +23,21 @@ export type PickUpDropOffType =
23
23
 
24
24
  export type PickUpDropOffTypeString = keyof typeof PickUpDropOffTypes;
25
25
 
26
- export type RawPickUpDropOffType = PickUpDropOffType;
26
+ /** Returns the identifier name for a pickup/drop-off type. */
27
+ export const pickUpDropOffTypeToString = (
28
+ type: PickUpDropOffType,
29
+ ): PickUpDropOffTypeString => {
30
+ switch (type) {
31
+ case PickUpDropOffTypes.REGULAR:
32
+ return 'REGULAR';
33
+ case PickUpDropOffTypes.NOT_AVAILABLE:
34
+ return 'NOT_AVAILABLE';
35
+ case PickUpDropOffTypes.MUST_PHONE_AGENCY:
36
+ return 'MUST_PHONE_AGENCY';
37
+ case PickUpDropOffTypes.MUST_COORDINATE_WITH_DRIVER:
38
+ return 'MUST_COORDINATE_WITH_DRIVER';
39
+ }
40
+ };
27
41
 
28
42
  /*
29
43
  * A trip route index corresponds to the index of a given trip in a route.
@@ -71,7 +85,7 @@ export class Route {
71
85
  * ...
72
86
  * }
73
87
  */
74
- private readonly stopIndices: Map<StopId, StopRouteIndex[]>;
88
+ private readonly stopIndices: Map<StopId, StopRouteIndex | StopRouteIndex[]>;
75
89
  /**
76
90
  * The identifier of the route as a service shown to users.
77
91
  */
@@ -101,15 +115,17 @@ export class Route {
101
115
  this.serviceRouteId = serviceRouteId;
102
116
  this.nbStops = stops.length;
103
117
  this.nbTrips = this.stopTimes.length / (this.stops.length * 2);
104
- this.stopIndices = new Map<StopId, StopRouteIndex[]>();
118
+ this.stopIndices = new Map<StopId, StopRouteIndex | StopRouteIndex[]>();
105
119
  for (let i = 0; i < stops.length; i++) {
106
120
  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
107
121
  const stopId = stops[i]!;
108
122
  const existingIndices = this.stopIndices.get(stopId);
109
- if (existingIndices) {
110
- existingIndices.push(i);
123
+ if (existingIndices === undefined) {
124
+ this.stopIndices.set(stopId, i);
125
+ } else if (typeof existingIndices === 'number') {
126
+ this.stopIndices.set(stopId, [existingIndices, i]);
111
127
  } else {
112
- this.stopIndices.set(stopId, [i]);
128
+ existingIndices.push(i);
113
129
  }
114
130
  }
115
131
  }
@@ -323,7 +339,7 @@ export class Route {
323
339
  dropOffTypeAtOffset(
324
340
  stopIndex: StopRouteIndex,
325
341
  offset: number,
326
- ): RawPickUpDropOffType {
342
+ ): PickUpDropOffType {
327
343
  const globalIndex = offset + stopIndex;
328
344
  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
329
345
  const byte = this.pickupDropOffTypes[globalIndex >> 1]!;
@@ -331,7 +347,7 @@ export class Route {
331
347
  // First pair → drop-off in lower 2 bits; second pair → drop-off in bits 4-5.
332
348
  return (
333
349
  globalIndex & 1 ? (byte >> 4) & 0x03 : byte & 0x03
334
- ) as RawPickUpDropOffType;
350
+ ) as PickUpDropOffType;
335
351
  }
336
352
 
337
353
  /**
@@ -362,7 +378,7 @@ export class Route {
362
378
  pickUpTypeFrom(
363
379
  stopIndex: StopRouteIndex,
364
380
  tripIndex: TripRouteIndex,
365
- ): RawPickUpDropOffType {
381
+ ): PickUpDropOffType {
366
382
  const globalIndex = tripIndex * this.stops.length + stopIndex;
367
383
  const byteIndex = globalIndex >> 1;
368
384
  const isSecondPair = (globalIndex & 1) === 1;
@@ -377,7 +393,7 @@ export class Route {
377
393
  const pickUpValue = isSecondPair
378
394
  ? (byte >> 6) & 0x03 // Upper 2 bits for second pair
379
395
  : (byte >> 2) & 0x03; // Bits 2-3 for first pair
380
- return pickUpValue as RawPickUpDropOffType;
396
+ return pickUpValue as PickUpDropOffType;
381
397
  }
382
398
 
383
399
  /**
@@ -390,7 +406,7 @@ export class Route {
390
406
  dropOffTypeAt(
391
407
  stopIndex: StopRouteIndex,
392
408
  tripIndex: TripRouteIndex,
393
- ): RawPickUpDropOffType {
409
+ ): PickUpDropOffType {
394
410
  const globalIndex = tripIndex * this.stops.length + stopIndex;
395
411
  const byteIndex = globalIndex >> 1;
396
412
  const isSecondPair = (globalIndex & 1) === 1;
@@ -405,7 +421,7 @@ export class Route {
405
421
  const dropOffValue = isSecondPair
406
422
  ? (byte >> 4) & 0x03 // Bits 4-5 for second pair
407
423
  : byte & 0x03; // Lower 2 bits for first pair
408
- return dropOffValue as RawPickUpDropOffType;
424
+ return dropOffValue as PickUpDropOffType;
409
425
  }
410
426
 
411
427
  /**
@@ -457,9 +473,21 @@ export class Route {
457
473
  if (stopIndex === undefined) {
458
474
  return [];
459
475
  }
476
+ if (typeof stopIndex === 'number') {
477
+ // Preserve stable, mutable array results for callers that request all indices.
478
+ const indices = [stopIndex];
479
+ this.stopIndices.set(stopId, indices);
480
+ return indices;
481
+ }
460
482
  return stopIndex;
461
483
  }
462
484
 
485
+ /** Returns the first occurrence without allocating an array. */
486
+ public firstStopRouteIndex(stopId: StopId): StopRouteIndex | undefined {
487
+ const indices = this.stopIndices.get(stopId);
488
+ return typeof indices === 'number' ? indices : indices?.[0];
489
+ }
490
+
463
491
  /**
464
492
  * Retrieves the id of a stop at a given index in a route.
465
493
  * @param stopRouteIndex The route index of the stop.
@@ -300,7 +300,7 @@ export class Timetable {
300
300
  if (!serviceRoute || !transportModes.has(serviceRoute.type)) continue;
301
301
  }
302
302
 
303
- const originStopIndex = route.stopRouteIndices(originStop)[0]!;
303
+ const originStopIndex = route.firstStopRouteIndex(originStop)!;
304
304
  const existingHopOnStopIndex = reachableRoutes.get(route);
305
305
  if (existingHopOnStopIndex !== undefined) {
306
306
  if (originStopIndex < existingHopOnStopIndex) {