minotor 11.1.2 → 11.2.0

package/src/cli/repl.ts

@@ -2,7 +2,7 @@ import repl from 'node:repl';
 
 import fs from 'fs';
 
-import { Query, Router, StopsIndex, Timetable } from '../router.js';
+import { Query, RangeQuery, Router, StopsIndex, Timetable } from '../router.js';
 import type { Stop } from '../stops/stops.js';
 import {
   MUST_COORDINATE_WITH_DRIVER,
@@ -50,31 +50,52 @@ export const startRepl = (stopsPath: string, timetablePath: string) => {
     },
   });
   replServer.defineCommand('route', {
-    help: 'Find a route using .route from <stationIdOrName> to <stationIdOrName> at <HH:mm> [with <N> transfers]',
+    help: 'Find a route using .route from <stop> to <stop> at <HH:mm> [before <HH:mm>] [with <N> transfers]',
     action(routeQuery: string) {
       this.clearBufferedCommand();
       const parts = routeQuery.split(' ').filter(Boolean);
-      const withTransfersIndex = parts.indexOf('with');
-      const maxTransfers =
-        withTransfersIndex !== -1 && parts[withTransfersIndex + 1] !== undefined
-          ? parseInt(parts[withTransfersIndex + 1] as string)
-          : 4;
-      const atTime = parts
-        .slice(
-          withTransfersIndex === -1
-            ? parts.indexOf('at') + 1
-            : parts.indexOf('at') + 1,
-          withTransfersIndex === -1 ? parts.length : withTransfersIndex,
-        )
-        .join(' ');
+
       const fromIndex = parts.indexOf('from');
       const toIndex = parts.indexOf('to');
+      const atIndex = parts.indexOf('at');
+      const beforeIndex = parts.indexOf('before');
+      const withIndex = parts.indexOf('with');
+
+      if (fromIndex === -1 || toIndex === -1 || atIndex === -1) {
+        console.log(
+          'Usage: .route from <stop> to <stop> at <HH:mm> [before <HH:mm>] [with <N> transfers]',
+        );
+        this.displayPrompt();
+        return;
+      }
+
       const fromId = parts.slice(fromIndex + 1, toIndex).join(' ');
-      const toId = parts.slice(toIndex + 1, parts.indexOf('at')).join(' ');
+      const toId = parts.slice(toIndex + 1, atIndex).join(' ');
+
+      // atTime ends at 'before', 'with', or the end of the input.
+      const atTimeEnd =
+        beforeIndex !== -1
+          ? beforeIndex
+          : withIndex !== -1
+            ? withIndex
+            : parts.length;
+      const atTime = parts.slice(atIndex + 1, atTimeEnd).join(' ');
+
+      // beforeTime is only present when the 'before' keyword appears.
+      const beforeTimeEnd = withIndex !== -1 ? withIndex : parts.length;
+      const beforeTime =
+        beforeIndex !== -1
+          ? parts.slice(beforeIndex + 1, beforeTimeEnd).join(' ')
+          : undefined;
+
+      const maxTransfers =
+        withIndex !== -1 && parts[withIndex + 1] !== undefined
+          ? parseInt(parts[withIndex + 1] as string)
+          : 4;
 
       if (!fromId || !toId || !atTime) {
         console.log(
-          'Usage: .route from <stationIdOrName> to <stationIdOrName> at <HH:mm> [with <N> transfers]',
+          'Usage: .route from <stop> to <stop> at <HH:mm> [before <HH:mm>] [with <N> transfers]',
         );
         this.displayPrompt();
         return;
@@ -105,34 +126,68 @@ export const startRepl = (stopsPath: string, timetablePath: string) => {
         return;
       }
 
-      const departureTime = timeFromString(atTime);
-
       try {
-        const query = new Query.Builder()
-          .from(fromStop.id)
-          .to(toStop.id)
-          .departureTime(departureTime)
-          .maxTransfers(maxTransfers)
-          .build();
-
+        const departureTime = timeFromString(atTime);
         const router = new Router(timetable, stopsIndex);
-
-        const result = router.route(query);
-        const arrivalTime = result.arrivalAt(toStop.id);
-        if (arrivalTime === undefined) {
-          console.log(`Destination not reachable`);
+        if (beforeTime !== undefined) {
+          const lastDepartureTime = timeFromString(beforeTime);
+          const query = new RangeQuery.Builder()
+            .from(fromStop.id)
+            .to(toStop.id)
+            .departureTime(departureTime)
+            .lastDepartureTime(lastDepartureTime)
+            .maxTransfers(maxTransfers)
+            .build();
+
+          const result = router.rangeRoute(query);
+
+          if (result.size === 0) {
+            console.log(
+              `No journeys found from ${fromStop.name} to ${toStop.name} ` +
+                `between ${atTime} and ${beforeTime}.`,
+            );
+          } else {
+            console.log(
+              `Found ${result.size} Pareto-optimal journey${result.size === 1 ? '' : 's'} ` +
+                `from ${fromStop.name} to ${toStop.name} ` +
+                `(window ${atTime}–${beforeTime}):`,
+            );
+            const routes = result.getRoutes();
+            routes.forEach((route, index) => {
+              const journeyNumber = index + 1;
+              console.log(`\nJourney ${journeyNumber}:`);
+              console.log(route.toString());
+            });
+          }
         } else {
-          console.log(
-            `Arriving to ${toStop.name} at ${timeToString(arrivalTime.arrival)} with ${arrivalTime.legNumber - 1} transfers from ${fromStop.name}.`,
-          );
-        }
-        const bestRoute = result.bestRoute(toStop.id);
+          const query = new Query.Builder()
+            .from(fromStop.id)
+            .to(toStop.id)
+            .departureTime(departureTime)
+            .maxTransfers(maxTransfers)
+            .build();
+
+          const result = router.route(query);
+          const arrivalTime = result.arrivalAt(toStop.id);
+
+          if (arrivalTime === undefined) {
+            console.log(`Destination not reachable`);
+          } else {
+            const transfers = Math.max(0, arrivalTime.legNumber - 1);
+            console.log(
+              `Arriving to ${toStop.name} at ${timeToString(arrivalTime.arrival)} ` +
+                `with ${transfers} transfer${transfers === 1 ? '' : 's'} ` +
+                `from ${fromStop.name}.`,
+            );
+          }
 
-        if (bestRoute) {
-          console.log(`Found route from ${fromStop.name} to ${toStop.name}:`);
-          console.log(bestRoute.toString());
-        } else {
-          console.log('No route found');
+          const bestRoute = result.bestRoute(toStop.id);
+          if (bestRoute) {
+            console.log(`Found route from ${fromStop.name} to ${toStop.name}:`);
+            console.log(bestRoute.toString());
+          } else {
+            console.log('No route found');
+          }
         }
       } catch (error) {
         console.log('Error querying route:', error);

package/src/router.ts

@@ -1,10 +1,14 @@
 import { Plotter } from './routing/plotter.js';
-import { Query } from './routing/query.js';
+import { Query, RangeQuery } from './routing/query.js';
 import { Result } from './routing/result.js';
 import type { Leg, Transfer, VehicleLeg } from './routing/route.js';
 import { Route } from './routing/route.js';
-import type { Arrival } from './routing/router.js';
-import { Router } from './routing/router.js';
+import type {
+  Arrival,
+  ArrivalWithDuration,
+  ParetoRun,
+} from './routing/router.js';
+import { RangeResult, Router } from './routing/router.js';
 import type { LocationType, SourceStopId, StopId } from './stops/stops.js';
 import type { Stop } from './stops/stops.js';
 import { StopsIndex } from './stops/stopsIndex.js';
@@ -20,6 +24,8 @@ export {
   Duration,
   Plotter,
   Query,
+  RangeQuery,
+  RangeResult,
   Result,
   Route,
   Router,
@@ -30,8 +36,10 @@ export {
 
 export type {
   Arrival,
+  ArrivalWithDuration,
   Leg,
   LocationType,
+  ParetoRun,
   RouteType,
   ServiceRouteInfo,
   SourceStopId,

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

@@ -0,0 +1,294 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+
+import { Stop } from '../../stops/stops.js';
+import { StopsIndex } from '../../stops/stopsIndex.js';
+import { Route } from '../../timetable/route.js';
+import { timeFromHM } from '../../timetable/time.js';
+import {
+  ServiceRoute,
+  StopAdjacency,
+  Timetable,
+} from '../../timetable/timetable.js';
+import { AccessFinder, AccessPoint } from '../access.js';
+
+// Timetable: stop 0 is an isolated origin; stop 1 is a boarding stop on route 0;
+// stop 2 is a second stop served by route 0.
+// Stop 0 has a REQUIRES_MINIMAL_TIME transfer to stop 1 (5 min)
+//         and a GUARANTEED transfer to stop 2 (must be ignored).
+const stopsAdjacency: StopAdjacency[] = [
+  {
+    transfers: [
+      { destination: 1, type: 'REQUIRES_MINIMAL_TIME', minTransferTime: 5 },
+      { destination: 2, type: 'GUARANTEED' },
+    ],
+    routes: [],
+  },
+  { routes: [0] },
+  { routes: [0] },
+];
+
+const routesAdjacency = [
+  Route.of({
+    id: 0,
+    serviceRouteId: 0,
+    trips: [
+      {
+        stops: [
+          {
+            id: 1,
+            arrivalTime: timeFromHM(8, 10),
+            departureTime: timeFromHM(8, 10),
+          },
+          {
+            id: 2,
+            arrivalTime: timeFromHM(8, 20),
+            departureTime: timeFromHM(8, 20),
+          },
+        ],
+      },
+      {
+        stops: [
+          {
+            id: 1,
+            arrivalTime: timeFromHM(8, 40),
+            departureTime: timeFromHM(8, 40),
+          },
+          {
+            id: 2,
+            arrivalTime: timeFromHM(8, 50),
+            departureTime: timeFromHM(8, 50),
+          },
+        ],
+      },
+    ],
+  }),
+];
+
+const serviceRoutes: ServiceRoute[] = [
+  { type: 'BUS', name: 'Line 1', routes: [0] },
+];
+
+const stops: Stop[] = [
+  {
+    id: 0,
+    sourceStopId: 'A',
+    name: 'Stop A',
+    lat: 0,
+    lon: 0,
+    children: [],
+    locationType: 'SIMPLE_STOP_OR_PLATFORM',
+  },
+  {
+    id: 1,
+    sourceStopId: 'B',
+    name: 'Stop B',
+    lat: 0,
+    lon: 0,
+    children: [],
+    locationType: 'SIMPLE_STOP_OR_PLATFORM',
+  },
+  {
+    id: 2,
+    sourceStopId: 'C',
+    name: 'Stop C',
+    lat: 0,
+    lon: 0,
+    children: [],
+    locationType: 'SIMPLE_STOP_OR_PLATFORM',
+  },
+];
+
+const timetable = new Timetable(stopsAdjacency, routesAdjacency, serviceRoutes);
+const stopsIndex = new StopsIndex(stops);
+const finder = new AccessFinder(timetable, stopsIndex);
+
+describe('AccessFinder', () => {
+  describe('collectAccessPaths', () => {
+    it('returns the origin itself as a zero-cost access path', () => {
+      const paths = finder.collectAccessPaths(0, 2);
+      const selfPath = paths.find((p) => p.toStopId === 0);
+      assert(selfPath);
+      assert.strictEqual(selfPath.duration, 0);
+    });
+
+    it('includes REQUIRES_MINIMAL_TIME transfers with the specified duration', () => {
+      const paths = finder.collectAccessPaths(0, 2);
+      const walkPath = paths.find((p) => p.toStopId === 1);
+      assert(walkPath);
+      assert.strictEqual(walkPath.duration, 5);
+      assert.strictEqual(walkPath.fromStopId, 0);
+    });
+
+    it('uses the fallback transfer time when the timetable specifies none', () => {
+      // Temporarily use a timetable where the transfer has no minTransferTime.
+      const adj: StopAdjacency[] = [
+        {
+          transfers: [{ destination: 1, type: 'REQUIRES_MINIMAL_TIME' }],
+          routes: [],
+        },
+        { routes: [0] },
+        { routes: [0] },
+      ];
+      const localTimetable = new Timetable(adj, routesAdjacency, serviceRoutes);
+      const localFinder = new AccessFinder(localTimetable, stopsIndex);
+      const paths = localFinder.collectAccessPaths(0, 3); // fallback = 3 min
+      const walkPath = paths.find((p) => p.toStopId === 1);
+      assert(walkPath);
+      assert.strictEqual(walkPath.duration, 3);
+    });
+
+    it('does not include GUARANTEED transfers', () => {
+      const paths = finder.collectAccessPaths(0, 2);
+      const guaranteedPath = paths.find((p) => p.toStopId === 2);
+      assert.strictEqual(guaranteedPath, undefined);
+    });
+
+    it('keeps the shortest walk when multiple equivalent origins can reach the same stop', () => {
+      // Parent stop 3 with two children: stop 4 (8-min walk to stop 1)
+      // and stop 5 (3-min walk to stop 1).
+      const adj: StopAdjacency[] = [
+        { routes: [] },
+        { routes: [0] },
+        { routes: [0] },
+        { routes: [] },
+        {
+          transfers: [
+            {
+              destination: 1,
+              type: 'REQUIRES_MINIMAL_TIME',
+              minTransferTime: 8,
+            },
+          ],
+          routes: [],
+        },
+        {
+          transfers: [
+            {
+              destination: 1,
+              type: 'REQUIRES_MINIMAL_TIME',
+              minTransferTime: 3,
+            },
+          ],
+          routes: [],
+        },
+      ];
+      const extraStops: Stop[] = [
+        ...stops,
+        {
+          id: 3,
+          sourceStopId: 'parent',
+          name: 'Parent',
+          lat: 0,
+          lon: 0,
+          children: [4, 5],
+          locationType: 'STATION',
+        },
+        {
+          id: 4,
+          sourceStopId: 'child1',
+          name: 'Child 1',
+          lat: 0,
+          lon: 0,
+          children: [],
+          parent: 3,
+          locationType: 'SIMPLE_STOP_OR_PLATFORM',
+        },
+        {
+          id: 5,
+          sourceStopId: 'child2',
+          name: 'Child 2',
+          lat: 0,
+          lon: 0,
+          children: [],
+          parent: 3,
+          locationType: 'SIMPLE_STOP_OR_PLATFORM',
+        },
+      ];
+      const localTimetable = new Timetable(adj, routesAdjacency, serviceRoutes);
+      const localStopsIndex = new StopsIndex(extraStops);
+      const localFinder = new AccessFinder(localTimetable, localStopsIndex);
+
+      // Origin is child stop 4; equivalentStops(4) = [4, 5] (siblings).
+      const paths = localFinder.collectAccessPaths(4, 2);
+      const walkToStop1 = paths.find((p) => p.toStopId === 1);
+      assert(walkToStop1);
+      assert.strictEqual(walkToStop1.duration, 3); // shorter walk wins
+      assert.strictEqual(walkToStop1.fromStopId, 5);
+    });
+  });
+
+  describe('collectDepartureTimes', () => {
+    it('returns slots sorted latest-departure-first', () => {
+      const paths: AccessPoint[] = [
+        { fromStopId: 0, toStopId: 1, duration: 0 },
+      ];
+      const slots = finder.collectDepartureTimes(
+        paths,
+        timeFromHM(8, 0),
+        timeFromHM(8, 45),
+      );
+      assert.strictEqual(slots.length, 2);
+      assert.strictEqual(slots[0]?.depTime, timeFromHM(8, 40));
+      assert.strictEqual(slots[1]?.depTime, timeFromHM(8, 10));
+    });
+
+    it('excludes trips departing outside the query window', () => {
+      const paths: AccessPoint[] = [
+        { fromStopId: 0, toStopId: 1, duration: 0 },
+      ];
+      const slots = finder.collectDepartureTimes(
+        paths,
+        timeFromHM(8, 0),
+        timeFromHM(8, 30),
+      );
+      assert.strictEqual(slots.length, 1);
+      assert.strictEqual(slots[0]?.depTime, timeFromHM(8, 10));
+    });
+
+    it('returns empty when no trip falls within the window', () => {
+      const paths: AccessPoint[] = [
+        { fromStopId: 0, toStopId: 1, duration: 0 },
+      ];
+      const slots = finder.collectDepartureTimes(
+        paths,
+        timeFromHM(9, 0),
+        timeFromHM(10, 0),
+      );
+      assert.strictEqual(slots.length, 0);
+    });
+
+    it('zero-duration paths to stops with routes generate slots at exact trip departure times', () => {
+      // The self-path (stop 0, duration 0) has no routes in this timetable,
+      // so it contributes no slots. The walk path (stop 1, duration 5) has
+      // trips at 08:10 and 08:40; with the window ending at 08:05 only the
+      // 08:10 trip is reachable, producing a single slot at 08:05 (= 08:10 - 5).
+      const equivalentPath: AccessPoint = {
+        fromStopId: 0,
+        toStopId: 0,
+        duration: 0,
+      };
+      const walkPath: AccessPoint = {
+        fromStopId: 0,
+        toStopId: 1,
+        duration: 5,
+      };
+
+      const slots = finder.collectDepartureTimes(
+        [equivalentPath, walkPath],
+        timeFromHM(8, 0),
+        timeFromHM(8, 5),
+      );
+
+      assert.strictEqual(slots.length, 1);
+      assert.strictEqual(slots[0]!.depTime, timeFromHM(8, 5));
+      const legIds = slots[0]!.legs.map((l) => l.toStopId);
+      assert(legIds.includes(1), 'walk path must appear in its own slot');
+      assert(
+        !legIds.includes(0),
+        'equivalent path without routes must not appear in a slot it did not generate',
+      );
+    });
+  });
+});