minotor 7.0.2 → 9.0.0

package/src/timetable/route.ts

@@ -26,11 +26,14 @@ 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
+ * A trip route index corresponds to the index of a given trip in a route.
  */
-export type TripIndex = number;
+export type TripRouteIndex = number;
+
+/*
+ * A stop route index corresponds to the index of a given stop in a route.
+ */
+export type StopRouteIndex = number;
 
 const pickUpDropOffTypeMap: PickUpDropOffType[] = [
   'REGULAR',
@@ -59,6 +62,7 @@ const toPickupDropOffType = (numericalType: number): PickUpDropOffType => {
  * A route identifies all trips of a given service route sharing the same list of stops.
  */
 export class Route {
+  public readonly id: RouteId;
   /**
    * Arrivals and departures encoded as minutes from midnight.
    * Format: [arrival1, departure1, arrival2, departure2, etc.]
@@ -90,7 +94,7 @@ export class Route {
    *   ...
    * }
    */
-  private readonly stopIndices: Map<StopId, number>;
+  private readonly stopIndices: Map<StopId, StopRouteIndex[]>;
   /**
    * The identifier of the route as a service shown to users.
    */
@@ -107,22 +111,131 @@ export class Route {
   private readonly nbTrips: number;
 
   constructor(
+    id: RouteId,
     stopTimes: Uint16Array,
     pickUpDropOffTypes: Uint8Array,
     stops: Uint32Array,
     serviceRouteId: ServiceRouteId,
   ) {
+    this.id = id;
     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>();
+    this.stopIndices = new Map<StopId, StopRouteIndex[]>();
     for (let i = 0; i < stops.length; i++) {
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      this.stopIndices.set(stops[i]!, i);
+      const stopId = stops[i]!;
+      const existingIndices = this.stopIndices.get(stopId);
+      if (existingIndices) {
+        existingIndices.push(i);
+      } else {
+        this.stopIndices.set(stopId, [i]);
+      }
+    }
+  }
+
+  /**
+   * Creates a new route from multiple trips with their stops.
+   *
+   * @param params The route parameters including ID, service route ID, and trips.
+   * @returns The new route.
+   */
+  static of(params: {
+    id: RouteId;
+    serviceRouteId: ServiceRouteId;
+    trips: Array<{
+      stops: Array<{
+        id: StopId;
+        arrivalTime: Time;
+        departureTime: Time;
+        dropOffType?: number;
+        pickUpType?: number;
+      }>;
+    }>;
+  }): Route {
+    const { id, serviceRouteId, trips } = params;
+
+    if (trips.length === 0) {
+      throw new Error('At least one trip must be provided');
+    }
+
+    // All trips must have the same stops in the same order
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const firstTrip = trips[0]!;
+    const stopIds = new Uint32Array(firstTrip.stops.map((stop) => stop.id));
+    const numStops = stopIds.length;
+
+    // Validate all trips have the same stops
+    for (let tripIndex = 1; tripIndex < trips.length; tripIndex++) {
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      const trip = trips[tripIndex]!;
+      if (trip.stops.length !== numStops) {
+        throw new Error(
+          `Trip ${tripIndex} has ${trip.stops.length} stops, expected ${numStops}`,
+        );
+      }
+      for (let stopIndex = 0; stopIndex < numStops; stopIndex++) {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        if (trip.stops[stopIndex]!.id !== stopIds[stopIndex]) {
+          throw new Error(
+            `Trip ${tripIndex} has different stop at index ${stopIndex}`,
+          );
+        }
+      }
+    }
+
+    // Create stopTimes array with arrivals and departures for all trips
+    const stopTimes = new Uint16Array(trips.length * numStops * 2);
+    for (let tripIndex = 0; tripIndex < trips.length; tripIndex++) {
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      const trip = trips[tripIndex]!;
+      for (let stopIndex = 0; stopIndex < numStops; stopIndex++) {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        const stop = trip.stops[stopIndex]!;
+        const baseIndex = (tripIndex * numStops + stopIndex) * 2;
+        stopTimes[baseIndex] = stop.arrivalTime.toMinutes();
+        stopTimes[baseIndex + 1] = stop.departureTime.toMinutes();
+      }
+    }
+
+    // Create pickUpDropOffTypes array (2-bit encoded) for all trips
+    const totalStopEntries = trips.length * numStops;
+    const pickUpDropOffTypes = new Uint8Array(Math.ceil(totalStopEntries / 2));
+
+    for (let tripIndex = 0; tripIndex < trips.length; tripIndex++) {
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      const trip = trips[tripIndex]!;
+      for (let stopIndex = 0; stopIndex < numStops; stopIndex++) {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        const stop = trip.stops[stopIndex]!;
+        const globalIndex = tripIndex * numStops + stopIndex;
+        const pickUp = stop.pickUpType ?? REGULAR;
+        const dropOff = stop.dropOffType ?? REGULAR;
+        const byteIndex = Math.floor(globalIndex / 2);
+        const isSecondPair = globalIndex % 2 === 1;
+
+        if (isSecondPair) {
+          // Second pair: pickup in upper 2 bits, dropOff in bits 4-5
+          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+          pickUpDropOffTypes[byteIndex]! |= (pickUp << 6) | (dropOff << 4);
+        } else {
+          // First pair: pickup in bits 2-3, dropOff in lower 2 bits
+          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+          pickUpDropOffTypes[byteIndex]! |= (pickUp << 2) | dropOff;
+        }
+      }
     }
+
+    return new Route(
+      id,
+      stopTimes,
+      pickUpDropOffTypes,
+      stopIds,
+      serviceRouteId,
+    );
   }
 
   /**
@@ -140,35 +253,21 @@ export class Route {
   }
 
   /**
-   * Checks if stop A is before stop B in the route.
+   * Retrieves the number of stops 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.
+   * @returns The total number of stops in the route.
    */
-  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;
+  getNbStops(): number {
+    return this.nbStops;
   }
 
   /**
-   * Retrieves the number of stops in the route.
+   * Retrieves the number of trips in the route.
    *
-   * @returns The total number of stops in the route.
+   * @returns The total number of trips in the route.
    */
-  getNbStops(): number {
-    return this.nbStops;
+  getNbTrips(): number {
+    return this.nbTrips;
   }
 
   /**
@@ -184,17 +283,16 @@ export class Route {
   /**
    * Retrieves the arrival time at a specific stop for a given trip.
    *
-   * @param stopId - The identifier of the stop.
+   * @param stopIndex - The index of the stop in the route.
    * @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;
+  arrivalAt(stopIndex: StopRouteIndex, tripIndex: TripRouteIndex): Time {
+    const arrivalIndex = (tripIndex * this.stops.length + stopIndex) * 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}`,
+        `Arrival time not found for stop ${this.stopId(stopIndex)} (${stopIndex}) at trip index ${tripIndex} in route ${this.serviceRouteId}`,
       );
     }
     return Time.fromMinutes(arrival);
@@ -203,17 +301,16 @@ export class Route {
   /**
    * Retrieves the departure time at a specific stop for a given trip.
    *
-   * @param stopId - The identifier of the stop.
+   * @param stopIndex - The index of the stop in the route.
    * @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;
+  departureFrom(stopIndex: StopRouteIndex, tripIndex: TripRouteIndex): Time {
+    const departureIndex = (tripIndex * this.stops.length + stopIndex) * 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}`,
+        `Departure time not found for stop ${this.stopId(stopIndex)} (${stopIndex}) at trip index ${tripIndex} in route ${this.serviceRouteId}`,
       );
     }
     return Time.fromMinutes(departure);
@@ -222,19 +319,22 @@ export class Route {
   /**
    * Retrieves the pick-up type for a specific stop and trip.
    *
-   * @param stopId - The identifier of the stop.
+   * @param stopIndex - The index of the stop in the route.
    * @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 globalIndex = tripIndex * this.stops.length + this.stopIndex(stopId);
+  pickUpTypeFrom(
+    stopIndex: StopRouteIndex,
+    tripIndex: TripRouteIndex,
+  ): PickUpDropOffType {
+    const globalIndex = tripIndex * this.stops.length + stopIndex;
     const byteIndex = Math.floor(globalIndex / 2);
     const isSecondPair = globalIndex % 2 === 1;
 
     const byte = this.pickUpDropOffTypes[byteIndex];
     if (byte === undefined) {
       throw new Error(
-        `Pick up type not found for stop ${stopId} at trip index ${tripIndex} in route ${this.serviceRouteId}`,
+        `Pick up type not found for stop ${this.stopId(stopIndex)} (${stopIndex}) at trip index ${tripIndex} in route ${this.serviceRouteId}`,
       );
     }
 
@@ -247,19 +347,22 @@ export class Route {
   /**
    * Retrieves the drop-off type for a specific stop and trip.
    *
-   * @param stopId - The identifier of the stop.
+   * @param stopIndex - The index of the stop in the route.
    * @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 globalIndex = tripIndex * this.stops.length + this.stopIndex(stopId);
+  dropOffTypeAt(
+    stopIndex: StopRouteIndex,
+    tripIndex: TripRouteIndex,
+  ): PickUpDropOffType {
+    const globalIndex = tripIndex * this.stops.length + stopIndex;
     const byteIndex = Math.floor(globalIndex / 2);
     const isSecondPair = globalIndex % 2 === 1;
 
     const byte = this.pickUpDropOffTypes[byteIndex];
     if (byte === undefined) {
       throw new Error(
-        `Drop off type not found for stop ${stopId} at trip index ${tripIndex} in route ${this.serviceRouteId}`,
+        `Drop off type not found for stop ${this.stopId(stopIndex)} (${stopIndex}) at trip index ${tripIndex} in route ${this.serviceRouteId}`,
       );
     }
 
@@ -274,7 +377,7 @@ export class 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 stopIndex - The route index 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.
@@ -282,10 +385,10 @@ export class Route {
    * @returns The index of the earliest trip meeting the criteria, or undefined if no such trip is found.
    */
   findEarliestTrip(
-    stopId: StopId,
+    stopIndex: StopRouteIndex,
     after: Time = Time.origin(),
-    beforeTrip?: TripIndex,
-  ): TripIndex | undefined {
+    beforeTrip?: TripRouteIndex,
+  ): TripRouteIndex | undefined {
     if (this.nbTrips <= 0) return undefined;
 
     let hi = this.nbTrips - 1;
@@ -296,7 +399,7 @@ export class Route {
     let lb = -1;
     while (lo <= hi) {
       const mid = (lo + hi) >>> 1;
-      const depMid = this.departureFrom(stopId, mid);
+      const depMid = this.departureFrom(stopIndex, mid);
       if (depMid.isBefore(after)) {
         lo = mid + 1;
       } else {
@@ -307,7 +410,7 @@ export class Route {
     if (lb === -1) return undefined;
 
     for (let t = lb; t < (beforeTrip ?? this.nbTrips); t++) {
-      const pickup = this.pickUpTypeFrom(stopId, t);
+      const pickup = this.pickUpTypeFrom(stopIndex, t);
       if (pickup !== 'NOT_AVAILABLE') {
         return t;
       }
@@ -316,17 +419,30 @@ export class Route {
   }
 
   /**
-   * Retrieves the index of a stop within the route.
+   * Retrieves the indices 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.
+   * @returns An array of indices where the stop appears in the route, or an empty array if the stop is not found.
    */
-  public stopIndex(stopId: StopId): number {
+  public stopRouteIndices(stopId: StopId): StopRouteIndex[] {
     const stopIndex = this.stopIndices.get(stopId);
     if (stopIndex === undefined) {
+      return [];
+    }
+    return stopIndex;
+  }
+
+  /**
+   * Retrieves the id of a stop at a given index in a route.
+   * @param stopRouteIndex The route index of the stop.
+   * @returns The id of the stop at the given index in the route.
+   */
+  public stopId(stopRouteIndex: StopRouteIndex): StopId {
+    const stopId = this.stops[stopRouteIndex];
+    if (stopId === undefined) {
       throw new Error(
-        `Stop index for ${stopId} not found in route ${this.serviceRouteId}`,
+        `StopId for stop at index ${stopRouteIndex} not found in route ${this.serviceRouteId}`,
       );
     }
-    return stopIndex;
+    return stopId;
   }
 }

package/src/timetable/timetable.ts

@@ -7,12 +7,15 @@ import {
   deserializeRoutesAdjacency,
   deserializeServiceRoutesMap,
   deserializeStopsAdjacency,
+  deserializeTripContinuations,
   serializeRoutesAdjacency,
   serializeServiceRoutesMap,
   serializeStopsAdjacency,
+  serializeTripContinuations,
 } from './io.js';
 import { Timetable as ProtoTimetable } from './proto/timetable.js';
-import { Route, RouteId } from './route.js';
+import { Route, RouteId, StopRouteIndex, TripRouteIndex } from './route.js';
+import { encode, TripBoardingId } from './tripBoardingId.js';
 
 export type TransferType =
   | 'RECOMMENDED'
@@ -26,11 +29,19 @@ export type Transfer = {
   minTransferTime?: Duration;
 };
 
+export type TripBoarding = {
+  hopOnStopIndex: StopRouteIndex;
+  routeId: RouteId;
+  tripIndex: TripRouteIndex;
+};
+
 export type StopAdjacency = {
-  transfers: Transfer[];
+  transfers?: Transfer[];
   routes: RouteId[];
 };
 
+export type TripContinuations = Map<TripBoardingId, TripBoarding[]>;
+
 export type ServiceRouteId = number;
 
 export type RouteType =
@@ -68,7 +79,9 @@ export const ALL_TRANSPORT_MODES: Set<RouteType> = new Set([
   'MONORAIL',
 ]);
 
-export const CURRENT_VERSION = '0.0.7';
+const EMPTY_TRIP_CONTINUATIONS: TripBoarding[] = [];
+
+export const CURRENT_VERSION = '0.0.9';
 
 /**
  * The internal transit timetable format.
@@ -77,21 +90,26 @@ export class Timetable {
   private readonly stopsAdjacency: StopAdjacency[];
   private readonly routesAdjacency: Route[];
   private readonly serviceRoutes: ServiceRoute[];
+  private readonly tripContinuations?: TripContinuations;
   private readonly activeStops: Set<StopId>;
 
   constructor(
     stopsAdjacency: StopAdjacency[],
     routesAdjacency: Route[],
     routes: ServiceRoute[],
+    tripContinuations?: TripContinuations,
   ) {
     this.stopsAdjacency = stopsAdjacency;
     this.routesAdjacency = routesAdjacency;
     this.serviceRoutes = routes;
+    this.tripContinuations = tripContinuations;
     this.activeStops = new Set<StopId>();
     for (let i = 0; i < stopsAdjacency.length; i++) {
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
       const stop = stopsAdjacency[i]!;
-      if (stop.routes.length > 0 || stop.transfers.length > 0) {
+      if (
+        stop.routes.length > 0 ||
+        (stop.transfers && stop.transfers.length > 0)
+      ) {
         this.activeStops.add(i);
       }
     }
@@ -108,6 +126,9 @@ export class Timetable {
       stopsAdjacency: serializeStopsAdjacency(this.stopsAdjacency),
       routesAdjacency: serializeRoutesAdjacency(this.routesAdjacency),
       serviceRoutes: serializeServiceRoutesMap(this.serviceRoutes),
+      tripContinuations: serializeTripContinuations(
+        this.tripContinuations || new Map<TripBoardingId, TripBoarding[]>(),
+      ),
     };
     const writer = new BinaryWriter();
     ProtoTimetable.encode(protoTimetable, writer);
@@ -131,8 +152,8 @@ export class Timetable {
     return new Timetable(
       deserializeStopsAdjacency(protoTimetable.stopsAdjacency),
       deserializeRoutesAdjacency(protoTimetable.routesAdjacency),
-
       deserializeServiceRoutesMap(protoTimetable.serviceRoutes),
+      deserializeTripContinuations(protoTimetable.tripContinuations),
     );
   }
 
@@ -166,7 +187,33 @@ export class Timetable {
    * @returns An array of transfer options available at the stop.
    */
   getTransfers(stopId: StopId): Transfer[] {
-    return this.stopsAdjacency[stopId]?.transfers ?? [];
+    const stopAdjacency = this.stopsAdjacency[stopId];
+    if (!stopAdjacency) {
+      throw new Error(`Stop ID ${stopId} not found`);
+    }
+    return stopAdjacency.transfers || [];
+  }
+
+  /**
+   * Retrieves all trip continuation options available at the specified stop for a given trip.
+   *
+   * @param stopIndex - The index in the route of the stop to get trip continuations for.
+   * @param routeId - The ID of the route to get continuations for.
+   * @param tripIndex - The index of the trip to get continuations for.
+   * @returns An array of trip continuation options available at the stop for the specified trip.
+   */
+  getContinuousTrips(
+    stopIndex: StopRouteIndex,
+    routeId: RouteId,
+    tripIndex: TripRouteIndex,
+  ): TripBoarding[] {
+    const tripContinuations = this.tripContinuations?.get(
+      encode(stopIndex, routeId, tripIndex),
+    );
+    if (!tripContinuations) {
+      return EMPTY_TRIP_CONTINUATIONS;
+    }
+    return tripContinuations;
   }
 
   /**
@@ -211,18 +258,18 @@ export class Timetable {
 
   /**
    * Finds routes that are reachable from a set of stop IDs.
-   * Also identifies the first stop available to hop on each route among
+   * Also identifies the first stop index available to hop on each route among
    * the input stops.
    *
    * @param fromStops - The set of stop IDs to find reachable routes from.
    * @param transportModes - The set of transport modes to consider for reachable routes.
-   * @returns A map of reachable routes to the first stop available to hop on each route.
+   * @returns A map of reachable routes to the first stop index available to hop on each route.
    */
   findReachableRoutes(
     fromStops: Set<StopId>,
     transportModes: Set<RouteType> = ALL_TRANSPORT_MODES,
-  ): Map<Route, StopId> {
-    const reachableRoutes = new Map<Route, StopId>();
+  ): Map<Route, StopRouteIndex> {
+    const reachableRoutes = new Map<Route, StopRouteIndex>();
     const fromStopsArray = Array.from(fromStops);
     for (let i = 0; i < fromStopsArray.length; i++) {
       const originStop = fromStopsArray[i]!;
@@ -234,14 +281,17 @@ export class Timetable {
       );
       for (let j = 0; j < validRoutes.length; j++) {
         const route = validRoutes[j]!;
-        const hopOnStop = reachableRoutes.get(route);
-        if (hopOnStop) {
-          if (route.isBefore(originStop, hopOnStop)) {
+        const originStopIndices = route.stopRouteIndices(originStop);
+        const originStopIndex = originStopIndices[0]!;
+
+        const existingHopOnStopIndex = reachableRoutes.get(route);
+        if (existingHopOnStopIndex !== undefined) {
+          if (originStopIndex < existingHopOnStopIndex) {
             // if the current stop is before the existing hop on stop, replace it
-            reachableRoutes.set(route, originStop);
+            reachableRoutes.set(route, originStopIndex);
           }
         } else {
-          reachableRoutes.set(route, originStop);
+          reachableRoutes.set(route, originStopIndex);
         }
       }
     }

package/src/timetable/tripBoardingId.ts

@@ -0,0 +1,94 @@
+import { RouteId, StopRouteIndex, TripRouteIndex } from './route.js';
+
+// Each value uses 20 bits, allowing values from 0 to 1,048,575 (2^20 - 1)
+const VALUE_MASK = (1n << 20n) - 1n; // 0xFFFFF
+const MAX_VALUE = 1_048_575; // 2^20 - 1
+
+// Bit positions for each value in the 60-bit bigint
+const TRIP_INDEX_SHIFT = 0n;
+const ROUTE_ID_SHIFT = 20n;
+const STOP_INDEX_SHIFT = 40n;
+
+// A TripId encodes a stop index, route ID, and trip index into a single bigint value
+export type TripBoardingId = bigint;
+
+/**
+ * Validates that a value fits within 20 bits (0 to 1,048,575)
+ * @param value - The value to validate
+ * @param name - The name of the value for error reporting
+ * @throws Error if the value is out of range
+ */
+const validateValue = (value: number, name: string): void => {
+  if (value < 0 || value > MAX_VALUE) {
+    throw new Error(`${name} must be between 0 and ${MAX_VALUE}, got ${value}`);
+  }
+};
+
+/**
+ * Encodes a stop index, route ID, and trip index into a single trip boarding ID.
+ * @param stopIndex - The index of the stop within the route (0 to 1,048,575)
+ * @param routeId - The route identifier (0 to 1,048,575)
+ * @param tripIndex - The index of the trip within the route (0 to 1,048,575)
+ * @returns The encoded trip ID as a bigint
+ */
+export const encode = (
+  stopIndex: StopRouteIndex,
+  routeId: RouteId,
+  tripIndex: TripRouteIndex,
+): TripBoardingId => {
+  validateValue(stopIndex, 'stopIndex');
+  validateValue(routeId, 'routeId');
+  validateValue(tripIndex, 'tripIndex');
+
+  return (
+    (BigInt(stopIndex) << STOP_INDEX_SHIFT) |
+    (BigInt(routeId) << ROUTE_ID_SHIFT) |
+    (BigInt(tripIndex) << TRIP_INDEX_SHIFT)
+  );
+};
+
+/**
+ * Decodes a trip boarding ID back into its constituent stop index, route ID, and trip index.
+ * @param tripBoardingId - The encoded trip ID
+ * @returns A tuple containing [stopIndex, routeId, tripIndex]
+ */
+export const decode = (
+  tripBoardingId: TripBoardingId,
+): [StopRouteIndex, RouteId, TripRouteIndex] => {
+  const stopIndex = Number((tripBoardingId >> STOP_INDEX_SHIFT) & VALUE_MASK);
+  const routeId = Number((tripBoardingId >> ROUTE_ID_SHIFT) & VALUE_MASK);
+  const tripIndex = Number((tripBoardingId >> TRIP_INDEX_SHIFT) & VALUE_MASK);
+
+  return [stopIndex, routeId, tripIndex];
+};
+
+/**
+ * Extracts just the stop index from a trip ID without full decoding.
+ * @param tripBoardingId - The encoded trip boarding ID
+ * @returns The stop index
+ */
+export const getStopIndex = (
+  tripBoardingId: TripBoardingId,
+): StopRouteIndex => {
+  return Number((tripBoardingId >> STOP_INDEX_SHIFT) & VALUE_MASK);
+};
+
+/**
+ * Extracts just the route ID from a trip ID without full decoding.
+ * @param tripBoardingId - The encoded trip boarding ID
+ * @returns The route ID
+ */
+export const getRouteId = (tripBoardingId: TripBoardingId): RouteId => {
+  return Number((tripBoardingId >> ROUTE_ID_SHIFT) & VALUE_MASK);
+};
+
+/**
+ * Extracts just the trip index from a trip ID without full decoding.
+ * @param tripBoardingId - The encoded trip boarding ID
+ * @returns The trip index
+ */
+export const getTripIndex = (
+  tripBoardingId: TripBoardingId,
+): TripRouteIndex => {
+  return Number((tripBoardingId >> TRIP_INDEX_SHIFT) & VALUE_MASK);
+};

package/tsconfig.json

@@ -1,8 +1,8 @@
 {
   "include": ["./src/**/*.ts"],
   "compilerOptions": {
-    "target": "es2015",
-    "lib": ["es2019"],
+    "target": "es2022",
+    "lib": ["es2022"],
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
     "rootDir": "./src",