minotor 3.0.0 → 3.0.2

package/src/routing/__tests__/router.test.ts

@@ -4,6 +4,7 @@ import { beforeEach, describe, it } from 'node:test';
 import { StopsMap } from '../../stops/stops.js';
 import { StopsIndex } from '../../stops/stopsIndex.js';
 import { Duration } from '../../timetable/duration.js';
+import { REGULAR, Route } from '../../timetable/route.js';
 import { Time } from '../../timetable/time.js';
 import {
   RoutesAdjacency,
@@ -30,8 +31,8 @@ describe('Router', () => {
       const routesAdjacency: RoutesAdjacency = new Map([
         [
           'route1',
-          {
-            stopTimes: new Uint16Array([
+          new Route(
+            new Uint16Array([
               Time.fromString('08:00:00').toMinutes(),
               Time.fromString('08:10:00').toMinutes(),
               Time.fromString('08:15:00').toMinutes(),
@@ -39,22 +40,17 @@ describe('Router', () => {
               Time.fromString('08:35:00').toMinutes(),
               Time.fromString('08:45:00').toMinutes(),
             ]),
-            pickUpDropOffTypes: new Uint8Array([
-              0,
-              0, // REGULAR
-              0,
-              0, // REGULAR
-              0,
-              0, // REGULAR
-            ]),
-            stops: new Uint32Array([0, 1, 2]),
-            stopIndices: new Map([
-              [0, 0],
-              [1, 1],
-              [2, 2],
+            new Uint8Array([
+              REGULAR,
+              REGULAR,
+              REGULAR,
+              REGULAR,
+              REGULAR,
+              REGULAR,
             ]),
-            serviceRouteId: 'service_route1',
-          },
+            new Uint32Array([0, 1, 2]),
+            'service_route1',
+          ),
         ],
       ]);
 
@@ -147,7 +143,7 @@ describe('Router', () => {
 
       const timeToStop3 = result.arrivalAt('stop3');
       assert.strictEqual(
-        timeToStop3?.time.toMinutes(),
+        timeToStop3?.arrival.toMinutes(),
         Time.fromString('08:35:00').toMinutes(),
       );
     });
@@ -167,8 +163,8 @@ describe('Router', () => {
       const routesAdjacency: RoutesAdjacency = new Map([
         [
           'route1',
-          {
-            stopTimes: new Uint16Array([
+          new Route(
+            new Uint16Array([
               Time.fromString('08:00:00').toMinutes(),
               Time.fromString('08:15:00').toMinutes(),
               Time.fromString('08:30:00').toMinutes(),
@@ -176,27 +172,22 @@ describe('Router', () => {
               Time.fromString('09:00:00').toMinutes(),
               Time.fromString('09:10:00').toMinutes(),
             ]),
-            pickUpDropOffTypes: new Uint8Array([
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
+            new Uint8Array([
+              REGULAR,
+              REGULAR,
+              REGULAR,
+              REGULAR,
+              REGULAR,
+              REGULAR,
             ]),
-            stops: new Uint32Array([0, 1, 2]),
-            stopIndices: new Map([
-              [0, 0],
-              [1, 1],
-              [2, 2],
-            ]),
-            serviceRouteId: 'service_route1',
-          },
+            new Uint32Array([0, 1, 2]),
+            'service_route1',
+          ),
         ],
         [
           'route2',
-          {
-            stopTimes: new Uint16Array([
+          new Route(
+            new Uint16Array([
               Time.fromString('08:05:00').toMinutes(),
               Time.fromString('08:20:00').toMinutes(),
               Time.fromString('09:00:00').toMinutes(),
@@ -204,22 +195,17 @@ describe('Router', () => {
               Time.fromString('09:20:00').toMinutes(),
               Time.fromString('09:35:00').toMinutes(),
             ]),
-            pickUpDropOffTypes: new Uint8Array([
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
+            new Uint8Array([
+              REGULAR,
+              REGULAR,
+              REGULAR,
+              REGULAR,
+              REGULAR,
+              REGULAR,
             ]),
-            stops: new Uint32Array([3, 1, 4]),
-            stopIndices: new Map([
-              [3, 0],
-              [1, 1],
-              [4, 2],
-            ]),
-            serviceRouteId: 'service_route2',
-          },
+            new Uint32Array([3, 1, 4]),
+            'service_route2',
+          ),
         ],
       ]);
 
@@ -333,7 +319,7 @@ describe('Router', () => {
 
       const timeToStop5 = result.arrivalAt('stop5');
       assert.strictEqual(
-        timeToStop5?.time.toMinutes(),
+        timeToStop5?.arrival.toMinutes(),
         Time.fromString('09:20:00').toMinutes(),
       );
     });
@@ -367,8 +353,8 @@ describe('Router', () => {
       const routesAdjacency: RoutesAdjacency = new Map([
         [
           'route1',
-          {
-            stopTimes: new Uint16Array([
+          new Route(
+            new Uint16Array([
               Time.fromString('08:00:00').toMinutes(),
               Time.fromString('08:15:00').toMinutes(),
               Time.fromString('08:25:00').toMinutes(),
@@ -376,27 +362,22 @@ describe('Router', () => {
               Time.fromString('08:45:00').toMinutes(),
               Time.fromString('08:55:00').toMinutes(),
             ]),
-            pickUpDropOffTypes: new Uint8Array([
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
+            new Uint8Array([
+              REGULAR,
+              REGULAR,
+              REGULAR,
+              REGULAR,
+              REGULAR,
+              REGULAR,
             ]),
-            stops: new Uint32Array([0, 1, 2]),
-            stopIndices: new Map([
-              [0, 0],
-              [1, 1],
-              [2, 2],
-            ]),
-            serviceRouteId: 'service_route1',
-          },
+            new Uint32Array([0, 1, 2]),
+            'service_route1',
+          ),
         ],
         [
           'route2',
-          {
-            stopTimes: new Uint16Array([
+          new Route(
+            new Uint16Array([
               Time.fromString('08:10:00').toMinutes(),
               Time.fromString('08:20:00').toMinutes(),
               Time.fromString('08:40:00').toMinutes(),
@@ -404,22 +385,17 @@ describe('Router', () => {
               Time.fromString('09:00:00').toMinutes(),
               Time.fromString('09:10:00').toMinutes(),
             ]),
-            pickUpDropOffTypes: new Uint8Array([
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
+            new Uint8Array([
+              REGULAR,
+              REGULAR,
+              REGULAR,
+              REGULAR,
+              REGULAR,
+              REGULAR,
             ]),
-            stops: new Uint32Array([3, 4, 5]),
-            stopIndices: new Map([
-              [3, 0],
-              [4, 1],
-              [5, 2],
-            ]),
-            serviceRouteId: 'service_route2',
-          },
+            new Uint32Array([3, 4, 5]),
+            'service_route2',
+          ),
         ],
       ]);
 
@@ -543,7 +519,7 @@ describe('Router', () => {
 
       const timeToStop5 = result.arrivalAt('stop5');
       assert.strictEqual(
-        timeToStop5?.time.toMinutes(),
+        timeToStop5?.arrival.toMinutes(),
         Time.fromString('08:30:00').toMinutes(),
       );
     });
@@ -564,8 +540,8 @@ describe('Router', () => {
       const routesAdjacency: RoutesAdjacency = new Map([
         [
           'route1',
-          {
-            stopTimes: new Uint16Array([
+          new Route(
+            new Uint16Array([
               Time.fromString('08:00:00').toMinutes(),
               Time.fromString('08:15:00').toMinutes(),
               Time.fromString('08:30:00').toMinutes(),
@@ -573,27 +549,22 @@ describe('Router', () => {
               Time.fromString('09:00:00').toMinutes(),
               Time.fromString('09:15:00').toMinutes(),
             ]),
-            pickUpDropOffTypes: new Uint8Array([
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
+            new Uint8Array([
+              REGULAR,
+              REGULAR,
+              REGULAR,
+              REGULAR,
+              REGULAR,
+              REGULAR,
             ]),
-            stops: new Uint32Array([0, 1, 2]),
-            stopIndices: new Map([
-              [0, 0],
-              [1, 1],
-              [2, 2],
-            ]),
-            serviceRouteId: 'service_route1',
-          },
+            new Uint32Array([0, 1, 2]),
+            'service_route1',
+          ),
         ],
         [
           'route2',
-          {
-            stopTimes: new Uint16Array([
+          new Route(
+            new Uint16Array([
               Time.fromString('08:10:00').toMinutes(),
               Time.fromString('08:25:00').toMinutes(),
               Time.fromString('08:50:00').toMinutes(),
@@ -601,45 +572,31 @@ describe('Router', () => {
               Time.fromString('09:10:00').toMinutes(),
               Time.fromString('09:25:00').toMinutes(),
             ]),
-            pickUpDropOffTypes: new Uint8Array([
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
+            new Uint8Array([
+              REGULAR,
+              REGULAR,
+              REGULAR,
+              REGULAR,
+              REGULAR,
+              REGULAR,
             ]),
-            stops: new Uint32Array([3, 1, 4]),
-            stopIndices: new Map([
-              [3, 0],
-              [1, 1],
-              [4, 2],
-            ]),
-            serviceRouteId: 'service_route2',
-          },
+            new Uint32Array([3, 1, 4]),
+            'service_route2',
+          ),
         ],
         [
           'route3',
-          {
-            stopTimes: new Uint16Array([
+          new Route(
+            new Uint16Array([
               Time.fromString('08:00:00').toMinutes(),
               Time.fromString('08:15:00').toMinutes(),
               Time.fromString('09:45:00').toMinutes(),
               Time.fromString('10:00:00').toMinutes(),
             ]),
-            pickUpDropOffTypes: new Uint8Array([
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
-              0, // REGULAR
-            ]),
-            stops: new Uint32Array([0, 4]),
-            stopIndices: new Map([
-              [0, 0],
-              [4, 1],
-            ]),
-            serviceRouteId: 'service_route3',
-          },
+            new Uint8Array([REGULAR, REGULAR, REGULAR, REGULAR]),
+            new Uint32Array([0, 4]),
+            'service_route3',
+          ),
         ],
       ]);
 

package/src/routing/query.ts

@@ -5,13 +5,13 @@ import { ALL_TRANSPORT_MODES, RouteType } from '../timetable/timetable.js';
 
 export class Query {
   from: SourceStopId;
-  to: SourceStopId[];
+  to: Set<SourceStopId>;
   departureTime: Time;
   lastDepartureTime?: Time;
   options: {
     maxTransfers: number;
     minTransferTime: Duration;
-    transportModes: RouteType[];
+    transportModes: Set<RouteType>;
   };
 
   constructor(builder: typeof Query.Builder.prototype) {
@@ -23,46 +23,67 @@ export class Query {
 
   static Builder = class {
     fromValue!: SourceStopId;
-    toValue: SourceStopId[] = [];
+    toValue: Set<SourceStopId> = new Set();
     departureTimeValue!: Time;
     // lastDepartureTimeValue?: Date;
     // via: StopId[] = [];
     optionsValue: {
       maxTransfers: number;
       minTransferTime: Duration;
-      transportModes: RouteType[];
+      transportModes: Set<RouteType>;
     } = {
       maxTransfers: 5,
       minTransferTime: Duration.fromSeconds(120),
       transportModes: ALL_TRANSPORT_MODES,
     };
 
+    /**
+     * Sets the starting stop.
+     */
     from(from: SourceStopId): this {
       this.fromValue = from;
       return this;
     }
 
-    to(to: SourceStopId | SourceStopId[]): this {
-      this.toValue = Array.isArray(to) ? to : [to];
+    /**
+     * Sets the destination stops(s), routing will stop when all the provided stops are reached.
+     */
+    to(to: SourceStopId | Set<SourceStopId>): this {
+      this.toValue = to instanceof Set ? to : new Set([to]);
       return this;
     }
 
+    /**
+     * Sets the departure time for the query.
+     * Note that the router will favor routes that depart shortly after the provided departure time,
+     * even if a later route might arrive at the same time.
+     * Range queries will allow to specify a range of departure times in the future.
+     */
     departureTime(departureTime: Time): this {
       this.departureTimeValue = departureTime;
       return this;
     }
 
+    /**
+     * Sets the maximum number of transfers allowed.
+     */
     maxTransfers(maxTransfers: number): this {
       this.optionsValue.maxTransfers = maxTransfers;
       return this;
     }
 
+    /**
+     * Sets the minimum transfer time to use when no transfer time is provided in the data.
+     */
     minTransferTime(minTransferTime: Duration): this {
       this.optionsValue.minTransferTime = minTransferTime;
       return this;
     }
 
-    transportModes(transportModes: RouteType[]): this {
+    /**
+     * Sets the transport modes to consider.
+     */
+    transportModes(transportModes: Set<RouteType>): this {
       this.optionsValue.transportModes = transportModes;
       return this;
     }

package/src/routing/result.ts

@@ -29,8 +29,13 @@ export class Result {
    * @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?: SourceStopId | SourceStopId[]): Route | undefined {
-    const destinationList = Array.isArray(to) ? to : to ? [to] : this.query.to;
+  bestRoute(to?: SourceStopId | Set<SourceStopId>): Route | undefined {
+    const destinationList =
+      to instanceof Set
+        ? Array.from(to)
+        : to
+          ? [to]
+          : Array.from(this.query.to);
     const destinations = destinationList.flatMap((destination) =>
       this.stopsIndex.equivalentStops(destination),
     );
@@ -42,7 +47,7 @@ export class Result {
       if (arrivalTime !== undefined) {
         if (
           fastestTime === undefined ||
-          arrivalTime.time.toMinutes() < fastestTime.time.toMinutes()
+          arrivalTime.arrival.isBefore(fastestTime.arrival)
         ) {
           fastestDestination = destination.id;
           fastestTime = arrivalTime;
@@ -91,7 +96,7 @@ export class Result {
     const relevantArrivals =
       maxTransfers !== undefined
         ? // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-          this.earliestArrivalsPerRound[maxTransfers - 1]!
+          this.earliestArrivalsPerRound[maxTransfers + 1]!
         : this.earliestArrivals;
 
     for (const equivalentStop of equivalentStops) {
@@ -99,7 +104,7 @@ export class Result {
       if (arrivalTime !== undefined) {
         if (
           earliestArrival === undefined ||
-          arrivalTime.time.toMinutes() < earliestArrival.time.toMinutes()
+          arrivalTime.arrival.isBefore(earliestArrival.arrival)
         ) {
           earliestArrival = arrivalTime;
         }

package/src/routing/route.ts

@@ -1,8 +1,23 @@
-import { Stop } from '../stops/stops.js';
+import { SourceStopId, Stop } from '../stops/stops.js';
 import { Duration } from '../timetable/duration.js';
 import { Time } from '../timetable/time.js';
 import { ServiceRoute, TransferType } from '../timetable/timetable.js';
 
+export type JsonLeg = {
+  from: SourceStopId;
+  to: SourceStopId;
+} & (
+  | {
+      departure: string;
+      arrival: string;
+      route: ServiceRoute;
+    }
+  | {
+      type: TransferType;
+      minTransferTime?: string;
+    }
+);
+
 export type PickUpDropOffType =
   | 'REGULAR'
   | 'NOT_AVAILABLE'
@@ -32,6 +47,10 @@ export type VehicleLeg = BaseLeg & {
 
 export type Leg = Transfer | VehicleLeg;
 
+/**
+ * Represents a resolved route consisting of multiple legs,
+ * which can be either vehicle legs or transfer legs.
+ */
 export class Route {
   legs: Leg[];
 
@@ -39,6 +58,12 @@ export class Route {
     this.legs = legs;
   }
 
+  /**
+   * Calculates the departure time of the route.
+   *
+   * @returns The departure time of the route.
+   * @throws If no vehicle leg is found in the route.
+   */
   departureTime(): Time {
     const cumulativeTransferTime: Duration = Duration.zero();
     for (let i = 0; i < this.legs.length; i++) {
@@ -54,6 +79,12 @@ export class Route {
     throw new Error('No vehicle leg found in route');
   }
 
+  /**
+   * Calculates the arrival time of the route.
+   *
+   * @returns The arrival time of the route.
+   * @throws If no vehicle leg is found in the route.
+   */
   arrivalTime(): Time {
     let lastVehicleArrivalTime: Time = Time.origin();
     const totalTransferTime: Duration = Duration.zero();
@@ -82,22 +113,77 @@ export class Route {
     return lastVehicleArrivalTime.plus(totalTransferTime);
   }
 
+  /**
+   * Calculates the total duration of the route.
+   *
+   * @returns The total duration of the route.
+   */
   totalDuration(): Duration {
     if (this.legs.length === 0) return Duration.zero();
     return this.arrivalTime().diff(this.departureTime());
   }
 
-  print(): string {
+  /**
+   * Generates a human-readable string representation of the route.
+   *
+   * @returns A formatted string describing each leg of the route.
+   */
+  toString(): 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'}`;
+        const fromStop = `From: ${leg.from.name}${leg.from.platform ? ` (Pl. ${leg.from.platform})` : ''}`;
+        const toStop = `To: ${leg.to.name}${leg.to.platform ? ` (Pl. ${leg.to.platform})` : ''}`;
+        const transferDetails =
+          'minTransferTime' in leg
+            ? `Minimum Transfer Time: ${leg.minTransferTime?.toString()}`
+            : '';
+        const travelDetails =
+          'route' in leg && 'departureTime' in leg && 'arrivalTime' in leg
+            ? `Route: ${leg.route.type} ${leg.route.name}, Departure: ${leg.departureTime.toString()}, Arrival: ${leg.arrivalTime.toString()}`
+            : '';
+
+        return [
+          `Leg ${index + 1}:`,
+          `  ${fromStop}`,
+          `  ${toStop}`,
+          transferDetails ? `  ${transferDetails}` : '',
+          travelDetails ? `  ${travelDetails}` : '',
+        ]
+          .filter((line) => line.trim() !== '')
+          .join('\n');
       })
       .join('\n');
   }
+
+  /**
+   * Generates a concise JSON representation of the route.
+   * This is particularly useful for generating regression tests
+   * to verify the correctness of route calculations.
+   *
+   * @returns A JSON representation of the route.
+   */
+  asJson(): JsonLeg[] {
+    const jsonLegs: JsonLeg[] = this.legs.map((leg: Leg) => {
+      if ('route' in leg) {
+        return {
+          from: leg.from.sourceStopId,
+          to: leg.to.sourceStopId,
+          departure: leg.departureTime.toString(),
+          arrival: leg.arrivalTime.toString(),
+          route: leg.route,
+        };
+      } else {
+        return {
+          from: leg.from.sourceStopId,
+          to: leg.to.sourceStopId,
+          type: leg.type,
+          ...(leg.minTransferTime !== undefined && {
+            minTransferTime: leg.minTransferTime.toString(),
+          }),
+        };
+      }
+    });
+
+    return jsonLegs;
+  }
 }