minotor 3.0.0 → 3.0.2

package/src/timetable/io.ts

@@ -7,16 +7,24 @@ import {
   Transfer as ProtoTransfer,
   TransferType as ProtoTransferType,
 } from './proto/timetable.js';
+import { Route } from './route.js';
 import {
-  Route,
   RoutesAdjacency,
   RouteType,
+  ServiceRouteId,
   ServiceRoutesMap,
   StopsAdjacency,
   Transfer,
   TransferType,
 } from './timetable.js';
 
+export type SerializedRoute = {
+  stopTimes: Uint16Array;
+  pickUpDropOffTypes: Uint8Array;
+  stops: Uint32Array;
+  serviceRouteId: ServiceRouteId;
+};
+
 const isLittleEndian = (() => {
   const buffer = new ArrayBuffer(4);
   const view = new DataView(buffer);
@@ -26,7 +34,7 @@ const isLittleEndian = (() => {
 
 const STANDARD_ENDIANNESS = true; // true = little-endian
 
-function uint32ArrayToBytes(array: Uint32Array): Uint8Array {
+const uint32ArrayToBytes = (array: Uint32Array): Uint8Array => {
   if (isLittleEndian === STANDARD_ENDIANNESS) {
     return new Uint8Array(array.buffer, array.byteOffset, array.byteLength);
   }
@@ -41,9 +49,9 @@ function uint32ArrayToBytes(array: Uint32Array): Uint8Array {
   }
 
   return result;
-}
+};
 
-function bytesToUint32Array(bytes: Uint8Array): Uint32Array {
+const bytesToUint32Array = (bytes: Uint8Array): Uint32Array => {
   if (bytes.byteLength % 4 !== 0) {
     throw new Error(
       'Byte array length must be a multiple of 4 to convert to Uint32Array',
@@ -68,9 +76,9 @@ function bytesToUint32Array(bytes: Uint8Array): Uint32Array {
   }
 
   return result;
-}
+};
 
-function uint16ArrayToBytes(array: Uint16Array): Uint8Array {
+const uint16ArrayToBytes = (array: Uint16Array): Uint8Array => {
   if (isLittleEndian === STANDARD_ENDIANNESS) {
     return new Uint8Array(array.buffer, array.byteOffset, array.byteLength);
   }
@@ -85,9 +93,9 @@ function uint16ArrayToBytes(array: Uint16Array): Uint8Array {
   }
 
   return result;
-}
+};
 
-function bytesToUint16Array(bytes: Uint8Array): Uint16Array {
+const bytesToUint16Array = (bytes: Uint8Array): Uint16Array => {
   if (bytes.byteLength % 2 !== 0) {
     throw new Error(
       'Byte array length must be a multiple of 2 to convert to Uint16Array',
@@ -112,7 +120,7 @@ function bytesToUint16Array(bytes: Uint8Array): Uint16Array {
   }
 
   return result;
-}
+};
 
 export const serializeStopsAdjacency = (
   stopsAdjacency: StopsAdjacency,
@@ -146,12 +154,13 @@ export const serializeRoutesAdjacency = (
     routes: {},
   };
 
-  routesAdjacency.forEach((value: Route, key: string) => {
+  routesAdjacency.forEach((route: Route, key: string) => {
+    const routeData = route.serialize();
     protoRoutesAdjacency.routes[key] = {
-      stopTimes: uint16ArrayToBytes(value.stopTimes),
-      pickUpDropOffTypes: value.pickUpDropOffTypes,
-      stops: uint32ArrayToBytes(value.stops),
-      serviceRouteId: value.serviceRouteId,
+      stopTimes: uint16ArrayToBytes(routeData.stopTimes),
+      pickUpDropOffTypes: routeData.pickUpDropOffTypes,
+      stops: uint32ArrayToBytes(routeData.stops),
+      serviceRouteId: routeData.serviceRouteId,
     };
   });
 
@@ -208,18 +217,15 @@ export const deserializeRoutesAdjacency = (
 
   Object.entries(protoRoutesAdjacency.routes).forEach(([key, value]) => {
     const stops = bytesToUint32Array(value.stops);
-    const indices = new Map<number, number>();
-    for (let i = 0; i < stops.length; i++) {
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      indices.set(stops[i]!, i);
-    }
-    routesAdjacency.set(key, {
-      stopTimes: bytesToUint16Array(value.stopTimes),
-      pickUpDropOffTypes: value.pickUpDropOffTypes,
-      stops: stops,
-      stopIndices: indices,
-      serviceRouteId: value.serviceRouteId,
-    });
+    routesAdjacency.set(
+      key,
+      new Route(
+        bytesToUint16Array(value.stopTimes),
+        value.pickUpDropOffTypes,
+        stops,
+        value.serviceRouteId,
+      ),
+    );
   });
 
   return routesAdjacency;

package/src/timetable/proto/timetable.proto

@@ -4,7 +4,7 @@ package minotor.timetable;
 
 message Route {
   /**
-   * Arrivals and departures encoded as a 32 bit uint array.
+   * Arrivals and departures encoded as a 16 bit uint array.
    * Format: [arrival1, departure1, arrival2, departure2, etc.]
    */
   bytes stopTimes = 1;

package/src/timetable/proto/timetable.ts

@@ -1,6 +1,6 @@
 // Code generated by protoc-gen-ts_proto. DO NOT EDIT.
 // versions:
-//   protoc-gen-ts_proto  v2.6.1
+//   protoc-gen-ts_proto  v2.7.7
 //   protoc               v4.23.4
 // source: src/timetable/proto/timetable.proto
 
@@ -137,7 +137,7 @@ export function routeTypeToJSON(object: RouteType): string {
 
 export interface Route {
   /**
-   * Arrivals and departures encoded as a 32 bit uint array.
+   * Arrivals and departures encoded as a 16 bit uint array.
    * Format: [arrival1, departure1, arrival2, departure2, etc.]
    */
   stopTimes: Uint8Array;
@@ -237,7 +237,7 @@ export const Route: MessageFns<Route> = {
 
   decode(input: BinaryReader | Uint8Array, length?: number): Route {
     const reader = input instanceof BinaryReader ? input : new BinaryReader(input);
-    let end = length === undefined ? reader.len : reader.pos + length;
+    const end = length === undefined ? reader.len : reader.pos + length;
     const message = createBaseRoute();
     while (reader.pos < end) {
       const tag = reader.uint32();
@@ -338,7 +338,7 @@ export const RoutesAdjacency: MessageFns<RoutesAdjacency> = {
 
   decode(input: BinaryReader | Uint8Array, length?: number): RoutesAdjacency {
     const reader = input instanceof BinaryReader ? input : new BinaryReader(input);
-    let end = length === undefined ? reader.len : reader.pos + length;
+    const end = length === undefined ? reader.len : reader.pos + length;
     const message = createBaseRoutesAdjacency();
     while (reader.pos < end) {
       const tag = reader.uint32();
@@ -420,7 +420,7 @@ export const RoutesAdjacency_RoutesEntry: MessageFns<RoutesAdjacency_RoutesEntry
 
   decode(input: BinaryReader | Uint8Array, length?: number): RoutesAdjacency_RoutesEntry {
     const reader = input instanceof BinaryReader ? input : new BinaryReader(input);
-    let end = length === undefined ? reader.len : reader.pos + length;
+    const end = length === undefined ? reader.len : reader.pos + length;
     const message = createBaseRoutesAdjacency_RoutesEntry();
     while (reader.pos < end) {
       const tag = reader.uint32();
@@ -499,7 +499,7 @@ export const Transfer: MessageFns<Transfer> = {
 
   decode(input: BinaryReader | Uint8Array, length?: number): Transfer {
     const reader = input instanceof BinaryReader ? input : new BinaryReader(input);
-    let end = length === undefined ? reader.len : reader.pos + length;
+    const end = length === undefined ? reader.len : reader.pos + length;
     const message = createBaseTransfer();
     while (reader.pos < end) {
       const tag = reader.uint32();
@@ -585,7 +585,7 @@ export const StopsAdjacency: MessageFns<StopsAdjacency> = {
 
   decode(input: BinaryReader | Uint8Array, length?: number): StopsAdjacency {
     const reader = input instanceof BinaryReader ? input : new BinaryReader(input);
-    let end = length === undefined ? reader.len : reader.pos + length;
+    const end = length === undefined ? reader.len : reader.pos + length;
     const message = createBaseStopsAdjacency();
     while (reader.pos < end) {
       const tag = reader.uint32();
@@ -670,7 +670,7 @@ export const StopsAdjacency_StopAdjacency: MessageFns<StopsAdjacency_StopAdjacen
 
   decode(input: BinaryReader | Uint8Array, length?: number): StopsAdjacency_StopAdjacency {
     const reader = input instanceof BinaryReader ? input : new BinaryReader(input);
-    let end = length === undefined ? reader.len : reader.pos + length;
+    const end = length === undefined ? reader.len : reader.pos + length;
     const message = createBaseStopsAdjacency_StopAdjacency();
     while (reader.pos < end) {
       const tag = reader.uint32();
@@ -748,7 +748,7 @@ export const StopsAdjacency_StopsEntry: MessageFns<StopsAdjacency_StopsEntry> =
 
   decode(input: BinaryReader | Uint8Array, length?: number): StopsAdjacency_StopsEntry {
     const reader = input instanceof BinaryReader ? input : new BinaryReader(input);
-    let end = length === undefined ? reader.len : reader.pos + length;
+    const end = length === undefined ? reader.len : reader.pos + length;
     const message = createBaseStopsAdjacency_StopsEntry();
     while (reader.pos < end) {
       const tag = reader.uint32();
@@ -826,7 +826,7 @@ export const ServiceRoute: MessageFns<ServiceRoute> = {
 
   decode(input: BinaryReader | Uint8Array, length?: number): ServiceRoute {
     const reader = input instanceof BinaryReader ? input : new BinaryReader(input);
-    let end = length === undefined ? reader.len : reader.pos + length;
+    const end = length === undefined ? reader.len : reader.pos + length;
     const message = createBaseServiceRoute();
     while (reader.pos < end) {
       const tag = reader.uint32();
@@ -899,7 +899,7 @@ export const ServiceRoutesMap: MessageFns<ServiceRoutesMap> = {
 
   decode(input: BinaryReader | Uint8Array, length?: number): ServiceRoutesMap {
     const reader = input instanceof BinaryReader ? input : new BinaryReader(input);
-    let end = length === undefined ? reader.len : reader.pos + length;
+    const end = length === undefined ? reader.len : reader.pos + length;
     const message = createBaseServiceRoutesMap();
     while (reader.pos < end) {
       const tag = reader.uint32();
@@ -984,7 +984,7 @@ export const ServiceRoutesMap_RoutesEntry: MessageFns<ServiceRoutesMap_RoutesEnt
 
   decode(input: BinaryReader | Uint8Array, length?: number): ServiceRoutesMap_RoutesEntry {
     const reader = input instanceof BinaryReader ? input : new BinaryReader(input);
-    let end = length === undefined ? reader.len : reader.pos + length;
+    const end = length === undefined ? reader.len : reader.pos + length;
     const message = createBaseServiceRoutesMap_RoutesEntry();
     while (reader.pos < end) {
       const tag = reader.uint32();
@@ -1068,7 +1068,7 @@ export const Timetable: MessageFns<Timetable> = {
 
   decode(input: BinaryReader | Uint8Array, length?: number): Timetable {
     const reader = input instanceof BinaryReader ? input : new BinaryReader(input);
-    let end = length === undefined ? reader.len : reader.pos + length;
+    const end = length === undefined ? reader.len : reader.pos + length;
     const message = createBaseTimetable();
     while (reader.pos < end) {
       const tag = reader.uint32();

package/src/timetable/route.ts

@@ -0,0 +1,347 @@
+import { StopId } from '../stops/stops.js';
+import { SerializedRoute } from './io.js';
+import { Time } from './time.js';
+import { ServiceRouteId } from './timetable.js';
+
+/**
+ * An internal identifier for routes.
+ * Not to mix with the ServiceRouteId which corresponds to the GTFS RouteId.
+ * This one is used for identifying groups of trips
+ * from a service route sharing the same list of stops.
+ */
+export type RouteId = string;
+
+/**
+ * Details about the pickup and drop-off modalities at each stop in each trip of a route.
+ */
+export type PickUpDropOffType =
+  | 'REGULAR'
+  | 'NOT_AVAILABLE'
+  | 'MUST_PHONE_AGENCY'
+  | 'MUST_COORDINATE_WITH_DRIVER';
+
+export const REGULAR = 0;
+export const NOT_AVAILABLE = 1;
+export const MUST_PHONE_AGENCY = 2;
+export const MUST_COORDINATE_WITH_DRIVER = 3;
+
+/*
+ * A trip index corresponds to the index of the
+ * first stop time in the trip divided by the number of stops
+ * in the given route
+ */
+export type TripIndex = number;
+
+const pickUpDropOffTypeMap: PickUpDropOffType[] = [
+  'REGULAR',
+  'NOT_AVAILABLE',
+  'MUST_PHONE_AGENCY',
+  'MUST_COORDINATE_WITH_DRIVER',
+];
+
+/**
+ * Converts a numerical representation of a pick-up/drop-off type
+ * into its corresponding string representation.
+ *
+ * @param numericalType - The numerical value representing the pick-up/drop-off type.
+ * @returns The corresponding PickUpDropOffType as a string.
+ * @throws An error if the numerical type is invalid.
+ */
+const toPickupDropOffType = (numericalType: number): PickUpDropOffType => {
+  const type = pickUpDropOffTypeMap[numericalType];
+  if (!type) {
+    throw new Error(`Invalid pickup/drop-off type ${numericalType}`);
+  }
+  return type;
+};
+
+/**
+ * A route identifies all trips of a given service route sharing the same list of stops.
+ */
+export class Route {
+  /**
+   * Arrivals and departures encoded as minutes from midnight.
+   * Format: [arrival1, departure1, arrival2, departure2, etc.]
+   */
+  private readonly stopTimes: Uint16Array;
+  /**
+   * PickUp and DropOff types represented as a binary Uint8Array.
+   * Values:
+   *   0: REGULAR
+   *   1: NOT_AVAILABLE
+   *   2: MUST_PHONE_AGENCY
+   *   3: MUST_COORDINATE_WITH_DRIVER
+   * Format: [pickupTypeStop1, dropOffTypeStop1, pickupTypeStop2, dropOffTypeStop2, etc.]
+   * TODO: Encode 4 values instead of 1 in 8 bits.
+   */
+  private readonly pickUpDropOffTypes: Uint8Array;
+  /**
+   * A binary array of stopIds in the route.
+   * [stop1, stop2, stop3,...]
+   */
+  private readonly stops: Uint32Array;
+  /**
+   * A reverse mapping of each stop with their index in the route:
+   * {
+   *   4: 0,
+   *   5: 1,
+   *   ...
+   * }
+   */
+  private readonly stopIndices: Map<StopId, number>;
+  /**
+   * The identifier of the route as a service shown to users.
+   */
+  private readonly serviceRouteId: ServiceRouteId;
+
+  /**
+   * The total number of stops in the route.
+   */
+  private readonly nbStops: number;
+
+  /**
+   * The total number of trips in the route.
+   */
+  private readonly nbTrips: number;
+
+  constructor(
+    stopTimes: Uint16Array,
+    pickUpDropOffTypes: Uint8Array,
+    stops: Uint32Array,
+    serviceRouteId: ServiceRouteId,
+  ) {
+    this.stopTimes = stopTimes;
+    this.pickUpDropOffTypes = pickUpDropOffTypes;
+    this.stops = stops;
+    this.serviceRouteId = serviceRouteId;
+    this.nbStops = stops.length;
+    this.nbTrips = this.stopTimes.length / (this.stops.length * 2);
+    this.stopIndices = new Map<number, number>();
+    for (let i = 0; i < stops.length; i++) {
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      this.stopIndices.set(stops[i]!, i);
+    }
+  }
+
+  /**
+   * Serializes the Route into binary arrays.
+   *
+   * @returns The serialized binary data.
+   */
+  serialize(): SerializedRoute {
+    return {
+      stopTimes: this.stopTimes,
+      pickUpDropOffTypes: this.pickUpDropOffTypes,
+      stops: this.stops,
+      serviceRouteId: this.serviceRouteId,
+    };
+  }
+
+  /**
+   * Checks if stop A is before stop B in the route.
+   *
+   * @param stopA - The StopId of the first stop.
+   * @param stopB - The StopId of the second stop.
+   * @returns True if stop A is before stop B, false otherwise.
+   */
+  isBefore(stopA: StopId, stopB: StopId): boolean {
+    const stopAIndex = this.stopIndices.get(stopA);
+    if (stopAIndex === undefined) {
+      throw new Error(
+        `Stop index ${stopAIndex} not found in route ${this.serviceRouteId}`,
+      );
+    }
+    const stopBIndex = this.stopIndices.get(stopB);
+    if (stopBIndex === undefined) {
+      throw new Error(
+        `Stop index ${stopBIndex} not found in route ${this.serviceRouteId}`,
+      );
+    }
+    return stopAIndex < stopBIndex;
+  }
+
+  /**
+   * Retrieves the number of stops in the route.
+   *
+   * @returns The total number of stops in the route.
+   */
+  getNbStops(): number {
+    return this.nbStops;
+  }
+
+  /**
+   * Finds the ServiceRouteId of the route. It corresponds the identifier
+   * of the service shown to the end user as a route.
+   *
+   * @returns The ServiceRouteId of the route.
+   */
+  serviceRoute(): ServiceRouteId {
+    return this.serviceRouteId;
+  }
+
+  /**
+   * Retrieves the arrival time at a specific stop for a given trip.
+   *
+   * @param stopId - The identifier of the stop.
+   * @param tripIndex - The index of the trip.
+   * @returns The arrival time at the specified stop and trip as a Time object.
+   */
+  arrivalAt(stopId: StopId, tripIndex: TripIndex): Time {
+    const arrivalIndex =
+      (tripIndex * this.stops.length + this.stopIndex(stopId)) * 2;
+    const arrival = this.stopTimes[arrivalIndex];
+    if (arrival === undefined) {
+      throw new Error(
+        `Arrival time not found for stop ${stopId} at trip index ${tripIndex} in route ${this.serviceRouteId}`,
+      );
+    }
+    return Time.fromMinutes(arrival);
+  }
+
+  /**
+   * Retrieves the departure time at a specific stop for a given trip.
+   *
+   * @param stopId - The identifier of the stop.
+   * @param tripIndex - The index of the trip.
+   * @returns The departure time at the specified stop and trip as a Time object.
+   */
+  departureFrom(stopId: StopId, tripIndex: TripIndex): Time {
+    const departureIndex =
+      (tripIndex * this.stops.length + this.stopIndex(stopId)) * 2 + 1;
+    const departure = this.stopTimes[departureIndex];
+    if (departure === undefined) {
+      throw new Error(
+        `Departure time not found for stop ${stopId} at trip index ${tripIndex} in route ${this.serviceRouteId}`,
+      );
+    }
+    return Time.fromMinutes(departure);
+  }
+
+  /**
+   * Retrieves the pick-up type for a specific stop and trip.
+   *
+   * @param stopId - The identifier of the stop.
+   * @param tripIndex - The index of the trip.
+   * @returns The pick-up type at the specified stop and trip.
+   */
+  pickUpTypeFrom(stopId: StopId, tripIndex: TripIndex): PickUpDropOffType {
+    const pickUpIndex =
+      (tripIndex * this.stops.length + this.stopIndex(stopId)) * 2;
+    const pickUpValue = this.pickUpDropOffTypes[pickUpIndex];
+    if (pickUpValue === undefined) {
+      throw new Error(
+        `Pick up type not found for stop ${stopId} at trip index ${tripIndex} in route ${this.serviceRouteId}`,
+      );
+    }
+    return toPickupDropOffType(pickUpValue);
+  }
+
+  /**
+   * Retrieves the drop-off type for a specific stop and trip.
+   *
+   * @param stopId - The identifier of the stop.
+   * @param tripIndex - The index of the trip.
+   * @returns The drop-off type at the specified stop and trip.
+   */
+  dropOffTypeAt(stopId: StopId, tripIndex: TripIndex): PickUpDropOffType {
+    const dropOffIndex =
+      (tripIndex * this.stops.length + this.stopIndex(stopId)) * 2 + 1;
+    const dropOffValue = this.pickUpDropOffTypes[dropOffIndex];
+    if (dropOffValue === undefined) {
+      throw new Error(
+        `Drop off type not found for stop ${stopId} at trip index ${tripIndex} in route ${this.serviceRouteId}`,
+      );
+    }
+    return toPickupDropOffType(dropOffValue);
+  }
+
+  /**
+   * Iterates over the stops in the route, starting from an optional specified stop.
+   * If no start stop is provided, the iteration begins from the first stop in the route.
+   *
+   * @param [startStopId] - (Optional) The StopId of the stop to start the iteration from.
+   * @returns An IterableIterator of StopIds, starting from the specified stop or the first stop.
+   * @throws An error if the specified start stop is not found in the route.
+   */
+  stopsIterator(startStopId?: StopId): IterableIterator<StopId> {
+    const startIndex =
+      startStopId !== undefined ? this.stopIndices.get(startStopId) : 0;
+    if (startIndex === undefined) {
+      throw new Error(
+        `Start stop ${startStopId} not found in route ${this.serviceRouteId}`,
+      );
+    }
+
+    function* generator(
+      stops: Uint32Array,
+      startIndex: number,
+    ): IterableIterator<StopId> {
+      for (let i = startIndex; i < stops.length; i++) {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        yield stops[i]!;
+      }
+    }
+
+    return generator(this.stops, startIndex);
+  }
+
+  /**
+   * 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.
+   * *
+   * @param stopId - The StopId of the stop where the trip should be found.
+   * @param [after=Time.origin()] - The earliest time after which the trip should depart.
+   *                                    If not provided, searches all available trips.
+   * @param [beforeTrip] - (Optional) The index of the trip before which the search should be constrained.
+   *                                   If not provided, searches all available trips.
+   * @returns The index of the earliest trip meeting the criteria, or undefined if no such trip is found.
+   */
+  findEarliestTrip(
+    stopId: StopId,
+    after: Time = Time.origin(),
+    beforeTrip?: TripIndex,
+  ): TripIndex | undefined {
+    const maxTripIndex =
+      beforeTrip !== undefined
+        ? Math.min(beforeTrip - 1, this.nbTrips - 1)
+        : this.nbTrips - 1;
+    if (maxTripIndex < 0) {
+      return undefined;
+    }
+    let earliestTripIndex: TripIndex | undefined;
+    let lowTrip = 0;
+    let highTrip = maxTripIndex;
+
+    while (lowTrip <= highTrip) {
+      const midTrip = Math.floor((lowTrip + highTrip) / 2);
+      const departure = this.departureFrom(stopId, midTrip);
+      const pickUpType = this.pickUpTypeFrom(stopId, midTrip);
+      if (
+        (departure.isAfter(after) || departure.equals(after)) &&
+        pickUpType !== 'NOT_AVAILABLE'
+      ) {
+        earliestTripIndex = midTrip;
+        highTrip = midTrip - 1;
+      } else {
+        lowTrip = midTrip + 1;
+      }
+    }
+    return earliestTripIndex;
+  }
+
+  /**
+   * Retrieves the index of a stop within the route.
+   * @param stopId The StopId of the stop to locate in the route.
+   * @returns The index of the stop in the route.
+   */
+  private stopIndex(stopId: StopId): number {
+    const stopIndex = this.stopIndices.get(stopId);
+    if (stopIndex === undefined) {
+      throw new Error(
+        `Stop index for ${stopId} not found in route ${this.serviceRouteId}`,
+      );
+    }
+    return stopIndex;
+  }
+}

package/src/timetable/time.ts

@@ -107,9 +107,12 @@ export class Time {
     if (
       hoursStr === undefined ||
       minutesStr === undefined ||
+      hoursStr.trim() === '' ||
+      minutesStr.trim() === '' ||
       isNaN(Number(hoursStr)) ||
       isNaN(Number(minutesStr)) ||
-      (secondsStr !== undefined && isNaN(Number(secondsStr)))
+      (secondsStr !== undefined &&
+        (secondsStr.trim() === '' || isNaN(Number(secondsStr))))
     ) {
       throw new Error(
         'Input string must be in the format "HH:MM:SS" or "HH:MM".',
@@ -127,8 +130,11 @@ export class Time {
    * @returns A string representing the time.
    */
   toString(): string {
-    const hours = Math.floor(this.minutesSinceMidnight / 60);
+    let hours = Math.floor(this.minutesSinceMidnight / 60);
     const minutes = Math.floor(this.minutesSinceMidnight % 60);
+    if (hours >= 24) {
+      hours = hours % 24;
+    }
     return `${hours.toString().padStart(2, '0')}:${minutes.toString().padStart(2, '0')}`;
   }
 
@@ -188,9 +194,7 @@ export class Time {
       throw new Error('At least one Time instance is required.');
     }
     return times.reduce((maxTime, currentTime) => {
-      return currentTime.toMinutes() > maxTime.toMinutes()
-        ? currentTime
-        : maxTime;
+      return currentTime.isAfter(maxTime) ? currentTime : maxTime;
     });
   }
 
@@ -205,9 +209,37 @@ export class Time {
       throw new Error('At least one Time instance is required.');
     }
     return times.reduce((minTime, currentTime) => {
-      return currentTime.toMinutes() < minTime.toMinutes()
-        ? currentTime
-        : minTime;
+      return currentTime.isBefore(minTime) ? currentTime : minTime;
     });
   }
+
+  /**
+   * Determines if the current Time instance is after another Time instance.
+   *
+   * @param otherTime - A Time instance to compare against.
+   * @returns True if the current Time instance is after the other Time instance, otherwise false.
+   */
+  isAfter(otherTime: Time): boolean {
+    return this.minutesSinceMidnight > otherTime.toMinutes();
+  }
+
+  /**
+   * Determines if the current Time instance is before another Time instance.
+   *
+   * @param otherTime - A Time instance to compare against.
+   * @returns True if the current Time instance is before the other Time instance, otherwise false.
+   */
+  isBefore(otherTime: Time): boolean {
+    return this.minutesSinceMidnight < otherTime.toMinutes();
+  }
+
+  /**
+   * Determines if the current Time instance is equal to another Time instance.
+   *
+   * @param otherTime - A Time instance to compare against.
+   * @returns True if the current Time instance is equal to the other Time instance, otherwise false.
+   */
+  equals(otherTime: Time): boolean {
+    return this.minutesSinceMidnight === otherTime.toMinutes();
+  }
 }