minotor 11.1.2 → 11.2.0

package/src/cli/minotor.ts

@@ -12,8 +12,11 @@ import {
 import { Router, StopsIndex, Timetable } from '../router.js';
 import {
   loadQueriesFromJson,
+  loadRangeQueriesFromJson,
   prettyPrintPerformanceResults,
   testBestRoutePerformance,
+  testRangeResultPerformance,
+  testRangeRouterPerformance,
   testRouterPerformance,
 } from './perf.js';
 import { startRepl } from './repl.js';
@@ -160,17 +163,50 @@ program
       const queries = loadQueriesFromJson(routesPath, stopsIndex);
       const iterations = parseInt(options.iterations, 10);
 
-      const routerResults = testRouterPerformance(router, queries, iterations);
-      prettyPrintPerformanceResults(routerResults, 'Router Performance');
+      const routerResults = testRouterPerformance(
+        router,
+        queries,
+        iterations,
+        stopsIndex,
+      );
+      prettyPrintPerformanceResults(
+        routerResults,
+        'Point queries — router.route()',
+      );
 
       const bestRouteResults = testBestRoutePerformance(
         router,
         queries,
         iterations,
+        stopsIndex,
       );
       prettyPrintPerformanceResults(
         bestRouteResults,
-        'bestRoute Performance (reconstruction only)',
+        'Point queries — result.bestRoute() (reconstruction only)',
+      );
+
+      const rangeQueries = loadRangeQueriesFromJson(routesPath, stopsIndex);
+
+      const rangeRouterResults = testRangeRouterPerformance(
+        router,
+        rangeQueries,
+        iterations,
+        stopsIndex,
+      );
+      prettyPrintPerformanceResults(
+        rangeRouterResults,
+        'Range queries — router.rangeRoute()',
+      );
+
+      const rangeResultResults = testRangeResultPerformance(
+        router,
+        rangeQueries,
+        iterations,
+        stopsIndex,
+      );
+      prettyPrintPerformanceResults(
+        rangeResultResults,
+        'Range queries — rangeResult.getRoutes() (reconstruction only)',
       );
     },
   );

package/src/cli/perf.ts

@@ -1,11 +1,17 @@
 import fs from 'fs';
 import { performance } from 'perf_hooks';
 
-import { Query, Router, StopsIndex } from '../router.js';
-import { timeFromString } from '../timetable/time.js';
+import {
+  Query,
+  RangeQuery,
+  RangeResult,
+  Router,
+  StopsIndex,
+} from '../router.js';
+import { timeFromString, timeToString } from '../timetable/time.js';
 
 type PerformanceResult = {
-  task: Query;
+  label: string;
   meanTimeUs: number;
   meanMemoryMb: number;
 };
@@ -14,18 +20,78 @@ type SerializedQuery = {
   from: string;
   to: string[];
   departureTime: string;
+  lastDepartureTime?: string;
   maxTransfers?: number;
 };
 
+// ─── Table renderer ───────────────────────────────────────────────────────────
+
+type Column = {
+  header: string;
+  width: number;
+  align: 'left' | 'right';
+};
+
+const renderTable = (
+  columns: Column[],
+  rows: string[][],
+  footerRow: string[],
+): string => {
+  const bar = (l: string, m: string, r: string) =>
+    l + columns.map((c) => '─'.repeat(c.width + 2)).join(m) + r;
+
+  const renderRow = (cells: string[]) =>
+    '│' +
+    cells
+      .map((cell, i) => {
+        const width = columns[i]?.width ?? 0;
+        const align = columns[i]?.align ?? 'left';
+        const padded =
+          align === 'right' ? cell.padStart(width) : cell.padEnd(width);
+        return ` ${padded} `;
+      })
+      .join('│') +
+    '│';
+
+  return [
+    bar('┌', '┬', '┐'),
+    renderRow(columns.map((c) => c.header)),
+    bar('├', '┼', '┤'),
+    ...rows.map(renderRow),
+    bar('├', '┼', '┤'),
+    renderRow(footerRow),
+    bar('└', '┴', '┘'),
+  ].join('\n');
+};
+
+// ─── Query label ──────────────────────────────────────────────────────────────
+
+const buildQueryLabel = (query: Query, stopsIndex: StopsIndex): string => {
+  const fromName =
+    stopsIndex.findStopById(query.from)?.name ?? String(query.from);
+
+  const toNames = [...query.to]
+    .map((id) => stopsIndex.findStopById(id)?.name ?? String(id))
+    .join(' / ');
+
+  const dep = timeToString(query.departureTime);
+
+  if (query instanceof RangeQuery) {
+    const lastDep = timeToString(query.lastDepartureTime);
+    return `${fromName} → ${toNames}  ${dep}–${lastDep}`;
+  }
+
+  return `${fromName} → ${toNames}  ${dep}`;
+};
+
+// ─── Query loaders ────────────────────────────────────────────────────────────
+
 /**
  * Loads a list of routing queries from a JSON file and resolves the
  * human-readable stop IDs to the internal numeric IDs used by the router.
  *
- * The file must contain a JSON array whose elements each have the shape:
- * ```json
- * { "from": "STOP_A", "to": ["STOP_B", "STOP_C"], "departureTime": "08:30:00" }
- * ```
- * An optional `maxTransfers` integer field is also supported.
+ * Only entries that do **not** carry a `lastDepartureTime` field are loaded —
+ * range-query entries are silently skipped.
  *
  * @param filePath - Path to the JSON file containing the serialized queries.
  * @param stopsIndex - The stops index used to resolve source stop IDs to the
@@ -44,31 +110,88 @@ export const loadQueriesFromJson = (
     fileContent,
   ) as SerializedQuery[];
 
-  return serializedQueries.map((serializedQuery) => {
-    const fromStop = stopsIndex.findStopBySourceStopId(serializedQuery.from);
-    const toStops = Array.from(serializedQuery.to).map((stopId) =>
-      stopsIndex.findStopBySourceStopId(stopId),
-    );
+  return serializedQueries
+    .filter((q) => q.lastDepartureTime === undefined)
+    .map((serializedQuery) => {
+      const fromStop = stopsIndex.findStopBySourceStopId(serializedQuery.from);
+      const toStops = Array.from(serializedQuery.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(serializedQuery)}`,
+        );
+      }
+      const queryBuilder = new Query.Builder()
+        .from(fromStop.id)
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        .to(new Set(toStops.map((stop) => stop!.id)))
+        .departureTime(timeFromString(serializedQuery.departureTime));
+
+      if (serializedQuery.maxTransfers !== undefined) {
+        queryBuilder.maxTransfers(serializedQuery.maxTransfers);
+      }
+
+      return queryBuilder.build();
+    });
+};
+
+/**
+ * Loads a list of range routing queries from a JSON file and resolves the
+ * human-readable stop IDs to the internal numeric IDs used by the router.
+ *
+ * Only entries that carry a `lastDepartureTime` field are loaded — plain
+ * point-query entries are silently skipped.
+ *
+ * @param filePath - Path to the JSON file containing the serialized queries.
+ * @param stopsIndex - The stops index used to resolve source stop IDs to the
+ *   internal numeric IDs expected by the router.
+ * @returns An array of fully constructed {@link RangeQuery} objects ready to
+ *   be passed to {@link Router.rangeRoute}.
+ * @throws If the file cannot be read, the JSON is malformed, or any stop ID
+ *   referenced in the file cannot be found in the stops index.
+ */
+export const loadRangeQueriesFromJson = (
+  filePath: string,
+  stopsIndex: StopsIndex,
+): RangeQuery[] => {
+  const fileContent = fs.readFileSync(filePath, 'utf-8');
+  const serializedQueries: SerializedQuery[] = JSON.parse(
+    fileContent,
+  ) as SerializedQuery[];
 
-    if (!fromStop || toStops.some((toStop) => !toStop)) {
-      throw new Error(
-        `Invalid task: Start or end station not found for task ${JSON.stringify(serializedQuery)}`,
+  return serializedQueries
+    .filter((q) => q.lastDepartureTime !== undefined)
+    .map((serializedQuery) => {
+      const fromStop = stopsIndex.findStopBySourceStopId(serializedQuery.from);
+      const toStops = Array.from(serializedQuery.to).map((stopId) =>
+        stopsIndex.findStopBySourceStopId(stopId),
       );
-    }
-    const queryBuilder = new Query.Builder()
-      .from(fromStop.id)
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      .to(new Set(toStops.map((stop) => stop!.id)))
-      .departureTime(timeFromString(serializedQuery.departureTime));
-
-    if (serializedQuery.maxTransfers !== undefined) {
-      queryBuilder.maxTransfers(serializedQuery.maxTransfers);
-    }
 
-    return queryBuilder.build();
-  });
+      if (!fromStop || toStops.some((toStop) => !toStop)) {
+        throw new Error(
+          `Invalid task: Start or end station not found for task ${JSON.stringify(serializedQuery)}`,
+        );
+      }
+      const queryBuilder = new RangeQuery.Builder()
+        .from(fromStop.id)
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        .to(new Set(toStops.map((stop) => stop!.id)))
+        .departureTime(timeFromString(serializedQuery.departureTime))
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        .lastDepartureTime(timeFromString(serializedQuery.lastDepartureTime!));
+
+      if (serializedQuery.maxTransfers !== undefined) {
+        queryBuilder.maxTransfers(serializedQuery.maxTransfers);
+      }
+
+      return queryBuilder.build();
+    });
 };
 
+// ─── Benchmark runners ────────────────────────────────────────────────────────
+
 /**
  * Benchmarks {@link Router.route} across a set of queries.
  *
@@ -77,6 +200,7 @@ export const loadQueriesFromJson = (
  *   produced per query.
  * @param iterations - Number of times each query is repeated. Higher values
  *   yield a more stable mean at the cost of longer wall-clock time.
+ * @param stopsIndex - Used to resolve stop names for result labels.
  * @returns An array of {@link PerformanceResult} objects, one per query, each
  *   containing the mean wall-clock time (µs) and mean heap delta (MB).
  */
@@ -84,6 +208,7 @@ export const testRouterPerformance = (
   router: Router,
   tasks: Query[],
   iterations: number,
+  stopsIndex: StopsIndex,
 ): PerformanceResult[] => {
   const results: PerformanceResult[] = [];
 
@@ -111,7 +236,7 @@ export const testRouterPerformance = (
     }
 
     results.push({
-      task,
+      label: buildQueryLabel(task, stopsIndex),
       meanTimeUs: totalTime / iterations,
       meanMemoryMb: totalMemory / iterations / (1024 * 1024),
     });
@@ -129,6 +254,7 @@ export const testRouterPerformance = (
  * @param tasks - The list of queries to benchmark. One {@link PerformanceResult}
  *   is produced per query.
  * @param iterations - Number of times `bestRoute` is called per query.
+ * @param stopsIndex - Used to resolve stop names for result labels.
  * @returns An array of {@link PerformanceResult} objects, one per query, each
  *   containing the mean wall-clock time (µs) and mean heap delta (MB) for the
  *   `bestRoute` call alone.
@@ -137,11 +263,11 @@ export const testBestRoutePerformance = (
   router: Router,
   tasks: Query[],
   iterations: number,
+  stopsIndex: StopsIndex,
 ): PerformanceResult[] => {
   const results: PerformanceResult[] = [];
 
   for (const task of tasks) {
-    // Compute the routing result once — this is not part of the benchmark.
     const result = router.route(task);
 
     let totalTime = 0;
@@ -167,7 +293,7 @@ export const testBestRoutePerformance = (
     }
 
     results.push({
-      task,
+      label: buildQueryLabel(task, stopsIndex),
       meanTimeUs: totalTime / iterations,
       meanMemoryMb: totalMemory / iterations / (1024 * 1024),
     });
@@ -177,44 +303,182 @@ export const testBestRoutePerformance = (
 };
 
 /**
- * Prints a human-readable summary of performance results to stdout.
+ * Benchmarks {@link Router.rangeRoute} across a set of range queries.
  *
- * Displays an overall mean across all tasks followed by a per-task breakdown.
- * An optional {@link label} is printed as a section header so that results
- * from different benchmark phases (e.g. routing vs. reconstruction) can be
- * told apart when several calls appear in the same run.
+ * @param router - The router instance to benchmark.
+ * @param tasks - The list of range queries to run. One {@link PerformanceResult}
+ *   is produced per query.
+ * @param iterations - Number of times each query is repeated.
+ * @param stopsIndex - Used to resolve stop names for result labels.
+ * @returns An array of {@link PerformanceResult} objects, one per query, each
+ *   containing the mean wall-clock time (µs) and mean heap delta (MB).
+ */
+export const testRangeRouterPerformance = (
+  router: Router,
+  tasks: RangeQuery[],
+  iterations: number,
+  stopsIndex: StopsIndex,
+): PerformanceResult[] => {
+  const results: PerformanceResult[] = [];
+
+  for (const task of tasks) {
+    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.rangeRoute(task);
+
+      const endTime = performance.now();
+      const endMemory = process.memoryUsage().heapUsed;
+
+      totalTime += (endTime - startTime) * 1_000;
+      if (endMemory >= startMemory) {
+        totalMemory += endMemory - startMemory;
+      }
+    }
+
+    results.push({
+      label: buildQueryLabel(task, stopsIndex),
+      meanTimeUs: totalTime / iterations,
+      meanMemoryMb: totalMemory / iterations / (1024 * 1024),
+    });
+  }
+
+  return results;
+};
+
+/**
+ * Benchmarks {@link RangeResult.getRoutes} — the full Pareto-frontier
+ * reconstruction phase — independently of the range routing phase.
  *
- * @param results - The performance results to display, as returned by
- *   {@link testRouterPerformance} or {@link testBestRoutePerformance}.
- * @param label - Optional heading printed above the results block.
- *   Defaults to `'Performance Results'`.
+ * @param router - The router instance used to produce the range results that
+ *   are then fed into `getRoutes`.
+ * @param tasks - The list of range queries to benchmark. One
+ *   {@link PerformanceResult} is produced per query.
+ * @param iterations - Number of times `getRoutes` is called per query.
+ * @param stopsIndex - Used to resolve stop names for result labels.
+ * @returns An array of {@link PerformanceResult} objects, one per query, each
+ *   containing the mean wall-clock time (µs) and mean heap delta (MB) for the
+ *   `getRoutes` call alone.
+ */
+export const testRangeResultPerformance = (
+  router: Router,
+  tasks: RangeQuery[],
+  iterations: number,
+  stopsIndex: StopsIndex,
+): PerformanceResult[] => {
+  const results: PerformanceResult[] = [];
+
+  for (const task of tasks) {
+    const rangeResult: RangeResult = router.rangeRoute(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();
+
+      rangeResult.getRoutes();
+
+      const endTime = performance.now();
+      const endMemory = process.memoryUsage().heapUsed;
+
+      totalTime += (endTime - startTime) * 1_000;
+      if (endMemory >= startMemory) {
+        totalMemory += endMemory - startMemory;
+      }
+    }
+
+    results.push({
+      label: buildQueryLabel(task, stopsIndex),
+      meanTimeUs: totalTime / iterations,
+      meanMemoryMb: totalMemory / iterations / (1024 * 1024),
+    });
+  }
+
+  return results;
+};
+
+// ─── Output ───────────────────────────────────────────────────────────────────
+
+/**
+ * Prints a table summary of performance results to stdout.
+ *
+ * Each row corresponds to one task, identified by a human-readable query label
+ * (origin → destination + departure time). A footer row shows the mean across
+ * all tasks. An optional `label` is printed as a section header above the table.
+ *
+ * @param results - The performance results to display.
+ * @param label - Heading printed above the table. Defaults to `'Performance Results'`.
  */
 export const prettyPrintPerformanceResults = (
   results: PerformanceResult[],
   label = 'Performance Results',
 ): void => {
+  console.log(`\n${label}`);
+
   if (results.length === 0) {
-    console.log('No performance results to display.');
+    console.log('  (no results)');
     return;
   }
 
-  const overallMeanTimeNs =
-    results.reduce((sum, result) => sum + result.meanTimeUs, 0) /
-    results.length;
-  const overallMeanMemoryMb =
-    results.reduce((sum, result) => sum + result.meanMemoryMb, 0) /
-    results.length;
-
-  console.log(`${label}:`);
-  console.log(`  Mean Time (µs): ${overallMeanTimeNs.toFixed(0)}`);
-  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 (µs): ${result.meanTimeUs.toFixed(0)}`);
-    console.log(`  Mean Memory (MB): ${result.meanMemoryMb.toFixed(2)}`);
-    console.log('');
-  });
+  const fmtTime = (n: number) => Math.round(n).toLocaleString('en-US');
+  const fmtMem = (n: number) => n.toFixed(2);
+
+  const meanTime =
+    results.reduce((s, r) => s + r.meanTimeUs, 0) / results.length;
+  const meanMem =
+    results.reduce((s, r) => s + r.meanMemoryMb, 0) / results.length;
+
+  const queryHeader = 'Query';
+  const timeHeader = 'Time (µs)';
+  const memHeader = 'Mem (MB)';
+
+  const timeVals = results.map((r) => fmtTime(r.meanTimeUs));
+  const memVals = results.map((r) => fmtMem(r.meanMemoryMb));
+  const meanTimeStr = fmtTime(meanTime);
+  const meanMemStr = fmtMem(meanMem);
+
+  const queryWidth = Math.max(
+    queryHeader.length,
+    'mean'.length,
+    ...results.map((r) => r.label.length),
+  );
+  const timeWidth = Math.max(
+    timeHeader.length,
+    meanTimeStr.length,
+    ...timeVals.map((v) => v.length),
+  );
+  const memWidth = Math.max(
+    memHeader.length,
+    meanMemStr.length,
+    ...memVals.map((v) => v.length),
+  );
+
+  const columns: Column[] = [
+    { header: queryHeader, width: queryWidth, align: 'left' },
+    { header: timeHeader, width: timeWidth, align: 'right' },
+    { header: memHeader, width: memWidth, align: 'right' },
+  ];
+
+  const rows = results.map((r, i) => [
+    r.label,
+    timeVals[i] ?? '',
+    memVals[i] ?? '',
+  ]);
+  const footer = ['mean', meanTimeStr, meanMemStr];
+
+  console.log(renderTable(columns, rows, footer));
 };