minotor 1.0.0

package/src/gtfs/profiles/ch.ts

@@ -0,0 +1,70 @@
+import { Platform } from '../../stops/stops.js';
+import { RouteType } from '../../timetable/timetable.js';
+import { GtfsProfile } from '../parser.js';
+import { StopEntry } from '../stops.js';
+import { Maybe } from '../utils.js';
+
+/**
+ * Parses the platform number from a stop entry.
+ * @param stopEntry The stop entry.
+ * @returns The platform corresponding to this stop.
+ */
+const platformParser = (stopEntry: StopEntry): Maybe<Platform> => {
+  const stopId = String(stopEntry.stop_id);
+  const stopParts = stopId.split(':');
+  if (stopParts.length > 2) {
+    return stopParts[2];
+  }
+  return undefined;
+};
+
+/**
+ * Parses the SBB extended route type and returns the corresponding basic GTFS route type.
+ * @param routeType The SBB route type to parse.
+ * @returns The corresponding GTFS route type, or undefined if the route type is not recognized.
+ */
+const routeTypeParser = (routeType: number): Maybe<RouteType> => {
+  switch (routeType) {
+    case 1700: // Lift
+    case 1400: // Cogwheel train, funicular
+      return 'FUNICULAR'; // Funicular
+    case 700: // Bus
+    case 705: // Night bus
+    case 710: // Panorama bus
+    case 202: // National long-distance bus
+    case 201: // International long-distance bus
+    case 702: // Express bus
+    case 715: // On-demand bus
+      return 'BUS'; // Bus
+    case 1300: // Chairlift, Gondola
+      return 'AERIAL_LIFT'; // Aerial lift
+    case 401: // Metro
+      return 'SUBWAY'; // Subway
+    case 1000: // Boat / Ship
+      return 'FERRY'; // Boat
+    case 900: // Tram
+      return 'TRAM'; // Tram
+    case 117: // Special train
+    case 102: // International train
+    case 104: // Car train
+    case 101: // International train
+    case 111: // Airport train
+    case 105: // Night train
+    case 103: // Fast train
+    case 107: // Mountain train
+    case 100: // No guaranteed train
+    case 106: // Regional train
+    case 109: // Urban train
+    case 116: // ??? train TODO figure out what this means
+      return 'RAIL'; // Train
+    case 1100: // Aircraft
+    case 1500: // Taxi
+    default:
+      return undefined;
+  }
+};
+
+export const chGtfsProfile: GtfsProfile = {
+  routeTypeParser,
+  platformParser,
+};

package/src/gtfs/profiles/standard.ts

@@ -0,0 +1,39 @@
+import { Platform } from '../../stops/stops.js';
+import { GtfsProfile } from '../parser.js';
+import { StopEntry } from '../stops.js';
+import { Maybe } from '../utils.js';
+
+export const standardProfile: GtfsProfile = {
+  routeTypeParser: (routeType: number) => {
+    switch (routeType) {
+      case 0:
+        return 'TRAM';
+      case 1:
+        return 'SUBWAY';
+      case 2:
+        return 'RAIL';
+      case 3:
+        return 'BUS';
+      case 4:
+        return 'FERRY';
+      case 5:
+        return 'CABLE_TRAM';
+      case 6:
+        return 'AERIAL_LIFT';
+      case 7:
+        return 'FUNICULAR';
+      case 11:
+        return 'TROLLEYBUS';
+      case 12:
+        return 'MONORAIL';
+      default:
+        return undefined;
+    }
+  },
+  platformParser: (stopEntry: StopEntry): Maybe<Platform> => {
+    if (stopEntry.platform_code) {
+      return stopEntry.platform_code;
+    }
+    return undefined;
+  },
+};

package/src/gtfs/routes.ts

@@ -0,0 +1,48 @@
+import log from 'loglevel';
+
+import { RouteId, ServiceRoutesMap } from '../timetable/timetable.js';
+import { GtfsProfile } from './parser.js';
+import { standardProfile } from './profiles/standard.js';
+import { parseCsv } from './utils.js';
+
+// Can be a standard gtfs route type or an extended route type
+// the profile converter handles the conversion to a route type.
+export type GtfsRouteType = number;
+
+type RouteEntry = {
+  route_id: RouteId;
+  agency_id: string;
+  route_short_name: string;
+  route_long_name: string;
+  route_desc: string;
+  route_type: number;
+};
+
+/**
+ * Parses a GTFS routes.txt file and returns a map of all the valid routes.
+ *
+ * @param routesStream A readable stream for the GTFS routes.txt file.
+ * @param profile A configuration object defining the specificities of the GTFS feed.
+ * @returns A map of all the valid routes.
+ */
+export const parseRoutes = async (
+  routesStream: NodeJS.ReadableStream,
+  profile: GtfsProfile = standardProfile,
+): Promise<ServiceRoutesMap> => {
+  const routes: ServiceRoutesMap = new Map();
+  for await (const rawLine of parseCsv(routesStream)) {
+    const line = rawLine as RouteEntry;
+    const routeType = profile.routeTypeParser(line.route_type);
+    if (routeType === undefined) {
+      log.info(
+        `Unsupported route type ${line.route_type} for route ${line.route_id}.`,
+      );
+      continue;
+    }
+    routes.set(line.route_id, {
+      name: line.route_short_name + '',
+      type: routeType,
+    });
+  }
+  return routes;
+};

package/src/gtfs/services.ts

@@ -0,0 +1,98 @@
+import { DateTime } from 'luxon';
+
+import { toGtfsDate } from './time.js';
+import { parseCsv } from './utils.js';
+
+export type ServiceId = string;
+export type ServiceIds = Set<ServiceId>;
+
+type Weekday = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+type ActiveFlag = 0 | 1;
+type RawGtfsDate = number;
+type ExceptionType = 1 | 2;
+
+type CalendarEntry = {
+  service_id: string;
+  monday: ActiveFlag;
+  tuesday: ActiveFlag;
+  wednesday: ActiveFlag;
+  thursday: ActiveFlag;
+  friday: ActiveFlag;
+  saturday: ActiveFlag;
+  sunday: ActiveFlag;
+  start_date: RawGtfsDate;
+  end_date: RawGtfsDate;
+};
+
+type CalendarDatesEntry = {
+  service_id: ServiceId;
+  date: RawGtfsDate;
+  exception_type: ExceptionType;
+};
+
+const weekdays = {
+  1: 'monday',
+  2: 'tuesday',
+  3: 'wednesday',
+  4: 'thursday',
+  5: 'friday',
+  6: 'saturday',
+  7: 'sunday',
+};
+
+/**
+ * Parses a GTFS calendar.txt file and finds the service_ids of a given date.
+ *
+ * @param serviceIds A map of the active service ids (will be populated with active service_ids).
+ * @param date The active date.
+ * @param calendarStream A readable stream for the GTFS calendar.txt file.
+ */
+export const parseCalendar = async (
+  calendarStream: NodeJS.ReadableStream,
+  serviceIds: ServiceIds,
+  date: DateTime,
+) => {
+  const activeDate: number = toGtfsDate(date);
+  const weekday = date.weekday as Weekday;
+  const weekdayIndex = weekdays[weekday] as keyof CalendarEntry;
+  for await (const rawLine of parseCsv(calendarStream)) {
+    const line = rawLine as CalendarEntry;
+    if (activeDate < line.start_date || activeDate > line.end_date) {
+      // If the service is not valid on this date
+      continue;
+    }
+    if (line[weekdayIndex] !== 1) {
+      // If the service is not valid on this week day
+      continue;
+    }
+    serviceIds.add(line['service_id']);
+  }
+};
+
+/**
+ * Parses a gtfs calendar_dates.txt file and finds the service ids valid at a given date.
+ *
+ * @param serviceIds A map of the active service ids (will be populated and filtered).
+ * @param date The active date, in the format "YYYYMMDD".
+ * @param calendarDatesStream A readable stream for the GTFS calendar_dates.txt file.
+ */
+export const parseCalendarDates = async (
+  calendarDatesStream: NodeJS.ReadableStream,
+  serviceIds: ServiceIds,
+  date: DateTime,
+) => {
+  const activeDate: number = toGtfsDate(date);
+  for await (const rawLine of parseCsv(calendarDatesStream)) {
+    const line = rawLine as CalendarDatesEntry;
+    if (line.date !== activeDate) {
+      // No rule on the active date
+    } else if (line.exception_type === 2 && serviceIds.has(line.service_id)) {
+      // Service has been removed for the specified date.
+
+      serviceIds.delete(line.service_id);
+    } else if (line.exception_type === 1) {
+      // Service is present on the active date
+      serviceIds.add(line.service_id);
+    }
+  }
+};

package/src/gtfs/stops.ts

@@ -0,0 +1,112 @@
+import {
+  Latitude,
+  LocationType,
+  Longitude,
+  Platform,
+  Stop,
+  StopId,
+  StopsMap,
+} from '../stops/stops.js';
+import { Maybe, parseCsv } from './utils.js';
+
+export type StopIds = Set<StopId>;
+
+export type GtfsLocationType =
+  | 0 // simple stop or platform (can also be empty)
+  | 1 // station
+  | 2 // entrance / exit
+  | 3 // generic node
+  | 4; // boarding area
+
+export type StopEntry = {
+  stop_id: StopId;
+  stop_name: string;
+  stop_lat?: Latitude;
+  stop_lon?: Longitude;
+  location_type?: GtfsLocationType;
+  parent_station?: StopId;
+  platform_code?: Platform;
+};
+
+/**
+ * Parses the stops.txt file from a GTFS feed.
+ *
+ * @param stopsStream The readable stream containing the stops data.
+ * @return A mapping of stop IDs to corresponding stop details.
+ */
+export const parseStops = async (
+  stopsStream: NodeJS.ReadableStream,
+  platformParser?: (stopEntry: StopEntry) => Maybe<Platform>,
+  validStops?: StopIds,
+): Promise<StopsMap> => {
+  const stops: StopsMap = new Map();
+
+  for await (const rawLine of parseCsv(stopsStream)) {
+    const line = rawLine as StopEntry;
+    const stop: Stop = {
+      id: line.stop_id,
+      name: line.stop_name,
+      lat: line.stop_lat,
+      lon: line.stop_lon,
+      locationType: line.location_type
+        ? parseGtfsLocationType(line.location_type)
+        : 'SIMPLE_STOP_OR_PLATFORM',
+      children: [],
+      ...(line.parent_station && { parent: line.parent_station }),
+    };
+    if (platformParser) {
+      try {
+        const platform = platformParser(line);
+        if (platform) {
+          stop.platform = platform;
+        }
+      } catch {
+        console.info(`Could not parse platform for stop ${line.stop_id}.`);
+      }
+    }
+    stops.set(line.stop_id, stop);
+  }
+
+  for (const [stopId, stop] of stops) {
+    if (stop.parent) {
+      const parentStop = stops.get(stop.parent);
+      if (!parentStop) {
+        console.warn(`Cannot find parent stop ${stop.parent} of ${stopId}`);
+        continue;
+      }
+      parentStop.children.push(stopId);
+    }
+  }
+  if (validStops) {
+    // Remove all stops which don't have at least one valid stopId as a child,
+    // a parent or as its own.
+    for (const [stopId, stop] of stops) {
+      if (
+        !validStops.has(stopId) &&
+        (!stop.parent || !validStops.has(stop.parent)) &&
+        !stop.children.some((childId) => validStops.has(childId))
+      ) {
+        stops.delete(stopId);
+      }
+    }
+  }
+  return stops;
+};
+
+const parseGtfsLocationType = (
+  gtfsLocationType: GtfsLocationType,
+): LocationType => {
+  switch (gtfsLocationType) {
+    case 0:
+    default:
+      return 'SIMPLE_STOP_OR_PLATFORM';
+    case 1:
+      return 'STATION';
+    case 2:
+      return 'ENTRANCE_EXIT';
+    case 3:
+      return 'GENERIC_NODE';
+    case 4:
+      return 'BOARDING_AREA';
+  }
+};

package/src/gtfs/time.ts

@@ -0,0 +1,33 @@
+import { DateTime } from 'luxon';
+
+import { Time } from '../timetable/time.js';
+
+export type GtfsDate = number;
+export type GtfsTime = string;
+
+export const toGtfsDate = (date: DateTime): GtfsDate => {
+  return parseInt(date.toFormat('yyyyLLdd'));
+};
+
+/**
+ * Converts a time string in the format 'HH:mm:ss' to a Time object
+ * (number of seconds since midnight).
+ *
+ * This method splits the input time string into hours, minutes, and seconds,
+ * and then calculates the total number of seconds.
+ *
+ * @param time - A string representing the time in 'HH:mm:ss' format.
+ * @returns The GTFS time as the number of seconds since midnight.
+ * @throws An error if the input time string is not in the correct format.
+ */
+export const toTime = (time: GtfsTime): Time => {
+  const splits = time.split(':');
+  if (!splits[0] || !splits[1] || !splits[2]) {
+    throw new Error(`Invalid time ${time}.`);
+  }
+  return Time.fromHMS(
+    parseInt(splits[0]),
+    parseInt(splits[1]),
+    parseInt(splits[2]),
+  );
+};

package/src/gtfs/transfers.ts

@@ -0,0 +1,102 @@
+import { StopId } from '../stops/stops.js';
+import { Duration } from '../timetable/duration.js';
+import {
+  ServiceRouteId,
+  Transfer,
+  TransferType,
+} from '../timetable/timetable.js';
+import { TripId } from './trips.js';
+import { parseCsv } from './utils.js';
+
+export type GtfsTransferType =
+  | 0 // recommended transfer point
+  | 1 // timed transfer (guaranteed)
+  | 2 // requires a minimal amount of time
+  | 3 // transfer not possible
+  | 4 // in-seat transfer
+  | 5; //  in-seat transfer not allowed (must alight)
+
+export type TransfersMap = Map<StopId, Transfer[]>;
+
+export type TransferEntry = {
+  from_stop_id?: StopId;
+  to_stop_id?: StopId;
+  from_trip_id?: TripId;
+  to_trip_id?: TripId;
+  from_route_id?: ServiceRouteId;
+  to_route_id?: ServiceRouteId;
+  transfer_type: GtfsTransferType;
+  min_transfer_time?: number;
+};
+
+/**
+ * Parses the transfers.txt file from a GTFS feed.
+ *
+ * @param stopsStream The readable stream containing the stops data.
+ * @return A mapping of stop IDs to corresponding stop details.
+ */
+export const parseTransfers = async (
+  transfersStream: NodeJS.ReadableStream,
+): Promise<TransfersMap> => {
+  const transfers: TransfersMap = new Map();
+
+  for await (const rawLine of parseCsv(transfersStream)) {
+    const transferEntry = rawLine as TransferEntry;
+    if (
+      transferEntry.transfer_type === 3 ||
+      transferEntry.transfer_type === 5
+    ) {
+      continue;
+    }
+    if (transferEntry.from_trip_id && transferEntry.to_trip_id) {
+      console.warn(
+        `Unsupported transfer between trips ${transferEntry.from_trip_id} and ${transferEntry.to_trip_id}.`,
+      );
+      continue;
+    }
+    if (transferEntry.from_route_id && transferEntry.to_route_id) {
+      console.warn(
+        `Unsupported transfer between routes ${transferEntry.from_route_id} and ${transferEntry.to_route_id}.`,
+      );
+      continue;
+    }
+    if (!transferEntry.from_stop_id || !transferEntry.to_stop_id) {
+      console.warn(`Missing transfer origin or destination stop.`);
+      continue;
+    }
+    if (transferEntry.transfer_type === 2 && !transferEntry.min_transfer_time) {
+      console.info(
+        `Missing minimum transfer time between ${transferEntry.from_stop_id} and ${transferEntry.to_stop_id}.`,
+      );
+    }
+
+    const transfer: Transfer = {
+      destination: transferEntry.to_stop_id,
+      type: parseGtfsTransferType(transferEntry.transfer_type),
+      ...(transferEntry.min_transfer_time && {
+        minTransferTime: Duration.fromSeconds(transferEntry.min_transfer_time),
+      }),
+    };
+
+    const fromStopTransfers = transfers.get(transferEntry.from_stop_id) || [];
+    fromStopTransfers.push(transfer);
+    transfers.set(transferEntry.from_stop_id, fromStopTransfers);
+  }
+  return transfers;
+};
+
+const parseGtfsTransferType = (
+  gtfsTransferType: GtfsTransferType,
+): TransferType => {
+  switch (gtfsTransferType) {
+    case 0:
+    default:
+      return 'RECOMMENDED';
+    case 1:
+      return 'GUARANTEED';
+    case 2:
+      return 'REQUIRES_MINIMAL_TIME';
+    case 4:
+      return 'IN_SEAT';
+  }
+};