This is the documentation of version 1.0.0-rc.2. Go to the latest version, 1.0.0-rc.5.

Function withInsertedWaypoint

withInsertedWaypoint(
    route: Route,
    existingWaypoints: WaypointLike[],
    newWaypoint: WaypointLike,
): WaypointLike[]
Returns a new array of waypoints with the new waypoint inserted at the optimal position.

It finds the best insertion index and inserts the waypoint in one step, using findBestWaypointInsertionIndex to find where the waypoint fits most naturally along the route.
Parameters
- route: Route
  The existing calculated route, a Feature with LineString geometry.
- existingWaypoints: WaypointLike[]
  The existing waypoints in order, from origin through intermediate waypoints to destination.
- newWaypoint: WaypointLike
Returns WaypointLike[]
A new array with the waypoint inserted at the optimal position.
Remarks
- It returns a new array and leaves the original waypoints array unmodified.
- It places the waypoint with the same logic as findBestWaypointInsertionIndex.
- It handles all edge cases, such as an empty route or fewer than 2 waypoints.
Example
```
const route: Route = {
  type: 'Feature',
  id: 'route-1',
  geometry: {
    type: 'LineString',
    coordinates: [[4.9, 52.3], [4.95, 52.35], [5.0, 52.4]]
  },
  properties: { ... },
  bbox: [4.9, 52.3, 5.0, 52.4]
};

const waypoints: WaypointLike[] = [
  [4.9, 52.3],   // origin
  [5.0, 52.4]    // destination
];

const newWaypoint: WaypointLike = [4.95, 52.35];

const updatedWaypoints = withInsertedWaypoint(route, waypoints, newWaypoint);
// Returns: [[4.9, 52.3], [4.95, 52.35], [5.0, 52.4]]
```