minotor/dist/timetable/route.d.ts

A lightweight client-side transit routing library.

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 = number;
export declare const PickUpDropOffTypes: {
    readonly REGULAR: 0;
    readonly NOT_AVAILABLE: 1;
    readonly MUST_PHONE_AGENCY: 2;
    readonly MUST_COORDINATE_WITH_DRIVER: 3;
};
export type PickUpDropOffType = (typeof PickUpDropOffTypes)[keyof typeof PickUpDropOffTypes];
export type PickUpDropOffTypeString = keyof typeof PickUpDropOffTypes;
export type RawPickUpDropOffType = PickUpDropOffType;
export type TripRouteIndex = number;
export type StopRouteIndex = number;
/**
 * A route identifies all trips of a given service route sharing the same list of stops.
 */
export declare class Route {
    readonly id: RouteId;
    /**
     * Arrivals and departures encoded as minutes from midnight.
     * Format: [arrival1, departure1, arrival2, departure2, etc.]
     */
    private readonly stopTimes;
    /**
     * PickUp and DropOff types represented as a 2-bit encoded Uint8Array.
     * Values (2 bits each):
     *   0: REGULAR
     *   1: NOT_AVAILABLE
     *   2: MUST_PHONE_AGENCY
     *   3: MUST_COORDINATE_WITH_DRIVER
     *
     * Encoding format: Each byte contains 2 pickup/drop-off pairs (4 bits each)
     * Bit layout per byte: [pickup_1 (2 bits)][drop_off_1 (2 bits)][pickup_0 (2 bits)][drop_off_0 (2 bits)]
     * Example: For stops 0 and 1 in a trip, one byte encodes all 4 values
     */
    private readonly pickupDropOffTypes;
    /**
     * A binary array of stopIds in the route.
     * [stop1, stop2, stop3,...]
     */
    readonly stops: Uint32Array;
    /**
     * A reverse mapping of each stop with their index in the route:
     * {
     *   4: 0,
     *   5: 1,
     *   ...
     * }
     */
    private readonly stopIndices;
    /**
     * The identifier of the route as a service shown to users.
     */
    private readonly serviceRouteId;
    /**
     * The total number of stops in the route.
     */
    private readonly nbStops;
    /**
     * The total number of trips in the route.
     */
    private readonly nbTrips;
    constructor(id: RouteId, stopTimes: Uint16Array, pickupDropOffTypes: Uint8Array, stops: Uint32Array, serviceRouteId: ServiceRouteId);
    /**
     * 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;
    /**
     * Serializes the Route into binary arrays.
     *
     * @returns The serialized binary data.
     */
    serialize(): SerializedRoute;
    /**
     * Retrieves the number of stops in the route.
     *
     * @returns The total number of stops in the route.
     */
    getNbStops(): number;
    /**
     * Retrieves the number of trips in the route.
     *
     * @returns The total number of trips in the route.
     */
    getNbTrips(): number;
    /**
     * 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;
    /**
     * Retrieves the arrival time at a specific stop for a given trip.
     *
     * @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.
     */
    arrivalAt(stopIndex: StopRouteIndex, tripIndex: TripRouteIndex): Time;
    /**
     * Computes the per-trip base offset used by the hot-path scanning methods.
     *
     * Cache the result once when boarding a new trip and pass it to
     * {@link arrivalAtOffset} and {@link dropOffTypeAtOffset} throughout the
     * scanning loop to avoid recomputing `tripIndex × nbStops` on every stop.
     *
     * @param tripIndex - The index of the trip.
     * @returns `tripIndex × nbStops`.
     */
    tripStopOffset(tripIndex: TripRouteIndex): number;
    /**
     * Hot-path variant of {@link arrivalAt} that accepts a precomputed base offset.
     *
     * @param stopIndex - The index of the stop in the route.
     * @param offset    - Precomputed value from {@link tripStopOffset}.
     * @returns The arrival time at the specified stop.
     */
    arrivalAtOffset(stopIndex: StopRouteIndex, offset: number): Time;
    /**
     * Hot-path variant of {@link departureFrom} that accepts a precomputed base offset.
     *
     * @param stopIndex - The index of the stop in the route.
     * @param offset    - Precomputed value from {@link tripStopOffset}.
     * @returns The departure time at the specified stop.
     */
    departureAtOffset(stopIndex: StopRouteIndex, offset: number): Time;
    /**
     * Hot-path variant of {@link dropOffTypeAt} that accepts a precomputed base offset.
     *
     * @param stopIndex - The index of the stop in the route.
     * @param offset    - Precomputed value from {@link tripStopOffset}.
     * @returns The drop-off type at the specified stop.
     */
    dropOffTypeAtOffset(stopIndex: StopRouteIndex, offset: number): RawPickUpDropOffType;
    /**
     * Retrieves the departure time at a specific stop for a given trip.
     *
     * @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.
     */
    departureFrom(stopIndex: StopRouteIndex, tripIndex: TripRouteIndex): Time;
    /**
     * Retrieves the pick-up type for a specific stop and trip.
     *
     * @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(stopIndex: StopRouteIndex, tripIndex: TripRouteIndex): RawPickUpDropOffType;
    /**
     * Retrieves the drop-off type for a specific stop and trip.
     *
     * @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(stopIndex: StopRouteIndex, tripIndex: TripRouteIndex): RawPickUpDropOffType;
    /**
     * 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 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.
     *                                   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(stopIndex: StopRouteIndex, after?: Time, beforeTrip?: TripRouteIndex): TripRouteIndex | undefined;
    /**
     * Retrieves the indices of a stop within the route.
     * @param stopId The StopId of the stop to locate 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.
     */
    stopRouteIndices(stopId: StopId): StopRouteIndex[];
    /**
     * 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.
     */
    stopId(stopRouteIndex: StopRouteIndex): StopId;
}