Add docs for RequestTransformFunction

GitOrigin-RevId: b9963ac36ff160574670f9ab3a21318ec74ce596

Author: stepankuzmin

src/index.esm.ts

@@ -19,8 +19,7 @@ export type {Event, ErrorEvent} from './util/evented';
 export type {GeoJSONFeature, TargetFeature} from './util/vectortile_to_geojson';
 export type {InteractionEvent} from './ui/interactions';
 export type {PaddingOptions} from './geo/edge_insets';
-export type {RequestParameters} from './util/ajax';
-export type {RequestTransformFunction, ResourceType} from './util/mapbox';
+export type {RequestParameters, RequestTransformFunction, ResourceType} from './util/ajax';
 export type {LngLatLike, LngLatBoundsLike} from './geo/lng_lat';
 
 export type {FeatureSelector} from './style/style';

src/index.ts

@@ -48,8 +48,7 @@ export type {Event, ErrorEvent} from './util/evented';
 export type {GeoJSONFeature, TargetFeature} from './util/vectortile_to_geojson';
 export type {InteractionEvent} from './ui/interactions';
 export type {PaddingOptions} from './geo/edge_insets';
-export type {RequestParameters} from './util/ajax';
-export type {RequestTransformFunction, ResourceType} from './util/mapbox';
+export type {RequestParameters, RequestTransformFunction, ResourceType} from './util/ajax';
 export type {LngLatLike, LngLatBoundsLike} from './geo/lng_lat';
 
 export type {FeatureSelector} from './style/style';

src/types/deprecated-aliases.ts

@@ -2,7 +2,7 @@ import type {GeoJSONFeature} from '../util/vectortile_to_geojson';
 import type {MapOptions} from '../ui/map';
 import type {FeatureSelector} from '../style/style';
 import type {ErrorEvent} from '../util/evented';
-import type {RequestTransformFunction} from '../util/mapbox';
+import type {RequestTransformFunction} from '../util/ajax';
 import type {MapEvent, MapMouseEvent, MapTouchEvent} from '../ui/events';
 import type {
     Source,

src/ui/map.ts

@@ -54,8 +54,7 @@ import type SourceCache from '../source/source_cache';
 import type {MapEventType, MapEventOf} from './events';
 import type {PointLike} from '../types/point-like';
 import type {FeatureState} from '../style-spec/expression/index';
-import type {AJAXError} from '../util/ajax';
-import type {RequestTransformFunction} from '../util/mapbox';
+import type {AJAXError, RequestTransformFunction} from '../util/ajax';
 import type {LngLatLike, LngLatBoundsLike} from '../geo/lng_lat';
 import type {CustomLayerInterface} from '../style/style_layer/custom_style_layer';
 import type {StyleImageInterface, StyleImageMetadata} from '../style/style_image';

src/util/ajax.ts

@@ -11,7 +11,7 @@ import {isMapboxHTTPURL, hasCacheDefeatingSku} from './mapbox_url';
  * @readonly
  * @enum {string}
  */
-const ResourceType = {
+export const ResourceType = {
     Unknown: 'Unknown',
     Style: 'Style',
     Source: 'Source',
@@ -24,48 +24,97 @@ const ResourceType = {
     Model: 'Model'
 } as const;
 
-export {ResourceType};
-
 Object.freeze(ResourceType);
 
 /**
- * A `RequestParameters` object to be returned from Map.options.transformRequest callbacks.
+ * The type of resource being requested in a {@link RequestTransformFunction}.
+ *
+ * @enum {string}
+ * @property {string} Unknown An unknown resource.
+ * @property {string} Style A style resource.
+ * @property {string} Source A source resource.
+ * @property {string} Tile A tile resource.
+ * @property {string} Glyphs A glyphs resource.
+ * @property {string} SpriteImage A sprite image resource.
+ * @property {string} SpriteJSON A sprite JSON resource.
+ * @property {string} Iconset An iconset resource.
+ * @property {string} Image An image resource.
+ * @property {string} Model A model resource.
+ * @see {@link RequestTransformFunction}
+ */
+export type ResourceType = keyof typeof ResourceType;
+
+/**
+ * A `RequestParameters` object to be returned from the {@link Map} `transformRequest` option callback.
  * @typedef {Object} RequestParameters
  * @property {string} url The URL to be requested.
- * @property {Object} headers The headers to be sent with the request.
- * @property {string} method Request method `'GET' | 'POST' | 'PUT'`.
- * @property {string} body Request body.
- * @property {string} type Response body type to be returned `'string' | 'json' | 'arrayBuffer'`.
- * @property {string} credentials `'same-origin'|'include'` Use 'include' to send cookies with cross-origin requests.
- * @property {boolean} collectResourceTiming If true, Resource Timing API information will be collected for these transformed requests and returned in a resourceTiming property of relevant data events.
- * @property {string} referrerPolicy A string representing the request's referrerPolicy. For more information and possible values, see the [Referrer-Policy HTTP header page](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy).
+ * @property {Object} [headers] The headers to be sent with the request.
+ * @property {string} [method='GET'] Request method, one of `'GET' | 'POST' | 'PUT'`.
+ * @property {string} [body] Request body.
+ * @property {string} [type='string'] Response body type to be returned, one of `'string' | 'json' | 'arrayBuffer'`.
+ * @property {string} [credentials] Cross-origin credentials mode, one of `'same-origin' | 'include'`. Use `'include'` to send cookies with cross-origin requests.
+ * @property {boolean} [collectResourceTiming=false] If `true`, Resource Timing API information will be collected for these transformed requests and returned in a `resourceTiming` property of relevant `data` events.
+ * @property {string} [referrerPolicy] A string representing the request's referrerPolicy. For more information and possible values, see the [Referrer-Policy HTTP header page](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy).
+ * @see {@link RequestTransformFunction}
+ * @see {@link ResourceType}
+ */
+export type RequestParameters = {
+    url: string;
+    headers?: Record<string, string>;
+    method?: 'GET' | 'POST' | 'PUT';
+    body?: string;
+    type?: 'string' | 'json' | 'arrayBuffer';
+    credentials?: 'same-origin' | 'include';
+    collectResourceTiming?: boolean;
+    referrerPolicy?: ReferrerPolicy;
+};
+
+/**
+ * A callback run before the Map makes a request for an external URL, used to rewrite the URL, attach headers, or set the credentials property for cross-origin requests.
+ * The callback may return a {@link RequestParameters} object synchronously, or a `Promise` that resolves to one when the parameters need to be computed asynchronously — useful when each request needs a credential that has to be fetched at runtime, such as a [temporary access token](https://docs.mapbox.com/api/accounts/tokens/#create-a-temporary-token).
+ *
+ * @callback RequestTransformFunction
+ * @param {string} url The URL to be requested.
+ * @param {ResourceType} [resourceType] The type of resource being requested.
+ * @param {Object} [options] Options including an `AbortSignal` that will be aborted if the request is cancelled.
+ * @param {AbortSignal} [options.signal] An `AbortSignal` that will be aborted if the request is cancelled. Pass this to any async work (e.g. a `fetch` call) inside the callback so that the work is cancelled together with the request.
+ * @returns {RequestParameters | Promise<RequestParameters>} The modified request parameters, or a `Promise` that resolves to them.
+ *
  * @example
- * // use transformRequest to modify requests that begin with `http://myHost`
- * const map = new Map({
+ * const map = new mapboxgl.Map({
  *     container: 'map',
- *     style: 'mapbox://styles/mapbox/streets-v11',
+ *     style: 'mapbox://styles/mapbox/standard',
  *     transformRequest: (url, resourceType) => {
- *         if (resourceType === 'Source' && url.indexOf('http://myHost') > -1) {
+ *         // Use `transformRequest` to modify requests that begin with `http://myHost`.
+ *         if (resourceType === 'Source' && url.startsWith('http://myHost')) {
  *             return {
  *                 url: url.replace('http', 'https'),
  *                 headers: {'my-custom-header': true},
- *                 credentials: 'include'  // Include cookies for cross-origin requests
+ *                 credentials: 'include'
  *             };
  *         }
  *     }
  * });
  *
+ * @example
+ * let tokenCache;
+ * const map = new mapboxgl.Map({
+ *     container: 'map',
+ *     style: 'mapbox://styles/mapbox/standard',
+ *     transformRequest: async (url, resourceType, {signal}) => {
+ *         if (!tokenCache || Date.now() > new Date(tokenCache.expires).getTime()) {
+ *             const response = await fetch('https://example.com/token', {signal});
+ *             tokenCache = await response.json(); // {token, expires}
+ *         }
+ *         return {url, headers: {Authorization: `Bearer ${tokenCache.token}`}};
+ *     }
+ * });
+ *
+ * @see {@link RequestParameters}
+ * @see {@link ResourceType}
+ * @see {@link Map}
  */
-export type RequestParameters = {
-    url: string;
-    headers?: Record<string, string>;
-    method?: 'GET' | 'POST' | 'PUT';
-    body?: string;
-    type?: 'string' | 'json' | 'arrayBuffer';
-    credentials?: 'same-origin' | 'include';
-    collectResourceTiming?: boolean;
-    referrerPolicy?: ReferrerPolicy;
-};
+export type RequestTransformFunction = (url: string, resourceType?: ResourceType, options?: {signal?: AbortSignal}) => RequestParameters | Promise<RequestParameters>;
 
 export type ResponseCallback<T> = (
     error?: Error | DOMException | AJAXError | null,

src/util/mapbox.ts

@@ -21,7 +21,7 @@ import {uuid, validateUuid, storageAvailable, b64DecodeUnicode, b64EncodeUnicode
 import {postData, getData} from './ajax';
 import {getLivePerformanceMetrics} from '../util/live_performance';
 
-import type {ResourceType as ResourceTypeEnum, RequestParameters} from './ajax';
+import type {ResourceType, RequestParameters, RequestTransformFunction} from './ajax';
 import type {LivePerformanceData} from '../util/live_performance';
 import type {TileJSON} from '../types/tilejson';
 import type {Map as MapboxMap} from "../ui/map";
@@ -35,9 +35,6 @@ const EXTENSION_RE = /\.[\w]+$/;
 const TILE_PATH_RE = /^(\/v4\/|\/(raster|rasterarrays)\/v1\/)/;
 const ACCESS_TOKEN_PARAM_RE = /^access_token=(.*)$/;
 
-export type ResourceType = keyof typeof ResourceTypeEnum;
-export type RequestTransformFunction = (url: string, resourceType?: ResourceType, options?: {signal?: AbortSignal}) => RequestParameters | Promise<RequestParameters>;
-
 type UrlObject = {
     protocol: string;
     authority: string;

test/unit/source/raster_dem_tile_source.test.ts

@@ -10,7 +10,7 @@ import config from '../../../src/util/config';
 import type Tile from '../../../src/source/tile';
 import type Dispatcher from '../../../src/util/dispatcher';
 import type {Map as MapboxMap} from '../../../src/ui/map';
-import type {RequestTransformFunction} from '../../../src/util/mapbox';
+import type {RequestTransformFunction} from '../../../src/util/ajax';
 import type {RasterDEMSourceSpecification} from '../../../src/style-spec/types';
 
 function createSource(options: Partial<RasterDEMSourceSpecification>, transformCallback?: RequestTransformFunction) {