project-inter-server/src/repositories/shuttle/ShuttleGetterRepository.ts

import { IEta, IOrderedStop, IRoute, IShuttle, IStop } from "../../entities/ShuttleRepositoryEntities";
import type EventEmitter from "node:events";

export const ShuttleRepositoryEvent = {
  ETA_UPDATED: "etaUpdated",
  ETA_REMOVED: "etaRemoved",
  ETA_DATA_CLEARED: "etaDataCleared",
} as const;

export type ShuttleRepositoryEventName = typeof ShuttleRepositoryEvent[keyof typeof ShuttleRepositoryEvent];

export type EtaRemovedEventPayload = IEta;
export type EtaDataClearedEventPayload = IEta[];

export interface ShuttleRepositoryEventPayloads {
  [ShuttleRepositoryEvent.ETA_UPDATED]: IEta;
  [ShuttleRepositoryEvent.ETA_REMOVED]: EtaRemovedEventPayload;
  [ShuttleRepositoryEvent.ETA_DATA_CLEARED]: EtaDataClearedEventPayload;
}

export type ShuttleRepositoryEventListener<T extends ShuttleRepositoryEventName> = (
  payload: ShuttleRepositoryEventPayloads[T],
) => void;

export interface ShuttleStopArrival {
  stopId: string;
  timestamp: Date;
}

export interface ShuttleTravelTimeDataIdentifier {
  routeId: string;
  fromStopId: string;
  toStopId: string;
}

export interface ShuttleTravelTimeDateFilterArguments {
  from: Date;
  to: Date;
}

/**
 * Shuttle getter repository to be linked to a system.
 */
export interface ShuttleGetterRepository extends EventEmitter {
  getStops(): Promise<IStop[]>;
  getStopById(stopId: string): Promise<IStop | null>;

  getRoutes(): Promise<IRoute[]>;
  getRouteById(routeId: string): Promise<IRoute | null>;

  getShuttles(): Promise<IShuttle[]>;
  getShuttleById(shuttleId: string): Promise<IShuttle | null>;
  getShuttlesByRouteId(routeId: string): Promise<IShuttle[]>;

  getEtasForShuttleId(shuttleId: string): Promise<IEta[]>;
  getEtasForStopId(stopId: string): Promise<IEta[]>;
  getEtaForShuttleAndStopId(shuttleId: string, stopId: string): Promise<IEta | null>;

  on<T extends ShuttleRepositoryEventName>(event: T, listener: ShuttleRepositoryEventListener<T>): this;
  once<T extends ShuttleRepositoryEventName>(event: T, listener: ShuttleRepositoryEventListener<T>): this;
  off<T extends ShuttleRepositoryEventName>(event: T, listener: ShuttleRepositoryEventListener<T>): this;
  addListener<T extends ShuttleRepositoryEventName>(event: T, listener: ShuttleRepositoryEventListener<T>): this;
  removeListener<T extends ShuttleRepositoryEventName>(event: T, listener: ShuttleRepositoryEventListener<T>): this;

  getOrderedStopByRouteAndStopId(routeId: string, stopId: string): Promise<IOrderedStop | null>;

  /**
   * Get ordered stops with the given stop ID.
   * Returns an empty array if no ordered stops found.
   * @param stopId
   */
  getOrderedStopsByStopId(stopId: string): Promise<IOrderedStop[]>;

  /**
   * Get ordered stops with the given route ID.
   * Returns an empty array if no ordered stops found.
   * @param routeId
   */
  getOrderedStopsByRouteId(routeId: string): Promise<IOrderedStop[]>;

  /**
   * Get the last stop arrival for a shuttle.
   * Returns undefined if no last stop arrival has been recorded.
   * @param shuttleId
   */
  getShuttleLastStopArrival(shuttleId: string): Promise<ShuttleStopArrival | undefined>;

  /**
   * Check if a shuttle has arrived at a stop within the given delta.
   * Returns the stop if the shuttle is at a stop, otherwise undefined.
   * @param shuttle
   * @param delta - The coordinate delta tolerance (default 0.001)
   */
  getArrivedStopIfExists(shuttle: IShuttle, delta?: number): Promise<IStop | undefined>;
}