minotor 11.1.2 → 11.2.0

package/src/routing/state.ts

@@ -3,6 +3,8 @@ import { StopId } from '../stops/stops.js';
 import { StopRouteIndex } from '../timetable/route.js';
 import { Duration, Time } from '../timetable/time.js';
 import { TransferType, TripStop } from '../timetable/timetable.js';
+import { AccessPoint } from './access.js';
+import type { IRaptorState } from './raptor.js';
 
 /**
  * Sentinel value used in the internal arrival-time array to mark stops not yet reached.
@@ -10,14 +12,20 @@ import { TransferType, TripStop } from '../timetable/timetable.js';
  */
 export const UNREACHED_TIME: Time = 0xffff;
 
-/** An origin stop reached at the query departure time, before any transit leg. */
-export type OriginNode = { arrival: Time };
+export type OriginNode = { stopId: StopId; arrival: Time };
+
+export type AccessEdge = {
+  arrival: Time;
+  from: StopId;
+  to: StopId;
+  duration: Duration;
+};
 
 /** A boarded transit trip that carries the passenger from one stop to another. */
 export type VehicleEdge = TripStop & {
   arrival: Time;
   hopOffStopIndex: StopRouteIndex;
-  /** Set when this edge continues directly from another trip (in-seat transfer). */
+  /** modeling in-seat transfer */
   continuationOf?: VehicleEdge;
 };
 
@@ -30,7 +38,7 @@ export type TransferEdge = {
   minTransferTime?: Duration;
 };
 
-export type RoutingEdge = OriginNode | VehicleEdge | TransferEdge;
+export type RoutingEdge = OriginNode | AccessEdge | VehicleEdge | TransferEdge;
 
 /** The earliest arrival at a stop together with how many legs were needed to reach it. */
 export type Arrival = {
@@ -41,9 +49,9 @@ export type Arrival = {
 /**
  * Encapsulates all mutable state for a single RAPTOR routing query.
  */
-export class RoutingState {
+export class RoutingState implements IRaptorState {
   /** Origin stop IDs for this query. */
-  readonly origins: StopId[];
+  origins: StopId[];
 
   /** Destination stop IDs for this query. */
   readonly destinations: StopId[];
@@ -70,38 +78,78 @@ export class RoutingState {
   private earliestArrivalLegs: Uint8Array;
 
   /**
-   * Initializes the routing state for a fresh query.
-   *
-   * All stops start as unreached. Each origin is immediately recorded at the
-   * departure time with leg number 0, and a corresponding OriginNode is placed
-   * in round 0 of the graph.
-   *
-   * @param origins      Stop IDs to depart from (may be several equivalent stops).
-   * @param destinations Stop IDs that count as the target of the query.
-   * @param departureTime Earliest departure time in minutes from midnight.
-   * @param nbStops      Total number of stops in the timetable (sets array sizes).
+   * Fast O(1) membership test for destination stops.
+   * Built once at construction time from the `destinations` array.
    */
+  private readonly destinationSet: Set<StopId>;
+
+  /**
+   * Cached best arrival time at any destination stop, kept up-to-date by
+   * {@link updateArrival} so that destination pruning is always O(1).
+   */
+  private _destinationBest: Time = UNREACHED_TIME;
+
+  /**
+   * Every stop that has received an arrival improvement during the current run,
+   * in the order the improvements occurred.  Used by {@link resetFor} to clear
+   * only the touched entries instead of scanning the entire array.
+   */
+  private readonly reachedStops: StopId[] = [];
+
   constructor(
-    origins: StopId[],
-    destinations: StopId[],
     departureTime: Time,
+    destinations: StopId[],
+    accessPaths: AccessPoint[],
     nbStops: number,
+    maxRounds: number = 0,
   ) {
-    this.origins = origins;
     this.destinations = destinations;
-
-    const earliestArrivalTimes = new Uint16Array(nbStops).fill(UNREACHED_TIME);
-    const earliestArrivalLegs = new Uint8Array(nbStops); // zero-initialized = leg 0
-    const graph0 = new Array<RoutingEdge | undefined>(nbStops);
-
-    for (const stop of origins) {
-      earliestArrivalTimes[stop] = departureTime;
-      graph0[stop] = { arrival: departureTime };
+    this.destinationSet = new Set(destinations);
+    this.earliestArrivalTimes = new Uint16Array(nbStops).fill(UNREACHED_TIME);
+    this.earliestArrivalLegs = new Uint8Array(nbStops);
+    this.origins = []; // overwritten by seedAccessPaths below
+    this.graph = [new Array<RoutingEdge | undefined>(nbStops)];
+    for (let r = 1; r <= maxRounds; r++) {
+      this.graph.push(new Array<RoutingEdge | undefined>(nbStops));
     }
+    this.seedAccessPaths(departureTime, accessPaths);
+  }
 
-    this.earliestArrivalTimes = earliestArrivalTimes;
-    this.earliestArrivalLegs = earliestArrivalLegs;
-    this.graph = [graph0];
+  /**
+   * Seeds round-0 arrivals and {@link origins} from a set of access paths.
+   * Called by the constructor and by {@link resetFor}.
+   * Assumes {@link earliestArrivalTimes} and {@link graph}[0] are already
+   * allocated and in their "cleared" state (all entries at UNREACHED_TIME /
+   * undefined) before this method runs.
+   */
+  private seedAccessPaths(depTime: Time, accessPaths: AccessPoint[]): void {
+    const seededOrigins = new Set<StopId>();
+    for (const access of accessPaths) {
+      const arrival = depTime + access.duration;
+      const edge: OriginNode | AccessEdge =
+        access.duration === 0
+          ? { stopId: access.fromStopId, arrival: depTime }
+          : {
+              arrival,
+              from: access.fromStopId,
+              to: access.toStopId,
+              duration: access.duration,
+            };
+      const stop = access.toStopId;
+      if (arrival < this.earliestArrivalTimes[stop]!) {
+        this.earliestArrivalTimes[stop] = arrival;
+        this.graph[0]![stop] = edge;
+      }
+      seededOrigins.add(stop);
+    }
+    for (const stop of seededOrigins) {
+      this.reachedStops.push(stop);
+    }
+    this.origins = Array.from(seededOrigins);
+    for (let i = 0; i < this.destinations.length; i++) {
+      const t = this.earliestArrivalTimes[this.destinations[i]!]!;
+      if (t < this._destinationBest) this._destinationBest = t;
+    }
   }
 
   /** Total number of stops in the timetable */
@@ -118,16 +166,101 @@ export class RoutingState {
   }
 
   /**
-   * Records a new earliest arrival at a stop.
+   * Earliest arrival at any destination stop; {@link UNREACHED_TIME} if none
+   * has been reached yet. Updated automatically by {@link updateArrival}. O(1).
+   */
+  get destinationBest(): Time {
+    return this._destinationBest;
+  }
+
+  /**
+   * In standard RAPTOR the improvement bound is simply the per-run earliest
+   * arrival; the `round` argument is ignored.
+   */
+  improvementBound(_round: number, stop: StopId): Time {
+    return this.arrivalTime(stop);
+  }
 
+  /** No-op in standard RAPTOR — there are no shared cross-run labels to propagate. */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  initRound(_round: number): void {}
+
+  /**
+   * Records a new earliest arrival at a stop.
    *
    * @param stop The stop that was reached.
    * @param time The arrival time in minutes from midnight.
    * @param leg  The round number (number of transit legs taken so far).
    */
   updateArrival(stop: StopId, time: Time, leg: number): void {
+    this.reachedStops.push(stop);
     this.earliestArrivalTimes[stop] = time;
     this.earliestArrivalLegs[stop] = leg;
+    if (this.destinationSet.has(stop) && time < this._destinationBest) {
+      this._destinationBest = time;
+    }
+  }
+
+  /**
+   * Resets this state for a new departure-time iteration **without
+   * reallocating** the underlying arrays.
+   *
+   * Only the stops recorded in {@link reachedStops} are touched — all other
+   * entries are already at their initial bound values.
+   *
+   * After this call the state is equivalent to a freshly constructed
+   * {@link RoutingState} for the given `depTime` and `accessPaths`.
+   *
+   * @param depTime     New origin departure time.
+   * @param accessPaths Access legs for this departure-time slot.
+   */
+  resetFor(depTime: Time, accessPaths: AccessPoint[]): void {
+    for (const stop of this.reachedStops) {
+      this.earliestArrivalTimes[stop] = UNREACHED_TIME;
+      this.earliestArrivalLegs[stop] = 0;
+      for (let r = 0; r < this.graph.length; r++) {
+        this.graph[r]![stop] = undefined;
+      }
+    }
+    this.reachedStops.length = 0;
+    this._destinationBest = UNREACHED_TIME;
+    this.seedAccessPaths(depTime, accessPaths);
+  }
+
+  /**
+   * Iterates over every stop that has been reached, yielding its stop ID,
+   * earliest arrival time, and the number of legs taken to reach it.
+   *
+   * Unreached stops (those still at UNREACHED_TIME) are skipped entirely.
+   *
+   * @example
+   * ```ts
+   * for (const { stop, arrival, legNumber } of routingState.arrivals()) {
+   *   console.log(`Stop ${stop}: arrived at ${arrival} after ${legNumber} leg(s)`);
+   * }
+   * ```
+   */
+  *arrivals(): Generator<{ stop: StopId; arrival: Time; legNumber: number }> {
+    for (let stop = 0; stop < this.earliestArrivalTimes.length; stop++) {
+      const time = this.earliestArrivalTimes[stop]!;
+      if (time < UNREACHED_TIME) {
+        yield {
+          stop,
+          arrival: time,
+          legNumber: this.earliestArrivalLegs[stop]!,
+        };
+      }
+    }
+  }
+
+  /**
+   * Finds the earliest arrival time at any stop from a given set of destinations.
+   *
+   * @param routingState The routing state containing arrival times and destinations.
+   * @returns The earliest arrival time among the provided destinations.
+   */
+  earliestArrivalAtAnyDestination(): Time {
+    return this._destinationBest;
   }
 
   /**
@@ -140,6 +273,14 @@ export class RoutingState {
     return { arrival: time, legNumber: this.earliestArrivalLegs[stop]! };
   }
 
+  /**
+   * Returns `true` if `stop` is one of the query's destination stops.
+   * O(1) — backed by a `Set` built at construction time.
+   */
+  isDestination(stop: StopId): boolean {
+    return this.destinationSet.has(stop);
+  }
+
   /**
    * Creates a {@link RoutingState} from fully-specified raw data.
    *
@@ -170,7 +311,16 @@ export class RoutingState {
     arrivals?: [stop: StopId, time: Time, leg: number][];
     graph?: [stop: StopId, edge: RoutingEdge][][];
   }): RoutingState {
-    const state = new RoutingState(origins, destinations, 0, nbStops);
+    const state = new RoutingState(
+      0,
+      destinations,
+      origins.map((stop) => ({
+        fromStopId: stop,
+        toStopId: stop,
+        duration: 0,
+      })),
+      nbStops,
+    );
 
     // Replace the arrival arrays with freshly built ones so the constructor's
     // origin-seeding doesn't bleed into the test state.
@@ -183,6 +333,15 @@ export class RoutingState {
     state.earliestArrivalTimes = earliestArrivalTimes;
     state.earliestArrivalLegs = earliestArrivalLegs;
 
+    // Recompute _destinationBest from the test data since we bypassed updateArrival.
+    // fromTestData is a static method of RoutingState, so private access is allowed.
+    state._destinationBest = UNREACHED_TIME;
+    for (const dest of destinations) {
+      const t = earliestArrivalTimes[dest];
+      if (t !== undefined && t < state._destinationBest)
+        state._destinationBest = t;
+    }
+
     // Convert the sparse per-round representation to dense arrays and replace
     // the graph in-place.
     const denseRounds = graph.map((round) => {

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

@@ -9,6 +9,7 @@ import {
   StopAdjacency,
   Timetable,
   TripStop,
+  TripTransfers,
 } from '../timetable.js';
 import { encode } from '../tripStopId.js';
 
@@ -655,5 +656,377 @@ describe('Timetable', () => {
         );
       });
     });
+
+    describe('findFirstBoardableTrip', () => {
+      const BOARDING_STOP_INDEX = 0;
+      const FFBT_ROUTE_ID = 2;
+
+      const ffbtRoute = Route.of({
+        id: FFBT_ROUTE_ID,
+        serviceRouteId: 2,
+        trips: [
+          {
+            stops: [
+              {
+                id: 0,
+                arrivalTime: timeFromHMS(8, 0, 0),
+                departureTime: timeFromHMS(8, 0, 0),
+              },
+              {
+                id: 1,
+                arrivalTime: timeFromHMS(8, 30, 0),
+                departureTime: timeFromHMS(8, 30, 0),
+              },
+            ],
+          },
+          {
+            stops: [
+              {
+                id: 0,
+                arrivalTime: timeFromHMS(9, 0, 0),
+                departureTime: timeFromHMS(9, 0, 0),
+                pickUpType: NOT_AVAILABLE,
+              },
+              {
+                id: 1,
+                arrivalTime: timeFromHMS(9, 30, 0),
+                departureTime: timeFromHMS(9, 30, 0),
+              },
+            ],
+          },
+          {
+            stops: [
+              {
+                id: 0,
+                arrivalTime: timeFromHMS(10, 0, 0),
+                departureTime: timeFromHMS(10, 0, 0),
+              },
+              {
+                id: 1,
+                arrivalTime: timeFromHMS(10, 30, 0),
+                departureTime: timeFromHMS(10, 30, 0),
+              },
+            ],
+          },
+          {
+            stops: [
+              {
+                id: 0,
+                arrivalTime: timeFromHMS(11, 0, 0),
+                departureTime: timeFromHMS(11, 0, 0),
+              },
+              {
+                id: 1,
+                arrivalTime: timeFromHMS(11, 30, 0),
+                departureTime: timeFromHMS(11, 30, 0),
+              },
+            ],
+          },
+        ],
+      });
+
+      const ffbtStopsAdjacency: StopAdjacency[] = [
+        { routes: [FFBT_ROUTE_ID] },
+        { routes: [FFBT_ROUTE_ID] },
+      ];
+
+      const ffbtServiceRoutes = [
+        { type: 'BUS' as const, name: 'Route 2', routes: [FFBT_ROUTE_ID] },
+      ];
+
+      const ffbtTimetable = new Timetable(
+        ffbtStopsAdjacency,
+        [ffbtRoute],
+        ffbtServiceRoutes,
+      );
+
+      describe('without fromTripStop', () => {
+        it('returns the first trip with an available pickup', () => {
+          const result = ffbtTimetable.findFirstBoardableTrip(
+            BOARDING_STOP_INDEX,
+            ffbtRoute,
+            0,
+          );
+          assert.strictEqual(result, 0);
+        });
+
+        it('skips trips with NOT_AVAILABLE pickup', () => {
+          // Start scanning from trip 1 (NOT_AVAILABLE) → must return trip 2.
+          const result = ffbtTimetable.findFirstBoardableTrip(
+            BOARDING_STOP_INDEX,
+            ffbtRoute,
+            1,
+          );
+          assert.strictEqual(result, 2);
+        });
+
+        it('starts scanning at earliestTrip', () => {
+          // Even though trip 0 is valid, scanning starts at trip 2.
+          const result = ffbtTimetable.findFirstBoardableTrip(
+            BOARDING_STOP_INDEX,
+            ffbtRoute,
+            2,
+          );
+          assert.strictEqual(result, 2);
+        });
+
+        it('respects the beforeTrip exclusive upper bound', () => {
+          // beforeTrip=1 means only trip 0 is in scope.
+          const result = ffbtTimetable.findFirstBoardableTrip(
+            BOARDING_STOP_INDEX,
+            ffbtRoute,
+            0,
+            0,
+            1,
+          );
+          assert.strictEqual(result, 0);
+        });
+
+        it('returns undefined when the only trip in range has a NOT_AVAILABLE pickup', () => {
+          // [1, 2) contains only trip 1, which is NOT_AVAILABLE.
+          const result = ffbtTimetable.findFirstBoardableTrip(
+            BOARDING_STOP_INDEX,
+            ffbtRoute,
+            1,
+            0,
+            2,
+          );
+          assert.strictEqual(result, undefined);
+        });
+
+        it('returns undefined when earliestTrip is past all trips', () => {
+          const result = ffbtTimetable.findFirstBoardableTrip(
+            BOARDING_STOP_INDEX,
+            ffbtRoute,
+            99,
+          );
+          assert.strictEqual(result, undefined);
+        });
+
+        it('returns undefined when beforeTrip equals earliestTrip (empty range)', () => {
+          const result = ffbtTimetable.findFirstBoardableTrip(
+            BOARDING_STOP_INDEX,
+            ffbtRoute,
+            2,
+            0,
+            2,
+          );
+          assert.strictEqual(result, undefined);
+        });
+      });
+
+      describe('with fromTripStop', () => {
+        const fromTripStop: TripStop = {
+          routeId: 99,
+          stopIndex: 0,
+          tripIndex: 0,
+        };
+
+        it('returns the first trip whose departure satisfies after + transferTime', () => {
+          // after=09:30, transferTime=30 → requiredTime=10:00.
+          // trip 0 (08:00) < 10:00 → skip.
+          // trip 1 (09:00) NOT_AVAILABLE → skip.
+          // trip 2 (10:00) ≥ 10:00 → returned.
+          const result = ffbtTimetable.findFirstBoardableTrip(
+            BOARDING_STOP_INDEX,
+            ffbtRoute,
+            0,
+            timeFromHMS(9, 30, 0),
+            undefined,
+            fromTripStop,
+            30,
+          );
+          assert.strictEqual(result, 2);
+        });
+
+        it('treats departure exactly equal to after as satisfying (transferTime=0)', () => {
+          // after=10:00, transferTime=0 → requiredTime=10:00.
+          // trip 0 (08:00) < 10:00 → skip.
+          // trip 1 (09:00) NOT_AVAILABLE → skip.
+          // trip 2 (10:00) ≥ 10:00 → returned.
+          const result = ffbtTimetable.findFirstBoardableTrip(
+            BOARDING_STOP_INDEX,
+            ffbtRoute,
+            0,
+            timeFromHMS(10, 0, 0),
+            undefined,
+            fromTripStop,
+            0,
+          );
+          assert.strictEqual(result, 2);
+        });
+
+        it('returns undefined when all trips depart before after + transferTime', () => {
+          // after=11:00, transferTime=30 → requiredTime=11:30.
+          // trip 3 (11:00) < 11:30 → skip. No further trips.
+          const result = ffbtTimetable.findFirstBoardableTrip(
+            BOARDING_STOP_INDEX,
+            ffbtRoute,
+            0,
+            timeFromHMS(11, 0, 0),
+            undefined,
+            fromTripStop,
+            30,
+          );
+          assert.strictEqual(result, undefined);
+        });
+
+        it('returns undefined when beforeTrip excludes all trips that would satisfy the requirement', () => {
+          // Only trips 0 and 1 are in scope (beforeTrip=2).
+          // after=09:00, transferTime=30 → requiredTime=09:30.
+          // trip 0 (08:00) < 09:30 → skip.
+          // trip 1 (09:00) NOT_AVAILABLE → skip.
+          // beforeTrip reached → undefined.
+          const result = ffbtTimetable.findFirstBoardableTrip(
+            BOARDING_STOP_INDEX,
+            ffbtRoute,
+            0,
+            timeFromHMS(9, 0, 0),
+            2,
+            fromTripStop,
+            30,
+          );
+          assert.strictEqual(result, undefined);
+        });
+      });
+
+      describe('guaranteed connection', () => {
+        it('bypasses the after + transferTime departure check', () => {
+          const fromTripStop: TripStop = {
+            routeId: 99,
+            stopIndex: 0,
+            tripIndex: 0,
+          };
+          const guaranteedTransfers: TripTransfers = new Map([
+            [
+              encode(
+                fromTripStop.stopIndex,
+                fromTripStop.routeId,
+                fromTripStop.tripIndex,
+              ),
+              [
+                {
+                  stopIndex: BOARDING_STOP_INDEX,
+                  routeId: FFBT_ROUTE_ID,
+                  tripIndex: 0,
+                },
+              ],
+            ],
+          ]);
+          const timetableWithGuarantee = new Timetable(
+            ffbtStopsAdjacency,
+            [ffbtRoute],
+            ffbtServiceRoutes,
+            new Map(),
+            guaranteedTransfers,
+          );
+
+          // after=07:00, transferTime=120 → requiredTime=09:00; trip 0 (08:00) is below
+          // that threshold but the guarantee returns it immediately.
+          const result = timetableWithGuarantee.findFirstBoardableTrip(
+            BOARDING_STOP_INDEX,
+            ffbtRoute,
+            0,
+            timeFromHMS(7, 0, 0),
+            undefined,
+            fromTripStop,
+            120,
+          );
+          assert.strictEqual(result, 0);
+        });
+
+        it('does not bypass a NOT_AVAILABLE pickup', () => {
+          const fromTripStop: TripStop = {
+            routeId: 99,
+            stopIndex: 0,
+            tripIndex: 0,
+          };
+          const guaranteedTransfers: TripTransfers = new Map([
+            [
+              encode(
+                fromTripStop.stopIndex,
+                fromTripStop.routeId,
+                fromTripStop.tripIndex,
+              ),
+              [
+                {
+                  stopIndex: BOARDING_STOP_INDEX,
+                  routeId: FFBT_ROUTE_ID,
+                  tripIndex: 1,
+                },
+              ],
+            ],
+          ]);
+          const timetableWithGuarantee = new Timetable(
+            ffbtStopsAdjacency,
+            [ffbtRoute],
+            ffbtServiceRoutes,
+            new Map(),
+            guaranteedTransfers,
+          );
+
+          // after=08:30, transferTime=60 → requiredTime=09:30.
+          // trip 0 (08:00): not guaranteed for trip 0, 08:00 < 09:30 → skip.
+          // trip 1 (09:00): NOT_AVAILABLE → skip (guarantee is irrelevant).
+          // trip 2 (10:00): no guarantee, but 10:00 ≥ 09:30 → first boardable.
+          const result = timetableWithGuarantee.findFirstBoardableTrip(
+            BOARDING_STOP_INDEX,
+            ffbtRoute,
+            0,
+            timeFromHMS(8, 30, 0),
+            undefined,
+            fromTripStop,
+            60,
+          );
+          assert.strictEqual(result, 2);
+        });
+
+        it('applies only to its declared target trip index', () => {
+          const fromTripStop: TripStop = {
+            routeId: 99,
+            stopIndex: 0,
+            tripIndex: 0,
+          };
+          const guaranteedTransfers: TripTransfers = new Map([
+            [
+              encode(
+                fromTripStop.stopIndex,
+                fromTripStop.routeId,
+                fromTripStop.tripIndex,
+              ),
+              [
+                {
+                  stopIndex: BOARDING_STOP_INDEX,
+                  routeId: FFBT_ROUTE_ID,
+                  tripIndex: 2,
+                },
+              ],
+            ],
+          ]);
+          const timetableWithGuarantee = new Timetable(
+            ffbtStopsAdjacency,
+            [ffbtRoute],
+            ffbtServiceRoutes,
+            new Map(),
+            guaranteedTransfers,
+          );
+
+          // after=09:30, transferTime=120 → requiredTime=11:30.
+          // trip 0 (08:00): not guaranteed, 08:00 < 11:30 → skip.
+          // trip 1 (09:00): NOT_AVAILABLE → skip.
+          // trip 2 (10:00): guaranteed → returned immediately despite 10:00 < 11:30.
+          const result = timetableWithGuarantee.findFirstBoardableTrip(
+            BOARDING_STOP_INDEX,
+            ffbtRoute,
+            0,
+            timeFromHMS(9, 30, 0),
+            undefined,
+            fromTripStop,
+            120,
+          );
+          assert.strictEqual(result, 2);
+        });
+      });
+    });
   });
 });