@stadiamaps/ferrostar 0.42.0 → 0.44.0

package/ferrostar.d.ts

@@ -399,6 +399,28 @@ export type WaypointKind = "Break" | "Via";
 export interface Waypoint {
     coordinate: GeographicCoordinate;
     kind: WaypointKind;
+    /**
+     * 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
+     *
+     * 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.
+     */
+    properties: number[] | undefined;
 }
 
 /**
@@ -416,19 +438,173 @@ export interface GeographicCoordinate {
 }
 
 /**
- * Status information that describes whether the user is proceeding according to the route or not.
+ * 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;
+}
+
+/**
+ * A road class in the Valhalla taxonomy.
  *
- * 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.
+ * These are ordered from highest (fastest travel speed) to lowest.
  */
-export type RouteDeviation = "NoDeviation" | { OffRoute: { deviationFromRouteLine: number } };
+export type ValhallaRoadClass = "motorway" | "trunk" | "primary" | "secondary" | "tertiary" | "unclassified" | "residential" | "service_other";
 
 /**
- * Determines if the user has deviated from the expected route.
+ * Specifies a preferred side for departing from / arriving at a location.
+ *
+ * Examples:
+ * - Germany drives on the right side of the road. A value of `same` will only allow leaving
+ *   or arriving at a location such that it is on your right.
+ * - Australia drives on the left side of the road. Passing a value of `same` will only allow
+ *   leaving or arriving at a location such that it is on your left.
  */
-export type RouteDeviationTracking = "None" | { StaticThreshold: { minimumHorizontalAccuracy: number; maxAcceptableDeviation: number } };
+export type ValhallaWaypointPreferredSide = "same" | "opposite" | "either";
+
+/**
+ * Waypoint properties supported by Valhalla servers.
+ *
+ * Our docstrings are short here, since Valhalla is the final authority.
+ * Refer to <https://valhalla.github.io/valhalla/api/turn-by-turn/api-reference/#locations>
+ * for more details, including default values.
+ * Other Valhalla-based APIs such as Stadia Maps or Mapbox may have slightly different defaults.
+ * Refer to your vendor\'s documentation when in doubt.
+ *
+ * NOTE: Waypoint properties will NOT currently be echoed back in OSRM format,
+ * so these are sent to the server one time.
+ */
+export interface ValhallaWaypointProperties {
+    /**
+     * Preferred direction of travel for the start from the location.
+     */
+    heading: number | undefined;
+    /**
+     * How close in degrees a given street\'s angle must be
+     * in order for it to be considered as in the same direction of the heading parameter.
+     */
+    heading_tolerance: number | undefined;
+    /**
+     * Minimum number of nodes (intersections) reachable for a given edge
+     * (road between intersections) to consider that edge as belonging to a connected region.
+     * Disconnected edges are ignored.
+     */
+    minimum_reachability: number | undefined;
+    /**
+     * The number of meters about this input location within which edges
+     * will be considered as candidates for said location.
+     * If there are no candidates within this distance,
+     * it will return the closest candidate within reason.
+     */
+    radius: number | undefined;
+    /**
+     * Determines whether the location should be visited from the same, opposite or either side of the road,
+     * with respect to the side of the road the given locale drives on.
+     *
+     * NOTE: If the location is not offset from the road centerline
+     * or is very close to an intersection, this option has no effect!
+     */
+    preferred_side: ValhallaWaypointPreferredSide | undefined;
+    /**
+     * Latitude of the map location in degrees.
+     *
+     * If provided, the waypoint location will still be used for routing,
+     * but these coordinates will determine the side of the street.
+     */
+    display_coordinate: GeographicCoordinate | undefined;
+    /**
+     * The cutoff at which we will assume the input is too far away from civilization
+     * to be worth correlating to the nearest graph elements.
+     */
+    search_cutoff: number | undefined;
+    /**
+     * During edge correlation, this is the tolerance used to determine whether to snap
+     * to the intersection rather than along the street.
+     * If the snap location is within this distance from the intersection,
+     * the intersection is used instead.
+     */
+    node_snap_tolerance: number | undefined;
+    /**
+     * A tolerance in meters from the edge centerline used for determining the side of the street
+     * that the location is on.
+     * If the distance to the centerline is less than this tolerance,
+     * no side will be inferred.
+     * Otherwise, the left or right side will be selected depending on the direction of travel.
+     */
+    street_side_tolerance: number | undefined;
+    /**
+     * The max distance in meters that the input coordinates or display lat/lon can be
+     * from the edge centerline for them to be used for determining the side of the street.
+     * Beyond this distance, no street side is inferred.
+     */
+    street_side_max_distance: number | undefined;
+    /**
+     * Disables the `preferred_side` when set to `same` or `opposite`
+     * if the edge has a road class less than that provided by `street_side_cutoff`.
+     */
+    street_side_cutoff: ValhallaRoadClass | undefined;
+    /**
+     * A set of optional filters to exclude candidate edges based on their attributes.
+     */
+    search_filter: ValhallaLocationSearchFilter | undefined;
+}
 
-export type SerializableStepAdvanceCondition = "Manual" | { DistanceToEndOfStep: { distance: number; minimumHorizontalAccuracy: number } } | { DistanceFromStep: { distance: number; minimumHorizontalAccuracy: number } } | { DistanceEntryExit: { distanceToEndOfStep: number; distanceAfterEndStep: number; minimumHorizontalAccuracy: number; hasReachedEndOfCurrentStep: boolean } } | { OrAdvanceConditions: { conditions: SerializableStepAdvanceCondition[] } } | { AndAdvanceConditions: { conditions: SerializableStepAdvanceCondition[] } };
+/**
+ * Waypoint properties parsed from an OSRM-compatible server response.
+ *
+ * NOTE: Some servers (such as Valhalla) may support additional parameters at request time
+ * which are _not_ echoed back in the response time.
+ * This is unfortunate; PRs upstream would likely be welcomed!
+ * Similarly, if your server is OSRM-compatible and returns additional attributes,
+ * feel free to open a PR to include these as optional properties.
+ */
+export interface OsrmWaypointProperties {
+    /**
+     * The name of the street that the waypoint snapped to.
+     */
+    name: string | undefined;
+    /**
+     * The distance (in meters) between the snapped point and the input coordinate.
+     */
+    distance: number | undefined;
+}
 
 /**
  * The event type.
@@ -453,6 +629,8 @@ export interface NavigationRecordingEvent {
     event_data: NavigationRecordingEventData;
 }
 
+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[] } };
+
 export interface SerializableNavigationControllerConfig {
     /**
      * Configures when navigation advances to the next waypoint in the route.
@@ -502,7 +680,7 @@ export interface SerializableNavigationControllerConfig {
  * manually advancing to the next step does not *necessarily* imply
  * that the waypoint will be marked as complete!
  */
-export type WaypointAdvanceMode = { WaypointWithinRange: number };
+export type WaypointAdvanceMode = { WaypointWithinRange: number } | { WaypointAlongAdvancingStep: number };
 
 /**
  * Controls filtering/post-processing of user course by the [`NavigationController`].
@@ -564,9 +742,21 @@ export interface TripProgress {
 export interface SerializableNavState {
     tripState: TripState;
     stepAdvanceCondition: SerializableStepAdvanceCondition;
-    recordingEvents: NavigationRecordingEvent[] | undefined;
 }
 
+/**
+ * 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";
 
 /**
@@ -595,7 +785,6 @@ export class NavigationController {
   getInitialState(location: any): any;
   advanceToNextStep(state: any): any;
   updateUserLocation(location: any, state: any): any;
-  getRecording(events: any): any;
 }
 /**
  * A WebAssembly-compatible wrapper for `NavigationReplay` that exposes its functionality as a JavaScript object.
@@ -612,6 +801,30 @@ export class NavigationReplay {
   getInitialTimestamp(): any;
   getInitialRoute(): any;
 }
+/**
+ * JavaScript wrapper for `NavigationSession` (simple version).
+ * This wrapper provides basic navigation functionality without observers.
+ */
+export class NavigationSession {
+  free(): void;
+  constructor(route: any, config: any);
+  getInitialState(location: any): any;
+  advanceToNextStep(state: any): any;
+  updateUserLocation(location: any, state: any): any;
+}
+/**
+ * JavaScript wrapper for `NavigationSession` with recording capabilities.
+ * This version includes a NavigationRecorder observer and provides direct access to recording functionality.
+ */
+export class NavigationSessionRecording {
+  free(): void;
+  constructor(route: any, config: any);
+  getInitialState(location: any): any;
+  advanceToNextStep(state: any): any;
+  updateUserLocation(location: any, state: any): any;
+  getRecording(): any;
+  getEvents(): any;
+}
 /**
  * JavaScript wrapper for `RouteAdapter`.
  */

package/ferrostar_bg.js

@@ -319,17 +319,6 @@ export class NavigationController {
         }
         return takeFromExternrefTable0(ret[0]);
     }
-    /**
-     * @param {any} events
-     * @returns {any}
-     */
-    getRecording(events) {
-        const ret = wasm.navigationcontroller_getRecording(this.__wbg_ptr, events);
-        if (ret[2]) {
-            throw takeFromExternrefTable0(ret[1]);
-        }
-        return takeFromExternrefTable0(ret[0]);
-    }
 }
 
 const NavigationReplayFinalization = (typeof FinalizationRegistry === 'undefined')
@@ -419,6 +408,164 @@ export class NavigationReplay {
     }
 }
 
+const NavigationSessionFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_navigationsession_free(ptr >>> 0, 1));
+/**
+ * JavaScript wrapper for `NavigationSession` (simple version).
+ * This wrapper provides basic navigation functionality without observers.
+ */
+export class NavigationSession {
+
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        NavigationSessionFinalization.unregister(this);
+        return ptr;
+    }
+
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_navigationsession_free(ptr, 0);
+    }
+    /**
+     * @param {any} route
+     * @param {any} config
+     */
+    constructor(route, config) {
+        const ret = wasm.navigationsession_new(route, config);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        this.__wbg_ptr = ret[0] >>> 0;
+        NavigationSessionFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+    /**
+     * @param {any} location
+     * @returns {any}
+     */
+    getInitialState(location) {
+        const ret = wasm.navigationsession_getInitialState(this.__wbg_ptr, location);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    /**
+     * @param {any} state
+     * @returns {any}
+     */
+    advanceToNextStep(state) {
+        const ret = wasm.navigationsession_advanceToNextStep(this.__wbg_ptr, state);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    /**
+     * @param {any} location
+     * @param {any} state
+     * @returns {any}
+     */
+    updateUserLocation(location, state) {
+        const ret = wasm.navigationsession_updateUserLocation(this.__wbg_ptr, location, state);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+}
+
+const NavigationSessionRecordingFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_navigationsessionrecording_free(ptr >>> 0, 1));
+/**
+ * JavaScript wrapper for `NavigationSession` with recording capabilities.
+ * This version includes a NavigationRecorder observer and provides direct access to recording functionality.
+ */
+export class NavigationSessionRecording {
+
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        NavigationSessionRecordingFinalization.unregister(this);
+        return ptr;
+    }
+
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_navigationsessionrecording_free(ptr, 0);
+    }
+    /**
+     * @param {any} route
+     * @param {any} config
+     */
+    constructor(route, config) {
+        const ret = wasm.navigationsessionrecording_new(route, config);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        this.__wbg_ptr = ret[0] >>> 0;
+        NavigationSessionRecordingFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+    /**
+     * @param {any} location
+     * @returns {any}
+     */
+    getInitialState(location) {
+        const ret = wasm.navigationsessionrecording_getInitialState(this.__wbg_ptr, location);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    /**
+     * @param {any} state
+     * @returns {any}
+     */
+    advanceToNextStep(state) {
+        const ret = wasm.navigationsessionrecording_advanceToNextStep(this.__wbg_ptr, state);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    /**
+     * @param {any} location
+     * @param {any} state
+     * @returns {any}
+     */
+    updateUserLocation(location, state) {
+        const ret = wasm.navigationsessionrecording_updateUserLocation(this.__wbg_ptr, location, state);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    /**
+     * @returns {any}
+     */
+    getRecording() {
+        const ret = wasm.navigationsessionrecording_getRecording(this.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    /**
+     * @returns {any}
+     */
+    getEvents() {
+        const ret = wasm.navigationsessionrecording_getEvents(this.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+}
+
 const RouteAdapterFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_routeadapter_free(ptr >>> 0, 1));
@@ -515,7 +662,7 @@ export function __wbg_entries_3265d4158b33e5dc(arg0) {
     return ret;
 };
 
-export function __wbg_getRandomValues_38097e921c2494c3() { return handleError(function (arg0, arg1) {
+export function __wbg_getRandomValues_38a1ff1ea09f6cc7() { return handleError(function (arg0, arg1) {
     globalThis.crypto.getRandomValues(getArrayU8FromWasm0(arg0, arg1));
 }, arguments) };
 

package/package.json

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