minotor 11.1.2 → 11.2.0

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

@@ -0,0 +1,78 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+
+import { timeFromHM } from '../../timetable/time.js';
+import { RoutingState, UNREACHED_TIME } from '../state.js';
+
+describe('RoutingState', () => {
+  describe('arrivals', () => {
+    it('yields every reached stop with its arrival time and leg number', () => {
+      const state = RoutingState.fromTestData({
+        nbStops: 4,
+        arrivals: [
+          [1, timeFromHM(8, 30), 1],
+          [3, timeFromHM(9, 0), 2],
+        ],
+      });
+
+      const reached = [...state.arrivals()];
+      assert.strictEqual(reached.length, 2);
+      assert.deepStrictEqual(reached[0], {
+        stop: 1,
+        arrival: timeFromHM(8, 30),
+        legNumber: 1,
+      });
+      assert.deepStrictEqual(reached[1], {
+        stop: 3,
+        arrival: timeFromHM(9, 0),
+        legNumber: 2,
+      });
+    });
+
+    it('skips stops still at UNREACHED_TIME', () => {
+      const state = RoutingState.fromTestData({
+        nbStops: 3,
+        arrivals: [[0, timeFromHM(8, 0), 0]],
+      });
+
+      const reached = [...state.arrivals()];
+      assert.strictEqual(reached.length, 1);
+      assert.strictEqual(reached[0]!.stop, 0);
+    });
+
+    it('yields nothing when no stop has been reached', () => {
+      const state = RoutingState.fromTestData({ nbStops: 3 });
+      assert.strictEqual([...state.arrivals()].length, 0);
+    });
+  });
+
+  describe('destinationBest', () => {
+    it('reflects the earliest arrival at any destination', () => {
+      const state = RoutingState.fromTestData({
+        nbStops: 3,
+        destinations: [1, 2],
+        arrivals: [
+          [1, timeFromHM(9, 30), 1],
+          [2, timeFromHM(9, 0), 1],
+        ],
+      });
+      assert.strictEqual(state.destinationBest, timeFromHM(9, 0));
+    });
+
+    it('is UNREACHED_TIME when no destination has been reached', () => {
+      const state = RoutingState.fromTestData({
+        nbStops: 3,
+        destinations: [2],
+      });
+      assert.strictEqual(state.destinationBest, UNREACHED_TIME);
+    });
+  });
+
+  describe('nbStops', () => {
+    it('matches the size passed to fromTestData', () => {
+      const state = RoutingState.fromTestData({ nbStops: 7 });
+      assert.strictEqual(state.nbStops, 7);
+    });
+  });
+});

package/src/routing/access.ts

@@ -0,0 +1,144 @@
+import { StopId } from '../stops/stops.js';
+import { StopsIndex } from '../stops/stopsIndex.js';
+import { NOT_AVAILABLE } from '../timetable/route.js';
+import { Duration, Time } from '../timetable/time.js';
+import { Timetable } from '../timetable/timetable.js';
+
+/**
+ * An access path from the query origin to an initial boarding stop.
+ *
+ * Equivalent origin stops (reached at zero cost) have no `duration`.
+ * Stops reachable via a timed walking transfer carry a `duration` in minutes.
+ */
+export type AccessPoint = {
+  fromStopId: StopId;
+  toStopId: StopId;
+  duration: Duration;
+};
+
+/**
+ * Collects access paths from a query origin and resolves the set of
+ * distinct departure-time slots for Range RAPTOR.
+ */
+export class AccessFinder {
+  private readonly timetable: Timetable;
+  private readonly stopsIndex: StopsIndex;
+
+  constructor(timetable: Timetable, stopsIndex: StopsIndex) {
+    this.timetable = timetable;
+    this.stopsIndex = stopsIndex;
+  }
+
+  /**
+   * Returns every initial access path from the query origin: equivalent stops
+   * (no duration) plus every stop reachable via a single timed walking transfer
+   * (REQUIRES_MINIMAL_TIME), keeping the shortest walk when multiple origins
+   * can reach the same stop.
+   *
+   * @param origin                  Origin stop ID.
+   * @param fallbackMinTransferTime Transfer time used when a walking transfer
+   *                                has no explicit `minTransferTime` in the timetable data.
+   */
+  collectAccessPaths(
+    queryOrigin: StopId,
+    fallbackMinTransferTime: Duration,
+  ): AccessPoint[] {
+    const equivalentOrigins = this.stopsIndex
+      .equivalentStops(queryOrigin)
+      .map((stop) => stop.id);
+
+    const accessPaths = new Map<StopId, AccessPoint>();
+    for (const origin of equivalentOrigins) {
+      const existingAccess = accessPaths.get(origin);
+      if (existingAccess === undefined || existingAccess.duration > 0) {
+        accessPaths.set(origin, {
+          fromStopId: origin,
+          toStopId: origin,
+          duration: 0,
+        });
+      }
+      for (const transfer of this.timetable.getTransfers(origin)) {
+        if (transfer.type === 'REQUIRES_MINIMAL_TIME') {
+          const duration = transfer.minTransferTime ?? fallbackMinTransferTime;
+          const existingAccess = accessPaths.get(transfer.destination);
+          // Keep the shortest walk to maximize the set of reachable trips.
+          if (
+            existingAccess === undefined ||
+            (existingAccess.duration && duration < existingAccess.duration)
+          ) {
+            accessPaths.set(transfer.destination, {
+              fromStopId: origin,
+              toStopId: transfer.destination,
+              duration,
+            });
+          }
+        }
+      }
+    }
+    return Array.from(accessPaths.values());
+  }
+
+  /**
+   * Collects all distinct origin departure times within `[from, to]`
+   * (inclusive) and, for each slot, the specific access paths that directly
+   * induce it — i.e. paths whose boarded stop has a boardable trip departing
+   * at exactly `depTime + path.duration`.
+   *
+   * Returned array is sorted **latest-first**. The Range RAPTOR outer loop
+   * seeds only the responsible paths for each slot, avoiding redundant
+   * exploration of access stops whose boarding opportunities belong to a
+   * later slot and whose journeys would therefore be dominated by it.
+   *
+
+   * @param accessPaths Access paths from the origin to initial boarding stops.
+   * @param from        Earliest origin departure time (inclusive).
+   * @param to          Latest origin departure time (inclusive).
+   */
+  collectDepartureTimes(
+    accessPaths: AccessPoint[],
+    from: Time,
+    to: Time,
+  ): { depTime: Time; legs: AccessPoint[] }[] {
+    // Map from origin-departure-time → the set of access paths that induce it.
+    const slotMap = new Map<Time, Set<AccessPoint>>();
+
+    for (const path of accessPaths) {
+      const { toStopId } = path;
+      // Trips from this stop must depart in [from + duration, to + duration]
+      // so that the corresponding origin departure (dep - duration) falls in
+      // [from, to].
+      const searchFrom = from + path.duration;
+      const searchTo = to + path.duration;
+      for (const route of this.timetable.routesPassingThrough(toStopId)) {
+        for (const stopIndex of route.stopRouteIndices(toStopId)) {
+          let tripIndex = route.findEarliestTrip(stopIndex, searchFrom);
+          if (tripIndex === undefined) continue;
+          const nbTrips = route.getNbTrips();
+          while (tripIndex < nbTrips) {
+            const dep = route.departureFrom(stopIndex, tripIndex);
+            if (dep > searchTo) break;
+            if (route.pickUpTypeFrom(stopIndex, tripIndex) !== NOT_AVAILABLE) {
+              const t = dep - path.duration;
+              let paths = slotMap.get(t);
+              if (paths === undefined) {
+                slotMap.set(t, (paths = new Set<AccessPoint>()));
+              }
+              paths.add(path);
+            }
+            tripIndex++;
+          }
+        }
+      }
+    }
+
+    if (slotMap.size === 0) return [];
+
+    // Sort descending so the outer loop processes latest departures first.
+    const sorted = Array.from(slotMap.entries()).sort(([a], [b]) => b - a);
+
+    return sorted.map(([depTime, paths]) => ({
+      depTime,
+      legs: Array.from(paths),
+    }));
+  }
+}

package/src/routing/plainRouter.ts

@@ -0,0 +1,60 @@
+import { StopsIndex } from '../stops/stopsIndex.js';
+import { Timetable } from '../timetable/timetable.js';
+import { AccessFinder } from './access.js';
+import { Query } from './query.js';
+import { Raptor } from './raptor.js';
+import { Result } from './result.js';
+import { RoutingState } from './state.js';
+
+export class PlainRouter {
+  private readonly timetable: Timetable;
+  private readonly stopsIndex: StopsIndex;
+  private readonly accessFinder: AccessFinder;
+  private readonly raptor: Raptor;
+
+  constructor(
+    timetable: Timetable,
+    stopsIndex: StopsIndex,
+    accessFinder: AccessFinder,
+    raptor: Raptor,
+  ) {
+    this.timetable = timetable;
+    this.stopsIndex = stopsIndex;
+    this.accessFinder = accessFinder;
+    this.raptor = raptor;
+  }
+
+  /**
+   * Standard RAPTOR: finds the earliest-arrival journey from `query.from` to
+   * `query.to` for the given departure time.
+   *
+   * @param query The routing query.
+   * @returns A {@link Result} that can reconstruct the best route and arrival times.
+   */
+  route(query: Query): Result {
+    const accessLegs = this.accessFinder.collectAccessPaths(
+      query.from,
+      query.options.minTransferTime,
+    );
+
+    const destinations = Array.from(query.to)
+      .flatMap((destination) => this.stopsIndex.equivalentStops(destination))
+      .map((destination) => destination.id);
+
+    const routingState = new RoutingState(
+      query.departureTime,
+      destinations,
+      accessLegs,
+      this.timetable.nbStops(),
+      query.options.maxTransfers + 1,
+    );
+
+    this.raptor.run(query.options, routingState);
+    return new Result(
+      new Set(destinations),
+      routingState,
+      this.stopsIndex,
+      this.timetable,
+    );
+  }
+}

package/src/routing/plotter.ts

@@ -1,7 +1,12 @@
 import { StopId } from '../stops/stops.js';
 import { durationToString, timeToString } from '../timetable/time.js';
 import { Result } from './result.js';
-import { RoutingEdge, TransferEdge, VehicleEdge } from './router.js';
+import {
+  AccessEdge,
+  RoutingEdge,
+  TransferEdge,
+  VehicleEdge,
+} from './router.js';
 
 /**
  * Configuration for DOT graph styling.
@@ -44,6 +49,13 @@ function isTransferEdge(edge: RoutingEdge): edge is TransferEdge {
   return 'from' in edge && 'to' in edge && 'type' in edge;
 }
 
+/**
+ * Type guard to check if an edge is an AccessEdge (walking access leg).
+ */
+function isAccessEdge(edge: RoutingEdge): edge is AccessEdge {
+  return 'from' in edge && 'duration' in edge;
+}
+
 /**
  * Helper class for building DOT graph syntax.
  */
@@ -164,6 +176,13 @@ export class Plotter {
     return `e_${fromStopId}_${toStopId}_${round}`;
   }
 
+  /**
+   * Generates a unique node ID for a walking access edge oval.
+   */
+  private accessEdgeNodeId(fromStopId: StopId, toStopId: StopId): string {
+    return `access_${fromStopId}_${toStopId}`;
+  }
+
   /**
    * Generates a unique node ID for a continuation edge oval.
    */
@@ -326,6 +345,24 @@ export class Plotter {
     ];
   }
 
+  /**
+   * Creates a walking access leg as a dashed oval connecting the query origin
+   * to the initial boarding stop.
+   */
+  private createAccessEdge(edge: AccessEdge): string[] {
+    const fromNodeId = this.stationNodeId(edge.from);
+    const toNodeId = this.stationNodeId(edge.to);
+    const color = DOT_CONFIG.colors.defaultRound;
+    const ovalId = this.accessEdgeNodeId(edge.from, edge.to);
+    const label = `Walk\\n${durationToString(edge.duration)}`;
+
+    return [
+      `  "${ovalId}" [label="${label}" shape=oval style="dashed,filled" fillcolor="white" color="${color}"];`,
+      `  "${fromNodeId}" -> "${ovalId}" [color="${color}" style="dashed"];`,
+      `  "${ovalId}" -> "${toNodeId}" [color="${color}" style="dashed"];`,
+    ];
+  }
+
   /**
    * Creates a transfer edge with transfer information oval in the middle.
    */
@@ -433,6 +470,11 @@ export class Plotter {
           const toStopId = this.getVehicleEdgeToStopId(edge);
           if (fromStopId) stations.add(fromStopId);
           if (toStopId) stations.add(toStopId);
+        } else if (isAccessEdge(edge)) {
+          // Ensure the query origin (edge.from) is always collected even when
+          // its own OriginNode hasn't been processed yet in this iteration.
+          stations.add(edge.from);
+          stations.add(edge.to);
         }
       }
     }
@@ -475,14 +517,19 @@ export class Plotter {
       const roundEdges = graph[round];
       if (!roundEdges) continue;
 
-      // Skip round 0 as it contains only origin nodes
-      if (round === 0) {
-        continue;
-      }
-
       for (let stopId = 0; stopId < roundEdges.length; stopId++) {
         const edge = roundEdges[stopId];
         if (edge === undefined) continue;
+
+        if (round === 0) {
+          // Round 0 holds OriginNodes (no edge to draw) and AccessEdges
+          // (walking legs from the query origin to the first boarding stop).
+          if (isAccessEdge(edge)) {
+            edges.push(...this.createAccessEdge(edge));
+          }
+          continue;
+        }
+
         if (isVehicleEdge(edge)) {
           edges.push(...this.createVehicleEdge(edge, round));
 

package/src/routing/query.ts

@@ -6,13 +6,28 @@ export type QueryOptions = {
   maxTransfers: number;
   minTransferTime: Duration;
   transportModes: Set<RouteType>;
+  /**
+   * Maximum time (in minutes) the traveler is willing to wait at the first
+   * boarding stop before the first transit vehicle departs.
+   *
+   * When set, any trip that would require waiting longer than this duration
+   * after arriving at the stop is skipped for the first boarding leg.
+   * Undefined means no limit.
+   */
+  maxInitialWaitingTime?: Duration;
 };
 
+/**
+ * A routing query for standard RAPTOR.
+ *
+ * Finds the earliest-arrival journey from `from` to `to` for a single
+ * departure time.  Use {@link RangeQuery} (and `router.rangeRoute()`) when
+ * you want all Pareto-optimal journeys within a departure-time window.
+ */
 export class Query {
   from: StopId;
   to: Set<StopId>;
   departureTime: Time;
-  lastDepartureTime?: Time;
   options: QueryOptions;
 
   constructor(builder: typeof Query.Builder.prototype) {
@@ -26,11 +41,7 @@ export class Query {
     fromValue!: StopId;
     toValue: Set<StopId> = new Set();
     departureTimeValue!: Time;
-    optionsValue: {
-      maxTransfers: number;
-      minTransferTime: Duration;
-      transportModes: Set<RouteType>;
-    } = {
+    optionsValue: QueryOptions = {
       maxTransfers: 5,
       minTransferTime: durationFromSeconds(120),
       transportModes: ALL_TRANSPORT_MODES,
@@ -45,7 +56,8 @@ export class Query {
     }
 
     /**
-     * Sets the destination stops(s), routing will stop when all the provided stops are reached.
+     * Sets the destination stop(s).
+     * Routing stops as soon as all provided stops have been reached.
      */
     to(to: StopId | Set<StopId>): this {
       this.toValue = to instanceof Set ? to : new Set([to]);
@@ -53,9 +65,8 @@ export class Query {
     }
 
     /**
-     * Sets the departure time for the query as minutes since midnight.
-     * 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.
+     * Sets the departure time in minutes from midnight.
+     * The router favours trips departing shortly after this time.
      */
     departureTime(departureTime: Time): this {
       this.departureTimeValue = departureTime;
@@ -71,8 +82,8 @@ export class Query {
     }
 
     /**
-     * Sets the minimum transfer time (in minutes)
-     * to use when no transfer time is provided in the data.
+     * Sets the fallback minimum transfer time (in minutes) used when the
+     * timetable data does not specify one for a particular transfer.
      */
     minTransferTime(minTransferTime: Duration): this {
       this.optionsValue.minTransferTime = minTransferTime;
@@ -80,15 +91,107 @@ export class Query {
     }
 
     /**
-     * Sets the transport modes to consider.
+     * Restricts routing to the given transport modes.
      */
     transportModes(transportModes: Set<RouteType>): this {
       this.optionsValue.transportModes = transportModes;
       return this;
     }
 
+    /**
+     * Sets the maximum time (in minutes) the traveler is willing to wait at
+     * the first boarding stop before the first transit vehicle departs.
+     *
+     * When set, any trip that would require waiting longer than this duration
+     * after arriving at the stop is not considered for the first boarding leg.
+     */
+    maxInitialWaitingTime(maxInitialWaitingTime: Duration): this {
+      this.optionsValue.maxInitialWaitingTime = maxInitialWaitingTime;
+      return this;
+    }
+
     build(): Query {
       return new Query(this);
     }
   };
 }
+
+/**
+ * Options specific to a {@link RangeQuery}.
+ */
+export type RangeQueryOptions = {
+  /**
+   * When `true`, a full RAPTOR pass is run at `lastDepartureTime + 1` before
+   * the main departure-time loop (the *boundary run*).
+   *
+   * The boundary run seeds the shared Pareto labels with the best arrival
+   * achievable by departing just after the window closes.  Any in-window
+   * journey whose arrival is no better than what that post-window departure
+   * achieves is therefore suppressed — you only see journeys that are still
+   * worth taking given that a later departure exists.
+   *
+   * **Timetable use-case** (`boundaryRun: true`): the window is a *display
+   * filter*.  A journey at 10:55 that arrives at 12:30 is hidden when an
+   * 11:05 departure arrives at 12:00 — the router pre-empts the dominated
+   * option on the caller's behalf.
+   *
+   * **Isochrone / accessibility use-case** (`boundaryRun: false`, the
+   * default): the window is a hard constraint.  Every Pareto-optimal journey
+   * whose departure falls strictly within `[departureTime, lastDepartureTime]`
+   * is returned, regardless of what might be available just outside the
+   * window.
+   *
+   * @default false
+   */
+  optimizeBeyondLatestDeparture: boolean;
+};
+
+/**
+ * A routing query for Range RAPTOR.
+ *
+ * Extends {@link Query} with a required `lastDepartureTime` that defines the
+ * upper bound of the departure-time window.  `router.rangeRoute()` returns
+ * all Pareto-optimal journeys departing in
+ * `[departureTime, lastDepartureTime]`.
+ *
+ */
+export class RangeQuery extends Query {
+  /** Upper bound of the departure-time window (minutes from midnight). */
+  readonly lastDepartureTime: Time;
+  /** Options specific to Range RAPTOR behavior. */
+  readonly rangeOptions: RangeQueryOptions;
+
+  constructor(builder: typeof RangeQuery.Builder.prototype) {
+    super(builder);
+    this.lastDepartureTime = builder.lastDepartureTimeValue;
+    this.rangeOptions = builder.rangeOptionsValue;
+  }
+
+  static Builder = class extends Query.Builder {
+    lastDepartureTimeValue!: Time;
+    rangeOptionsValue: RangeQueryOptions = {
+      optimizeBeyondLatestDeparture: true,
+    };
+
+    /**
+     * Sets the upper bound of the departure-time window.
+     */
+    lastDepartureTime(time: Time): this {
+      this.lastDepartureTimeValue = time;
+      return this;
+    }
+
+    /**
+     * Overrides individual Range RAPTOR options.
+     * Unspecified fields keep their defaults.
+     */
+    rangeOptions(options: Partial<RangeQueryOptions>): this {
+      this.rangeOptionsValue = { ...this.rangeOptionsValue, ...options };
+      return this;
+    }
+
+    build(): RangeQuery {
+      return new RangeQuery(this);
+    }
+  };
+}