minotor 1.0.0

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

@@ -0,0 +1,175 @@
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+
+import { Duration } from '../duration.js';
+import {
+  deserializeRoutesAdjacency,
+  deserializeServiceRoutesMap,
+  deserializeStopsAdjacency,
+  serializeRoutesAdjacency,
+  serializeServiceRoutesMap,
+  serializeStopsAdjacency,
+} from '../io.js';
+import { Time } from '../time.js';
+import {
+  RoutesAdjacency,
+  ServiceRoutesMap,
+  StopsAdjacency,
+} from '../timetable.js';
+
+describe('timetable io', () => {
+  const stopsAdjacency: StopsAdjacency = new Map([
+    [
+      'stop1',
+      {
+        transfers: [{ destination: 'stop2', type: 'RECOMMENDED' }],
+        routes: ['route1'],
+      },
+    ],
+    [
+      'stop2',
+      {
+        transfers: [
+          {
+            destination: 'stop1',
+            type: 'GUARANTEED',
+            minTransferTime: Duration.fromMinutes(3),
+          },
+        ],
+        routes: ['route2'],
+      },
+    ],
+  ]);
+  const routesAdjacency: RoutesAdjacency = new Map([
+    [
+      'route1',
+      {
+        stopTimes: [
+          {
+            arrival: Time.fromSeconds(1000),
+            departure: Time.fromSeconds(1010),
+            pickUpType: 'REGULAR',
+            dropOffType: 'REGULAR',
+          },
+        ],
+        stops: ['stop1', 'stop2'],
+        stopIndices: new Map([
+          ['stop1', 0],
+          ['stop2', 1],
+        ]),
+        serviceRouteId: 'gtfs1',
+      },
+    ],
+    [
+      'route2',
+      {
+        stopTimes: [
+          {
+            arrival: Time.fromSeconds(2000),
+            departure: Time.fromSeconds(2010),
+            pickUpType: 'REGULAR',
+            dropOffType: 'REGULAR',
+          },
+        ],
+        stops: ['stop2', 'stop1'],
+        stopIndices: new Map([
+          ['stop2', 0],
+          ['stop1', 1],
+        ]),
+        serviceRouteId: 'gtfs2',
+      },
+    ],
+  ]);
+  const routes: ServiceRoutesMap = new Map([
+    ['gtfs1', { type: 'RAIL', name: 'Route 1' }],
+    ['gtfs2', { type: 'RAIL', name: 'Route 2' }],
+  ]);
+
+  const stopsAdjacencyProto = {
+    stops: {
+      stop1: {
+        transfers: [{ destination: 'stop2', type: 0 }],
+        routes: ['route1'],
+      },
+      stop2: {
+        transfers: [
+          {
+            destination: 'stop1',
+            type: 1,
+            minTransferTime: 180,
+          },
+        ],
+        routes: ['route2'],
+      },
+    },
+  };
+
+  const routesAdjacencyProto = {
+    routes: {
+      route1: {
+        stopTimes: [
+          {
+            arrival: 1000,
+            departure: 1010,
+            pickUpType: undefined,
+            dropOffType: undefined,
+          },
+        ],
+        stops: ['stop1', 'stop2'],
+        serviceRouteId: 'gtfs1',
+      },
+      route2: {
+        stopTimes: [
+          {
+            arrival: 2000,
+            departure: 2010,
+            pickUpType: undefined,
+            dropOffType: undefined,
+          },
+        ],
+        stops: ['stop2', 'stop1'],
+        serviceRouteId: 'gtfs2',
+      },
+    },
+  };
+
+  const routesProto = {
+    routes: {
+      gtfs1: { type: 2, name: 'Route 1' },
+      gtfs2: { type: 2, name: 'Route 2' },
+    },
+  };
+
+  it('should serialize a stops adjacency matrix to a Uint8Array', () => {
+    const serializedData = serializeStopsAdjacency(stopsAdjacency);
+    assert.deepStrictEqual(serializedData, stopsAdjacencyProto);
+  });
+
+  it('should deserialize a Uint8Array to a stops adjacency matrix', () => {
+    const serializedData = serializeStopsAdjacency(stopsAdjacency);
+    const deserializedData = deserializeStopsAdjacency(serializedData);
+    assert.deepStrictEqual(deserializedData, stopsAdjacency);
+  });
+
+  it('should serialize a routes adjacency matrix to a Uint8Array', () => {
+    const serializedData = serializeRoutesAdjacency(routesAdjacency);
+    assert.deepStrictEqual(serializedData, routesAdjacencyProto);
+  });
+
+  it('should deserialize a Uint8Array to a routes adjacency matrix', () => {
+    const serializedData = serializeRoutesAdjacency(routesAdjacency);
+    const deserializedData = deserializeRoutesAdjacency(serializedData);
+    assert.deepStrictEqual(deserializedData, routesAdjacency);
+  });
+
+  it('should serialize a service route map to a Uint8Array', () => {
+    const serializedData = serializeServiceRoutesMap(routes);
+    assert.deepStrictEqual(serializedData, routesProto);
+  });
+
+  it('should deserialize a Uint8Array to a service route map', () => {
+    const serializedData = serializeServiceRoutesMap(routes);
+    const deserializedData = deserializeServiceRoutesMap(serializedData);
+    assert.deepStrictEqual(deserializedData, routes);
+  });
+});

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

@@ -0,0 +1,180 @@
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+
+import { Duration } from '../duration.js';
+import { Time } from '../time.js';
+import {
+  RoutesAdjacency,
+  ServiceRoutesMap,
+  StopsAdjacency,
+  Timetable,
+} from '../timetable.js';
+
+describe('timetable io', () => {
+  const stopsAdjacency: StopsAdjacency = new Map([
+    [
+      'stop1',
+      {
+        transfers: [{ destination: 'stop2', type: 'RECOMMENDED' }],
+        routes: ['route1'],
+      },
+    ],
+    [
+      'stop2',
+      {
+        transfers: [
+          {
+            destination: 'stop1',
+            type: 'GUARANTEED',
+            minTransferTime: Duration.fromMinutes(3),
+          },
+        ],
+        routes: ['route2'],
+      },
+    ],
+  ]);
+  const routesAdjacency: RoutesAdjacency = new Map([
+    [
+      'route1',
+      {
+        stopTimes: [
+          {
+            arrival: Time.fromHMS(0, 16, 40),
+            departure: Time.fromHMS(0, 16, 50),
+            pickUpType: 'REGULAR',
+            dropOffType: 'REGULAR',
+          },
+          {
+            arrival: Time.fromHMS(0, 33, 20),
+            departure: Time.fromHMS(0, 33, 30),
+            pickUpType: 'NOT_AVAILABLE',
+            dropOffType: 'REGULAR',
+          },
+          {
+            arrival: Time.fromHMS(0, 50, 0),
+            departure: Time.fromHMS(0, 50, 10),
+            pickUpType: 'REGULAR',
+            dropOffType: 'REGULAR',
+          },
+          {
+            arrival: Time.fromHMS(1, 10, 0),
+            departure: Time.fromHMS(1, 10, 10),
+            pickUpType: 'REGULAR',
+            dropOffType: 'REGULAR',
+          },
+        ],
+        stops: ['stop1', 'stop2'],
+        stopIndices: new Map([
+          ['stop1', 0],
+          ['stop2', 1],
+        ]),
+        serviceRouteId: 'gtfs1',
+      },
+    ],
+    [
+      'route2',
+      {
+        stopTimes: [
+          {
+            arrival: Time.fromHMS(1, 6, 40),
+            departure: Time.fromHMS(1, 6, 50),
+            pickUpType: 'REGULAR',
+            dropOffType: 'REGULAR',
+          },
+          {
+            arrival: Time.fromHMS(1, 23, 20),
+            departure: Time.fromHMS(1, 23, 30),
+            pickUpType: 'REGULAR',
+            dropOffType: 'REGULAR',
+          },
+        ],
+        stops: ['stop2', 'stop1'],
+        stopIndices: new Map([
+          ['stop2', 0],
+          ['stop1', 1],
+        ]),
+        serviceRouteId: 'gtfs2',
+      },
+    ],
+  ]);
+  const routes: ServiceRoutesMap = new Map([
+    ['gtfs1', { type: 'RAIL', name: 'Route 1' }],
+    ['gtfs2', { type: 'RAIL', name: 'Route 2' }],
+  ]);
+
+  const sampleTimetable: Timetable = new Timetable(
+    stopsAdjacency,
+    routesAdjacency,
+    routes,
+  );
+
+  it('should serialize a timetable to a Uint8Array', () => {
+    const serializedData = sampleTimetable.serialize();
+    assert(serializedData instanceof Uint8Array);
+    assert(serializedData.length > 0);
+  });
+  it('should deserialize a Uint8Array to a timetable', () => {
+    const serializedData = sampleTimetable.serialize();
+    const deserializedTimetable = Timetable.fromData(serializedData);
+    assert.deepStrictEqual(deserializedTimetable, sampleTimetable);
+  });
+
+  it('should find the earliest trip for stop1 on route1', () => {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const route = sampleTimetable.getRoute('route1')!;
+    const tripIndex = sampleTimetable.findEarliestTrip(route, 'stop1');
+    assert.strictEqual(tripIndex, 0);
+  });
+
+  it('should find the earliest trip for stop1 on route1 after a specific time', () => {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const route = sampleTimetable.getRoute('route1')!;
+    const afterTime = Time.fromHMS(0, 25, 0);
+    const tripIndex = sampleTimetable.findEarliestTrip(
+      route,
+      'stop1',
+      undefined,
+      afterTime,
+    );
+    assert.strictEqual(tripIndex, 1);
+  });
+
+  it('should return undefined if no valid trip exists after a specific time', () => {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const route = sampleTimetable.getRoute('route1')!;
+    const afterTime = Time.fromHMS(0, 58, 20);
+    const tripIndex = sampleTimetable.findEarliestTrip(
+      route,
+      'stop1',
+      undefined,
+      afterTime,
+    );
+    assert.strictEqual(tripIndex, undefined);
+  });
+  it('should return undefined if the stop on a trip has pick up not available', () => {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const route = sampleTimetable.getRoute('route1')!;
+    const tripIndex = sampleTimetable.findEarliestTrip(route, 'stop2');
+    assert.strictEqual(tripIndex, 1);
+  });
+  it('should find reachable routes from a set of stop IDs', () => {
+    const fromStops = new Set(['stop1']);
+    const reachableRoutes = sampleTimetable.findReachableRoutes(fromStops);
+    assert.strictEqual(reachableRoutes.size, 1);
+    assert.strictEqual(reachableRoutes.get('route1'), 'stop1');
+  });
+
+  it('should find no reachable routes if starting from a non-existent stop', () => {
+    const fromStops = new Set(['non_existent_stop']);
+    const reachableRoutes = sampleTimetable.findReachableRoutes(fromStops);
+    assert.strictEqual(reachableRoutes.size, 0);
+  });
+
+  it('should find reachable routes filtered by transport modes', () => {
+    const fromStops = new Set(['stop1']);
+    const reachableRoutes = sampleTimetable.findReachableRoutes(fromStops, [
+      'BUS',
+    ]);
+    assert.strictEqual(reachableRoutes.size, 0);
+  });
+});

package/src/timetable/duration.ts

@@ -0,0 +1,85 @@
+export class Duration {
+  private totalSeconds: number;
+
+  private constructor(totalSeconds: number) {
+    this.totalSeconds = totalSeconds;
+  }
+  /**
+   * Creates a Duration instance from a given number of seconds.
+   *
+   * @param seconds - The number of seconds for the duration.
+   * @returns A Duration instance representing the specified duration.
+   */
+  static fromSeconds(seconds: number): Duration {
+    return new Duration(seconds);
+  }
+  /**
+   * Creates a Duration instance from a given number of minutes.
+   *
+   * @param minutes - The number of minutes for the duration.
+   * @returns A Duration instance representing the specified duration.
+   */
+  static fromMinutes(minutes: number): Duration {
+    return new Duration(minutes * 60);
+  }
+  /**
+   * Gets a Duration instance representing zero duration (0 hours, 0 minutes, 0 seconds).
+   *
+   * @returns A Duration instance representing zero duration.
+   */
+  static zero(): Duration {
+    return new Duration(0);
+  }
+
+  /**
+   * Converts the duration instance to a string in "HH:MM:SS" format.
+   *
+   * @returns A string representing the duration.
+   */
+  toString(): string {
+    const hours = Math.floor(this.totalSeconds / 3600);
+    const minutes = Math.floor((this.totalSeconds % 3600) / 60);
+    const seconds = this.totalSeconds % 60;
+    if (hours > 0) {
+      return `${hours.toString().padStart(2, '0')}:${minutes
+        .toString()
+        .padStart(2, '0')}:${seconds.toString().padStart(2, '0')}`;
+    } else {
+      return `${minutes.toString().padStart(2, '0')}:${seconds
+        .toString()
+        .padStart(2, '0')}`;
+    }
+  }
+
+  /**
+   * Gets the duration as the number of seconds.
+   *
+   * @returns The duration in seconds.
+   */
+  toSeconds(): number {
+    return this.totalSeconds;
+  }
+
+  /**
+   * Adds another Duration to this instance and returns the result as a new Duration.
+   *
+   * @param other - The other Duration to add.
+   * @returns A new Duration instance representing the sum.
+   */
+  add(other: Duration): Duration {
+    const totalSeconds = this.totalSeconds + other.toSeconds();
+    return new Duration(totalSeconds);
+  }
+
+  /**
+   * Subtracts another Duration from this instance and returns the result as a new Duration.
+   * If the result would be negative, it returns a Duration of 0 seconds.
+   *
+   * @param other - The other Duration to subtract.
+   * @returns A new Duration instance representing the difference.
+   */
+  subtract(other: Duration): Duration {
+    const totalSeconds = Math.max(0, this.totalSeconds - other.toSeconds());
+    return new Duration(totalSeconds);
+  }
+}

package/src/timetable/io.ts

@@ -0,0 +1,265 @@
+import { Duration } from './duration.js';
+import {
+  PickUpDropOffType as ProtoPickUpDropOffType,
+  RoutesAdjacency as ProtoRoutesAdjacency,
+  RouteType as ProtoRouteType,
+  ServiceRoutesMap as ProtoServiceRoutesMap,
+  StopsAdjacency as ProtoStopsAdjacency,
+  Transfer as ProtoTransfer,
+  TransferType as ProtoTransferType,
+} from './proto/timetable.js';
+import { Time } from './time.js';
+import {
+  PickUpDropOffType,
+  Route,
+  RoutesAdjacency,
+  RouteType,
+  ServiceRoutesMap,
+  StopsAdjacency,
+  Transfer,
+  TransferType,
+} from './timetable.js';
+
+export const serializeStopsAdjacency = (
+  stopsAdjacency: StopsAdjacency,
+): ProtoStopsAdjacency => {
+  const protoStopsAdjacency: ProtoStopsAdjacency = {
+    stops: {},
+  };
+
+  stopsAdjacency.forEach(
+    (value: { transfers: Transfer[]; routes: string[] }, key: string) => {
+      protoStopsAdjacency.stops[key] = {
+        transfers: value.transfers.map((transfer) => ({
+          destination: transfer.destination,
+          type: serializeTransferType(transfer.type),
+          ...(transfer.minTransferTime !== undefined && {
+            minTransferTime: transfer.minTransferTime.toSeconds(),
+          }),
+        })),
+        routes: value.routes,
+      };
+    },
+  );
+
+  return protoStopsAdjacency;
+};
+
+export const serializeRoutesAdjacency = (
+  routesAdjacency: RoutesAdjacency,
+): ProtoRoutesAdjacency => {
+  const protoRoutesAdjacency: ProtoRoutesAdjacency = {
+    routes: {},
+  };
+
+  routesAdjacency.forEach((value: Route, key: string) => {
+    protoRoutesAdjacency.routes[key] = {
+      stopTimes: value.stopTimes.map((stopTimes) => ({
+        arrival: stopTimes.arrival.toSeconds(),
+        departure: stopTimes.departure.toSeconds(),
+        pickUpType: serializePickUpDropOffType(stopTimes.pickUpType),
+        dropOffType: serializePickUpDropOffType(stopTimes.dropOffType),
+      })),
+      stops: value.stops,
+      serviceRouteId: value.serviceRouteId,
+    };
+  });
+
+  return protoRoutesAdjacency;
+};
+
+export const serializeServiceRoutesMap = (
+  serviceRoutesMap: ServiceRoutesMap,
+): ProtoServiceRoutesMap => {
+  const protoServiceRoutesMap: ProtoServiceRoutesMap = {
+    routes: {},
+  };
+
+  serviceRoutesMap.forEach(
+    (value: { type: RouteType; name: string }, key: string) => {
+      protoServiceRoutesMap.routes[key] = {
+        type: serializeRouteType(value.type),
+        name: value.name,
+      };
+    },
+  );
+
+  return protoServiceRoutesMap;
+};
+
+export const deserializeStopsAdjacency = (
+  protoStopsAdjacency: ProtoStopsAdjacency,
+): StopsAdjacency => {
+  const stopsAdjacency: StopsAdjacency = new Map();
+
+  Object.entries(protoStopsAdjacency.stops).forEach(([key, value]) => {
+    stopsAdjacency.set(key, {
+      transfers: value.transfers.map(
+        (transfer: ProtoTransfer): Transfer => ({
+          destination: transfer.destination,
+          type: parseTransferType(transfer.type),
+          ...(transfer.minTransferTime !== undefined && {
+            minTransferTime: Duration.fromSeconds(transfer.minTransferTime),
+          }),
+        }),
+      ),
+      routes: value.routes,
+    });
+  });
+
+  return stopsAdjacency;
+};
+
+export const deserializeRoutesAdjacency = (
+  protoRoutesAdjacency: ProtoRoutesAdjacency,
+): RoutesAdjacency => {
+  const routesAdjacency: RoutesAdjacency = new Map();
+
+  Object.entries(protoRoutesAdjacency.routes).forEach(([key, value]) => {
+    routesAdjacency.set(key, {
+      stopTimes: value.stopTimes.map((stopTimes) => ({
+        arrival: Time.fromSeconds(stopTimes.arrival),
+        departure: Time.fromSeconds(stopTimes.departure),
+        pickUpType:
+          stopTimes.pickUpType !== undefined
+            ? parsePickUpDropOffType(stopTimes.pickUpType)
+            : 'REGULAR',
+        dropOffType:
+          stopTimes.dropOffType !== undefined
+            ? parsePickUpDropOffType(stopTimes.dropOffType)
+            : 'REGULAR',
+      })),
+      stops: value.stops,
+      stopIndices: new Map(value.stops.map((stop, index) => [stop, index])),
+      serviceRouteId: value.serviceRouteId,
+    });
+  });
+
+  return routesAdjacency;
+};
+
+export const deserializeServiceRoutesMap = (
+  protoServiceRoutesMap: ProtoServiceRoutesMap,
+): ServiceRoutesMap => {
+  const serviceRoutesMap: ServiceRoutesMap = new Map();
+
+  Object.entries(protoServiceRoutesMap.routes).forEach(([key, value]) => {
+    serviceRoutesMap.set(key, {
+      type: parseRouteType(value.type),
+      name: value.name,
+    });
+  });
+
+  return serviceRoutesMap;
+};
+
+const parseTransferType = (type: ProtoTransferType): TransferType => {
+  switch (type) {
+    case ProtoTransferType.RECOMMENDED_TRANSFER_POINT:
+      return 'RECOMMENDED';
+    case ProtoTransferType.TIMED_TRANSFER:
+      return 'GUARANTEED';
+    case ProtoTransferType.REQUIRES_MINIMAL_TIME:
+      return 'REQUIRES_MINIMAL_TIME';
+    case ProtoTransferType.IN_SEAT_TRANSFER:
+      return 'IN_SEAT';
+    case ProtoTransferType.UNRECOGNIZED:
+      throw new Error('Unrecognized protobuf transfer type.');
+  }
+};
+
+const serializeTransferType = (type: TransferType): ProtoTransferType => {
+  switch (type) {
+    case 'RECOMMENDED':
+      return ProtoTransferType.RECOMMENDED_TRANSFER_POINT;
+    case 'GUARANTEED':
+      return ProtoTransferType.TIMED_TRANSFER;
+    case 'REQUIRES_MINIMAL_TIME':
+      return ProtoTransferType.REQUIRES_MINIMAL_TIME;
+    case 'IN_SEAT':
+      return ProtoTransferType.IN_SEAT_TRANSFER;
+  }
+};
+
+const parseRouteType = (type: ProtoRouteType): RouteType => {
+  switch (type) {
+    case ProtoRouteType.TRAM:
+      return 'TRAM';
+    case ProtoRouteType.SUBWAY:
+      return 'SUBWAY';
+    case ProtoRouteType.RAIL:
+      return 'RAIL';
+    case ProtoRouteType.BUS:
+      return 'BUS';
+    case ProtoRouteType.FERRY:
+      return 'FERRY';
+    case ProtoRouteType.CABLE_TRAM:
+      return 'CABLE_TRAM';
+    case ProtoRouteType.AERIAL_LIFT:
+      return 'AERIAL_LIFT';
+    case ProtoRouteType.FUNICULAR:
+      return 'FUNICULAR';
+    case ProtoRouteType.TROLLEYBUS:
+      return 'TROLLEYBUS';
+    case ProtoRouteType.MONORAIL:
+      return 'MONORAIL';
+    case ProtoRouteType.UNRECOGNIZED:
+    default:
+      throw new Error('Unrecognized protobuf route type.');
+  }
+};
+
+const serializeRouteType = (type: RouteType): ProtoRouteType => {
+  switch (type) {
+    case 'TRAM':
+      return ProtoRouteType.TRAM;
+    case 'SUBWAY':
+      return ProtoRouteType.SUBWAY;
+    case 'RAIL':
+      return ProtoRouteType.RAIL;
+    case 'BUS':
+      return ProtoRouteType.BUS;
+    case 'FERRY':
+      return ProtoRouteType.FERRY;
+    case 'CABLE_TRAM':
+      return ProtoRouteType.CABLE_TRAM;
+    case 'AERIAL_LIFT':
+      return ProtoRouteType.AERIAL_LIFT;
+    case 'FUNICULAR':
+      return ProtoRouteType.FUNICULAR;
+    case 'TROLLEYBUS':
+      return ProtoRouteType.TROLLEYBUS;
+    case 'MONORAIL':
+      return ProtoRouteType.MONORAIL;
+  }
+};
+
+const parsePickUpDropOffType = (
+  type: ProtoPickUpDropOffType,
+): PickUpDropOffType => {
+  switch (type) {
+    case ProtoPickUpDropOffType.MUST_PHONE_AGENCY:
+      return 'MUST_PHONE_AGENCY';
+    case ProtoPickUpDropOffType.MUST_COORDINATE_WITH_DRIVER:
+      return 'MUST_COORDINATE_WITH_DRIVER';
+    case ProtoPickUpDropOffType.NOT_AVAILABLE:
+      return 'NOT_AVAILABLE';
+    default:
+      return 'REGULAR';
+  }
+};
+
+const serializePickUpDropOffType = (
+  type: PickUpDropOffType,
+): ProtoPickUpDropOffType | undefined => {
+  switch (type) {
+    case 'REGULAR':
+      return undefined;
+    case 'NOT_AVAILABLE':
+      return ProtoPickUpDropOffType.NOT_AVAILABLE;
+    case 'MUST_COORDINATE_WITH_DRIVER':
+      return ProtoPickUpDropOffType.MUST_COORDINATE_WITH_DRIVER;
+    case 'MUST_PHONE_AGENCY':
+      return ProtoPickUpDropOffType.MUST_PHONE_AGENCY;
+  }
+};