minotor 1.0.0

package/src/timetable/time.ts

@@ -0,0 +1,192 @@
+import { Duration } from './duration.js';
+
+/**
+ * A class representing a time in hours, minutes, and seconds.
+ */
+export class Time {
+  private secondsSinceMidnight: number;
+  /**
+   * Gets the infinity time as a Time instance.
+   * This represents a time that is conceptually beyond any real possible time.
+   *
+   * @returns A Time instance representing an "infinity" time.
+   */
+  static infinity(): Time {
+    return new Time(Number.MAX_SAFE_INTEGER);
+  }
+  /**
+   * Gets the midnight time as a Time instance.
+   *
+   * @returns A Time instance representing midnight (00:00:00).
+   */
+  static origin(): Time {
+    return new Time(0);
+  }
+
+  private constructor(seconds: number) {
+    this.secondsSinceMidnight = seconds;
+  }
+
+  /**
+   * Creates a Time instance from the number of seconds since midnight.
+   *
+   * @param seconds - The number of seconds since midnight.
+   * @returns A Time instance representing the specified time.
+   */
+  static fromSeconds(seconds: number): Time {
+    return new Time(seconds);
+  }
+
+  /**
+   * Creates a Time instance from hours, minutes, and seconds.
+   *
+   * @param hours - The hours component of the time.
+   * @param minutes - The minutes component of the time.
+   * @param seconds - The seconds component of the time.
+   * @returns A Time instance representing the specified time.
+   */
+  static fromHMS(hours: number, minutes: number, seconds: number): Time {
+    if (
+      hours < 0 ||
+      minutes < 0 ||
+      seconds < 0 ||
+      minutes >= 60 ||
+      seconds >= 60
+    ) {
+      throw new Error(
+        'Invalid time. Ensure hours, minutes, and seconds are valid values.',
+      );
+    }
+    return new Time(seconds + 60 * minutes + 3600 * hours);
+  }
+
+  /**
+   * Parses a JavaScript Date object and creates a Time instance.
+   *
+   * @param date - A JavaScript Date object representing the time.
+   * @returns A Time instance representing the parsed time.
+   */
+  static fromDate(date: Date): Time {
+    const hours = date.getHours();
+    const minutes = date.getMinutes();
+    const seconds = date.getSeconds();
+    return new Time(seconds + 60 * minutes + 3600 * hours);
+  }
+
+  /**
+   * Parses a time string in the format "HH:MM:SS" or "HH:MM" and creates a Time instance.
+   *
+   * @param timeStr - A string representing the time in "HH:MM:SS" or "HH:MM" format.
+   * @returns A Time instance representing the parsed time.
+   */
+  static fromString(timeStr: string): Time {
+    const [hoursStr, minutesStr, secondsStr] = timeStr.split(':');
+    if (
+      hoursStr === undefined ||
+      minutesStr === undefined ||
+      isNaN(Number(hoursStr)) ||
+      isNaN(Number(minutesStr)) ||
+      (secondsStr !== undefined && isNaN(Number(secondsStr)))
+    ) {
+      throw new Error(
+        'Input string must be in the format "HH:MM:SS" or "HH:MM".',
+      );
+    }
+    const hours = parseInt(hoursStr, 10);
+    const minutes = parseInt(minutesStr, 10);
+    const seconds = secondsStr !== undefined ? parseInt(secondsStr, 10) : 0;
+    return new Time(seconds + 60 * minutes + 3600 * hours);
+  }
+
+  /**
+   * Converts the Time instance to a string in "HH:MM:SS" format.
+   *
+   * @returns A string representing the time.
+   */
+  toString(): string {
+    const hours = Math.floor(this.secondsSinceMidnight / 3600);
+    const minutes = Math.floor((this.secondsSinceMidnight % 3600) / 60);
+    const seconds = this.secondsSinceMidnight % 60;
+    return `${hours.toString().padStart(2, '0')}:${minutes
+      .toString()
+      .padStart(2, '0')}:${seconds.toString().padStart(2, '0')}`;
+  }
+
+  /**
+   * Gets the time as the number of seconds since midnight.
+   *
+   * @returns The time in seconds since midnight.
+   */
+  toSeconds(): number {
+    return this.secondsSinceMidnight;
+  }
+  /**
+   * Adds a Duration to the current Time instance and returns a new Time instance.
+   *
+   * @param duration - A Duration instance representing the duration to add.
+   * @returns A new Time instance with the added duration.
+   */
+  plus(duration: Duration): Time {
+    const totalSeconds = this.secondsSinceMidnight + duration.toSeconds();
+    return new Time(totalSeconds);
+  }
+
+  /**
+   * Subtracts a Duration from the current Time instance and returns a new Time instance.
+   *
+   * @param duration - A Duration instance representing the duration to subtract.
+   * @returns A new Time instance with the subtracted duration.
+   */
+  minus(duration: Duration): Time {
+    let totalSeconds = this.secondsSinceMidnight - duration.toSeconds();
+    if (totalSeconds < 0) {
+      totalSeconds += 24 * 3600; // Adjust for negative time to loop back to previous day
+    }
+    return new Time(totalSeconds);
+  }
+
+  /**
+   * Subtracts another Time instance from the current Time instance and returns the Duration.
+   *
+   * @param otherTime - A Time instance representing the time to subtract.
+   * @returns A Duration instance representing the time difference.
+   */
+  diff(otherTime: Time): Duration {
+    const totalSeconds = this.secondsSinceMidnight - otherTime.toSeconds();
+    return Duration.fromSeconds(Math.abs(totalSeconds));
+  }
+
+  /**
+   * Computes the maximum Time instance among the provided Time instances.
+   *
+   * @param times - An array of Time instances to compare.
+   * @returns A Time instance representing the maximum time.
+   */
+  static max(...times: Time[]): Time {
+    if (times.length === 0) {
+      throw new Error('At least one Time instance is required.');
+    }
+    return times.reduce((maxTime, currentTime) => {
+      return currentTime.toSeconds() > maxTime.toSeconds()
+        ? currentTime
+        : maxTime;
+    });
+  }
+
+  /**
+   * Computes the minimum Time instance among the provided Time instances.
+   *
+   * @param times - An array of Time instances to compare.
+   * @returns A Time instance representing the minimum time.
+   */
+  static min(...times: Time[]): Time {
+    if (times.length === 0) {
+      throw new Error('At least one Time instance is required.');
+    }
+    return times.reduce((minTime, currentTime) => {
+      return currentTime.toSeconds() < minTime.toSeconds()
+        ? currentTime
+        : minTime;
+    });
+  }
+}

package/src/timetable/timetable.ts

@@ -0,0 +1,286 @@
+import { BinaryReader, BinaryWriter } from '@bufbuild/protobuf/wire';
+
+import { StopId } from '../stops/stops.js';
+import { Duration } from './duration.js';
+import {
+  deserializeRoutesAdjacency,
+  deserializeServiceRoutesMap,
+  deserializeStopsAdjacency,
+  serializeRoutesAdjacency,
+  serializeServiceRoutesMap,
+  serializeStopsAdjacency,
+} from './io.js';
+import { Timetable as ProtoTimetable } from './proto/timetable.js';
+import { Time } from './time.js';
+
+export type PickUpDropOffType =
+  | 'REGULAR'
+  | 'NOT_AVAILABLE'
+  | 'MUST_PHONE_AGENCY'
+  | 'MUST_COORDINATE_WITH_DRIVER';
+
+export type StopTimes = {
+  arrival: Time;
+  departure: Time;
+  pickUpType: PickUpDropOffType;
+  dropOffType: PickUpDropOffType;
+};
+export type RouteId = string;
+
+export type IndexedStopId = {
+  stopId: StopId;
+  index: number;
+};
+export type Route = {
+  stopTimes: StopTimes[];
+  stops: StopId[];
+  stopIndices: Map<StopId, number>;
+  serviceRouteId: ServiceRouteId;
+};
+export type RoutesAdjacency = Map<RouteId, Route>;
+
+export type TransferType =
+  | 'RECOMMENDED'
+  | 'GUARANTEED'
+  | 'REQUIRES_MINIMAL_TIME'
+  | 'IN_SEAT';
+
+export type Transfer = {
+  destination: StopId;
+  type: TransferType;
+  minTransferTime?: Duration;
+};
+
+export type StopsAdjacency = Map<
+  StopId,
+  {
+    transfers: Transfer[];
+    routes: RouteId[];
+  }
+>;
+
+export type ServiceRouteId = string;
+
+export type RouteType =
+  | 'TRAM'
+  | 'SUBWAY'
+  | 'RAIL'
+  | 'BUS'
+  | 'FERRY'
+  | 'CABLE_TRAM'
+  | 'AERIAL_LIFT'
+  | 'FUNICULAR'
+  | 'TROLLEYBUS'
+  | 'MONORAIL';
+
+export type ServiceRoute = {
+  type: RouteType;
+  name: string;
+};
+
+// A service refers to a collection of trips that are displayed to riders as a single service.
+// As opposed to a route which consists of the subset of trips from a service which shares the same list of stops.
+// Service is here a synonym for route in the GTFS sense.
+export type ServiceRoutesMap = Map<ServiceRouteId, ServiceRoute>;
+
+// a trip index corresponds to the index of the
+// first stop time in the trip modulo the number of stops
+// in the given route
+type TripIndex = number;
+
+export const ALL_TRANSPORT_MODES: RouteType[] = [
+  'TRAM',
+  'SUBWAY',
+  'RAIL',
+  'BUS',
+  'FERRY',
+  'CABLE_TRAM',
+  'AERIAL_LIFT',
+  'FUNICULAR',
+  'TROLLEYBUS',
+  'MONORAIL',
+];
+
+export const CURRENT_VERSION = '0.0.1';
+
+/**
+ * The internal transit timetable format
+ * reuses some GTFS concepts for the sake of simplicity for now.
+ */
+export class Timetable {
+  private readonly stopsAdjacency: StopsAdjacency;
+  private readonly routesAdjacency: RoutesAdjacency;
+  private readonly routes: ServiceRoutesMap;
+
+  constructor(
+    stopsAdjacency: StopsAdjacency,
+    routesAdjacency: RoutesAdjacency,
+    routes: ServiceRoutesMap,
+  ) {
+    this.stopsAdjacency = stopsAdjacency;
+    this.routesAdjacency = routesAdjacency;
+    this.routes = routes;
+  }
+
+  /**
+   * Serializes the Timetable into a binary protobuf.
+   *
+   * @returns {Uint8Array} - The serialized binary data.
+   */
+  serialize(): Uint8Array {
+    const protoTimetable = {
+      version: CURRENT_VERSION,
+      stopsAdjacency: serializeStopsAdjacency(this.stopsAdjacency),
+      routesAdjacency: serializeRoutesAdjacency(this.routesAdjacency),
+      routes: serializeServiceRoutesMap(this.routes),
+    };
+    const writer = new BinaryWriter();
+    ProtoTimetable.encode(protoTimetable, writer);
+    return writer.finish();
+  }
+
+  /**
+   * Deserializes a binary protobuf into a Timetable object.
+   *
+   * @param {Uint8Array} data - The binary data to deserialize.
+   * @returns {Timetable} - The deserialized Timetable object.
+   */
+  static fromData(data: Uint8Array): Timetable {
+    const reader = new BinaryReader(data);
+    const protoTimetable = ProtoTimetable.decode(reader);
+    if (protoTimetable.version !== CURRENT_VERSION) {
+      throw new Error(
+        `Unsupported timetable version ${protoTimetable.version}`,
+      );
+    }
+    return new Timetable(
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      deserializeStopsAdjacency(protoTimetable.stopsAdjacency!),
+      deserializeRoutesAdjacency(
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        protoTimetable.routesAdjacency!,
+      ),
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      deserializeServiceRoutesMap(protoTimetable.routes!),
+    );
+  }
+
+  getRoute(routeId: RouteId): Route | undefined {
+    return this.routesAdjacency.get(routeId);
+  }
+
+  getTransfers(stopId: StopId): Transfer[] {
+    return this.stopsAdjacency.get(stopId)?.transfers ?? [];
+  }
+
+  /**
+   * Finds routes that are reachable from a set of stop IDs.
+   * Also identifies the first stop available to hop on each route among
+   * the input stops.
+   */
+  /* eslint-disable @typescript-eslint/no-non-null-assertion */
+  findReachableRoutes(
+    fromStops: Set<StopId>,
+    transportModes: RouteType[] = ALL_TRANSPORT_MODES,
+  ): Map<RouteId, StopId> {
+    const reachableRoutes = new Map<RouteId, StopId>();
+    for (const stop of fromStops) {
+      const validRoutes = this.stopsAdjacency
+        .get(stop)
+        ?.routes.filter((routeId) => {
+          const serviceRoute = this.getServiceRouteFromRouteId(routeId);
+          if (!serviceRoute) {
+            return false;
+          }
+          return transportModes.includes(serviceRoute.type);
+        });
+      for (const routeId of validRoutes || []) {
+        const hopOnStop = reachableRoutes.get(routeId);
+        if (hopOnStop) {
+          // Checks if the existing hop on stop is before the current stop
+          const routeStopIndices =
+            this.routesAdjacency.get(routeId)!.stopIndices;
+          const stopIndex = routeStopIndices.get(stop)!;
+          const hopOnStopIndex = routeStopIndices.get(hopOnStop)!;
+          if (stopIndex < hopOnStopIndex) {
+            // if the current stop is before the existing hop on stop, replace it
+            reachableRoutes.set(routeId, stop);
+          }
+        } else {
+          reachableRoutes.set(routeId, stop);
+        }
+      }
+    }
+    return reachableRoutes;
+  }
+
+  getServiceRouteFromRouteId(routeId: RouteId): ServiceRoute | undefined {
+    const route = this.routesAdjacency.get(routeId);
+    if (!route) {
+      console.warn(`Route ${routeId} not found.`);
+      return undefined;
+    }
+    return this.routes.get(route.serviceRouteId);
+  }
+
+  getServiceRoute(serviceRouteId: ServiceRouteId): ServiceRoute | undefined {
+    return this.routes.get(serviceRouteId);
+  }
+
+  /**
+   * Finds the earliest trip that can be taken from a specific stop on a given route,
+   * optionally constrained by a latest trip index and a time before which the trip
+   * should not depart.
+   */
+  findEarliestTrip(
+    route: Route,
+    stopId: StopId,
+    beforeTrip?: TripIndex,
+    after: Time = Time.origin(),
+  ): TripIndex | undefined {
+    const stopIndex = route.stopIndices.get(stopId)!;
+
+    const stopsNumber = route.stops.length;
+
+    if (beforeTrip === undefined) {
+      for (
+        let tripIndex = 0;
+        tripIndex < route.stopTimes.length / stopsNumber;
+        tripIndex++
+      ) {
+        const stopTimeIndex = tripIndex * stopsNumber + stopIndex;
+        const stopTime = route.stopTimes[stopTimeIndex]!;
+        if (
+          stopTime.departure > after &&
+          stopTime.pickUpType !== 'NOT_AVAILABLE'
+        ) {
+          return tripIndex;
+        }
+      }
+      return undefined;
+    } else {
+      let earliestTripIndex: TripIndex | undefined;
+      let earliestDeparture: Time | undefined;
+      for (
+        let tripIndex = beforeTrip; // ?? route.stopTimes.length / stopsNumber - 1;
+        tripIndex >= 0;
+        tripIndex--
+      ) {
+        const stopTimeIndex = tripIndex * stopsNumber + stopIndex;
+        const stopTime = route.stopTimes[stopTimeIndex]!;
+        if (stopTime.departure <= after) {
+          break;
+        }
+        if (
+          stopTime.pickUpType !== 'NOT_AVAILABLE' &&
+          (earliestDeparture === undefined ||
+            stopTime.departure < earliestDeparture)
+        ) {
+          earliestTripIndex = tripIndex;
+          earliestDeparture = stopTime.departure;
+        }
+      }
+      return earliestTripIndex;
+    }
+  }
+}

package/src/umdIndex.ts

@@ -0,0 +1,14 @@
+/*
+ * An index containing only browser compatible modules for the UMD build.
+ */
+
+import { Plotter } from './routing/plotter.js';
+import { Query } from './routing/query.js';
+import { Result } from './routing/result.js';
+import { Route } from './routing/route.js';
+import { Router } from './routing/router.js';
+import { StopsIndex } from './stops/stopsIndex.js';
+import { Time } from './timetable/time.js';
+import { Timetable } from './timetable/timetable.js';
+
+export { Plotter, Query, Result, Route, Router, StopsIndex, Time, Timetable };

package/tsconfig.build.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": ["./src/**/__tests__"]
+}

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "include": ["./src/**/*.ts"],
+  "compilerOptions": {
+    "target": "es2015",
+    "lib": ["es2019"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "./src",
+    "outDir": "dist",
+    "strict": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noUncheckedIndexedAccess": true,
+    "sourceMap": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "noImplicitReturns": true,
+    "noUnusedLocals": true
+  }
+}