@carto/api-client 0.4.1-alpha.0 → 0.4.1

package/CHANGELOG.md

@@ -1,7 +1,13 @@
 # CHANGELOG
 
+## Not released
+
 ## 0.4
 
+### 0.4.1
+
+- add cache control mechanism for sources and query APIs
+
 ### 0.4.0
 
 - feat: Add Picking Model API

package/build/api/query.d.ts

@@ -1,3 +1,3 @@
 import type { SourceOptions, QuerySourceOptions, QueryResult } from '../sources/types';
-export type QueryOptions = SourceOptions & QuerySourceOptions;
+export type QueryOptions = SourceOptions & Omit<QuerySourceOptions, 'spatialDataColumn'>;
 export declare const query: (options: QueryOptions) => Promise<QueryResult>;

package/build/api/request-with-parameters.d.ts

@@ -1,8 +1,10 @@
 import { APIErrorContext } from './carto-api-error';
-export declare function requestWithParameters<T = any>({ baseUrl, parameters, headers: customHeaders, errorContext, maxLengthURL, }: {
+import { LocalCacheOptions } from '../sources/types';
+export declare function requestWithParameters<T = any>({ baseUrl, parameters, headers: customHeaders, errorContext, maxLengthURL, localCache, }: {
     baseUrl: string;
     parameters?: Record<string, unknown>;
     headers?: Record<string, string>;
     errorContext: APIErrorContext;
     maxLengthURL?: number;
+    localCache?: LocalCacheOptions;
 }): Promise<T>;

package/build/api-client.cjs

@@ -509,43 +509,41 @@ function executeModel(props) {
     data,
     filters,
     filtersLogicalOperator = 'and',
-    spatialDataType = 'geo',
-    spatialFiltersMode = 'intersects',
-    spatialFiltersResolution = 0
+    geoColumn = DEFAULT_GEO_COLUMN
   } = source;
+  const queryParameters = source.queryParameters ? JSON.stringify(source.queryParameters) : '';
   const queryParams = {
     type,
     client: clientId,
     source: data,
-    params,
-    queryParameters: source.queryParameters || '',
-    filters,
+    params: JSON.stringify(params),
+    queryParameters,
+    filters: JSON.stringify(filters),
     filtersLogicalOperator
   };
-  const spatialDataColumn = source.spatialDataColumn || DEFAULT_GEO_COLUMN;
   // Picking Model API requires 'spatialDataColumn'.
   if (model === 'pick') {
-    queryParams.spatialDataColumn = spatialDataColumn;
+    queryParams.spatialDataColumn = geoColumn;
   }
-  // API supports multiple filters, we apply it only to spatialDataColumn
+  // API supports multiple filters, we apply it only to geoColumn
   const spatialFilters = source.spatialFilter ? {
-    [spatialDataColumn]: source.spatialFilter
+    [geoColumn]: source.spatialFilter
   } : undefined;
   if (spatialFilters) {
-    queryParams.spatialFilters = spatialFilters; // JSON.stringify(spatialFilters);
-    queryParams.spatialDataColumn = spatialDataColumn;
-    queryParams.spatialDataType = spatialDataType;
-  }
-  if (spatialDataType !== 'geo') {
-    if (spatialFiltersResolution > 0) {
-      queryParams.spatialFiltersResolution = spatialFiltersResolution;
-    }
-    queryParams.spatialFiltersMode = spatialFiltersMode;
+    queryParams.spatialFilters = JSON.stringify(spatialFilters);
   }
-  const urlWithSearchParams = url + '?' + objectToURLSearchParams(queryParams).toString();
+  const urlWithSearchParams = url + '?' + new URLSearchParams(queryParams).toString();
   const isGet = urlWithSearchParams.length <= REQUEST_GET_MAX_URL_LENGTH;
   if (isGet) {
     url = urlWithSearchParams;
+  } else {
+    // undo the JSON.stringify, @TODO find a better pattern
+    queryParams.params = params;
+    queryParams.filters = filters;
+    queryParams.queryParameters = source.queryParameters;
+    if (spatialFilters) {
+      queryParams.spatialFilters = spatialFilters;
+    }
   }
   return makeCall({
     url,
@@ -559,68 +557,6 @@ function executeModel(props) {
     }
   });
 }
-function objectToURLSearchParams(object) {
-  const params = new URLSearchParams();
-  for (const key in object) {
-    if (isPureObject(object[key])) {
-      params.append(key, JSON.stringify(object[key]));
-    } else if (Array.isArray(object[key])) {
-      params.append(key, JSON.stringify(object[key]));
-    } else if (object[key] === null) {
-      params.append(key, 'null');
-    } else if (object[key] !== undefined) {
-      params.append(key, String(object[key]));
-    }
-  }
-  return params;
-}
-
-const DEFAULT_TILE_SIZE = 512;
-const QUADBIN_ZOOM_MAX_OFFSET = 4;
-function getSpatialFiltersResolution(_ref) {
-  let {
-    source,
-    viewState
-  } = _ref;
-  assert(viewState, 'viewState prop is required to compute automatic spatialFiltersResolution when using spatialFilter with spatial indexes. Either pass a `spatialFiltersResolution` prop or a `viewState` prop to avoid this error');
-  const dataResolution = source.dataResolution ?? Number.MAX_VALUE;
-  const aggregationResLevel = source.aggregationResLevel ?? (source.spatialDataType === 'h3' ? DEFAULT_AGGREGATION_RES_LEVEL_H3 : DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN);
-  const aggregationResLevelOffset = Math.max(0, Math.floor(aggregationResLevel));
-  const currentZoomInt = Math.ceil(viewState.zoom);
-  if (source.spatialDataType === 'h3') {
-    const tileSize = DEFAULT_TILE_SIZE;
-    const maxResolutionForZoom = maxH3SpatialFiltersResolutions.find(_ref2 => {
-      let [zoom] = _ref2;
-      return zoom === currentZoomInt;
-    })?.[1] ?? Math.max(0, currentZoomInt - 3);
-    const maxSpatialFiltersResolution = maxResolutionForZoom ? Math.min(dataResolution, maxResolutionForZoom) : dataResolution;
-    const hexagonResolution = getHexagonResolution(viewState, tileSize) + aggregationResLevelOffset;
-    return Math.min(hexagonResolution, maxSpatialFiltersResolution);
-  }
-  if (source.spatialDataType === 'quadbin') {
-    const maxResolutionForZoom = currentZoomInt + QUADBIN_ZOOM_MAX_OFFSET;
-    const maxSpatialFiltersResolution = Math.min(dataResolution, maxResolutionForZoom);
-    const quadsResolution = Math.floor(viewState.zoom) + aggregationResLevelOffset;
-    return Math.min(quadsResolution, maxSpatialFiltersResolution);
-  }
-  return undefined;
-}
-const maxH3SpatialFiltersResolutions = [[20, 14], [19, 13], [18, 12], [17, 11], [16, 10], [15, 9], [14, 8], [13, 7], [12, 7], [11, 7], [10, 6], [9, 6], [8, 5], [7, 4], [6, 4], [5, 3], [4, 2], [3, 1], [2, 1], [1, 0]];
-// stolen from https://github.com/visgl/deck.gl/blob/master/modules/carto/src/layers/h3-tileset-2d.ts
-// Relative scale factor (0 = no biasing, 2 = a few hexagons cover view)
-const BIAS = 2;
-// Resolution conversion function. Takes a WebMercatorViewport and returns
-// a H3 resolution such that the screen space size of the hexagons is
-// similar
-function getHexagonResolution(viewport, tileSize) {
-  // Difference in given tile size compared to deck's internal 512px tile size,
-  // expressed as an offset to the viewport zoom.
-  const zoomOffset = Math.log2(tileSize / DEFAULT_TILE_SIZE);
-  const hexagonScaleFactor = 2 / 3 * (viewport.zoom - zoomOffset);
-  const latitudeScaleFactor = Math.log(1 / Math.cos(Math.PI * viewport.latitude / 180));
-  // Clip and bias
-  return Math.max(0, Math.floor(hexagonScaleFactor + latitudeScaleFactor - BIAS));
-}
 
 /**
  * Source for Widget API requests on a data source defined by a SQL query.
@@ -645,8 +581,7 @@ class WidgetBaseSource {
       connectionName: props.connectionName,
       filters: getApplicableFilters(owner, props.filters),
       filtersLogicalOperator: props.filtersLogicalOperator,
-      spatialDataType: props.spatialDataType,
-      spatialDataColumn: props.spatialDataColumn
+      geoColumn: props.geoColumn
     };
   }
   /****************************************************************************
@@ -662,9 +597,7 @@ class WidgetBaseSource {
       const {
         filterOwner,
         spatialFilter,
-        spatialFiltersMode,
         abortController,
-        viewState,
         ...params
       } = options;
       const {
@@ -672,20 +605,10 @@ class WidgetBaseSource {
         operation,
         operationColumn
       } = params;
-      const source = _this.getModelSource(filterOwner);
-      let spatialFiltersResolution;
-      if (spatialFilter && source.spatialDataType !== 'geo') {
-        spatialFiltersResolution = getSpatialFiltersResolution({
-          source,
-          viewState
-        });
-      }
       return Promise.resolve(executeModel({
         model: 'category',
         source: {
-          ...source,
-          spatialFiltersResolution,
-          spatialFiltersMode,
+          ..._this.getModelSource(filterOwner),
           spatialFilter
         },
         params: {
@@ -718,9 +641,7 @@ class WidgetBaseSource {
       const {
         filterOwner,
         spatialFilter,
-        spatialFiltersMode,
         abortController,
-        viewState,
         ...params
       } = options;
       const {
@@ -731,20 +652,10 @@ class WidgetBaseSource {
         limit,
         tileResolution
       } = params;
-      const source = _this2.getModelSource(filterOwner);
-      let spatialFiltersResolution;
-      if (spatialFilter && source.spatialDataType !== 'geo') {
-        spatialFiltersResolution = getSpatialFiltersResolution({
-          source,
-          viewState
-        });
-      }
       return Promise.resolve(executeModel({
         model: 'pick',
         source: {
-          ...source,
-          spatialFiltersResolution,
-          spatialFiltersMode,
+          ..._this2.getModelSource(filterOwner),
           spatialFilter
         },
         params: {
@@ -778,30 +689,18 @@ class WidgetBaseSource {
       const {
         filterOwner,
         spatialFilter,
-        spatialFiltersMode,
         abortController,
         operationExp,
-        viewState,
         ...params
       } = options;
       const {
         column,
         operation
       } = params;
-      const source = _this3.getModelSource(filterOwner);
-      let spatialFiltersResolution;
-      if (spatialFilter && source.spatialDataType !== 'geo') {
-        spatialFiltersResolution = getSpatialFiltersResolution({
-          source,
-          viewState
-        });
-      }
       return Promise.resolve(executeModel({
         model: 'formula',
         source: {
-          ...source,
-          spatialFiltersResolution,
-          spatialFiltersMode,
+          ..._this3.getModelSource(filterOwner),
           spatialFilter
         },
         params: {
@@ -830,9 +729,7 @@ class WidgetBaseSource {
       const {
         filterOwner,
         spatialFilter,
-        spatialFiltersMode,
         abortController,
-        viewState,
         ...params
       } = options;
       const {
@@ -840,20 +737,10 @@ class WidgetBaseSource {
         operation,
         ticks
       } = params;
-      const source = _this4.getModelSource(filterOwner);
-      let spatialFiltersResolution;
-      if (spatialFilter && source.spatialDataType !== 'geo') {
-        spatialFiltersResolution = getSpatialFiltersResolution({
-          source,
-          viewState
-        });
-      }
       return Promise.resolve(executeModel({
         model: 'histogram',
         source: {
-          ...source,
-          spatialFiltersResolution,
-          spatialFiltersMode,
+          ..._this4.getModelSource(filterOwner),
           spatialFilter
         },
         params: {
@@ -898,28 +785,16 @@ class WidgetBaseSource {
       const {
         filterOwner,
         spatialFilter,
-        spatialFiltersMode,
         abortController,
-        viewState,
         ...params
       } = options;
       const {
         column
       } = params;
-      const source = _this5.getModelSource(filterOwner);
-      let spatialFiltersResolution;
-      if (spatialFilter && source.spatialDataType !== 'geo') {
-        spatialFiltersResolution = getSpatialFiltersResolution({
-          source,
-          viewState
-        });
-      }
       return Promise.resolve(executeModel({
         model: 'range',
         source: {
-          ...source,
-          spatialFiltersResolution,
-          spatialFiltersMode,
+          ..._this5.getModelSource(filterOwner),
           spatialFilter
         },
         params: {
@@ -946,9 +821,7 @@ class WidgetBaseSource {
       const {
         filterOwner,
         spatialFilter,
-        spatialFiltersMode,
         abortController,
-        viewState,
         ...params
       } = options;
       const {
@@ -957,22 +830,12 @@ class WidgetBaseSource {
         yAxisColumn,
         yAxisJoinOperation
       } = params;
-      const source = _this6.getModelSource(filterOwner);
-      let spatialFiltersResolution;
-      if (spatialFilter && source.spatialDataType !== 'geo') {
-        spatialFiltersResolution = getSpatialFiltersResolution({
-          source,
-          viewState
-        });
-      }
       // Make sure this is sync with the same constant in cloud-native/maps-api
       const HARD_LIMIT = 500;
       return Promise.resolve(executeModel({
         model: 'scatterplot',
         source: {
-          ...source,
-          spatialFiltersResolution,
-          spatialFiltersMode,
+          ..._this6.getModelSource(filterOwner),
           spatialFilter
         },
         params: {
@@ -1009,9 +872,7 @@ class WidgetBaseSource {
       const {
         filterOwner,
         spatialFilter,
-        spatialFiltersMode,
         abortController,
-        viewState,
         ...params
       } = options;
       const {
@@ -1021,20 +882,10 @@ class WidgetBaseSource {
         offset = 0,
         limit = 10
       } = params;
-      const source = _this7.getModelSource(filterOwner);
-      let spatialFiltersResolution;
-      if (spatialFilter && source.spatialDataType !== 'geo') {
-        spatialFiltersResolution = getSpatialFiltersResolution({
-          source,
-          viewState
-        });
-      }
       return Promise.resolve(executeModel({
         model: 'table',
         source: {
-          ...source,
-          spatialFiltersResolution,
-          spatialFiltersMode,
+          ..._this7.getModelSource(filterOwner),
           spatialFilter
         },
         params: {
@@ -1070,8 +921,6 @@ class WidgetBaseSource {
         filterOwner,
         abortController,
         spatialFilter,
-        spatialFiltersMode,
-        viewState,
         ...params
       } = options;
       const {
@@ -1085,20 +934,10 @@ class WidgetBaseSource {
         splitByCategoryLimit,
         splitByCategoryValues
       } = params;
-      const source = _this8.getModelSource(filterOwner);
-      let spatialFiltersResolution;
-      if (spatialFilter && source.spatialDataType !== 'geo') {
-        spatialFiltersResolution = getSpatialFiltersResolution({
-          source,
-          viewState
-        });
-      }
       return Promise.resolve(executeModel({
         model: 'timeseries',
         source: {
-          ...source,
-          spatialFiltersResolution,
-          spatialFiltersMode,
+          ..._this8.getModelSource(filterOwner),
           spatialFilter
         },
         params: {
@@ -1129,7 +968,8 @@ WidgetBaseSource.defaultProps = {
   apiBaseUrl: DEFAULT_API_BASE_URL,
   clientId: getClient(),
   filters: {},
-  filtersLogicalOperator: 'and'
+  filtersLogicalOperator: 'and',
+  geoColumn: DEFAULT_GEO_COLUMN
 };
 
 /**
@@ -1308,7 +1148,8 @@ const requestWithParameters = function (_ref) {
     parameters = {},
     headers: customHeaders = {},
     errorContext,
-    maxLengthURL = DEFAULT_MAX_LENGTH_URL
+    maxLengthURL = DEFAULT_MAX_LENGTH_URL,
+    localCache
   } = _ref;
   try {
     // Parameters added to all requests issued with `requestWithParameters()`.
@@ -1324,7 +1165,12 @@ const requestWithParameters = function (_ref) {
     };
     baseUrl = excludeURLParameters(baseUrl, Object.keys(parameters));
     const key = createCacheKey(baseUrl, parameters, customHeaders);
-    if (REQUEST_CACHE.has(key)) {
+    const {
+      cache: REQUEST_CACHE,
+      canReadCache,
+      canStoreInCache
+    } = getCacheSettings(localCache);
+    if (canReadCache && REQUEST_CACHE.has(key)) {
       return Promise.resolve(REQUEST_CACHE.get(key));
     }
     const url = createURLWithParameters(baseUrl, parameters);
@@ -1352,10 +1198,14 @@ const requestWithParameters = function (_ref) {
       }
       return json;
     }).catch(error => {
-      REQUEST_CACHE.delete(key);
+      if (canStoreInCache) {
+        REQUEST_CACHE.delete(key);
+      }
       throw new CartoAPIError(error, errorContext, response, responseJson);
     });
-    REQUEST_CACHE.set(key, jsonPromise);
+    if (canStoreInCache) {
+      REQUEST_CACHE.set(key, jsonPromise);
+    }
     return Promise.resolve(jsonPromise);
   } catch (e) {
     return Promise.reject(e);
@@ -1365,7 +1215,17 @@ const DEFAULT_HEADERS = {
   Accept: 'application/json',
   'Content-Type': 'application/json'
 };
-const REQUEST_CACHE = new Map();
+const DEFAULT_REQUEST_CACHE = new Map();
+function getCacheSettings(localCache) {
+  const canReadCache = localCache?.cacheControl?.includes('no-cache') ? false : true;
+  const canStoreInCache = localCache?.cacheControl?.includes('no-store') ? false : true;
+  const cache = localCache?.cache || DEFAULT_REQUEST_CACHE;
+  return {
+    cache,
+    canReadCache,
+    canStoreInCache
+  };
+}
 function createCacheKey(baseUrl, parameters, headers) {
   const parameterEntries = Object.entries(parameters).sort((_ref2, _ref3) => {
     let [a] = _ref2;
@@ -1436,7 +1296,8 @@ const baseSource = function (endpoint, options, urlParameters) {
     const {
       clientId,
       maxLengthURL,
-      format
+      format,
+      localCache
     } = mergedOptions;
     const headers = {
       Authorization: `Bearer ${options.accessToken}`,
@@ -1457,7 +1318,8 @@ const baseSource = function (endpoint, options, urlParameters) {
       parameters,
       headers,
       errorContext,
-      maxLengthURL
+      maxLengthURL,
+      localCache
     })).then(function (mapInstantiation) {
       let _exit;
       function _temp2(_result) {
@@ -1465,7 +1327,8 @@ const baseSource = function (endpoint, options, urlParameters) {
           baseUrl: dataUrl,
           headers,
           errorContext,
-          maxLengthURL
+          maxLengthURL,
+          localCache
         }));
       }
       const dataUrl = mapInstantiation[format].url[0];
@@ -1479,7 +1342,8 @@ const baseSource = function (endpoint, options, urlParameters) {
             baseUrl: dataUrl,
             headers,
             errorContext,
-            maxLengthURL
+            maxLengthURL,
+            localCache
           })).then(function (json) {
             if (accessToken) {
               json.accessToken = accessToken;
@@ -1585,12 +1449,7 @@ const h3QuerySource = function (options) {
     }
     return Promise.resolve(baseSource('query', options, urlParameters).then(result => ({
       ...result,
-      widgetSource: new WidgetQuerySource({
-        ...options,
-        // NOTE: passing redundant spatialDataColumn here to apply the default value 'h3'
-        spatialDataColumn,
-        spatialDataType: 'h3'
-      })
+      widgetSource: new WidgetQuerySource(options)
     })));
   } catch (e) {
     return Promise.reject(e);
@@ -1621,12 +1480,7 @@ const h3TableSource = function (options) {
     }
     return Promise.resolve(baseSource('table', options, urlParameters).then(result => ({
       ...result,
-      widgetSource: new WidgetTableSource({
-        ...options,
-        // NOTE: passing redundant spatialDataColumn here to apply the default value 'h3'
-        spatialDataColumn,
-        spatialDataType: 'h3'
-      })
+      widgetSource: new WidgetTableSource(options)
     })));
   } catch (e) {
     return Promise.reject(e);
@@ -1695,12 +1549,7 @@ const quadbinQuerySource = function (options) {
     }
     return Promise.resolve(baseSource('query', options, urlParameters).then(result => ({
       ...result,
-      widgetSource: new WidgetQuerySource({
-        ...options,
-        // NOTE: passing redundant spatialDataColumn here to apply the default value 'quadbin'
-        spatialDataColumn,
-        spatialDataType: 'quadbin'
-      })
+      widgetSource: new WidgetQuerySource(options)
     })));
   } catch (e) {
     return Promise.reject(e);
@@ -1731,12 +1580,7 @@ const quadbinTableSource = function (options) {
     }
     return Promise.resolve(baseSource('table', options, urlParameters).then(result => ({
       ...result,
-      widgetSource: new WidgetTableSource({
-        ...options,
-        // NOTE: passing redundant spatialDataColumn here to apply the default value 'quadbin'
-        spatialDataColumn,
-        spatialDataType: 'quadbin'
-      })
+      widgetSource: new WidgetTableSource(options)
     })));
   } catch (e) {
     return Promise.reject(e);
@@ -1786,10 +1630,7 @@ const vectorQuerySource = function (options) {
     }
     return Promise.resolve(baseSource('query', options, urlParameters).then(result => ({
       ...result,
-      widgetSource: new WidgetQuerySource({
-        ...options,
-        spatialDataType: 'geo'
-      })
+      widgetSource: new WidgetQuerySource(options)
     })));
   } catch (e) {
     return Promise.reject(e);
@@ -1820,10 +1661,7 @@ const vectorTableSource = function (options) {
     }
     return Promise.resolve(baseSource('table', options, urlParameters).then(result => ({
       ...result,
-      widgetSource: new WidgetTableSource({
-        ...options,
-        spatialDataType: 'geo'
-      })
+      widgetSource: new WidgetTableSource(options)
     })));
   } catch (e) {
     return Promise.reject(e);
@@ -1852,6 +1690,7 @@ const query = function (options) {
       apiBaseUrl = SOURCE_DEFAULTS.apiBaseUrl,
       clientId = SOURCE_DEFAULTS.clientId,
       maxLengthURL = SOURCE_DEFAULTS.maxLengthURL,
+      localCache,
       connectionName,
       sqlQuery,
       queryParameters
@@ -1885,7 +1724,8 @@ const query = function (options) {
       parameters,
       headers,
       errorContext,
-      maxLengthURL
+      maxLengthURL,
+      localCache
     }));
   } catch (e) {
     return Promise.reject(e);