@stadiamaps/ferrostar 0.35.0 → 0.36.0

package/ferrostar.d.ts

@@ -16,164 +16,546 @@ export function locationSimulationFromPolyline(polyline: string, precision: numb
  * JavaScript wrapper for `advance_location_simulation`.
  */
 export function advanceLocationSimulation(state: any): any;
+/**
+ * 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 content of a visual instruction.
+ */
 export interface VisualInstructionContent {
+    /**
+     * The text to display.
+     */
     text: string;
+    /**
+     * A standardized maneuver type (if any).
+     */
     maneuverType: ManeuverType | undefined;
+    /**
+     * A standardized maneuver modifier (if any).
+     */
     maneuverModifier: ManeuverModifier | undefined;
+    /**
+     * If applicable, the number of degrees you need to go around the roundabout before exiting.
+     *
+     * For example, entering and exiting the roundabout in the same direction of travel
+     * (as if you had gone straight, apart from the detour)
+     * would be an exit angle of 180 degrees.
+     */
     roundaboutExitDegrees: number | undefined;
+    /**
+     * Detailed information about the lanes. This is typically only present in sub-maneuver instructions.
+     */
     laneInfo: LaneInfo[] | undefined;
+    /**
+     * The exit number (or similar identifier like \"8B\").
+     */
     exitNumbers: string[];
 }
 
+/**
+ * The content of a visual instruction.
+ */
 export interface LaneInfo {
     active: boolean;
     directions: string[];
     activeDirection: string | undefined;
 }
 
+/**
+ * An incident affecting the free flow of traffic,
+ * such as constructions, accidents, and congestion.
+ */
 export interface Incident {
+    /**
+     * A unique identifier for the incident.
+     */
     id: string;
+    /**
+     * The type of incident.
+     */
     incidentType: IncidentType;
+    /**
+     * A short description of the incident.
+     */
     description: string | undefined;
+    /**
+     * A longer description of the incident.
+     */
     longDescription: string | undefined;
+    /**
+     * The time at which the incident was *last* created.
+     *
+     * NB: This can change throughout the life of the incident.
+     */
     creationTime: Date | null;
+    /**
+     * The time at which the incident started or is expected to start (ex: planned closure).
+     */
     startTime: Date | null;
+    /**
+     * The time at which the incident ended or is expected to end.
+     */
     endTime: Date | null;
+    /**
+     * The level of impact to traffic.
+     */
     impact: Impact | undefined;
+    /**
+     * Lanes which are blocked by the incident.
+     */
     lanesBlocked: BlockedLane[];
+    /**
+     * Info about the amount of congestion on the road around the incident.
+     */
     congestion: Congestion | undefined;
+    /**
+     * Is the road completely closed?
+     */
     closed: boolean | undefined;
+    /**
+     * The index into the [`RouteStep`] geometry where the incident starts.
+     */
     geometryIndexStart: number;
+    /**
+     * The index into the [`RouteStep`] geometry where the incident ends.
+     */
     geometryIndexEnd: number | undefined;
+    /**
+     * Optional additional information about the type of incident (free-form text).
+     */
     subType: string | undefined;
+    /**
+     * Optional descriptions about the type of incident (free-form text).
+     */
     subTypeDescription: string | undefined;
+    /**
+     * The ISO 3166-1 alpha-2 code of the country in which the incident occurs.
+     */
     iso31661Alpha2: string | undefined;
+    /**
+     * The ISO 3166-1 alpha-3 code of the country in which the incident occurs.
+     */
     iso31661Alpha3: string | undefined;
+    /**
+     * A list of road names affected by the incident.
+     */
     affectedRoadNames: string[];
+    /**
+     * The bounding box over which the incident occurs.
+     */
     bbox: BoundingBox | undefined;
 }
 
+/**
+ * Details about congestion for an incident.
+ */
 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;
 }
 
+/**
+ * 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 impact of the incident that has occurred.
+ */
 export type Impact = "unknown" | "critical" | "major" | "minor" | "low";
 
+/**
+ * The type of incident that has occurred.
+ */
 export type IncidentType = "accident" | "congestion" | "construction" | "disabled_vehicle" | "lane_restriction" | "mass_transit" | "miscellaneous" | "other_news" | "planned_event" | "road_closure" | "road_hazard" | "weather";
 
+/**
+ * Additional information to further specify a [`ManeuverType`].
+ */
 export type ManeuverModifier = "uturn" | "sharp right" | "right" | "slight right" | "straight" | "slight left" | "left" | "sharp left";
 
+/**
+ * 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";
 
+/**
+ * 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 {
+    /**
+     * 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;
+    /**
+     * How far (in meters) from the upcoming maneuver the instruction should start being displayed
+     */
     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;
 }
 
+/**
+ * A maneuver (such as a turn or merge) followed by travel of a certain distance until reaching
+ * the next step.
+ */
 export interface RouteStep {
+    /**
+     * The full route geometry for this step.
+     */
     geometry: GeographicCoordinate[];
+    /**
+     * The distance, in meters, to travel along the route after the maneuver to reach the next step.
+     */
     distance: number;
+    /**
+     * The estimated duration, in seconds, that it will take to complete this step.
+     */
     duration: number;
+    /**
+     * The name of the road being traveled on (useful for certain UI styles).
+     */
     roadName: string | undefined;
+    /**
+     * A list of exits (name or number).
+     */
     exits: string[];
+    /**
+     * A description of the maneuver (ex: \"Turn wright onto main street\").
+     *
+     * Note for UI implementers: the context this appears in (or doesn\'t)
+     * depends somewhat on your use case and routing engine.
+     * For example, this field is useful as a written instruction in Valhalla.
+     */
     instruction: string;
+    /**
+     * A list of instructions for visual display (usually as banners) at specific points along the step.
+     */
     visualInstructions: VisualInstruction[];
+    /**
+     * A list of prompts to announce (via speech synthesis) at specific points along the step.
+     */
     spokenInstructions: SpokenInstruction[];
+    /**
+     * A list of json encoded strings representing annotations between each coordinate along the step.
+     */
     annotations: string[] | undefined;
+    /**
+     * A list of incidents that occur along the step.
+     */
     incidents: Incident[];
 }
 
+/**
+ * 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 location of the user that is navigating.
+ *
+ * In addition to coordinates, this includes estimated accuracy and course information,
+ * which can influence navigation logic and UI.
+ *
+ * NOTE: Heading is absent on purpose.
+ * Heading updates are not related to a change in the user\'s location.
+ */
 export interface UserLocation {
     coordinates: GeographicCoordinate;
+    /**
+     * The estimated accuracy of the coordinate (in meters)
+     */
     horizontalAccuracy: number;
     courseOverGround: CourseOverGround | undefined;
     timestamp: { secs_since_epoch: number; nanos_since_epoch: number };
     speed: Speed | undefined;
 }
 
+/**
+ * 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 direction in which the user/device is observed to be traveling.
+ */
 export interface CourseOverGround {
+    /**
+     * The direction in which the user\'s device is traveling, measured in clockwise degrees from
+     * true north (N = 0, E = 90, S = 180, W = 270).
+     */
     degrees: number;
+    /**
+     * The accuracy of the course value, measured in degrees.
+     */
     accuracy: number | undefined;
 }
 
+/**
+ * A geographic bounding box defined by its corners.
+ */
 export interface BoundingBox {
+    /**
+     * The southwest corner of the bounding box.
+     */
     sw: GeographicCoordinate;
+    /**
+     * The northeast corner of the bounding box.
+     */
     ne: GeographicCoordinate;
 }
 
+/**
+ * Describes characteristics of the waypoint for the routing backend.
+ */
 export type WaypointKind = "Break" | "Via";
 
+/**
+ * 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 Waypoint {
     coordinate: GeographicCoordinate;
     kind: WaypointKind;
 }
 
+/**
+ * A geographic coordinate in WGS84.
+ */
 export interface GeographicCoordinate {
+    /**
+     * The latitude (in degrees).
+     */
     lat: number;
+    /**
+     * The Longitude (in degrees).
+     */
     lng: number;
 }
 
-export type RouteDeviation = "NoDeviation" | { OffRoute: { deviationFromRouteLine: number } };
-
-export type RouteDeviationTracking = "None" | { StaticThreshold: { minimumHorizontalAccuracy: number; maxAcceptableDeviation: number } };
-
-export type SimulationError = { PolylineError: { error: string } } | "NotEnoughPoints";
-
-export type LocationBias = { Left: number } | { Right: number } | { Random: number } | "None";
-
-export interface LocationSimulationState {
-    current_location: UserLocation;
-    remaining_locations: GeographicCoordinate[];
-    bias: LocationBias;
-}
-
 export interface NavigationControllerConfig {
+    /**
+     * Configures when navigation advances to next waypoint in the route.
+     */
     waypointAdvance: WaypointAdvanceMode;
+    /**
+     * Configures when navigation advances to the next step in the route.
+     */
     stepAdvance: StepAdvanceMode;
+    /**
+     * 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.
+ *
+ * While a route may consist of thousands of points, waypoints are special.
+ * A simple trip will have only one waypoint: the final destination.
+ * A more complex trip may have several intermediate stops.
+ * Just as the navigation state keeps track of which steps remain in the route,
+ * it also tracks which waypoints are still remaining.
+ *
+ * Tracking waypoints enables Ferrostar to reroute users when they stray off the route line.
+ * The waypoint advance mode specifies how the framework decides
+ * that a waypoint has been visited (and is removed from the list).
+ *
+ * NOTE: Advancing to the next *step* and advancing to the next *waypoint*
+ * are separate processes.
+ * This will not normally cause any issues, but keep in mind that
+ * manually advancing to the next step does not *necessarily* imply
+ * that the waypoint will be marked as complete!
+ */
 export type WaypointAdvanceMode = { WaypointWithinRange: number };
 
+/**
+ * Special conditions which alter the normal step advance logic,
+ */
 export type SpecialAdvanceConditions = { AdvanceAtDistanceFromEnd: number } | { MinimumDistanceFromCurrentStepLine: number };
 
+/**
+ * The step advance mode describes when the current maneuver has been successfully completed,
+ * and we should advance to the next step.
+ */
 export type StepAdvanceMode = "Manual" | { DistanceToEndOfStep: { distance: number; minimumHorizontalAccuracy: number } } | { RelativeLineStringDistance: { minimumHorizontalAccuracy: number; specialAdvanceConditions: SpecialAdvanceConditions | undefined } };
 
+/**
+ * Controls filtering/post-processing of user course by the [`NavigationController`].
+ */
 export type CourseFiltering = "SnapToRoute" | "Raw";
 
-export type TripState = { Idle: { user_location: UserLocation | undefined } } | { Navigating: { currentStepGeometryIndex: number | undefined; userLocation: UserLocation; snappedUserLocation: UserLocation; remainingSteps: RouteStep[]; remainingWaypoints: Waypoint[]; progress: TripProgress; deviation: RouteDeviation; visualInstruction: VisualInstruction | undefined; spokenInstruction: SpokenInstruction | undefined; annotationJson: string | undefined } } | { Complete: { user_location: UserLocation } };
+/**
+ * The state of a navigation session.
+ *
+ * This is produced by [`NavigationController`](super::NavigationController) methods
+ * including [`get_initial_state`](super::NavigationController::get_initial_state)
+ * and [`update_user_location`](super::NavigationController::update_user_location).
+ */
+export type TripState = { Idle: { user_location: UserLocation | undefined } } | { Navigating: { currentStepGeometryIndex: number | undefined; userLocation: UserLocation; snappedUserLocation: UserLocation; remainingSteps: RouteStep[]; remainingWaypoints: Waypoint[]; progress: TripProgress; summary: TripSummary; deviation: RouteDeviation; visualInstruction: VisualInstruction | undefined; spokenInstruction: SpokenInstruction | undefined; annotationJson: string | undefined } } | { Complete: { user_location: UserLocation; summary: TripSummary } };
 
+/**
+ * Information pertaining to the user\'s full navigation trip. This includes
+ * simple stats like total duration and distance.
+ */
+export interface TripSummary {
+    /**
+     * The total raw distance traveled in the trip, in meters.
+     */
+    distanceTraveled: number;
+    /**
+     * The total snapped distance traveled in the trip, in meters.
+     */
+    snappedDistanceTraveled: number;
+    /**
+     * When the trip was started.
+     */
+    startedAt: Date;
+    /**
+     * When the trip was completed or canceled.
+     */
+    endedAt: Date | null;
+}
+
+/**
+ * High-level state describing progress through a route.
+ */
 export interface TripProgress {
+    /**
+     * The distance to the next maneuver, in meters.
+     */
     distanceToNextManeuver: number;
+    /**
+     * The total distance remaining in the trip, in meters.
+     *
+     * This is the sum of the distance remaining in the current step and the distance remaining in all subsequent steps.
+     */
     distanceRemaining: number;
+    /**
+     * The total duration remaining in the trip, in seconds.
+     */
     durationRemaining: number;
 }
 
+/**
+ * Status information that describes whether the user is proceeding according to the route or not.
+ *
+ * Note that the name is intentionally a bit generic to allow for expansion of other states.
+ * For example, we could conceivably add a \"wrong way\" status in the future.
+ */
+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 SimulationError = { PolylineError: { error: string } } | "NotEnoughPoints";
+
+/**
+ * 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";
+
+/**
+ * The current state of the simulation.
+ */
+export interface LocationSimulationState {
+    current_location: UserLocation;
+    remaining_locations: GeographicCoordinate[];
+    bias: LocationBias;
+}
+
 /**
  * JavaScript wrapper for `NavigationController`.
  */

package/ferrostar_bg.js

@@ -185,6 +185,13 @@ function takeFromExternrefTable0(idx) {
     wasm.__externref_table_dealloc(idx);
     return value;
 }
+
+function passArray8ToWasm0(arg, malloc) {
+    const ptr = malloc(arg.length * 1, 1) >>> 0;
+    getUint8ArrayMemory0().set(arg, ptr / 1);
+    WASM_VECTOR_LEN = arg.length;
+    return ptr;
+}
 /**
  * JavaScript wrapper for `location_simulation_from_coordinates`.
  * @param {any} coordinates
@@ -243,13 +250,6 @@ export function advanceLocationSimulation(state) {
     return ret;
 }
 
-function passArray8ToWasm0(arg, malloc) {
-    const ptr = malloc(arg.length * 1, 1) >>> 0;
-    getUint8ArrayMemory0().set(arg, ptr / 1);
-    WASM_VECTOR_LEN = arg.length;
-    return ptr;
-}
-
 const NavigationControllerFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_navigationcontroller_free(ptr >>> 0, 1));
@@ -394,14 +394,6 @@ export function __wbg_String_8f0eb39a4a4c2f66(arg0, arg1) {
     getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
 };
 
-export function __wbg_String_eecc4a11987127d6(arg0, arg1) {
-    const ret = String(arg1);
-    const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-    const len1 = WASM_VECTOR_LEN;
-    getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
-    getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
-};
-
 export function __wbg_buffer_609cc3eee51ed158(arg0) {
     const ret = arg0.buffer;
     return ret;
@@ -440,6 +432,11 @@ export function __wbg_getRandomValues_bcb4912f16000dc4() { return handleError(fu
     arg0.getRandomValues(arg1);
 }, arguments) };
 
+export function __wbg_getTime_46267b1c24877e30(arg0) {
+    const ret = arg0.getTime();
+    return ret;
+};
+
 export function __wbg_get_67b2ba62fc30de12() { return handleError(function (arg0, arg1) {
     const ret = Reflect.get(arg0, arg1);
     return ret;
@@ -507,6 +504,11 @@ export function __wbg_msCrypto_0a36e2ec3a343d26(arg0) {
     return ret;
 };
 
+export function __wbg_new0_f788a2397c7ca929() {
+    const ret = new Date();
+    return ret;
+};
+
 export function __wbg_new_405e22f390576ce2() {
     const ret = new Object();
     return ret;

package/package.json

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