@carto/api-client 0.4.3 → 0.4.5-alpha.0

package/build/api-client.modern.js

@@ -686,6 +686,8 @@ async function baseSource(endpoint, options, urlParameters) {
 }
 
 // deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
 const boundaryQuerySource = async function boundaryQuerySource(options) {
   const {
     columns,
@@ -711,6 +713,8 @@ const boundaryQuerySource = async function boundaryQuerySource(options) {
 };
 
 // deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
 const boundaryTableSource = async function boundaryTableSource(options) {
   const {
     filters,
@@ -831,41 +835,43 @@ function executeModel(props) {
     data,
     filters,
     filtersLogicalOperator = 'and',
-    geoColumn = DEFAULT_GEO_COLUMN
+    spatialDataType = 'geo',
+    spatialFiltersMode = 'intersects',
+    spatialFiltersResolution = 0
   } = source;
-  const queryParameters = source.queryParameters ? JSON.stringify(source.queryParameters) : '';
   const queryParams = {
     type,
     client: clientId,
     source: data,
-    params: JSON.stringify(params),
-    queryParameters,
-    filters: JSON.stringify(filters),
+    params,
+    queryParameters: source.queryParameters || '',
+    filters,
     filtersLogicalOperator
   };
+  const spatialDataColumn = source.spatialDataColumn || DEFAULT_GEO_COLUMN;
   // Picking Model API requires 'spatialDataColumn'.
   if (model === 'pick') {
-    queryParams.spatialDataColumn = geoColumn;
+    queryParams.spatialDataColumn = spatialDataColumn;
   }
-  // API supports multiple filters, we apply it only to geoColumn
+  // API supports multiple filters, we apply it only to spatialDataColumn
   const spatialFilters = source.spatialFilter ? {
-    [geoColumn]: source.spatialFilter
+    [spatialDataColumn]: source.spatialFilter
   } : undefined;
   if (spatialFilters) {
-    queryParams.spatialFilters = JSON.stringify(spatialFilters);
+    queryParams.spatialFilters = spatialFilters;
+    queryParams.spatialDataColumn = spatialDataColumn;
+    queryParams.spatialDataType = spatialDataType;
+  }
+  if (spatialDataType !== 'geo') {
+    if (spatialFiltersResolution > 0) {
+      queryParams.spatialFiltersResolution = spatialFiltersResolution;
+    }
+    queryParams.spatialFiltersMode = spatialFiltersMode;
   }
-  const urlWithSearchParams = url + '?' + new URLSearchParams(queryParams).toString();
+  const urlWithSearchParams = url + '?' + objectToURLSearchParams(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,
@@ -877,15 +883,71 @@ 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(source, viewState) {
+  var _source$dataResolutio, _source$aggregationRe;
+  const dataResolution = (_source$dataResolutio = source.dataResolution) != null ? _source$dataResolutio : Number.MAX_VALUE;
+  const aggregationResLevel = (_source$aggregationRe = source.aggregationResLevel) != null ? _source$aggregationRe : 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') {
+    var _maxH3SpatialFiltersR, _maxH3SpatialFiltersR2;
+    const tileSize = DEFAULT_TILE_SIZE;
+    const maxResolutionForZoom = (_maxH3SpatialFiltersR = (_maxH3SpatialFiltersR2 = maxH3SpatialFiltersResolutions.find(([zoom]) => zoom === currentZoomInt)) == null ? void 0 : _maxH3SpatialFiltersR2[1]) != null ? _maxH3SpatialFiltersR : 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));
+}
 
-const _excluded = ["filterOwner", "spatialFilter", "abortController"],
-  _excluded2 = ["filterOwner", "spatialFilter", "abortController"],
-  _excluded3 = ["filterOwner", "spatialFilter", "abortController", "operationExp"],
-  _excluded4 = ["filterOwner", "spatialFilter", "abortController"],
-  _excluded5 = ["filterOwner", "spatialFilter", "abortController"],
-  _excluded6 = ["filterOwner", "spatialFilter", "abortController"],
-  _excluded7 = ["filterOwner", "spatialFilter", "abortController"],
-  _excluded8 = ["filterOwner", "abortController", "spatialFilter"];
+const _excluded = ["filterOwner", "spatialFilter", "spatialFiltersMode", "spatialIndexReferenceViewState", "abortController"],
+  _excluded2 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "spatialIndexReferenceViewState", "abortController"],
+  _excluded3 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "spatialIndexReferenceViewState", "abortController", "operationExp"],
+  _excluded4 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "spatialIndexReferenceViewState", "abortController"],
+  _excluded5 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "spatialIndexReferenceViewState", "abortController"],
+  _excluded6 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "spatialIndexReferenceViewState", "abortController"],
+  _excluded7 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "spatialIndexReferenceViewState", "abortController"],
+  _excluded8 = ["filterOwner", "abortController", "spatialFilter", "spatialFiltersMode", "spatialIndexReferenceViewState"];
 /**
  * Source for Widget API requests on a data source defined by a SQL query.
  *
@@ -906,9 +968,21 @@ class WidgetBaseSource {
       connectionName: props.connectionName,
       filters: getApplicableFilters(owner, props.filters),
       filtersLogicalOperator: props.filtersLogicalOperator,
-      geoColumn: props.geoColumn
+      spatialDataType: props.spatialDataType,
+      spatialDataColumn: props.spatialDataColumn,
+      dataResolution: props.dataResolution
     };
   }
+  _getSpatialFiltersResolution(source, spatialFilter, referenceViewState) {
+    // spatialFiltersResolution applies only to spatial index sources.
+    if (!spatialFilter || source.spatialDataType === 'geo') {
+      return;
+    }
+    if (!referenceViewState) {
+      throw new Error('Missing required option, "spatialIndexReferenceViewState".');
+    }
+    return getSpatialFiltersResolution(source, referenceViewState);
+  }
   /****************************************************************************
    * CATEGORIES
    */
@@ -920,6 +994,8 @@ class WidgetBaseSource {
     const {
         filterOwner,
         spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
         abortController
       } = options,
       params = _objectWithoutPropertiesLoose(options, _excluded);
@@ -928,9 +1004,13 @@ class WidgetBaseSource {
       operation,
       operationColumn
     } = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
     return executeModel({
       model: 'category',
-      source: _extends({}, this.getModelSource(filterOwner), {
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
         spatialFilter
       }),
       params: {
@@ -958,6 +1038,8 @@ class WidgetBaseSource {
     const {
         filterOwner,
         spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
         abortController
       } = options,
       params = _objectWithoutPropertiesLoose(options, _excluded2);
@@ -969,9 +1051,13 @@ class WidgetBaseSource {
       limit,
       tileResolution
     } = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
     return executeModel({
       model: 'pick',
-      source: _extends({}, this.getModelSource(filterOwner), {
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
         spatialFilter
       }),
       params: {
@@ -1003,6 +1089,8 @@ class WidgetBaseSource {
     const {
         filterOwner,
         spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
         abortController,
         operationExp
       } = options,
@@ -1011,9 +1099,13 @@ class WidgetBaseSource {
       column,
       operation
     } = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
     return executeModel({
       model: 'formula',
-      source: _extends({}, this.getModelSource(filterOwner), {
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
         spatialFilter
       }),
       params: {
@@ -1037,6 +1129,8 @@ class WidgetBaseSource {
     const {
         filterOwner,
         spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
         abortController
       } = options,
       params = _objectWithoutPropertiesLoose(options, _excluded4);
@@ -1045,9 +1139,13 @@ class WidgetBaseSource {
       operation,
       ticks
     } = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
     const data = await executeModel({
       model: 'histogram',
-      source: _extends({}, this.getModelSource(filterOwner), {
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
         spatialFilter
       }),
       params: {
@@ -1083,15 +1181,21 @@ class WidgetBaseSource {
     const {
         filterOwner,
         spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
         abortController
       } = options,
       params = _objectWithoutPropertiesLoose(options, _excluded5);
     const {
       column
     } = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
     return executeModel({
       model: 'range',
-      source: _extends({}, this.getModelSource(filterOwner), {
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
         spatialFilter
       }),
       params: {
@@ -1113,6 +1217,8 @@ class WidgetBaseSource {
     const {
         filterOwner,
         spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
         abortController
       } = options,
       params = _objectWithoutPropertiesLoose(options, _excluded6);
@@ -1122,11 +1228,15 @@ class WidgetBaseSource {
       yAxisColumn,
       yAxisJoinOperation
     } = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
     // Make sure this is sync with the same constant in cloud-native/maps-api
     const HARD_LIMIT = 500;
     return executeModel({
       model: 'scatterplot',
-      source: _extends({}, this.getModelSource(filterOwner), {
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
         spatialFilter
       }),
       params: {
@@ -1155,6 +1265,8 @@ class WidgetBaseSource {
     const {
         filterOwner,
         spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
         abortController
       } = options,
       params = _objectWithoutPropertiesLoose(options, _excluded7);
@@ -1165,9 +1277,13 @@ class WidgetBaseSource {
       offset = 0,
       limit = 10
     } = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
     return executeModel({
       model: 'table',
-      source: _extends({}, this.getModelSource(filterOwner), {
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
         spatialFilter
       }),
       params: {
@@ -1200,7 +1316,9 @@ class WidgetBaseSource {
     const {
         filterOwner,
         abortController,
-        spatialFilter
+        spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState
       } = options,
       params = _objectWithoutPropertiesLoose(options, _excluded8);
     const {
@@ -1214,9 +1332,13 @@ class WidgetBaseSource {
       splitByCategoryLimit,
       splitByCategoryValues
     } = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
     return executeModel({
       model: 'timeseries',
-      source: _extends({}, this.getModelSource(filterOwner), {
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
         spatialFilter
       }),
       params: {
@@ -1247,8 +1369,7 @@ WidgetBaseSource.defaultProps = {
   apiBaseUrl: DEFAULT_API_BASE_URL,
   clientId: getClient(),
   filters: {},
-  filtersLogicalOperator: 'and',
-  geoColumn: DEFAULT_GEO_COLUMN
+  filtersLogicalOperator: 'and'
 };
 
 /**
@@ -1323,10 +1444,11 @@ const h3QuerySource = async function h3QuerySource(options) {
     queryParameters,
     filters
   } = options;
+  const spatialDataType = 'h3';
   const urlParameters = {
     aggregationExp,
     spatialDataColumn,
-    spatialDataType: 'h3',
+    spatialDataType,
     q: sqlQuery
   };
   if (aggregationResLevel) {
@@ -1339,7 +1461,11 @@ const h3QuerySource = async function h3QuerySource(options) {
     urlParameters.filters = filters;
   }
   return baseSource('query', options, urlParameters).then(result => _extends({}, result, {
-    widgetSource: new WidgetQuerySource(options)
+    widgetSource: new WidgetQuerySource(_extends({}, options, {
+      // NOTE: Parameters with default values above must be explicitly passed here.
+      spatialDataColumn,
+      spatialDataType
+    }))
   }));
 };
 
@@ -1351,11 +1477,12 @@ const h3TableSource = async function h3TableSource(options) {
     tableName,
     filters
   } = options;
+  const spatialDataType = 'h3';
   const urlParameters = {
     aggregationExp,
     name: tableName,
     spatialDataColumn,
-    spatialDataType: 'h3'
+    spatialDataType
   };
   if (aggregationResLevel) {
     urlParameters.aggregationResLevel = String(aggregationResLevel);
@@ -1364,11 +1491,17 @@ const h3TableSource = async function h3TableSource(options) {
     urlParameters.filters = filters;
   }
   return baseSource('table', options, urlParameters).then(result => _extends({}, result, {
-    widgetSource: new WidgetTableSource(options)
+    widgetSource: new WidgetTableSource(_extends({}, options, {
+      // NOTE: Parameters with default values above must be explicitly passed here.
+      spatialDataColumn,
+      spatialDataType
+    }))
   }));
 };
 
 // deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
 const h3TilesetSource = async function h3TilesetSource(options) {
   const {
     tableName
@@ -1380,6 +1513,8 @@ const h3TilesetSource = async function h3TilesetSource(options) {
 };
 
 // deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
 const rasterSource = async function rasterSource(options) {
   const {
     tableName,
@@ -1403,11 +1538,12 @@ const quadbinQuerySource = async function quadbinQuerySource(options) {
     queryParameters,
     filters
   } = options;
+  const spatialDataType = 'quadbin';
   const urlParameters = {
     aggregationExp,
     q: sqlQuery,
     spatialDataColumn,
-    spatialDataType: 'quadbin'
+    spatialDataType
   };
   if (aggregationResLevel) {
     urlParameters.aggregationResLevel = String(aggregationResLevel);
@@ -1419,7 +1555,11 @@ const quadbinQuerySource = async function quadbinQuerySource(options) {
     urlParameters.filters = filters;
   }
   return baseSource('query', options, urlParameters).then(result => _extends({}, result, {
-    widgetSource: new WidgetQuerySource(options)
+    widgetSource: new WidgetQuerySource(_extends({}, options, {
+      // NOTE: Parameters with default values above must be explicitly passed here.
+      spatialDataColumn,
+      spatialDataType
+    }))
   }));
 };
 
@@ -1431,11 +1571,12 @@ const quadbinTableSource = async function quadbinTableSource(options) {
     tableName,
     filters
   } = options;
+  const spatialDataType = 'quadbin';
   const urlParameters = {
     aggregationExp,
     name: tableName,
     spatialDataColumn,
-    spatialDataType: 'quadbin'
+    spatialDataType
   };
   if (aggregationResLevel) {
     urlParameters.aggregationResLevel = String(aggregationResLevel);
@@ -1444,11 +1585,17 @@ const quadbinTableSource = async function quadbinTableSource(options) {
     urlParameters.filters = filters;
   }
   return baseSource('table', options, urlParameters).then(result => _extends({}, result, {
-    widgetSource: new WidgetTableSource(options)
+    widgetSource: new WidgetTableSource(_extends({}, options, {
+      // NOTE: Parameters with default values above must be explicitly passed here.
+      spatialDataColumn,
+      spatialDataType
+    }))
   }));
 };
 
 // deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
 const quadbinTilesetSource = async function quadbinTilesetSource(options) {
   const {
     tableName
@@ -1469,9 +1616,10 @@ const vectorQuerySource = async function vectorQuerySource(options) {
     queryParameters,
     aggregationExp
   } = options;
+  const spatialDataType = 'geo';
   const urlParameters = {
     spatialDataColumn,
-    spatialDataType: 'geo',
+    spatialDataType,
     tileResolution: tileResolution.toString(),
     q: sqlQuery
   };
@@ -1488,7 +1636,12 @@ const vectorQuerySource = async function vectorQuerySource(options) {
     urlParameters.aggregationExp = aggregationExp;
   }
   return baseSource('query', options, urlParameters).then(result => _extends({}, result, {
-    widgetSource: new WidgetQuerySource(options)
+    widgetSource: new WidgetQuerySource(_extends({}, options, {
+      // NOTE: Parameters with default values above must be explicitly passed here.
+      spatialDataColumn,
+      spatialDataType,
+      tileResolution
+    }))
   }));
 };
 
@@ -1501,10 +1654,11 @@ const vectorTableSource = async function vectorTableSource(options) {
     tileResolution = DEFAULT_TILE_RESOLUTION,
     aggregationExp
   } = options;
+  const spatialDataType = 'geo';
   const urlParameters = {
     name: tableName,
     spatialDataColumn,
-    spatialDataType: 'geo',
+    spatialDataType,
     tileResolution: tileResolution.toString()
   };
   if (columns) {
@@ -1517,11 +1671,18 @@ const vectorTableSource = async function vectorTableSource(options) {
     urlParameters.aggregationExp = aggregationExp;
   }
   return baseSource('table', options, urlParameters).then(result => _extends({}, result, {
-    widgetSource: new WidgetTableSource(options)
+    widgetSource: new WidgetTableSource(_extends({}, options, {
+      // NOTE: Parameters with default values above must be explicitly passed here.
+      spatialDataColumn,
+      spatialDataType,
+      tileResolution
+    }))
   }));
 };
 
 // deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
 const vectorTilesetSource = async function vectorTilesetSource(options) {
   const {
     tableName