minotor 3.0.0 → 3.0.2

package/src/routing/router.ts

@@ -1,9 +1,10 @@
 /* eslint-disable @typescript-eslint/no-non-null-assertion */
-import { StopId } from '../stops/stops.js';
+import { Stop, StopId } from '../stops/stops.js';
 import { StopsIndex } from '../stops/stopsIndex.js';
 import { Duration } from '../timetable/duration.js';
+import { TripIndex } from '../timetable/route.js';
 import { Time } from '../timetable/time.js';
-import { NOT_AVAILABLE, Timetable } from '../timetable/timetable.js';
+import { Timetable } from '../timetable/timetable.js';
 import { Query } from './query.js';
 import { Result } from './result.js';
 import { Leg } from './route.js';
@@ -15,17 +16,23 @@ export type TripLeg = ReachingTime & {
 };
 
 export type ReachingTime = {
-  time: Time;
+  arrival: Time;
   legNumber: number;
   origin: StopId;
 };
 
 type CurrentTrip = {
-  trip: number;
+  tripIndex: TripIndex;
   origin: StopId;
   bestHopOnStop: StopId;
 };
 
+/**
+ * A public transportation network router utilizing the RAPTOR algorithm for
+ * efficient journey planning and routing. For more information on the RAPTOR
+ * algorithm, refer to its detailed explanation in the research paper:
+ * https://www.microsoft.com/en-us/research/wp-content/uploads/2012/01/raptor_alenex.pdf
+ */
 export class Router {
   private readonly timetable: Timetable;
   private readonly stopsIndex: StopsIndex;
@@ -50,6 +57,14 @@ export class Router {
     const { options } = query;
     const newlyMarkedStops: Set<StopId> = new Set();
     for (const stop of markedStops) {
+      const currentArrival = arrivalsAtCurrentRound.get(stop);
+      if (!currentArrival) continue;
+      // Skip transfers if the last leg was also a transfer
+      const previousLeg = currentArrival.leg;
+      if (previousLeg && !('route' in previousLeg)) {
+        continue;
+      }
+
       for (const transfer of this.timetable.getTransfers(stop)) {
         let transferTime: Duration;
         if (transfer.minTransferTime) {
@@ -59,15 +74,14 @@ export class Router {
         } else {
           transferTime = options.minTransferTime;
         }
-        const arrivalAfterTransfer = arrivalsAtCurrentRound
-          .get(stop)!
-          .time.plus(transferTime);
+        const arrivalAfterTransfer = currentArrival.arrival.plus(transferTime);
         const originalArrival =
-          arrivalsAtCurrentRound.get(transfer.destination)?.time ?? UNREACHED;
-        if (arrivalAfterTransfer.toMinutes() < originalArrival.toMinutes()) {
-          const origin = arrivalsAtCurrentRound.get(stop)?.origin ?? stop;
+          arrivalsAtCurrentRound.get(transfer.destination)?.arrival ??
+          UNREACHED;
+        if (arrivalAfterTransfer.isBefore(originalArrival)) {
+          const origin = currentArrival.origin;
           arrivalsAtCurrentRound.set(transfer.destination, {
-            time: arrivalAfterTransfer,
+            arrival: arrivalAfterTransfer,
             legNumber: round,
             origin: origin,
             leg: {
@@ -78,7 +92,7 @@ export class Router {
             },
           });
           earliestArrivals.set(transfer.destination, {
-            time: arrivalAfterTransfer,
+            arrival: arrivalAfterTransfer,
             legNumber: round,
             origin: origin,
           });
@@ -91,6 +105,29 @@ export class Router {
     }
   }
 
+  /**
+   * Finds the earliest arrival time at any stop from a given set of destinations.
+   *
+   * @param earliestArrivals A map of stops to their earliest reaching times.
+   * @param destinations An array of destination stops to evaluate.
+   * @returns The earliest arrival time among the provided destinations.
+   */
+  private earliestArrivalAtAnyStop(
+    earliestArrivals: Map<StopId, ReachingTime>,
+    destinations: Stop[],
+  ): Time {
+    let earliestArrivalAtAnyDestination = UNREACHED;
+    for (const destination of destinations) {
+      const arrival =
+        earliestArrivals.get(destination.id)?.arrival ?? UNREACHED;
+      earliestArrivalAtAnyDestination = Time.min(
+        earliestArrivalAtAnyDestination,
+        arrival,
+      );
+    }
+    return earliestArrivalAtAnyDestination;
+  }
+
   /**
    * The main Raptor algorithm implementation.
    *
@@ -102,7 +139,7 @@ export class Router {
     // Consider children or siblings of the "from" stop as potential origins
     const origins = this.stopsIndex.equivalentStops(from);
     // Consider children or siblings of the "to" stop(s) as potential destinations
-    const destinations = to.flatMap((destination) =>
+    const destinations = Array.from(to).flatMap((destination) =>
       this.stopsIndex.equivalentStops(destination),
     );
     const earliestArrivals = new Map<StopId, ReachingTime>();
@@ -115,12 +152,12 @@ export class Router {
     for (const originStop of origins) {
       markedStops.add(originStop.id);
       earliestArrivals.set(originStop.id, {
-        time: departureTime,
+        arrival: departureTime,
         legNumber: 0,
         origin: originStop.id,
       });
       earliestArrivalsWithoutAnyLeg.set(originStop.id, {
-        time: departureTime,
+        arrival: departureTime,
         legNumber: 0,
         origin: originStop.id,
       });
@@ -146,57 +183,33 @@ export class Router {
       );
       markedStops.clear();
       // for each route that can be reached with at least round - 1 trips
-      for (const [routeId, hopOnStop] of reachableRoutes.entries()) {
-        const route = this.timetable.getRoute(routeId)!;
+      for (const [route, hopOnStop] of reachableRoutes.entries()) {
         let currentTrip: CurrentTrip | undefined = undefined;
-        const hopOnIndex = route.stopIndices.get(hopOnStop)!;
-        // for each stop in the route starting with the hop-on one
-        for (let i = hopOnIndex; i < route.stops.length; i++) {
-          const currentStop = route.stops[i]!;
-          const stopNumbers = route.stops.length;
+        for (const currentStop of route.stopsIterator(hopOnStop)) {
           if (currentTrip !== undefined) {
-            const currentArrivalIndex =
-              (currentTrip.trip * stopNumbers + i) * 2;
-            const currentArrivalTime = Time.fromMinutes(
-              route.stopTimes[currentArrivalIndex]!,
+            const currentArrivalTime = route.arrivalAt(
+              currentStop,
+              currentTrip.tripIndex,
+            );
+            const currentDropOffType = route.dropOffTypeAt(
+              currentStop,
+              currentTrip.tripIndex,
             );
-            const currentDropOffType = route.pickUpDropOffTypes[i * 2 + 1];
             const earliestArrivalAtCurrentStop =
-              earliestArrivals.get(currentStop)?.time ?? UNREACHED;
-            let arrivalToImprove = earliestArrivalAtCurrentStop;
-            if (destinations.length > 0) {
-              const earliestArrivalsAtDestinations: Time[] = [];
-              // if multiple destinations are specified, the target pruning
-              // should compare to the earliest arrival at any of them
-              for (const destinationStop of destinations) {
-                const earliestArrivalAtDestination =
-                  earliestArrivals.get(destinationStop.id)?.time ?? UNREACHED;
-                earliestArrivalsAtDestinations.push(
-                  earliestArrivalAtDestination,
-                );
-              }
-              const earliestArrivalAtDestination = Time.min(
-                ...earliestArrivalsAtDestinations,
-              );
-              arrivalToImprove = Time.min(
-                earliestArrivalAtCurrentStop,
-                earliestArrivalAtDestination,
-              );
-            }
+              earliestArrivals.get(currentStop)?.arrival ?? UNREACHED;
             if (
-              currentDropOffType !== NOT_AVAILABLE &&
-              currentArrivalTime.toMinutes() < arrivalToImprove.toMinutes()
+              currentDropOffType !== 'NOT_AVAILABLE' &&
+              currentArrivalTime.isBefore(earliestArrivalAtCurrentStop) &&
+              currentArrivalTime.isBefore(
+                this.earliestArrivalAtAnyStop(earliestArrivals, destinations),
+              )
             ) {
-              const bestHopOnStopIndex = route.stopIndices.get(
+              const bestHopOnDepartureTime = route.departureFrom(
                 currentTrip.bestHopOnStop,
-              )!;
-              const bestHopOnStopDepartureIndex =
-                currentTrip.trip * stopNumbers * 2 + bestHopOnStopIndex * 2 + 1;
-              const bestHopOnDepartureTime = Time.fromMinutes(
-                route.stopTimes[bestHopOnStopDepartureIndex]!,
+                currentTrip.tripIndex,
               );
               arrivalsAtCurrentRound.set(currentStop, {
-                time: currentArrivalTime,
+                arrival: currentArrivalTime,
                 legNumber: round,
                 origin: currentTrip.origin,
                 leg: {
@@ -206,11 +219,11 @@ export class Router {
                   to: this.stopsIndex.findStopById(currentStop)!,
                   departureTime: bestHopOnDepartureTime,
                   arrivalTime: currentArrivalTime,
-                  route: this.timetable.getServiceRoute(route.serviceRouteId)!,
+                  route: this.timetable.getServiceRoute(route),
                 },
               });
               earliestArrivals.set(currentStop, {
-                time: currentArrivalTime,
+                arrival: currentArrivalTime,
                 legNumber: round,
                 origin: currentTrip.origin,
               });
@@ -220,22 +233,25 @@ export class Router {
           // check if we can catch a previous trip at the current stop
           // if there was no current trip, find the first one reachable
           const earliestArrivalOnPreviousRound =
-            arrivalsAtPreviousRound.get(currentStop)?.time;
+            arrivalsAtPreviousRound.get(currentStop)?.arrival;
           if (
             earliestArrivalOnPreviousRound !== undefined &&
             (currentTrip === undefined ||
-              earliestArrivalOnPreviousRound.toMinutes() <=
-                route.stopTimes[(currentTrip.trip * stopNumbers + i) * 2]!)
+              earliestArrivalOnPreviousRound.isBefore(
+                route.arrivalAt(currentStop, currentTrip.tripIndex),
+              ) ||
+              earliestArrivalOnPreviousRound.equals(
+                route.arrivalAt(currentStop, currentTrip.tripIndex),
+              ))
           ) {
-            const earliestTrip = this.timetable.findEarliestTrip(
-              route,
+            const earliestTrip = route.findEarliestTrip(
               currentStop,
-              currentTrip?.trip,
               earliestArrivalOnPreviousRound,
+              currentTrip?.tripIndex,
             );
             if (earliestTrip !== undefined) {
               currentTrip = {
-                trip: earliestTrip,
+                tripIndex: earliestTrip,
                 // we need to keep track of the best hop-on stop to reconstruct the route at the end
                 bestHopOnStop: currentStop,
                 origin:

package/src/stops/__tests__/io.test.ts

@@ -4,7 +4,7 @@ import { describe, it } from 'node:test';
 import { deserializeStopsMap, serializeStopsMap } from '../io.js';
 import { StopsMap } from '../stops.js';
 
-describe('stops io', () => {
+describe('Stops IO', () => {
   const stopsMap: StopsMap = new Map([
     [
       1,

package/src/stops/__tests__/stopFinder.test.ts

@@ -93,7 +93,7 @@ const mockStops: StopsMap = new Map([
   ],
 ]);
 
-describe('StopFinder', () => {
+describe('Stop Finder', () => {
   let stopFinder: StopsIndex;
 
   beforeEach(() => {

package/src/stops/proto/stops.ts

@@ -1,6 +1,6 @@
 // Code generated by protoc-gen-ts_proto. DO NOT EDIT.
 // versions:
-//   protoc-gen-ts_proto  v2.6.1
+//   protoc-gen-ts_proto  v2.7.7
 //   protoc               v4.23.4
 // source: src/stops/proto/stops.proto
 
@@ -127,7 +127,7 @@ export const Stop: MessageFns<Stop> = {
 
   decode(input: BinaryReader | Uint8Array, length?: number): Stop {
     const reader = input instanceof BinaryReader ? input : new BinaryReader(input);
-    let end = length === undefined ? reader.len : reader.pos + length;
+    const end = length === undefined ? reader.len : reader.pos + length;
     const message = createBaseStop();
     while (reader.pos < end) {
       const tag = reader.uint32();
@@ -291,7 +291,7 @@ export const StopsMap: MessageFns<StopsMap> = {
 
   decode(input: BinaryReader | Uint8Array, length?: number): StopsMap {
     const reader = input instanceof BinaryReader ? input : new BinaryReader(input);
-    let end = length === undefined ? reader.len : reader.pos + length;
+    const end = length === undefined ? reader.len : reader.pos + length;
     const message = createBaseStopsMap();
     while (reader.pos < end) {
       const tag = reader.uint32();
@@ -386,7 +386,7 @@ export const StopsMap_StopsEntry: MessageFns<StopsMap_StopsEntry> = {
 
   decode(input: BinaryReader | Uint8Array, length?: number): StopsMap_StopsEntry {
     const reader = input instanceof BinaryReader ? input : new BinaryReader(input);
-    let end = length === undefined ? reader.len : reader.pos + length;
+    const end = length === undefined ? reader.len : reader.pos + length;
     const message = createBaseStopsMap_StopsEntry();
     while (reader.pos < end) {
       const tag = reader.uint32();

package/src/stops/stopsIndex.ts

@@ -74,8 +74,8 @@ export class StopsIndex {
   /**
    * Deserializes a binary representation of the stops.
    *
-   * @param {Uint8Array} data - The binary data to deserialize.
-   * @returns {StopsMap} - The deserialized StopFinder.
+   * @param data - The binary data to deserialize.
+   * @returns The deserialized StopFinder.
    */
   static fromData(data: Uint8Array): StopsIndex {
     const reader = new BinaryReader(data);
@@ -87,7 +87,7 @@ export class StopsIndex {
   /**
    * Serializes the stops into a binary protobuf.
    *
-   * @returns {Uint8Array} - The serialized binary data.
+   * @returns The serialized binary data.
    */
   serialize(): Uint8Array {
     const protoStopsMap: ProtoStopsMap = serializeStopsMap(this.stopsMap);

package/src/timetable/__tests__/io.test.ts

@@ -10,6 +10,7 @@ import {
   serializeServiceRoutesMap,
   serializeStopsAdjacency,
 } from '../io.js';
+import { REGULAR, Route } from '../route.js';
 import { Time } from '../time.js';
 import {
   RoutesAdjacency,
@@ -17,7 +18,7 @@ import {
   StopsAdjacency,
 } from '../timetable.js';
 
-describe('timetable io', () => {
+describe('Timetable IO', () => {
   const stopsAdjacency: StopsAdjacency = new Map([
     [
       1,
@@ -43,35 +44,27 @@ describe('timetable io', () => {
   const routesAdjacency: RoutesAdjacency = new Map([
     [
       'route1',
-      {
-        stopTimes: new Uint16Array([
+      new Route(
+        new Uint16Array([
           Time.fromHMS(16, 40, 0).toMinutes(),
           Time.fromHMS(16, 50, 0).toMinutes(),
         ]),
-        pickUpDropOffTypes: new Uint8Array([0, 0]), // REGULAR
-        stops: new Uint32Array([1, 2]),
-        stopIndices: new Map([
-          [1, 0],
-          [2, 1],
-        ]),
-        serviceRouteId: 'gtfs1',
-      },
+        new Uint8Array([REGULAR, REGULAR]),
+        new Uint32Array([1, 2]),
+        'gtfs1',
+      ),
     ],
     [
       'route2',
-      {
-        stopTimes: new Uint16Array([
+      new Route(
+        new Uint16Array([
           Time.fromHMS(15, 20, 0).toMinutes(),
           Time.fromHMS(15, 30, 0).toMinutes(),
         ]),
-        pickUpDropOffTypes: new Uint8Array([0, 0]), // REGULAR
-        stops: new Uint32Array([2, 1]),
-        stopIndices: new Map([
-          [2, 0],
-          [1, 1],
-        ]),
-        serviceRouteId: 'gtfs2',
-      },
+        new Uint8Array([REGULAR, REGULAR]),
+        new Uint32Array([2, 1]),
+        'gtfs2',
+      ),
     ],
   ]);
   const routes: ServiceRoutesMap = new Map([
@@ -106,7 +99,7 @@ describe('timetable io', () => {
             Time.fromHMS(16, 50, 0).toMinutes(),
           ]).buffer,
         ),
-        pickUpDropOffTypes: new Uint8Array([0, 0]), // REGULAR
+        pickUpDropOffTypes: new Uint8Array([REGULAR, REGULAR]),
         stops: new Uint8Array(new Uint32Array([1, 2]).buffer),
         serviceRouteId: 'gtfs1',
       },
@@ -117,7 +110,7 @@ describe('timetable io', () => {
             Time.fromHMS(15, 30, 0).toMinutes(),
           ]).buffer,
         ),
-        pickUpDropOffTypes: new Uint8Array([0, 0]), // REGULAR
+        pickUpDropOffTypes: new Uint8Array([REGULAR, REGULAR]),
         stops: new Uint8Array(new Uint32Array([2, 1]).buffer),
         serviceRouteId: 'gtfs2',
       },