minotor 1.0.0

package/src/routing/plotter.ts

@@ -0,0 +1,70 @@
+import { StopId } from '../stops/stops.js';
+import { Result } from './result.js';
+import { TripLeg } from './router.js';
+
+export class Plotter {
+  private result: Result;
+
+  constructor(result: Result) {
+    this.result = result;
+  }
+
+  /**
+   * Plots the path three as a DOT for debugging purposes.
+   *
+   * @returns A string representing the DOT graph of the path tree.
+   */
+  plotDotGraph(): string {
+    const earliestArrivalsPerRound: Map<StopId, TripLeg>[] =
+      this.result.earliestArrivalsPerRound;
+
+    const dotParts: string[] = [
+      'digraph PathTree {',
+      '  graph [overlap=false];',
+      '  node [shape=ellipse style=filled fillcolor=lightgrey];',
+    ];
+    earliestArrivalsPerRound.forEach((arrivalsInRound, round) => {
+      arrivalsInRound.forEach((tripLeg: TripLeg) => {
+        const { origin, leg } = tripLeg;
+        if (!leg) return; // Skip if leg is undefined
+        const fromStop = this.result['stopsIndex'].findStopById(leg.from.id);
+        const toStop = this.result['stopsIndex'].findStopById(leg.to.id);
+        const originStop = this.result['stopsIndex'].findStopById(origin);
+
+        if (fromStop && toStop && originStop) {
+          const fromName = fromStop.platform
+            ? `${fromStop.name} (Pl. ${fromStop.platform})`
+            : fromStop.name;
+          const toName = toStop.platform
+            ? `${toStop.name} (Pl. ${toStop.platform})`
+            : toStop.name;
+          const originName = originStop.platform
+            ? `${originStop.name} (Pl. ${originStop.platform})`
+            : originStop.name;
+          const isVehicle = 'route' in leg;
+          const routeLabelContent = isVehicle
+            ? `${leg.route.name}\n${leg.departureTime.toString()} - ${leg.arrivalTime.toString()}`
+            : leg.minTransferTime
+              ? leg.minTransferTime.toString()
+              : '';
+          const intermediateNode = `IntermediateNode${fromStop.id}_${toStop.id}`;
+          const lineColor = isVehicle ? '' : ', color="red", fontcolor="red"';
+          const labelColor = isVehicle ? '' : ' fontcolor="red"';
+
+          dotParts.push(
+            `  "${fromName} (Origin: ${originName}) [R${round}]\n(${fromStop.id})" -> "${intermediateNode}" [shape=point${lineColor}];`,
+          );
+          dotParts.push(
+            `  "${intermediateNode}" [label="${routeLabelContent}" shape=rect style=filled fillcolor=white${labelColor} border=0];`,
+          );
+          dotParts.push(
+            `  "${intermediateNode}" -> "${toName} (Origin: ${originName}) [R${round}]\n(${toStop.id})" [${lineColor.replace(', ', '')}];`,
+          );
+        }
+      });
+    });
+
+    dotParts.push('}');
+    return dotParts.join('\n');
+  }
+}

package/src/routing/query.ts

@@ -0,0 +1,74 @@
+import { StopId } from '../stops/stops.js';
+import { Duration } from '../timetable/duration.js';
+import { Time } from '../timetable/time.js';
+import { ALL_TRANSPORT_MODES, RouteType } from '../timetable/timetable.js';
+
+export class Query {
+  from: StopId;
+  to: StopId[];
+  departureTime: Time;
+  lastDepartureTime?: Time;
+  options: {
+    maxTransfers: number;
+    minTransferTime: Duration;
+    transportModes: RouteType[];
+  };
+
+  constructor(builder: typeof Query.Builder.prototype) {
+    this.from = builder.fromValue;
+    this.to = builder.toValue;
+    this.departureTime = builder.departureTimeValue;
+    this.options = builder.optionsValue;
+  }
+
+  static Builder = class {
+    fromValue!: StopId;
+    toValue!: StopId[];
+    departureTimeValue!: Time;
+    // lastDepartureTimeValue?: Date;
+    // via: StopId[] = [];
+    optionsValue: {
+      maxTransfers: number;
+      minTransferTime: Duration;
+      transportModes: RouteType[];
+    } = {
+      maxTransfers: 5,
+      minTransferTime: Duration.fromSeconds(120),
+      transportModes: ALL_TRANSPORT_MODES,
+    };
+
+    from(from: StopId): this {
+      this.fromValue = from;
+      return this;
+    }
+
+    to(to: StopId | StopId[]): this {
+      this.toValue = Array.isArray(to) ? to : [to];
+      return this;
+    }
+
+    departureTime(departureTime: Time): this {
+      this.departureTimeValue = departureTime;
+      return this;
+    }
+
+    maxTransfers(maxTransfers: number): this {
+      this.optionsValue.maxTransfers = maxTransfers;
+      return this;
+    }
+
+    minTransferTime(minTransferTime: Duration): this {
+      this.optionsValue.minTransferTime = minTransferTime;
+      return this;
+    }
+
+    transportModes(transportModes: RouteType[]): this {
+      this.optionsValue.transportModes = transportModes;
+      return this;
+    }
+
+    build(): Query {
+      return new Query(this);
+    }
+  };
+}

package/src/routing/result.ts

@@ -0,0 +1,108 @@
+import { StopId } from '../stops/stops.js';
+import { StopsIndex } from '../umdIndex.js';
+import { Query } from './query.js';
+import { Leg, Route } from './route.js';
+import { ReachingTime, TripLeg } from './router.js';
+
+export class Result {
+  private readonly query: Query;
+  private readonly earliestArrivals: Map<StopId, ReachingTime>;
+  public readonly earliestArrivalsPerRound: Map<StopId, TripLeg>[];
+  private readonly stopsIndex: StopsIndex;
+
+  constructor(
+    query: Query,
+    earliestArrivals: Map<StopId, ReachingTime>,
+    earliestArrivalsPerRound: Map<StopId, TripLeg>[],
+    stopsIndex: StopsIndex,
+  ) {
+    this.query = query;
+    this.earliestArrivals = earliestArrivals;
+    this.earliestArrivalsPerRound = earliestArrivalsPerRound;
+    this.stopsIndex = stopsIndex;
+  }
+
+  /**
+   * Reconstructs the best route to a stop.
+   * (to any stop reachable in less time / transfers than the destination(s) of the query)
+   *
+   * @param to The destination stop. Defaults to the destination of the original query.
+   * @returns a route to the destination stop if it exists.
+   */
+  bestRoute(to?: StopId | StopId[]): Route | undefined {
+    const destinationList = Array.isArray(to) ? to : to ? [to] : this.query.to;
+    const destinations = destinationList.flatMap((destination) =>
+      this.stopsIndex.equivalentStops(destination),
+    );
+
+    let fastestDestination: StopId | undefined = undefined;
+    let fastestTime: ReachingTime | undefined = undefined;
+    for (const destination of destinations) {
+      const arrivalTime = this.earliestArrivals.get(destination);
+      if (arrivalTime !== undefined) {
+        if (
+          fastestTime === undefined ||
+          arrivalTime.time.toSeconds() < fastestTime.time.toSeconds()
+        ) {
+          fastestDestination = destination;
+          fastestTime = arrivalTime;
+        }
+      }
+    }
+    if (!fastestDestination || !fastestTime) {
+      return undefined;
+    }
+
+    const route: Leg[] = [];
+    let currentStop = fastestDestination;
+    let round = fastestTime.legNumber;
+    while (fastestTime.origin !== currentStop) {
+      const tripLeg = this.earliestArrivalsPerRound[round]?.get(currentStop);
+      if (!tripLeg?.leg) {
+        throw new Error(
+          `No leg found for a trip leg: start stop=${
+            tripLeg?.leg?.from.id ?? 'unknown'
+          }, end stop=${currentStop}, round=${round}, origin=${fastestTime.origin}`,
+        );
+      }
+      route.unshift(tripLeg.leg);
+      currentStop = tripLeg.leg.from.id;
+      if ('route' in tripLeg.leg) {
+        round -= 1;
+      }
+    }
+    return new Route(route);
+  }
+
+  /**
+   * Returns the arrival time at any stop reachable in less time / transfers than the destination(s) of the query)
+   *
+   * @param stop The target stop for which to return the arrival time.
+   * @param maxTransfers The optional maximum number of transfers allowed.
+   * @returns The arrival time if the target stop is reachable, otherwise undefined.
+   */
+  arrivalAt(stop: StopId, maxTransfers?: number): ReachingTime | undefined {
+    const equivalentStops = this.stopsIndex.equivalentStops(stop);
+    let earliestArrival: ReachingTime | undefined = undefined;
+
+    const relevantArrivals =
+      maxTransfers !== undefined
+        ? // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+          this.earliestArrivalsPerRound[maxTransfers - 1]!
+        : this.earliestArrivals;
+
+    for (const equivalentStop of equivalentStops) {
+      const arrivalTime = relevantArrivals.get(equivalentStop);
+      if (arrivalTime !== undefined) {
+        if (
+          earliestArrival === undefined ||
+          arrivalTime.time.toSeconds() < earliestArrival.time.toSeconds()
+        ) {
+          earliestArrival = arrivalTime;
+        }
+      }
+    }
+
+    return earliestArrival;
+  }
+}

package/src/routing/route.ts

@@ -0,0 +1,94 @@
+import { Stop } from '../stops/stops.js';
+import { Duration } from '../timetable/duration.js';
+import { Time } from '../timetable/time.js';
+import { ServiceRoute } from '../timetable/timetable.js';
+
+export type BaseLeg = {
+  from: Stop;
+  to: Stop;
+};
+
+export type Transfer = BaseLeg & {
+  minTransferTime?: Duration;
+};
+
+export type VehicleLeg = BaseLeg & {
+  route: ServiceRoute;
+  departureTime: Time;
+  arrivalTime: Time;
+};
+
+export type Leg = Transfer | VehicleLeg;
+
+export class Route {
+  legs: Leg[];
+
+  constructor(legs: Leg[]) {
+    if (legs.length === 0) {
+      throw new Error('There must be at least one leg in a route');
+    }
+    this.legs = legs;
+  }
+
+  departureTime(): Time {
+    const cumulativeTransferTime: Duration = Duration.zero();
+    for (let i = 0; i < this.legs.length; i++) {
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      const leg = this.legs[i]!;
+      if ('departureTime' in leg) {
+        return leg.departureTime.minus(cumulativeTransferTime);
+      }
+      if ('minTransferTime' in leg && leg.minTransferTime) {
+        cumulativeTransferTime.add(leg.minTransferTime);
+      }
+    }
+    throw new Error('No vehicle leg found in route');
+  }
+
+  arrivalTime(): Time {
+    let lastVehicleArrivalTime: Time = Time.origin();
+    const totalTransferTime: Duration = Duration.zero();
+    let vehicleLegFound = false;
+
+    for (let i = this.legs.length - 1; i >= 0; i--) {
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      const leg = this.legs[i]!;
+
+      if ('arrivalTime' in leg && !vehicleLegFound) {
+        lastVehicleArrivalTime = leg.arrivalTime;
+        vehicleLegFound = true;
+      } else if (
+        'minTransferTime' in leg &&
+        leg.minTransferTime &&
+        vehicleLegFound
+      ) {
+        totalTransferTime.add(leg.minTransferTime);
+      }
+    }
+
+    if (!vehicleLegFound) {
+      throw new Error('No vehicle leg found in route');
+    }
+
+    return lastVehicleArrivalTime.plus(totalTransferTime);
+  }
+
+  totalDuration(): Duration {
+    if (this.legs.length === 0) return Duration.zero();
+    return this.arrivalTime().diff(this.departureTime());
+  }
+
+  print(): string {
+    return this.legs
+      .map((leg, index) => {
+        if ('route' in leg) {
+          return `Leg ${index + 1}: ${leg.from.name} to ${leg.to.name}
+            via route ${leg.route.type} ${leg.route.name},
+            departs at ${leg.departureTime.toString()}, arrives at ${leg.arrivalTime.toString()}`;
+        }
+        return `Leg ${index + 1}: Transfer from ${leg.from.name} to ${leg.to.name},
+            minimum transfer time: ${leg.minTransferTime?.toString() ?? 'not specified'}`;
+      })
+      .join('\n');
+  }
+}

package/src/routing/router.ts

@@ -0,0 +1,262 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+import { StopId } from '../stops/stops.js';
+import { Duration } from '../timetable/duration.js';
+import { Time } from '../timetable/time.js';
+import { Timetable } from '../timetable/timetable.js';
+import { StopsIndex } from '../umdIndex.js';
+import { Query } from './query.js';
+import { Result } from './result.js';
+import { Leg } from './route.js';
+
+const UNREACHED = Time.infinity();
+
+export type TripLeg = ReachingTime & {
+  leg?: Leg; // leg is not set for the very first segment
+};
+
+export type ReachingTime = {
+  time: Time;
+  legNumber: number;
+  origin: StopId;
+};
+
+type CurrentTrip = {
+  trip: number;
+  origin: StopId;
+  bestHopOnStop: StopId;
+};
+
+export class Router {
+  private readonly timetable: Timetable;
+  private readonly stopsIndex: StopsIndex;
+
+  constructor(timetable: Timetable, stopsIndex: StopsIndex) {
+    this.timetable = timetable;
+    this.stopsIndex = stopsIndex;
+  }
+
+  /**
+   * Evaluates possible transfers for a given query on a transport
+   * network, updating the earliest arrivals at various stops and marking new
+   * stops that can be reached through these transfers.
+   */
+  private considerTransfers(
+    query: Query,
+    markedStops: Set<StopId>,
+    arrivalsAtCurrentRound: Map<StopId, TripLeg>,
+    earliestArrivals: Map<StopId, ReachingTime>,
+    round: number,
+  ): void {
+    const { options } = query;
+    const newlyMarkedStops: Set<StopId> = new Set();
+    for (const stop of markedStops) {
+      for (const transfer of this.timetable.getTransfers(stop)) {
+        let transferTime: Duration;
+        if (transfer.minTransferTime) {
+          transferTime = transfer.minTransferTime;
+        } else if (transfer.type === 'IN_SEAT') {
+          transferTime = Duration.zero();
+        } else {
+          transferTime = options.minTransferTime;
+        }
+        const arrivalAfterTransfer = arrivalsAtCurrentRound
+          .get(stop)!
+          .time.plus(transferTime);
+        const originalArrival =
+          arrivalsAtCurrentRound.get(transfer.destination)?.time ?? UNREACHED;
+        if (arrivalAfterTransfer.toSeconds() < originalArrival.toSeconds()) {
+          const origin = arrivalsAtCurrentRound.get(stop)?.origin ?? stop;
+          arrivalsAtCurrentRound.set(transfer.destination, {
+            time: arrivalAfterTransfer,
+            legNumber: round,
+            origin: origin,
+            leg: {
+              from: this.stopsIndex.findStopById(stop)!,
+              to: this.stopsIndex.findStopById(transfer.destination)!,
+              minTransferTime: transfer.minTransferTime,
+            },
+          });
+          earliestArrivals.set(transfer.destination, {
+            time: arrivalAfterTransfer,
+            legNumber: round,
+            origin: origin,
+          });
+          newlyMarkedStops.add(transfer.destination);
+        }
+      }
+    }
+    for (const newStop of newlyMarkedStops) {
+      markedStops.add(newStop);
+    }
+  }
+
+  /**
+   * The main Raptor algorithm implementation.
+   *
+   * @param query The query containing the main parameters for the routing.
+   * @returns A result object containing data structures allowing to reconstruct routes and .
+   */
+  route(query: Query): Result {
+    const { from, to, departureTime, options } = query;
+    // 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) =>
+      this.stopsIndex.equivalentStops(destination),
+    );
+    const earliestArrivals = new Map<StopId, ReachingTime>();
+
+    const earliestArrivalsWithoutAnyLeg = new Map<StopId, TripLeg>();
+    const earliestArrivalsPerRound = [earliestArrivalsWithoutAnyLeg];
+    // Stops that have been improved at round k-1
+    const markedStops = new Set<StopId>();
+
+    for (const originStop of origins) {
+      markedStops.add(originStop);
+      earliestArrivals.set(originStop, {
+        time: departureTime,
+        legNumber: 0,
+        origin: originStop,
+      });
+      earliestArrivalsWithoutAnyLeg.set(originStop, {
+        time: departureTime,
+        legNumber: 0,
+        origin: originStop,
+      });
+    }
+    // on the first round we need to first consider transfers to discover all possible route origins
+    this.considerTransfers(
+      query,
+      markedStops,
+      earliestArrivalsWithoutAnyLeg,
+      earliestArrivals,
+      0,
+    );
+
+    for (let round = 1; round <= options.maxTransfers + 1; round++) {
+      const arrivalsAtCurrentRound = new Map<StopId, TripLeg>();
+      earliestArrivalsPerRound.push(arrivalsAtCurrentRound);
+      const arrivalsAtPreviousRound = earliestArrivalsPerRound[round - 1]!;
+      // Routes that contain at least one stop reached with at least round - 1 legs
+      // together with corresponding hop on stop index (earliest marked stop)
+      const reachableRoutes = this.timetable.findReachableRoutes(
+        markedStops,
+        options.transportModes,
+      );
+      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)!;
+        let currentTrip: CurrentTrip | undefined = undefined;
+        const hopOnIndex = route.stopIndices.get(hopOnStop)!;
+        // for each stops 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;
+          if (currentTrip !== undefined) {
+            const currentStopTimes =
+              route.stopTimes[currentTrip.trip * stopNumbers + i]!;
+            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)?.time ?? UNREACHED;
+                earliestArrivalsAtDestinations.push(
+                  earliestArrivalAtDestination,
+                );
+              }
+              const earliestArrivalAtDestination = Time.min(
+                ...earliestArrivalsAtDestinations,
+              );
+              arrivalToImprove = Time.min(
+                earliestArrivalAtCurrentStop,
+                earliestArrivalAtDestination,
+              );
+            }
+            if (
+              currentStopTimes.dropOffType !== 'NOT_AVAILABLE' &&
+              currentStopTimes.arrival.toSeconds() <
+                arrivalToImprove.toSeconds()
+            ) {
+              const bestHopOnStopIndex = route.stopIndices.get(
+                currentTrip.bestHopOnStop,
+              )!;
+              const bestHopOnStopTimes =
+                route.stopTimes[
+                  currentTrip.trip * stopNumbers + bestHopOnStopIndex
+                ]!;
+              arrivalsAtCurrentRound.set(currentStop, {
+                time: currentStopTimes.arrival,
+                legNumber: round,
+                origin: currentTrip.origin,
+                leg: {
+                  from: this.stopsIndex.findStopById(
+                    currentTrip.bestHopOnStop,
+                  )!,
+                  to: this.stopsIndex.findStopById(currentStop)!,
+                  departureTime: bestHopOnStopTimes.departure,
+                  arrivalTime: currentStopTimes.arrival,
+                  route: this.timetable.getServiceRoute(route.serviceRouteId),
+                },
+              });
+              earliestArrivals.set(currentStop, {
+                time: currentStopTimes.arrival,
+                legNumber: round,
+                origin: currentTrip.origin,
+              });
+              markedStops.add(currentStop);
+            }
+          }
+          // 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;
+          if (
+            earliestArrivalOnPreviousRound !== undefined &&
+            (currentTrip === undefined ||
+              earliestArrivalOnPreviousRound.toSeconds() <=
+                route.stopTimes[
+                  currentTrip.trip * stopNumbers + i
+                ]!.departure.toSeconds())
+          ) {
+            const earliestTrip = this.timetable.findEarliestTrip(
+              route,
+              currentStop,
+              currentTrip?.trip,
+              earliestArrivalOnPreviousRound,
+            );
+            if (earliestTrip !== undefined) {
+              currentTrip = {
+                trip: earliestTrip,
+                // we need to keep track of the best hop-on stop to reconstruct the route at the end
+                bestHopOnStop: currentStop,
+                origin:
+                  arrivalsAtPreviousRound.get(currentStop)?.origin ??
+                  currentStop,
+              };
+            }
+          }
+        }
+      }
+      this.considerTransfers(
+        query,
+        markedStops,
+        arrivalsAtCurrentRound,
+        earliestArrivals,
+        round,
+      );
+      if (markedStops.size === 0) break;
+    }
+    return new Result(
+      query,
+      earliestArrivals,
+      earliestArrivalsPerRound,
+      this.stopsIndex,
+    );
+  }
+}

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

@@ -0,0 +1,43 @@
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+
+import { deserializeStopsMap, serializeStopsMap } from '../io.js';
+import { StopsMap } from '../stops.js';
+
+describe('stops io', () => {
+  const stopsMap: StopsMap = new Map([
+    [
+      'stop1',
+      {
+        id: 'stop1',
+        name: 'Stop 1',
+        lat: 40.712776,
+        lon: -74.005974,
+        children: ['stop2'],
+        parent: 'parentStop',
+        locationType: 'SIMPLE_STOP_OR_PLATFORM',
+        platform: 'Platform 1',
+      },
+    ],
+    [
+      'stop2',
+      {
+        id: 'stop2',
+        name: 'Stop 2',
+        lat: 34.052235,
+        lon: -118.243683,
+        children: [],
+        parent: 'stop1',
+        locationType: 'STATION',
+        platform: 'Platform 2',
+      },
+    ],
+  ]);
+
+  it('should serialize and deserialize stops correctly', () => {
+    const serializedData = serializeStopsMap(stopsMap);
+    const deserializedStopsMap = deserializeStopsMap(serializedData);
+
+    assert.deepStrictEqual(deserializedStopsMap, stopsMap);
+  });
+});