/**
 * Find routes between two or more locations and optionally get driving directions. The route module
 * uses ArcGIS Server network analysis services to calculate routes. Network analysis services
 * allow you to solve simple routing problems as well as complex ones that take into account
 * multiple stops, barriers, and time windows.
 *
 * To work directly with route, the basic pattern is:
 * 1. Define the URL to the ArcGIS Server REST resource
 * 2. [Configure the parameters](https://developers.arcgis.com/javascript/latest/references/core/rest/support/RouteParameters/)
 * 3. [Solve the route](https://developers.arcgis.com/javascript/latest/references/core/rest/route/#solve) and then specify [what to do with its results](https://developers.arcgis.com/javascript/latest/references/core/rest/support/RouteSolveResult/) and handle any errors that may be returned.
 *
 * @since 4.19
 * @see [RouteResult](https://developers.arcgis.com/javascript/latest/references/core/rest/support/RouteResult/)
 * @see [RouteSolveResult](https://developers.arcgis.com/javascript/latest/references/core/rest/support/RouteSolveResult/)
 * @see [RouteParameters](https://developers.arcgis.com/javascript/latest/references/core/rest/support/RouteParameters/)
 * @see [Esri Directions and Routing Services](https://developers.arcgis.com/en/features/directions/)
 * @see [Sample - Route](https://developers.arcgis.com/javascript/latest/sample-code/route/)
 */
import type RouteParameters from "./support/RouteParameters.js";
import type RouteSolveResult from "./support/RouteSolveResult.js";
import type { RequestOptions } from "../request/types.js";

/**
 * Solves the route against the route layer with the route parameters.
 *
 * @param url - URL to the ArcGIS Server REST resource that represents a network analysis service.
 * @param params - Route parameters used as input to generate the route.
 * @param requestOptions - Additional [options](https://developers.arcgis.com/javascript/latest/references/core/request/#request) to be used for the data request.
 * @returns When resolved, returns an instance of [RouteSolveResult](https://developers.arcgis.com/javascript/latest/references/core/rest/support/RouteSolveResult/).
 * @example
 * const [route, Collection, RouteParameters, Stop] = await $arcgis.import([
 *   "@arcgis/core/rest/route.js",
 *   "@arcgis/core/core/Collection.js",
 *   "@arcgis/core/rest/support/RouteParameters.js",
 *   "@arcgis/core/rest/support/Stop.js"
 * ]);
 *
 * // point the URL to a valid routing service
 * const routeUrl =
 *   "https://route-api.arcgis.com/arcgis/rest/services/World/Route/NAServer/Route_World";
 *
 * // create a Collection of new Stops
 * const stops = new Collection([
 *   new Stop({
 *     geometry: { x: -117.59275, y: 34.06200 },
 *     name: "Ontario Airport"
 *   }),
 *   new Stop({
 *     geometry: { x: -117.19570, y: 34.05609 },
 *     name: "Esri Campus"
 *   })
 * ]);
 *
 * // setup the RouteParameters with API key and Stops
 * const routeParams = new RouteParameters({
 *   // An authorization string used to access the routing service
 *   apiKey: "YOUR_API_KEY",
 *   stops
 * });
 *
 * // solve the route with the RouteParameters
 * function solveRoute() {
 *   route.solve(routeUrl, routeParams).then(showRouteInfo);
 * }
 *
 * // do something useful with the results
 * // like display them to the console
 * function showRouteInfo(routeSolveResult) {
 *   console.log("Show all results: ", routeSolveResult);
 *   console.log("Show the route information: ", routeSolveResult.routeResults[0].route);
 * }
 *
 * solveRoute();
 */
export function solve(url: string, params: RouteParameters, requestOptions?: RequestOptions): Promise<RouteSolveResult>;