@arcgis/core/core/urlUtils.d.ts

ArcGIS Maps SDK for JavaScript: A complete 2D and 3D mapping and data visualization API

/**
 * Utility methods for working with URLs.
 *
 * @since 4.0
 * @see [esriConfig.request](https://developers.arcgis.com/javascript/latest/references/core/config/#Config-request)
 * @see [Guide topic - Proxy pages](https://developers.arcgis.com/javascript/latest/proxies/)
 */

/**
 * Converts the URL arguments to an object representation.
 *
 * @param url - The input URL.
 * @returns Returns an object representing the URL, its parameters, and parameter values.
 *                  The specification of the object is the following:
 * Property | Type | Description
 * ---------|------|------------
 * path | String | The path of the given URL.
 * query | Object | An object whose properties and values are the parameters and parameter values of the given URL.
 * @example
 * let myObject = urlUtils.urlToObject("http://www.myworld.com?state_name=Ohio&city_name=Akron");
 *   // The value of my Object is...
 *   // { path: "http://www.myworld.com", query: {state_name: "Ohio", city_name: "Akron"} }
 */
export function urlToObject(url: string | null | undefined): any | null;

/**
 * Adds a proxy to the given url based on the proxy rules defined in `esriConfig.request.proxyRules`.
 * If no proxy rule matches, and `force` is true, the global proxy defined in `esriConfig.request.proxyUrl` is used.
 *
 * @param url - The URL to which the proxy will be added.
 * @param force - = false - If true, the global proxy defined in `esriConfig.request.proxyUrl` is used when no proxy rule matches.
 * @returns The URL with the proxy added if applicable.
 * @since 5.0
 */
export function addProxy(url: string, force?: boolean): string;

/**
 * Adds the given proxy rule to the proxy rules list: `esriConfig.request.proxyRules`.
 *
 * @param rule - An object specifying a URL that should use the proxy. See the
 *                      object specification table below for the required properties of this object.
 * @returns The index of the proxy rule in the `esriConfig.request.proxyRules` array.
 * @see [esriConfig.request](https://developers.arcgis.com/javascript/latest/references/core/config/#Config-request)
 */
export function addProxyRule(rule: ProxyRule): number;

/**
 * Returns the proxy rule that matches the given URL.
 *
 * @param url - The URL of the resources accessed via proxy.
 * @returns The proxy rule object as defined in `esriConfig.request.proxyRules`.
 * @see [esriConfig.request](https://developers.arcgis.com/javascript/latest/references/core/config/#Config-request)
 */
export function getProxyRule(url: string): ProxyRule | null | undefined;

/**
 * Tests whether a URL uses the data protocol.
 *
 * This will return `true` if the URL starts with `data:`.
 *
 * @param url - The URL to test.
 * @returns Returns `true` if the url uses the data protocol, `false` otherwise.
 * @since 4.32
 */
export function isDataProtocol(url: string | null | undefined): boolean;

/**
 * Converts a base64 encoded data url to an ArrayBuffer.
 *
 * @param dataUrl - The data URL.
 * @returns The array buffer with the data URL encoded as binary data.
 * @since 4.33
 */
export function dataToArrayBuffer(dataUrl: string): ArrayBuffer | null | undefined;

/**
 * Converts a base64 encoded data url to a Blob.
 *
 * @param dataUrl - The data URL.
 * @returns The blob with the data URL encoded as binary data.
 * @since 4.33
 */
export function dataToBlob(dataUrl: string): Blob | null | undefined;

/**
 * Trigger a browser file download from a base64 encoded data URL.
 *
 * @param dataUrl - The data URL.
 * @param filename - The filename.
 * @since 4.33
 */
export function downloadDataAsFile(dataUrl: string, filename: string): void;

/**
 * Trigger a browser file download from a data URL encoded as binary data.
 *
 * @param blob - The data URL to download (as binary data.
 * @param filename - The filename.
 * @since 4.33
 * @see [dataToBlob()](https://developers.arcgis.com/javascript/latest/references/core/core/urlUtils/#dataToBlob)
 */
export function downloadBlobAsFile(blob: Blob, filename: string): void;

/**
 * Tests whether a URL uses the https protocol.
 *
 * This will return `true` if the URL starts with the https protocol, or if
 * the URL is protocol relative and the application is running on https.
 *
 * @param url - The URL to test.
 * @returns Returns `true` if the URL uses the https protocol, `false` otherwise.
 * @since 4.32
 */
export function isHTTPSProtocol(url: string | null | undefined): boolean;

/**
 * Converts the URL arguments to an object representation.
 *
 * @see [urlToObject()](https://developers.arcgis.com/javascript/latest/references/core/core/urlUtils/#urlToObject)
 */
export interface UrlObject {
  /** the url path. */
  path: string;
  /** the url query. */
  query?: Record<string, string>;
  /** the url hash. */
  hash?: string;
}

/**
 * A proxy rule that matches a URL to a proxy URL.
 *
 * @see [getProxyRule()](https://developers.arcgis.com/javascript/latest/references/core/core/urlUtils/#getProxyRule)
 */
export interface ProxyRule {
  /** The URL of the proxy. */
  proxyUrl: string;
  /**
   * The URL prefix of the resources that should be accessed
   *                                through the given proxy.
   */
  urlPrefix: string;
}