@stadiamaps/ferrostar 0.47.1 → 0.47.2

package/ferrostar.d.ts

@@ -26,17 +26,41 @@ export interface UserLocation {
 export type IncidentType = "accident" | "congestion" | "construction" | "disabled_vehicle" | "lane_restriction" | "mass_transit" | "miscellaneous" | "other_news" | "planned_event" | "road_closure" | "road_hazard" | "weather";
 
 /**
- * A geographic coordinate in WGS84.
+ * The broad class of maneuver to perform.
+ *
+ * This is usually combined with [`ManeuverModifier`] in [`VisualInstructionContent`].
  */
-export interface GeographicCoordinate {
+export type ManeuverType = "turn" | "new name" | "depart" | "arrive" | "merge" | "on ramp" | "off ramp" | "fork" | "end of road" | "continue" | "roundabout" | "rotary" | "roundabout turn" | "notification" | "exit roundabout" | "exit rotary";
+
+/**
+ * An instruction that can be synthesized using a TTS engine to announce an upcoming maneuver.
+ *
+ * Note that these do not have any locale information attached.
+ */
+export interface SpokenInstruction {
     /**
-     * The latitude (in degrees).
+     * Plain-text instruction which can be synthesized with a TTS engine.
      */
-    lat: number;
+    text: string;
     /**
-     * The Longitude (in degrees).
+     * Speech Synthesis Markup Language, which should be preferred by clients capable of understanding it.
      */
-    lng: number;
+    ssml: string | undefined;
+    /**
+     * How far (in meters) from the upcoming maneuver the instruction should start being spoken.
+     */
+    triggerDistanceBeforeManeuver: number;
+    /**
+     * A unique identifier for this instruction.
+     *
+     * This is provided so that platform-layer integrations can easily disambiguate between distinct utterances,
+     * which may have the same textual content.
+     * UUIDs conveniently fill this purpose.
+     *
+     * NOTE: While it is possible to deterministically create UUIDs, we do not do so at this time.
+     * This should be theoretically possible though if someone cares to write up a proposal and a PR.
+     */
+    utteranceId: string;
 }
 
 /**
@@ -138,15 +162,6 @@ export interface Incident {
     bbox: BoundingBox | undefined;
 }
 
-/**
- * Which side of the road traffic drives on.
- *
- * This is needed by consumers like Android Auto to determine whether
- * a roundabout should be rendered as clockwise (right-hand traffic)
- * or counterclockwise (left-hand traffic).
- */
-export type DrivingSide = "left" | "right";
-
 /**
  * The direction in which the user/device is observed to be traveling.
  */
@@ -163,81 +178,33 @@ export interface CourseOverGround {
 }
 
 /**
- * The broad class of maneuver to perform.
- *
- * This is usually combined with [`ManeuverModifier`] in [`VisualInstructionContent`].
- */
-export type ManeuverType = "turn" | "new name" | "depart" | "arrive" | "merge" | "on ramp" | "off ramp" | "fork" | "end of road" | "continue" | "roundabout" | "rotary" | "roundabout turn" | "notification" | "exit roundabout" | "exit rotary";
-
-/**
- * A waypoint along a route.
- *
- * Within the context of Ferrostar, a route request consists of exactly one [`UserLocation`]
- * and at least one [`Waypoint`]. The route starts from the user\'s location (which may
- * contain other useful information like their current course for the [`crate::routing_adapters::RouteRequestGenerator`]
- * to use) and proceeds through one or more waypoints.
- *
- * Waypoints are used during route calculation, are tracked throughout the lifecycle of a trip,
- * and are used for recalculating when the user deviates from the expected route.
- *
- * Note that support for properties beyond basic geographic coordinates varies by routing engine.
+ * Details about congestion for an incident.
  */
-export interface Waypoint {
-    coordinate: GeographicCoordinate;
-    kind: WaypointKind;
+export interface Congestion {
     /**
-     * Optional additional properties that will be passed on to the [`crate::routing_adapters::RouteRequestGenerator`].
-     *
-     * Most users should prefer convenience functions like [`Waypoint::new_with_valhalla_properties`]
-     * (or, on platforms like iOS and Android with `UniFFI` bindings, [`crate::routing_adapters::valhalla::create_waypoint_with_valhalla_properties`]).
-     *
-     * # Format guidelines
+     * The level of congestion caused by the incident.
      *
-     * This MAY be any format agreed upon by both the request generator and response parser.
-     * However, to promote interoperability, all implementations in the Ferrostar codebase
-     * MUST use JSON.
+     * 0 = no congestion
      *
-     * We selected JSON is selected not because it is good,
-     * but because generics (i.e., becoming `Waypoint<T>`, where an example `T` is `ValhallaProperties`)
-     * would be way too painful, particularly for foreign code.
-     * Especially JavaScript.
+     * 100 = road closed
      *
-     * In any case, [`crate::routing_adapters::RouteRequestGenerator`] and [`crate::routing_adapters::RouteResponseParser`]
-     * implementations SHOULD document their level support for this,
-     * ideally with an exportable record type.
+     * Other values mean no congestion was calculated
      */
-    properties: number[] | undefined;
+    value: number;
 }
 
 /**
- * An instruction that can be synthesized using a TTS engine to announce an upcoming maneuver.
- *
- * Note that these do not have any locale information attached.
+ * A geographic coordinate in WGS84.
  */
-export interface SpokenInstruction {
-    /**
-     * Plain-text instruction which can be synthesized with a TTS engine.
-     */
-    text: string;
-    /**
-     * Speech Synthesis Markup Language, which should be preferred by clients capable of understanding it.
-     */
-    ssml: string | undefined;
+export interface GeographicCoordinate {
     /**
-     * How far (in meters) from the upcoming maneuver the instruction should start being spoken.
+     * The latitude (in degrees).
      */
-    triggerDistanceBeforeManeuver: number;
+    lat: number;
     /**
-     * A unique identifier for this instruction.
-     *
-     * This is provided so that platform-layer integrations can easily disambiguate between distinct utterances,
-     * which may have the same textual content.
-     * UUIDs conveniently fill this purpose.
-     *
-     * NOTE: While it is possible to deterministically create UUIDs, we do not do so at this time.
-     * This should be theoretically possible though if someone cares to write up a proposal and a PR.
+     * The Longitude (in degrees).
      */
-    utteranceId: string;
+    lng: number;
 }
 
 /**
@@ -274,6 +241,80 @@ export interface VisualInstructionContent {
     exitNumbers: string[];
 }
 
+/**
+ * An instruction for visual display (usually as banners) at a specific point along a [`RouteStep`].
+ */
+export interface VisualInstruction {
+    /**
+     * The primary instruction content.
+     *
+     * This is usually given more visual weight.
+     */
+    primaryContent: VisualInstructionContent;
+    /**
+     * Optional secondary instruction content.
+     */
+    secondaryContent: VisualInstructionContent | undefined;
+    /**
+     * Optional sub-maneuver instruction content.
+     */
+    subContent: VisualInstructionContent | undefined;
+    /**
+     * How far (in meters) from the upcoming maneuver the instruction should start being displayed
+     */
+    triggerDistanceBeforeManeuver: number;
+}
+
+/**
+ * The speed of the user from the location provider.
+ */
+export interface Speed {
+    /**
+     * The user\'s speed in meters per second.
+     */
+    value: number;
+    /**
+     * The accuracy of the speed value, measured in meters per second.
+     */
+    accuracy: number | undefined;
+}
+
+/**
+ * The content of a visual instruction.
+ */
+export interface LaneInfo {
+    active: boolean;
+    directions: string[];
+    activeDirection: string | undefined;
+}
+
+/**
+ * The impact of the incident that has occurred.
+ */
+export type Impact = "unknown" | "critical" | "major" | "minor" | "low";
+
+/**
+ * Information describing the series of steps needed to travel between two or more points.
+ *
+ * NOTE: This type is unstable and is still under active development and should be
+ * considered unstable.
+ */
+export interface Route {
+    geometry: GeographicCoordinate[];
+    bbox: BoundingBox;
+    /**
+     * The total route distance, in meters.
+     */
+    distance: number;
+    /**
+     * The ordered list of waypoints to visit, including the starting point.
+     * Note that this is distinct from the *geometry* which includes all points visited.
+     * A waypoint represents a start/end point for a route leg.
+     */
+    waypoints: Waypoint[];
+    steps: RouteStep[];
+}
+
 /**
  * A maneuver (such as a turn or merge) followed by travel of a certain distance until reaching
  * the next step.
@@ -337,41 +378,43 @@ export interface RouteStep {
 }
 
 /**
- * The content of a visual instruction.
- */
-export interface LaneInfo {
-    active: boolean;
-    directions: string[];
-    activeDirection: string | undefined;
-}
-
-/**
- * The impact of the incident that has occurred.
- */
-export type Impact = "unknown" | "critical" | "major" | "minor" | "low";
-
-/**
- * An instruction for visual display (usually as banners) at a specific point along a [`RouteStep`].
+ * A waypoint along a route.
+ *
+ * Within the context of Ferrostar, a route request consists of exactly one [`UserLocation`]
+ * and at least one [`Waypoint`]. The route starts from the user\'s location (which may
+ * contain other useful information like their current course for the [`crate::routing_adapters::RouteRequestGenerator`]
+ * to use) and proceeds through one or more waypoints.
+ *
+ * Waypoints are used during route calculation, are tracked throughout the lifecycle of a trip,
+ * and are used for recalculating when the user deviates from the expected route.
+ *
+ * Note that support for properties beyond basic geographic coordinates varies by routing engine.
  */
-export interface VisualInstruction {
+export interface Waypoint {
+    coordinate: GeographicCoordinate;
+    kind: WaypointKind;
     /**
-     * The primary instruction content.
+     * Optional additional properties that will be passed on to the [`crate::routing_adapters::RouteRequestGenerator`].
      *
-     * This is usually given more visual weight.
-     */
-    primaryContent: VisualInstructionContent;
-    /**
-     * Optional secondary instruction content.
-     */
-    secondaryContent: VisualInstructionContent | undefined;
-    /**
-     * Optional sub-maneuver instruction content.
-     */
-    subContent: VisualInstructionContent | undefined;
-    /**
-     * How far (in meters) from the upcoming maneuver the instruction should start being displayed
+     * Most users should prefer convenience functions like [`Waypoint::new_with_valhalla_properties`]
+     * (or, on platforms like iOS and Android with `UniFFI` bindings, [`crate::routing_adapters::valhalla::create_waypoint_with_valhalla_properties`]).
+     *
+     * # Format guidelines
+     *
+     * This MAY be any format agreed upon by both the request generator and response parser.
+     * However, to promote interoperability, all implementations in the Ferrostar codebase
+     * MUST use JSON.
+     *
+     * We selected JSON is selected not because it is good,
+     * but because generics (i.e., becoming `Waypoint<T>`, where an example `T` is `ValhallaProperties`)
+     * would be way too painful, particularly for foreign code.
+     * Especially JavaScript.
+     *
+     * In any case, [`crate::routing_adapters::RouteRequestGenerator`] and [`crate::routing_adapters::RouteResponseParser`]
+     * implementations SHOULD document their level support for this,
+     * ideally with an exportable record type.
      */
-    triggerDistanceBeforeManeuver: number;
+    properties: number[] | undefined;
 }
 
 /**
@@ -380,66 +423,23 @@ export interface VisualInstruction {
 export type ManeuverModifier = "uturn" | "sharp right" | "right" | "slight right" | "straight" | "slight left" | "left" | "sharp left";
 
 /**
- * Information describing the series of steps needed to travel between two or more points.
- *
- * NOTE: This type is unstable and is still under active development and should be
- * considered unstable.
- */
-export interface Route {
-    geometry: GeographicCoordinate[];
-    bbox: BoundingBox;
-    /**
-     * The total route distance, in meters.
-     */
-    distance: number;
-    /**
-     * The ordered list of waypoints to visit, including the starting point.
-     * Note that this is distinct from the *geometry* which includes all points visited.
-     * A waypoint represents a start/end point for a route leg.
-     */
-    waypoints: Waypoint[];
-    steps: RouteStep[];
-}
-
-/**
- * The lane type blocked by the incident.
- */
-export type BlockedLane = "left" | "left center" | "left turn lane" | "center" | "right" | "right center" | "right turn lane" | "hov";
-
-/**
- * The speed of the user from the location provider.
+ * Describes characteristics of the waypoint for routing purposes.
  */
-export interface Speed {
-    /**
-     * The user\'s speed in meters per second.
-     */
-    value: number;
-    /**
-     * The accuracy of the speed value, measured in meters per second.
-     */
-    accuracy: number | undefined;
-}
+export type WaypointKind = "Break" | "Via";
 
 /**
- * Details about congestion for an incident.
+ * Which side of the road traffic drives on.
+ *
+ * This is needed by consumers like Android Auto to determine whether
+ * a roundabout should be rendered as clockwise (right-hand traffic)
+ * or counterclockwise (left-hand traffic).
  */
-export interface Congestion {
-    /**
-     * The level of congestion caused by the incident.
-     *
-     * 0 = no congestion
-     *
-     * 100 = road closed
-     *
-     * Other values mean no congestion was calculated
-     */
-    value: number;
-}
+export type DrivingSide = "left" | "right";
 
 /**
- * Describes characteristics of the waypoint for routing purposes.
+ * The lane type blocked by the incident.
  */
-export type WaypointKind = "Break" | "Via";
+export type BlockedLane = "left" | "left center" | "left turn lane" | "center" | "right" | "right center" | "right turn lane" | "hov";
 
 /**
  * Configurations for built-in route providers.
@@ -477,41 +477,6 @@ export interface TripProgress {
     durationRemaining: number;
 }
 
-/**
- * Controls filtering/post-processing of user course by the [`NavigationController`].
- */
-export type CourseFiltering = "SnapToRoute" | "Raw";
-
-export interface SerializableNavigationControllerConfig {
-    /**
-     * Configures when navigation advances to the next waypoint in the route.
-     */
-    waypointAdvance: WaypointAdvanceMode;
-    /**
-     * Configures when navigation advances to the next step in the route.
-     */
-    stepAdvanceCondition: SerializableStepAdvanceCondition;
-    /**
-     * A special advance condition used for the final 2 route steps (last and arrival).
-     *
-     * This exists because several of our step advance conditions require entry and
-     * exit from a step\'s geometry. The end of the route/arrival doesn\'t always accommodate
-     * the expected location updates for the core step advance condition.
-     */
-    arrivalStepAdvanceCondition: SerializableStepAdvanceCondition;
-    /**
-     * Configures when the user is deemed to be off course.
-     *
-     * NOTE: This is distinct from the action that is taken.
-     * It is only the determination that the user has deviated from the expected route.
-     */
-    routeDeviationTracking: RouteDeviationTracking;
-    /**
-     * Configures how the heading component of the snapped location is reported in [`TripState`].
-     */
-    snappedLocationCourseFiltering: CourseFiltering;
-}
-
 /**
  * Controls when a waypoint should be marked as complete.
  *
@@ -561,14 +526,47 @@ export interface TripSummary {
     endedAt: Date | null;
 }
 
+/**
+ * Controls filtering/post-processing of user course by the [`NavigationController`].
+ */
+export type CourseFiltering = "SnapToRoute" | "Raw";
+
+export interface SerializableNavigationControllerConfig {
+    /**
+     * Configures when navigation advances to the next waypoint in the route.
+     */
+    waypointAdvance: WaypointAdvanceMode;
+    /**
+     * Configures when navigation advances to the next step in the route.
+     */
+    stepAdvanceCondition: SerializableStepAdvanceCondition;
+    /**
+     * A special advance condition used for the final 2 route steps (last and arrival).
+     *
+     * This exists because several of our step advance conditions require entry and
+     * exit from a step\'s geometry. The end of the route/arrival doesn\'t always accommodate
+     * the expected location updates for the core step advance condition.
+     */
+    arrivalStepAdvanceCondition: SerializableStepAdvanceCondition;
+    /**
+     * Configures when the user is deemed to be off course.
+     *
+     * NOTE: This is distinct from the action that is taken.
+     * It is only the determination that the user has deviated from the expected route.
+     */
+    routeDeviationTracking: RouteDeviationTracking;
+    /**
+     * Configures how the heading component of the snapped location is reported in [`TripState`].
+     */
+    snappedLocationCourseFiltering: CourseFiltering;
+}
+
 /**
  * Controls how simulated locations deviate from the actual route line.
  * This simulates real-world GPS behavior where readings often have systematic bias.
  */
 export type LocationBias = { Left: number } | { Right: number } | { Random: number } | "None";
 
-export type SimulationError = { PolylineError: { error: string } } | "NotEnoughPoints";
-
 /**
  * The current state of the simulation.
  */
@@ -578,6 +576,52 @@ export interface LocationSimulationState {
     bias: LocationBias;
 }
 
+export type SimulationError = { PolylineError: { error: string } } | "NotEnoughPoints";
+
+/**
+ * A set of optional filters to exclude candidate edges based on their attributes.
+ */
+export interface ValhallaLocationSearchFilter {
+    /**
+     * Whether to exclude roads marked as tunnels.
+     */
+    exclude_tunnel?: boolean;
+    /**
+     * Whether to exclude roads marked as bridges.
+     */
+    exclude_bridge?: boolean;
+    /**
+     * Whether to exclude roads with tolls.
+     */
+    exclude_tolls?: boolean;
+    /**
+     * Whether to exclude ferries.
+     */
+    exclude_ferry?: boolean;
+    /**
+     * Whether to exclude roads marked as ramps.
+     */
+    exclude_ramp?: boolean;
+    /**
+     * Whether to exclude roads marked as closed due to a live traffic closure.
+     */
+    exclude_closures?: boolean;
+    /**
+     * The lowest road class allowed.
+     */
+    min_road_class?: ValhallaRoadClass;
+    /**
+     * The highest road class allowed.
+     */
+    max_road_class?: ValhallaRoadClass;
+    /**
+     * If specified, will only consider edges that are on or traverse the passed floor level.
+     * It will set `search_cutoff` to a default value of 300 meters if no cutoff value is passed.
+     * Additionally, if a `search_cutoff` is passed, it will be clamped to 1000 meters.
+     */
+    level?: number;
+}
+
 /**
  * Specifies a preferred side for departing from / arriving at a location.
  *
@@ -589,6 +633,13 @@ export interface LocationSimulationState {
  */
 export type ValhallaWaypointPreferredSide = "same" | "opposite" | "either";
 
+/**
+ * A road class in the Valhalla taxonomy.
+ *
+ * These are ordered from highest (fastest travel speed) to lowest.
+ */
+export type ValhallaRoadClass = "motorway" | "trunk" | "primary" | "secondary" | "tertiary" | "unclassified" | "residential" | "service_other";
+
 /**
  * Waypoint properties supported by Valhalla servers.
  *
@@ -687,57 +738,6 @@ export interface ValhallaWaypointProperties {
     search_filter: ValhallaLocationSearchFilter | undefined;
 }
 
-/**
- * A road class in the Valhalla taxonomy.
- *
- * These are ordered from highest (fastest travel speed) to lowest.
- */
-export type ValhallaRoadClass = "motorway" | "trunk" | "primary" | "secondary" | "tertiary" | "unclassified" | "residential" | "service_other";
-
-/**
- * A set of optional filters to exclude candidate edges based on their attributes.
- */
-export interface ValhallaLocationSearchFilter {
-    /**
-     * Whether to exclude roads marked as tunnels.
-     */
-    exclude_tunnel?: boolean;
-    /**
-     * Whether to exclude roads marked as bridges.
-     */
-    exclude_bridge?: boolean;
-    /**
-     * Whether to exclude roads with tolls.
-     */
-    exclude_tolls?: boolean;
-    /**
-     * Whether to exclude ferries.
-     */
-    exclude_ferry?: boolean;
-    /**
-     * Whether to exclude roads marked as ramps.
-     */
-    exclude_ramp?: boolean;
-    /**
-     * Whether to exclude roads marked as closed due to a live traffic closure.
-     */
-    exclude_closures?: boolean;
-    /**
-     * The lowest road class allowed.
-     */
-    min_road_class?: ValhallaRoadClass;
-    /**
-     * The highest road class allowed.
-     */
-    max_road_class?: ValhallaRoadClass;
-    /**
-     * If specified, will only consider edges that are on or traverse the passed floor level.
-     * It will set `search_cutoff` to a default value of 300 meters if no cutoff value is passed.
-     * Additionally, if a `search_cutoff` is passed, it will be clamped to 1000 meters.
-     */
-    level?: number;
-}
-
 /**
  * The event type.
  *
@@ -781,6 +781,11 @@ export interface OsrmWaypointProperties {
     distance: number | undefined;
 }
 
+/**
+ * Determines if the user has deviated from the expected route.
+ */
+export type RouteDeviationTracking = "None" | { StaticThreshold: { minimumHorizontalAccuracy: number; maxAcceptableDeviation: number } };
+
 /**
  * Status information that describes whether the user is proceeding according to the route or not.
  *
@@ -789,11 +794,6 @@ export interface OsrmWaypointProperties {
  */
 export type RouteDeviation = "NoDeviation" | { OffRoute: { deviationFromRouteLine: number } };
 
-/**
- * Determines if the user has deviated from the expected route.
- */
-export type RouteDeviationTracking = "None" | { StaticThreshold: { minimumHorizontalAccuracy: number; maxAcceptableDeviation: number } };
-
 export type SerializableStepAdvanceCondition = "Manual" | { DistanceToEndOfStep: { distance: number; minimumHorizontalAccuracy: number } } | { DistanceFromStep: { distance: number; minimumHorizontalAccuracy: number; calculateWhileOffRoute: boolean } } | { DistanceEntryExit: { distanceToEndOfStep: number; distanceAfterEndStep: number; minimumHorizontalAccuracy: number; hasReachedEndOfCurrentStep: boolean } } | { DistanceEntryAndSnappedExit: { distanceToEndOfStep: number; distanceAfterEndStep: number; minimumHorizontalAccuracy: number; hasReachedEndOfCurrentStep: boolean } } | { OrAdvanceConditions: { conditions: SerializableStepAdvanceCondition[] } } | { AndAdvanceConditions: { conditions: SerializableStepAdvanceCondition[] } };
 
 

package/package.json

@@ -7,7 +7,7 @@
     "Luke Seelenbinder <luke@stadiamaps.com>"
   ],
   "description": "The core of modern turn-by-turn navigation.",
-  "version": "0.47.1",
+  "version": "0.47.2",
   "license": "BSD-3-Clause",
   "repository": {
     "type": "git",