minotor 3.0.0 → 3.0.2

package/src/__e2e__/benchmark.json

@@ -0,0 +1,22 @@
+[
+  {
+    "from": "Parent8504100",
+    "to": ["Parent8504748"],
+    "departureTime": "08:30"
+  },
+  {
+    "from": "Parent8507000",
+    "to": ["Parent8509253"],
+    "departureTime": "12:30"
+  },
+  {
+    "from": "Parent8501008",
+    "to": ["Parent8501008"],
+    "departureTime": "08:30"
+  },
+  {
+    "from": "Parent8500010",
+    "to": ["Parent8301003"],
+    "departureTime": "10:00"
+  }
+]

package/src/__e2e__/router.test.ts

@@ -0,0 +1,209 @@
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+
+import fs from 'fs';
+
+import { Query, Router, StopsIndex, Time, Timetable } from '../router.js';
+
+const routes = [
+  {
+    from: 'Parent8504100', // Fribourg/Freiburg
+    to: 'Parent8504748', // Le Moléson
+    at: '08:30',
+    route: [
+      {
+        from: '8504100:0:2', // Fribourg/Freiburg, Pl. 2
+        to: '8504086:0:2', // Bulle, Pl. 2
+        departure: '08:34',
+        arrival: '09:11',
+        route: {
+          type: 'RAIL',
+          name: 'RE2',
+        },
+      },
+      {
+        from: '8504086:0:2', // Bulle, Pl. 2
+        to: '8504086:0:4', // Bulle, Pl. 4
+        type: 'REQUIRES_MINIMAL_TIME',
+        minTransferTime: '03:00',
+      },
+      {
+        from: '8504086:0:4', // Bulle, Pl. 4
+        to: '8504077:0:1', // Gruyères, Pl. 1
+        departure: '09:20',
+        arrival: '09:28',
+        route: {
+          type: 'RAIL',
+          name: 'S51',
+        },
+      },
+      {
+        from: '8504077:0:1', // Gruyères, Pl. 1
+        to: '8577737', // Gruyères, gare
+        type: 'REQUIRES_MINIMAL_TIME',
+        minTransferTime: '02:00',
+      },
+      {
+        from: '8577737', // Gruyères, gare
+        to: '8504880', // Moléson-sur-Gruyères
+        departure: '09:33',
+        arrival: '09:44',
+        route: {
+          type: 'BUS',
+          name: '263',
+        },
+      },
+      {
+        from: '8504880', // Moléson-sur-Gruyères
+        to: '8530024', // Moléson-sur-Gruyères (funi)
+        type: 'REQUIRES_MINIMAL_TIME',
+        minTransferTime: '02:00',
+      },
+      {
+        from: '8530024', // Moléson-sur-Gruyères (funi)
+        to: '8504749', // Plan-Francey
+        departure: '10:00',
+        arrival: '10:05',
+        route: {
+          type: 'FUNICULAR',
+          name: 'FUN',
+        },
+      },
+      {
+        from: '8504749', // Plan-Francey
+        to: '8531209', // Plan-Francey (téléphérique)
+        type: 'REQUIRES_MINIMAL_TIME',
+        minTransferTime: '02:00',
+      },
+      {
+        from: '8531209', // Plan-Francey (téléphérique)
+        to: '8504748', // Le Moléson
+        departure: '10:10',
+        arrival: '10:15',
+        route: {
+          type: 'AERIAL_LIFT',
+          name: 'PB',
+        },
+      },
+    ],
+  },
+  {
+    from: 'Parent8507000', // Bern
+    to: 'Parent8509253', // St. Moritz
+    at: '12:30',
+    route: [
+      {
+        from: '8507000:0:8', // Bern, Pl.8
+        to: '8503000:0:33', // Zürich HB, Pl. 33
+        departure: '12:31',
+        arrival: '13:28',
+        route: {
+          type: 'RAIL',
+          name: 'IC1',
+        },
+      },
+      {
+        from: '8503000:0:33', // Zürich HB, Pl. 33
+        to: '8503000:0:9', // Zürich HB, Pl. 9
+        type: 'REQUIRES_MINIMAL_TIME',
+        minTransferTime: '07:00',
+      },
+      {
+        from: '8503000:0:9', // Zürich HB, Pl. 9
+        to: '8509000:0:9', // Chur, Pl. 9
+        departure: '13:38',
+        arrival: '14:52',
+        route: {
+          type: 'RAIL',
+          name: 'IC3',
+        },
+      },
+      {
+        from: '8509000:0:9', // Chur, Pl. 9
+        to: '8509000:0:10', // Chur, Pl. 10
+        type: 'REQUIRES_MINIMAL_TIME',
+        minTransferTime: '03:00',
+      },
+      {
+        from: '8509000:0:10', // Chur, Pl. 10
+        to: '8509253:0:2', // St-Moritz,  Pl. 2
+        departure: '14:58',
+        arrival: '16:56',
+        route: {
+          type: 'RAIL',
+          name: 'IR38',
+        },
+      },
+    ],
+  },
+  {
+    // Cross-border train as two routes (TODO, check if there is an in-seat transfer modeled for it)
+    from: 'Parent8500010', // Basel SBB
+    to: 'Parent8721202', // Strasbourg
+    at: '16:50',
+    route: [
+      {
+        from: '8500010:0:31', // Basel SBB, Pl. 31
+        to: '8718213', // Saint-Louis (Haut-Rhin)
+        departure: '16:50',
+        arrival: '16:58',
+        route: {
+          type: 'RAIL',
+          name: 'TER',
+        },
+      },
+      {
+        from: '8718213', // Saint-Louis (Haut-Rhin)
+        to: '8721202', // Strasbourg
+        departure: '16:59',
+        arrival: '18:09',
+        route: {
+          type: 'RAIL',
+          name: 'K200',
+        },
+      },
+    ],
+  },
+];
+
+const stopsPath = new URL('./timetable/stops.bin', import.meta.url).pathname;
+const timetablePath = new URL('./timetable/timetable.bin', import.meta.url)
+  .pathname;
+
+describe('E2E Tests for Transit Router', () => {
+  const stopsIndex = StopsIndex.fromData(fs.readFileSync(stopsPath));
+  const timetable = Timetable.fromData(fs.readFileSync(timetablePath));
+
+  const router = new Router(timetable, stopsIndex);
+
+  routes.forEach(({ from, to, at, route }) => {
+    it(`Route from ${from} to ${to} at ${at}`, () => {
+      const fromStop = stopsIndex.findStopBySourceStopId(from);
+      const toStop = stopsIndex.findStopBySourceStopId(to);
+
+      assert.ok(fromStop, `Stop not found: ${from}`);
+      assert.ok(toStop, `Stop not found: ${to}`);
+
+      const departureTime = Time.fromString(at);
+
+      const queryObject = new Query.Builder()
+        .from(fromStop.sourceStopId)
+        .to(toStop.sourceStopId)
+        .departureTime(departureTime)
+        .maxTransfers(5)
+        .build();
+
+      const result = router.route(queryObject);
+      const bestRoute = result.bestRoute(toStop.sourceStopId);
+
+      assert.ok(bestRoute, 'No route found');
+      const actualRoute = bestRoute.asJson();
+
+      assert.deepStrictEqual(
+        actualRoute,
+        route,
+        `Route mismatch for query from ${from} to ${to} at ${at}`,
+      );
+    });
+  });
+});

package/src/__e2e__/timetable/stops.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:af51977d74fcf12d054680c4de134b1fd411ada37fdc84588c45000797f69b3d
+size 5880221

package/src/__e2e__/timetable/timetable.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6725771bfd0e287d515b3ddd74202eab8023b39808818e422bd57b564013b37c
+size 29833126

package/src/cli/minotor.ts

@@ -4,6 +4,12 @@ import log from 'loglevel';
 import { DateTime } from 'luxon';
 
 import { chGtfsProfile, GtfsParser, GtfsProfile } from '../parser.js';
+import { Router, StopsIndex, Timetable } from '../router.js';
+import {
+  loadQueriesFromJson,
+  prettyPrintPerformanceResults,
+  testRouterPerformance,
+} from './perf.js';
 import { startRepl } from './repl.js';
 
 const program = new Command();
@@ -71,7 +77,7 @@ program
 
 program
   .command('parse-stops')
-  .description('Parse a GTFS feed and output a timetable and stops file.')
+  .description('Parse a GTFS feed and output a stops file.')
   .argument('<gtfsPath>', 'Path to GTFS data')
   .option('-s, --outputPath <path>', 'Path to output stops file', '/tmp/stops')
   .option('-p, --profileName <name>', 'Profile name for GTFS config', 'CH')
@@ -109,4 +115,48 @@ program
     startRepl(options.stopsPath, options.timetablePath);
   });
 
+program
+  .command('perf')
+  .description('Evaluate the performance of the router on a set of routes.')
+  .argument('<routesPath>', 'Path to the JSON file containing the routes')
+  .option('-s, --stopsPath <path>', 'Path to the stops file', '/tmp/stops')
+  .option(
+    '-t, --timetablePath <path>',
+    'Path to the timetable file',
+    '/tmp/timetable',
+  )
+  .option(
+    '-i, --iterations <number>',
+    'Number of iterations for performance tests',
+    '20',
+  )
+  .action(
+    (
+      routesPath: string,
+      options: {
+        stopsPath: string;
+        timetablePath: string;
+        iterations: string;
+      },
+    ) => {
+      const stopsIndex = StopsIndex.fromData(
+        fs.readFileSync(options.stopsPath),
+      );
+      const timetable = Timetable.fromData(
+        fs.readFileSync(options.timetablePath),
+      );
+      const router = new Router(timetable, stopsIndex);
+
+      const queries = loadQueriesFromJson(routesPath);
+      const performanceResults = testRouterPerformance(
+        router,
+        stopsIndex,
+        queries,
+        parseInt(options.iterations, 10),
+      );
+
+      prettyPrintPerformanceResults(performanceResults);
+    },
+  );
+
 program.parse(process.argv);

package/src/cli/perf.ts

@@ -0,0 +1,136 @@
+import fs from 'fs';
+import { performance } from 'perf_hooks';
+
+import { Query, Router, StopsIndex, Time } from '../router.js';
+
+type PerformanceResult = {
+  task: Query;
+  meanTimeMs: number;
+  meanMemoryMb: number;
+};
+
+type SerializedQuery = {
+  from: string;
+  to: string[];
+  departureTime: string;
+  maxTransfers?: number;
+};
+
+/**
+ *
+ * @param filePath
+ * @returns
+ */
+export const loadQueriesFromJson = (filePath: string): Query[] => {
+  const fileContent = fs.readFileSync(filePath, 'utf-8');
+  const serializedQueries: SerializedQuery[] = JSON.parse(
+    fileContent,
+  ) as SerializedQuery[];
+
+  return serializedQueries.map((serializedQuery) => {
+    const queryBuilder = new Query.Builder()
+      .from(serializedQuery.from)
+      .to(new Set(serializedQuery.to))
+      .departureTime(Time.fromString(serializedQuery.departureTime));
+
+    if (serializedQuery.maxTransfers !== undefined) {
+      queryBuilder.maxTransfers(serializedQuery.maxTransfers);
+    }
+
+    return queryBuilder.build();
+  });
+};
+
+/**
+ *
+ * @param router
+ * @param stopsIndex
+ * @param tasks
+ * @param iterations
+ * @returns
+ */
+export const testRouterPerformance = (
+  router: Router,
+  stopsIndex: StopsIndex,
+  tasks: Query[],
+  iterations: number,
+): PerformanceResult[] => {
+  const results: PerformanceResult[] = [];
+
+  for (const task of tasks) {
+    const fromStop = stopsIndex.findStopBySourceStopId(task.from);
+    const toStops = Array.from(task.to).map((stopId) =>
+      stopsIndex.findStopBySourceStopId(stopId),
+    );
+
+    if (!fromStop || toStops.some((toStop) => !toStop)) {
+      throw new Error(
+        `Invalid task: Start or end station not found for task ${JSON.stringify(task)}`,
+      );
+    }
+
+    let totalTime = 0;
+    let totalMemory = 0;
+
+    for (let i = 0; i < iterations; i++) {
+      if (global.gc) {
+        global.gc();
+      }
+
+      const startMemory = process.memoryUsage().heapUsed;
+      const startTime = performance.now();
+
+      router.route(task);
+
+      const endTime = performance.now();
+      const endMemory = process.memoryUsage().heapUsed;
+
+      totalTime += endTime - startTime;
+      if (endMemory >= startMemory) {
+        totalMemory += endMemory - startMemory;
+      }
+    }
+
+    results.push({
+      task,
+      meanTimeMs: totalTime / iterations,
+      meanMemoryMb: totalMemory / iterations / (1024 * 1024),
+    });
+  }
+
+  return results;
+};
+
+/**
+ *
+ * @param results
+ * @returns
+ */
+export const prettyPrintPerformanceResults = (
+  results: PerformanceResult[],
+): void => {
+  if (results.length === 0) {
+    console.log('No performance results to display.');
+    return;
+  }
+
+  const overallMeanTimeMs =
+    results.reduce((sum, result) => sum + result.meanTimeMs, 0) /
+    results.length;
+  const overallMeanMemoryMb =
+    results.reduce((sum, result) => sum + result.meanMemoryMb, 0) /
+    results.length;
+
+  console.log('Overall Performance Results:');
+  console.log(`  Mean Time (ms): ${overallMeanTimeMs.toFixed(2)}`);
+  console.log(`  Mean Memory (MB): ${overallMeanMemoryMb.toFixed(2)}`);
+  console.log('');
+
+  console.log('Individual Task Results:');
+  results.forEach((result, index) => {
+    console.log(`Task ${index + 1}:`);
+    console.log(`  Mean Time (ms): ${result.meanTimeMs.toFixed(2)}`);
+    console.log(`  Mean Memory (MB): ${result.meanMemoryMb.toFixed(2)}`);
+    console.log('');
+  });
+};

package/src/cli/repl.ts

@@ -3,7 +3,7 @@ import repl from 'node:repl';
 import fs from 'fs';
 
 import { Query, Router, StopsIndex, Time, Timetable } from '../router.js';
-import { plotGraphToDotFile, prettyPrintRoute } from './utils.js';
+import { plotGraphToDotFile } from './utils.js';
 
 export const startRepl = (stopsPath: string, timetablePath: string) => {
   const stopsIndex = StopsIndex.fromData(fs.readFileSync(stopsPath));
@@ -21,9 +21,20 @@ export const startRepl = (stopsPath: string, timetablePath: string) => {
     help: 'Find stops by name using .find <query>',
     action(query: string) {
       this.clearBufferedCommand();
-      const stops = stopsIndex.findStopsByName(query);
+      let stops = [];
+      const stopBySourceId = stopsIndex.findStopBySourceStopId(query);
+      if (stopBySourceId !== undefined) {
+        stops.push(stopBySourceId);
+      } else if (!isNaN(Number(query))) {
+        const stopById = stopsIndex.findStopById(Number(query));
+        if (stopById !== undefined) {
+          stops.push(stopById);
+        }
+      } else {
+        stops = stopsIndex.findStopsByName(query);
+      }
       stops.forEach((stop) => {
-        console.log(`${stop.name} (${stop.id})`);
+        console.log(`${stop.name} (${stop.sourceStopId} - ${stop.id})`);
       });
       this.displayPrompt();
     },
@@ -49,12 +60,7 @@ export const startRepl = (stopsPath: string, timetablePath: string) => {
       const fromIndex = parts.indexOf('from');
       const toIndex = parts.indexOf('to');
       const fromId = parts.slice(fromIndex + 1, toIndex).join(' ');
-      const toId = parts
-        .slice(
-          toIndex + 1,
-          withTransfersIndex === -1 ? parts.indexOf('at') : parts.indexOf('at'),
-        )
-        .join(' ');
+      const toId = parts.slice(toIndex + 1, parts.indexOf('at')).join(' ');
 
       if (!fromId || !toId || !atTime) {
         console.log(
@@ -66,9 +72,15 @@ export const startRepl = (stopsPath: string, timetablePath: string) => {
 
       const fromStop =
         stopsIndex.findStopBySourceStopId(fromId) ||
+        (isNaN(Number(fromId))
+          ? undefined
+          : stopsIndex.findStopById(Number(fromId))) ||
         stopsIndex.findStopsByName(fromId)[0];
       const toStop =
         stopsIndex.findStopBySourceStopId(toId) ||
+        (isNaN(Number(toId))
+          ? undefined
+          : stopsIndex.findStopById(Number(toId))) ||
         stopsIndex.findStopsByName(toId)[0];
 
       if (!fromStop) {
@@ -88,7 +100,7 @@ export const startRepl = (stopsPath: string, timetablePath: string) => {
       try {
         const query = new Query.Builder()
           .from(fromStop.sourceStopId)
-          .to([toStop.sourceStopId])
+          .to(toStop.sourceStopId)
           .departureTime(departureTime)
           .maxTransfers(maxTransfers)
           .build();
@@ -101,14 +113,15 @@ export const startRepl = (stopsPath: string, timetablePath: string) => {
           console.log(`Destination not reachable`);
         } else {
           console.log(
-            `Arriving to ${toStop.name} at ${arrivalTime.time.toString()} with ${arrivalTime.legNumber - 1} transfers from ${stopsIndex.findStopById(arrivalTime.origin)?.name}.`,
+            `Arriving to ${toStop.name} at ${arrivalTime.arrival.toString()} with ${arrivalTime.legNumber - 1} transfers from ${stopsIndex.findStopById(arrivalTime.origin)?.name}.`,
           );
         }
         const bestRoute = result.bestRoute(toStop.sourceStopId);
 
         if (bestRoute) {
           console.log(`Found route from ${fromStop.name} to ${toStop.name}:`);
-          prettyPrintRoute(bestRoute);
+          console.log(bestRoute.toString());
+          console.log(JSON.stringify(bestRoute.asJson(), null, 2));
         } else {
           console.log('No route found');
         }
@@ -184,7 +197,7 @@ export const startRepl = (stopsPath: string, timetablePath: string) => {
       try {
         const query = new Query.Builder()
           .from(fromStop.sourceStopId)
-          .to([toStop.sourceStopId])
+          .to(toStop.sourceStopId)
           .departureTime(departureTime)
           .maxTransfers(maxTransfers)
           .build();

package/src/cli/utils.ts

@@ -1,34 +1,12 @@
 import fs from 'fs';
 
-import { Plotter, Result, Route } from '../router.js';
-
-export const prettyPrintRoute = (route: Route): void => {
-  route.legs.forEach((leg, index) => {
-    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 + ')' : ''}`;
-    let transferDetails = '';
-    let travelDetails = '';
-
-    if ('minTransferTime' in leg) {
-      transferDetails = `Minimum Transfer Time: ${leg.minTransferTime?.toString()}`;
-    }
-    if ('route' in leg && 'departureTime' in leg && 'arrivalTime' in leg) {
-      travelDetails = `Route: ${leg.route.type} ${leg.route.name}, Departure: ${leg.departureTime.toString()}, Arrival: ${leg.arrivalTime.toString()}`;
-    }
-
-    console.log(`Leg ${index + 1}:`);
-    console.log(`  ${fromStop}`);
-    console.log(`  ${toStop}`);
-    if (transferDetails) {
-      console.log(`  ${transferDetails}`);
-    }
-    if (travelDetails) {
-      console.log(`  ${travelDetails}`);
-    }
-    console.log('');
-  });
-};
+import { Plotter, Result } from '../router.js';
 
+/**
+ * Plots the graph of the result to a dot file.
+ * @param result - The result object to plot.
+ * @param filePath - The path where the dot file will be saved.
+ */
 export const plotGraphToDotFile = (result: Result, filePath: string): void => {
   const plotter = new Plotter(result);
   const dotContent = plotter.plotDotGraph();

package/src/gtfs/__tests__/parser.test.ts

@@ -33,28 +33,25 @@ describe('GTFS parser', () => {
 
     const route = timetable.getRoute('AB_x');
     assert(route);
-    assert.strictEqual(route.serviceRouteId, 'AB');
+    assert.strictEqual(route.serviceRoute(), 'AB');
     const beattyAirportId =
       stopsIndex.findStopBySourceStopId('BEATTY_AIRPORT')?.id;
     const bullfrogId = stopsIndex.findStopBySourceStopId('BULLFROG')?.id;
     assert(beattyAirportId !== undefined && bullfrogId !== undefined);
-    assert.deepStrictEqual(Array.from(route.stops), [
-      beattyAirportId,
-      bullfrogId,
-    ]);
-    assert.strictEqual(route.stopTimes.length, 4);
-    assert.strictEqual(route.pickUpDropOffTypes.length, 4);
-    assert.strictEqual(route.stopTimes[0], Time.fromHMS(8, 0, 0).toMinutes());
-    assert.strictEqual(route.stopTimes[1], Time.fromHMS(8, 0, 0).toMinutes());
-    assert.strictEqual(route.stopTimes[2], Time.fromHMS(8, 10, 0).toMinutes());
-    assert.strictEqual(route.stopTimes[3], Time.fromHMS(8, 15, 0).toMinutes());
+    assert.strictEqual(route.getNbStops(), 2);
+    assert(route.arrivalAt(beattyAirportId, 0).equals(Time.fromHMS(8, 0, 0)));
+    assert(
+      route.departureFrom(beattyAirportId, 0).equals(Time.fromHMS(8, 0, 0)),
+    );
+    assert(route.arrivalAt(bullfrogId, 0).equals(Time.fromHMS(8, 10, 0)));
+    assert(route.departureFrom(bullfrogId, 0).equals(Time.fromHMS(8, 15, 0)));
 
-    const routes = timetable.getRoutesThroughStop(furCreekResId);
+    const routes = timetable.routesPassingThrough(furCreekResId);
     assert.strictEqual(routes.length, 2);
-    assert.strictEqual(routes[0], 'BFC_1q');
-    assert.strictEqual(routes[1], 'BFC_2');
+    assert.strictEqual(routes[0]?.serviceRoute(), 'BFC');
+    assert.strictEqual(routes[1]?.serviceRoute(), 'BFC');
 
-    const serviceRoute = timetable.getServiceRoute('AB');
+    const serviceRoute = timetable.getServiceRoute(route);
     assert(serviceRoute);
     assert.strictEqual(serviceRoute.name, '10');
     assert.strictEqual(serviceRoute.type, 'BUS');

package/src/gtfs/__tests__/services.test.ts

@@ -5,6 +5,7 @@ import { describe, it } from 'node:test';
 import { DateTime } from 'luxon';
 
 import { parseCalendar, parseCalendarDates, ServiceIds } from '../services.js';
+
 describe('GTFS calendar parser', () => {
   describe('parsing a well formed stream', () => {
     it('should find valid services present in the source', async () => {

package/src/gtfs/__tests__/transfers.test.ts

@@ -242,7 +242,6 @@ describe('GTFS transfers parser', () => {
         },
       ],
     ]);
-    console.log(JSON.stringify(stopsMap));
     const transfers = await parseTransfers(mockedStream, stopsMap);
     assert.deepEqual(
       transfers,