Update hafas-client to version 5.6 and add comments (#45276)

types/hafas-client/hafas-client-tests.ts

@@ -57,6 +57,10 @@ client.locations("", { results: 1 })
     .then(locations => { /* ... */ })
     .catch(() => { /* ... */ });
 
-client.journeys("", "", { results: 1 })
+client.journeys("", "", { results: 1, subStops: true })
     .then(journeys => { /* ... */ })
     .catch(() => { /* ... */ });
+
+client.radar({ north: 0, south: 0, west: 0, east: 0 }, { results: 1, duration: 10 })
+    .then(movements => { /* ... */ })
+    .catch(() => { /* ... */ });

types/hafas-client/index.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for hafas-client 5.5
+// Type definitions for hafas-client 5.6
 // Project: https://github.com/public-transport/hafas-client
 // Definitions by: Jürgen Bergmann <https://github.com/bergmannjg>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
@@ -8,15 +8,26 @@ export = createClient;
 declare function createClient(profile: createClient.Profile, userAgent: string): createClient.HafasClient;
 
 declare namespace createClient {
+    /**
+     * A ProductType relates to how a means of transport "works" in local context.
+     * Example: Even though S-Bahn and U-Bahn in Berlin are both trains, they have different operators, service patterns,
+     * stations and look different. Therefore, they are two distinct products subway and suburban.
+     */
     interface ProductType {
         id: string;
-        mode: string;
+        mode: 'train' | 'bus' | 'watercraft' | 'taxi' | 'gondola' | 'aircraft' | 'car' | 'bicycle' | 'walking';
         name: string;
         short: string;
     }
 
+    /**
+     * A profile is a specific customisation for each endpoint.
+     * It parses data from the API differently, add additional information, or enable non-default methods.
+     */
     interface Profile {
         locale: string;
+        timezone: string;
+        endpoint: string;
         products: ReadonlyArray<ProductType>;
         trip?: boolean;
         radar?: boolean;
@@ -24,6 +35,9 @@ declare namespace createClient {
         reachableFrom?: boolean;
     }
 
+    /**
+     * A location object is used by other items to indicate their locations.
+     */
     interface Location {
         type: 'location';
         id?: string;
@@ -35,14 +49,31 @@ declare namespace createClient {
         altitude?: number;
     }
 
-    // Each public transportation network exposes its products as boolean properties.
-    // They are modelled as TypeScript boolean index types.
-    // The products may be similar to Extended GTFS Route Types (https://developers.google.com/transit/gtfs/reference/extended-route-types)
-    // and to Netex Vehicle types (https://www.vdv.de/vdv-462-netex-recommendation-v00-22-english.pdfx)
+    /** Each public transportation network exposes its products as boolean properties. See {@link ProductType} */
     interface Products {
         [product: string]: boolean;
     }
 
+    interface Facilities {
+        [product: string]: string | boolean;
+    }
+
+    interface ReisezentrumOpeningHours {
+        Mo?: string;
+        Di?: string;
+        Mi?: string;
+        Do?: string;
+        Fr?: string;
+        Sa?: string;
+        So?: string;
+    }
+
+    /**
+     * A station is a larger building or area that can be identified by a name.
+     * It is usually represented by a single node on a public transport map.
+     * Whereas a stop usually specifies a location, a station often is a broader area
+     * that may span across multiple levels or buildings.
+     */
     interface Station {
         type: 'station';
         id: string;
@@ -51,9 +82,21 @@ declare namespace createClient {
         location?: Location;
         products?: Products;
         isMeta?: boolean;
-        regions?: ReadonlyArray<string>; // region ids
+        /** region ids */
+        regions?: ReadonlyArray<string>;
+        facilities?: Facilities;
+        reisezentrumOpeningHours?: ReisezentrumOpeningHours;
     }
 
+    interface Ids {
+        /** DELFI Haltestellen ID */
+        dhid?: string;
+    }
+
+    /**
+     * A stop is a single small point or structure at which vehicles stop.
+     * A stop always belongs to a station. It may for example be a sign, a basic shelter or a railway platform.
+     */
     interface Stop {
         type: 'stop';
         id: string;
@@ -61,14 +104,22 @@ declare namespace createClient {
         station?: Station;
         location?: Location;
         products: Products;
+        lines?: ReadonlyArray<Line>;
         isMeta?: boolean;
+        reisezentrumOpeningHours?: ReisezentrumOpeningHours;
+        ids?: Ids;
+        loadFactor?: string;
     }
 
+    /**
+     * A region is a group of stations, for example a metropolitan area or a geographical or cultural region.
+     */
     interface Region {
         type: 'region';
         id: string;
         name: string;
-        stations: ReadonlyArray<string>; // station ids
+        /** station ids */
+        stations: ReadonlyArray<string>;
     }
 
     interface Line {
@@ -81,7 +132,8 @@ declare namespace createClient {
         product?: string;
         public?: boolean;
         mode: 'train' | 'bus' | 'watercraft' | 'taxi' | 'gondola' | 'aircraft' | 'car' | 'bicycle' | 'walking';
-        routes?: ReadonlyArray<string>; // routes ids
+        /** routes ids */
+        routes?: ReadonlyArray<string>;
         operator?: Operator;
         express?: boolean;
         metro?: boolean;
@@ -90,12 +142,16 @@ declare namespace createClient {
         symbol?: string;
     }
 
+    /**
+     * A route represents a single set of stations, of a single line.
+     */
     interface Route {
         type: 'route';
         id: string;
         line: string;
         mode: 'train' | 'bus' | 'watercraft' | 'taxi' | 'gondola' | 'aircraft' | 'car' | 'bicycle' | 'walking';
-        stops: ReadonlyArray<string>; // stop ids
+        /** stop ids */
+        stops: ReadonlyArray<string>;
     }
 
     interface Cycle {
@@ -109,13 +165,19 @@ declare namespace createClient {
         departure?: number;
     }
 
+    /**
+     * There are many ways to format schedules of public transport routes.
+     * This one tries to balance the amount of data and consumability.
+     * It is specifically geared towards urban public transport, with frequent trains and homogenous travels.
+     */
     interface Schedule {
         type: 'schedule';
         id: string;
         route: string;
         mode: 'train' | 'bus' | 'watercraft' | 'taxi' | 'gondola' | 'aircraft' | 'car' | 'bicycle' | 'walking';
         sequence: ReadonlyArray<ArrivalDeparture>;
-        starts: ReadonlyArray<string>; // array of Unix timestamps
+        /** array of Unix timestamps */
+        starts: ReadonlyArray<string>;
     }
 
     interface Operator {
@@ -132,14 +194,35 @@ declare namespace createClient {
         tripId?: string;
     }
 
+    interface Geometry {
+        type: 'point';
+        coordinates: number[];
+    }
+
+    interface Feature {
+        type: 'Feature';
+        properties?: Station | Stop;
+        geometry: Geometry;
+    }
+
+    interface FeatureCollection {
+        type: 'FeatureCollection';
+        features: ReadonlyArray<Feature>;
+    }
+
+    /**
+     * A stopover represents a vehicle stopping at a stop/station at a specific time.
+     */
     interface StopOver {
         stop: Station | Stop;
-        departure?: string; // null, if last stopOver of trip
+        /** null, if last stopOver of trip */
+        departure?: string;
         departureDelay?: number;
         plannedDeparture?: string;
         departurePlatform?: string;
         plannedDeparturePlatform?: string;
-        arrival?: string; // null, if first stopOver of trip
+        /** null, if first stopOver of trip */
+        arrival?: string;
         arrivalDelay?: number;
         plannedArrival?: string;
         arrivalPlatform?: string;
@@ -166,6 +249,7 @@ declare namespace createClient {
         line?: Line;
         direction?: string;
         reachable?: boolean;
+        polyline?: FeatureCollection;
     }
 
     interface Price {
@@ -186,8 +270,12 @@ declare namespace createClient {
         plannedPlatform?: string;
         remarks?: ReadonlyArray<Hint>;
         cancelled?: boolean;
+        loadFactor?: string;
     }
 
+    /**
+     * Leg of journey
+     */
     interface Leg {
         tripId?: string;
         origin: Station | Stop;
@@ -217,8 +305,18 @@ declare namespace createClient {
         transfer?: boolean;
         cycle?: Cycle;
         alternatives?: ReadonlyArray<Alternative>;
+        polyline?: FeatureCollection;
+        remarks?: ReadonlyArray<Hint>;
     }
 
+    interface ScheduledDays {
+        [day: string]: boolean;
+    }
+
+    /**
+     * A journey is a computed set of directions to get from A to B at a specific time.
+     * It would typically be the result of a route planning algorithm.
+     */
     interface Journey {
         type: 'journey';
         legs: ReadonlyArray<Leg>;
@@ -226,9 +324,12 @@ declare namespace createClient {
         remarks?: ReadonlyArray<Hint>;
         price?: Price;
         cycle?: Cycle;
+        scheduledDays?: ScheduledDays;
     }
 
     interface Journeys {
+        earlierRef?: string;
+        laterRef?: string;
         journeys: ReadonlyArray<Journey>;
     }
 
@@ -237,93 +338,474 @@ declare namespace createClient {
         stations: ReadonlyArray<Station | Stop>;
     }
 
+    interface Frame {
+        origin: Stop | Location;
+        destination: Stop | Location;
+        t?: number;
+    }
+
+    interface Movement {
+        direction?: string;
+        tripId?: string;
+        line?: Line;
+        location?: Location;
+        nextStopovers?: ReadonlyArray<StopOver>;
+        frames?: ReadonlyArray<Frame>;
+        polyline?: FeatureCollection;
+    }
+
     interface JourneysOptions {
+        /**
+         * departure date, undefined corresponds to Date.Now
+         * @default undefined
+         */
         departure?: Date;
+        /**
+         * arrival date, departure and arrival are mutually exclusive.
+         * @default undefined
+         */
         arrival?: Date;
-        results?: number; // number of journeys
-        via?: string; // let journeys pass this station
-        stopovers?: boolean; // return stations on the way?
-        transfers?: number; // Maximum nr of transfers. Default: Let HAFAS decide.
-        transferTime?: number; // minimum time for a single transfer in minutes
-        accessibility?: string; // 'none', 'partial' or 'complete'
-        bike?: boolean; // only bike-friendly journeys
+        /**
+         * earlierThan, use {@link Journeys#earlierRef}, earlierThan and departure/arrival are mutually exclusive.
+         * @default undefined
+         */
+        earlierThan?: string;
+        /**
+         * laterThan, use {@link Journeys#laterRef}, laterThan and departure/arrival are mutually exclusive.
+         *  @default undefined
+         */
+        laterThan?: string;
+        /**
+         * how many search results?
+         * @default 3
+         */
+        results?: number;
+        /**
+         * let journeys pass this station
+         * @default undefined
+         */
+        via?: string;
+        /**
+         * return stations on the way?
+         * @default false
+         */
+        stopovers?: boolean;
+        /**
+         * Maximum nr of transfers. Default: Let HAFAS decide.
+         * @default 10
+         */
+        transfers?: number;
+        /**
+         * minimum time for a single transfer in minutes
+         * @default 10
+         */
+        transferTime?: number;
+        /**
+         * 'none', 'partial' or 'complete'
+         *  @default none
+         */
+        accessibility?: string;
+        /**
+         * only bike-friendly journeys
+         * @default false
+         */
+        bike?: boolean;
         products?: Products;
-        tickets?: boolean; // return tickets? only available with some profiles
-        polylines?: boolean; // return a shape for each leg?
-        remarks?: boolean; // parse & expose hints & warnings?
-        walkingSpeed?: string; // 'slow', 'normal', 'fast'
+        /**
+         * return tickets? only available with some profiles
+         * @default false
+         */
+        tickets?: boolean;
+        /**
+         * return a shape for each leg?
+         * @default false
+         */
+        polylines?: boolean;
+        /**
+         * parse & expose sub-stops of stations?
+         * @default false
+         */
+        subStops?: boolean;
+        /**
+         * parse & expose entrances of stops/stations?
+         * @default true
+         */
+        entrances?: boolean;
+        /**
+         * parse & expose hints & warnings?
+         * @default true
+         */
+        remarks?: boolean;
+        /**
+         * 'slow', 'normal', 'fast'
+         * @default slow
+         */
+        walkingSpeed?: string;
+        /**
+         * start with walking
+         * @default false
+         */
         startWithWalking?: boolean;
-        language?: string; // language to get results in
-        scheduledDays?: boolean; // parse which days each journey is valid on
+        /**
+         * language to get results in
+         * @default en
+         */
+        language?: string;
+        /**
+         * parse which days each journey is valid on
+         * @default false
+         */
+        scheduledDays?: boolean;
     }
 
     interface LocationsOptions {
-        fuzzy?: boolean; // find only exact matches?
-        results?: number; // how many search results?
-        stops?: boolean; // return stops/stations?
+        /**
+         * find only exact matches?
+         * @default true
+         */
+        fuzzy?: boolean;
+        /**
+         * how many search results?
+         * @default 10
+         */
+        results?: number;
+        /**
+         * return stops/stations?
+         * @default true
+         */
+        stops?: boolean;
+        /**
+         * return addresses
+         * @default false
+         */
         addresses?: boolean;
-        poi?: boolean; // points of interest
-        linesOfStops?: boolean; // parse & expose lines at each stop/station?
+        /**
+         * points of interest
+         * @default true
+         */
+        poi?: boolean;
+        /**
+         * parse & expose lines at each stop/station?
+         * @default false
+         */
+        linesOfStops?: boolean;
+        /**
+         * Language of the results
+         * @default en
+         */
         language?: string;
     }
 
     interface TripOptions {
-        stopovers?: boolean; // return stations on the way?
-        polyline?: boolean; // return a shape for the trip?
-        remarks?: boolean; // parse & expose hints & warnings?
+        /**
+         * return stations on the way?
+         * @default true
+         */
+        stopovers?: boolean;
+        /**
+         * return a shape for the trip?
+         * @default false
+         */
+        polyline?: boolean;
+        /**
+         * parse & expose sub-stops of stations?
+         * @default true
+         */
+        subStops?: boolean;
+        /**
+         * parse & expose entrances of stops/stations?
+         * @default true
+         */
+        entrances?: boolean;
+        /**
+         * parse & expose hints & warnings?
+         * @default true
+         */
+        remarks?: boolean;
+        /**
+         * Language of the results
+         * @default en
+         */
         language?: string;
     }
 
     interface StopOptions {
-        linesOfStops?: boolean; // parse & expose lines at the stop/station?
+        /**
+         * parse & expose lines at the stop/station?
+         * @default false
+         */
+        linesOfStops?: boolean;
+        /**
+         * parse & expose sub-stops of stations?
+         * @default true
+         */
+        subStops?: boolean;
+        /**
+         * parse & expose entrances of stops/stations?
+         * @default true
+         */
+        entrances?: boolean;
+        /**
+         * Language of the results
+         * @default en
+         */
         language?: string;
     }
 
     interface DeparturesArrivalsOptions {
+        /**
+         * departure date, undefined corresponds to Date.Now
+         * @default undefined
+         */
         when?: Date;
-        direction?: string; // only show departures heading to this station
-        duration?: number; // show departures for the next n minutes
-        results?: number; // max. number of results; `null` means "whatever HAFAS wants"
-        linesOfStops?: boolean; // parse & expose lines at the stop/station?
-        remarks?: boolean; // parse & expose hints & warnings?
-        stopovers?: boolean; // fetch & parse previous/next stopovers?
-        includeRelatedStations?: boolean; // departures at related stations
+        /**
+         * only show departures heading to this station
+         * @default undefined
+         */
+        direction?: string;
+        /**
+         * show departures for the next n minutes
+         * @default 120
+         */
+        duration?: number;
+        /**
+         * max. number of results; `null` means "whatever HAFAS wants"
+         * @default 10
+         */
+        results?: number;
+        /**
+         * parse & expose sub-stops of stations?
+         * @default true
+         */
+        subStops?: boolean;
+        /**
+         * parse & expose entrances of stops/stations?
+         * @default true
+         */
+        entrances?: boolean;
+        /**
+         * parse & expose lines at the stop/station?
+         * @default false
+         */
+        linesOfStops?: boolean;
+        /**
+         * parse & expose hints & warnings?
+         * @default false
+         */
+        remarks?: boolean;
+        /**
+         * fetch & parse previous/next stopovers?
+         * @default false
+         */
+        stopovers?: boolean;
+        /**
+         * departures at related stations
+         * @default false
+         */
+        includeRelatedStations?: boolean;
+        /**
+         * language
+         * @default en
+         */
         language?: string;
     }
 
     interface RefreshJourneyOptions {
-        stopovers?: boolean; // return stations on the way?
-        polylines?: boolean; // return a shape for each leg?
-        tickets?: boolean; // return tickets? only available with some profiles
-        remarks?: boolean; // parse & expose hints & warnings?
+        /**
+         * return stations on the way?
+         * @default false
+         */
+        stopovers?: boolean;
+        /**
+         * return a shape for each leg?
+         * @default false
+         */
+        polylines?: boolean;
+        /**
+         * return tickets? only available with some profiles
+         * @default false
+         */
+        tickets?: boolean;
+        /**
+         * parse & expose sub-stops of stations?
+         * @default true
+         */
+        subStops?: boolean;
+        /**
+         * parse & expose entrances of stops/stations?
+         * @default true
+         */
+        entrances?: boolean;
+        /**
+         * parse & expose hints & warnings?
+         * @default true
+         */
+        remarks?: boolean;
+        /**
+         * language
+         * @default en
+         */
         language?: string;
     }
 
     interface NearByOptions {
-        results?: number; // maximum number of results
-        distance?: number; // maximum walking distance in meters
-        poi?: boolean; // return points of interest?
-        stops?: boolean; // return stops/stations?
-        linesOfStops?: boolean; // parse & expose lines at each stop/station?
+        /**
+         * maximum number of results
+         * @default 8
+         */
+        results?: number;
+        /**
+         * maximum walking distance in meters
+         * @default undefined
+         */
+        distance?: number;
+        /**
+         * return points of interest?
+         * @default false
+         */
+        poi?: boolean;
+        /**
+         * return stops/stations?
+         * @default true
+         */
+        stops?: boolean;
+        /**
+         * parse & expose sub-stops of stations?
+         * @default true
+         */
+        subStops?: boolean;
+        /**
+         * parse & expose entrances of stops/stations?
+         * @default true
+         */
+        entrances?: boolean;
+        /**
+         * parse & expose lines at each stop/station?
+         * @default false
+         */
+        linesOfStops?: boolean;
+        /**
+         * language
+         * @default en
+         */
         language?: string;
     }
 
     interface ReachableFromOptions {
+        /**
+         * when
+         * @default undefined
+         */
         when?: Date;
-        maxTransfers?: number; // maximum of 5 transfers
-        maxDuration?: number; // maximum travel duration in minutes, pass `null` for infinite
+        /**
+         * maximum of transfers
+         * @default 5
+         */
+        maxTransfers?: number;
+        /**
+         * maximum travel duration in minutes, pass `null` for infinite
+         * @default 20
+         */
+        maxDuration?: number;
+        /**
+         * products
+         * @default undefined
+         */
         products?: Products;
+        /**
+         * parse & expose sub-stops of stations?
+         * @default true
+         */
+        subStops?: boolean;
+        /**
+         * parse & expose entrances of stops/stations?
+         * @default true
+         */
+        entrances?: boolean;
+    }
+
+    interface BoundingBox {
+        north: number;
+        west: number;
+        south: number;
+        east: number;
+    }
+
+    interface RadarOptions {
+        /**
+         * maximum number of vehicles
+         * @default 256
+         */
+        results?: number;
+        /**
+         * compute frames for the next n seconds
+         * @default 20
+         */
+        duration?: number;
     }
 
     interface HafasClient {
+        /**
+         * Retrieves journeys
+         * @param from uid of station
+         * @param to uid of station
+         * @param options options
+         */
         journeys: (from: string | Station | Location, to: string | Station | Location, options: JourneysOptions | undefined) => Promise<Journeys>;
+        /**
+         * refreshes a Journey
+         * @param refreshToken refreshToken must be a string, taken from {@link journey#refreshToken}
+         * @param options options
+         */
         refreshJourney: (refreshToken: string, options: RefreshJourneyOptions | undefined) => Promise<Journey>;
+        /**
+         * Refetch information about a trip
+         * @param id trip id, see {@link Leg#tripId}
+         * @param name name
+         * @param options options
+         */
         trip: (id: string, name: string, options: TripOptions | undefined) => Promise<Trip>;
+        /**
+         * Retrieves departures
+         * @param station uid of station
+         * @param options options
+         */
         departures: (station: string | Station, options: DeparturesArrivalsOptions | undefined) => Promise<ReadonlyArray<Alternative>>;
+        /**
+         * Retrieves arrivals
+         * @param station uid of station
+         * @param options options
+         */
         arrivals: (station: string | Station, options: DeparturesArrivalsOptions | undefined) => Promise<ReadonlyArray<Alternative>>;
-        locations: (from: string, options: LocationsOptions | undefined) => Promise<ReadonlyArray<Station | Stop | Location>>;
+        /**
+         * Retrieves locations or stops
+         * @param name name of station
+         * @param options options for search
+         */
+        locations: (name: string, options: LocationsOptions | undefined) => Promise<ReadonlyArray<Station | Stop | Location>>;
+        /**
+         * Retrieves information about a stop
+         * @param id uid of station
+         * @param options options for search
+         */
         stop: (id: string, options: StopOptions | undefined) => Promise<Stop>;
-        nearBy: (location: Location, options: NearByOptions | undefined) => Promise<Stop>;
+        /**
+         * Retrieves nearby stops from location
+         * @param location location
+         * @param options options for search
+         */
+        nearby: (location: Location, options: NearByOptions | undefined) => Promise<ReadonlyArray<Stop>>;
+        /**
+         * Retrieves stations reachable within a certain time from a location
+         * @param address location
+         * @param options options for search
+         */
         reachableFrom: (address: Location, options: ReachableFromOptions | undefined) => Promise<ReadonlyArray<Duration>>;
+        /**
+         * Retrieves all vehicles currently in an area.
+         * @param box area
+         * @param options options for search
+         */
+        radar: (box: BoundingBox, options: RadarOptions | undefined) => Promise<ReadonlyArray<Movement>>;
     }
 }