@carto/api-client 0.4.3 → 0.4.4

package/src/widget-sources/types.ts

@@ -1,4 +1,4 @@
-import {TileResolution} from '../sources/types';
+import {SpatialFilterPolyfillMode, TileResolution} from '../sources/types';
 import {
   GroupDateType,
   SortColumnType,
@@ -10,9 +10,18 @@ import {
  * WIDGET API REQUESTS
  */
 
+export interface ViewState {
+  zoom: number;
+  latitude: number;
+  longitude: number;
+}
+
 /** Common options for {@link WidgetBaseSource} requests. */
 interface BaseRequestOptions {
   spatialFilter?: SpatialFilter;
+  spatialFiltersMode?: SpatialFilterPolyfillMode;
+  /** Required for table- and query-based spatial index sources (H3, Quadbin). */
+  spatialIndexReferenceViewState?: ViewState;
   abortController?: AbortController;
   filterOwner?: string;
 }

package/src/widget-sources/widget-base-source.ts

@@ -16,21 +16,20 @@ import {
   TableResponse,
   TimeSeriesRequestOptions,
   TimeSeriesResponse,
+  ViewState,
 } from './types.js';
-import {FilterLogicalOperator, Filter} from '../types.js';
+import {FilterLogicalOperator, Filter, SpatialFilter} from '../types.js';
 import {getApplicableFilters, normalizeObjectKeys} from '../utils.js';
 import {getClient} from '../client.js';
 import {ModelSource} from '../models/model.js';
 import {SourceOptions} from '../sources/index.js';
 import {ApiVersion, DEFAULT_API_BASE_URL} from '../constants.js';
-import {
-  DEFAULT_GEO_COLUMN,
-  DEFAULT_TILE_RESOLUTION,
-} from '../constants-internal.js';
+import {DEFAULT_TILE_RESOLUTION} from '../constants-internal.js';
+import {getSpatialFiltersResolution} from '../spatial-index.js';
+import {AggregationOptions} from '../sources/types.js';
 
 export interface WidgetBaseSourceProps extends Omit<SourceOptions, 'filters'> {
   apiVersion?: ApiVersion;
-  geoColumn?: string;
   filters?: Record<string, Filter>;
   filtersLogicalOperator?: FilterLogicalOperator;
 }
@@ -51,7 +50,6 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
     clientId: getClient(),
     filters: {},
     filtersLogicalOperator: 'and',
-    geoColumn: DEFAULT_GEO_COLUMN,
   };
 
   constructor(props: Props) {
@@ -78,10 +76,31 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
       connectionName: props.connectionName,
       filters: getApplicableFilters(owner, props.filters),
       filtersLogicalOperator: props.filtersLogicalOperator,
-      geoColumn: props.geoColumn,
+      spatialDataType: props.spatialDataType,
+      spatialDataColumn: props.spatialDataColumn,
+      dataResolution: (props as Partial<AggregationOptions>).dataResolution,
     };
   }
 
+  protected _getSpatialFiltersResolution(
+    source: Omit<ModelSource, 'type' | 'data'>,
+    spatialFilter?: SpatialFilter,
+    referenceViewState?: ViewState
+  ): number | undefined {
+    // 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
    */
@@ -93,14 +112,32 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
   async getCategories(
     options: CategoryRequestOptions
   ): Promise<CategoryResponse> {
-    const {filterOwner, spatialFilter, abortController, ...params} = options;
+    const {
+      filterOwner,
+      spatialFilter,
+      spatialFiltersMode,
+      spatialIndexReferenceViewState,
+      abortController,
+      ...params
+    } = options;
     const {column, operation, operationColumn} = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(
+      source,
+      spatialFilter,
+      spatialIndexReferenceViewState
+    );
 
     type CategoriesModelResponse = {rows: {name: string; value: number}[]};
 
     return executeModel({
       model: 'category',
-      source: {...this.getModelSource(filterOwner), spatialFilter},
+      source: {
+        ...source,
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter,
+      },
       params: {
         column,
         operation,
@@ -125,14 +162,32 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
   async getFeatures(
     options: FeaturesRequestOptions
   ): Promise<FeaturesResponse> {
-    const {filterOwner, spatialFilter, abortController, ...params} = options;
+    const {
+      filterOwner,
+      spatialFilter,
+      spatialFiltersMode,
+      spatialIndexReferenceViewState,
+      abortController,
+      ...params
+    } = options;
     const {columns, dataType, featureIds, z, limit, tileResolution} = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(
+      source,
+      spatialFilter,
+      spatialIndexReferenceViewState
+    );
 
     type FeaturesModelResponse = {rows: Record<string, unknown>[]};
 
     return executeModel({
       model: 'pick',
-      source: {...this.getModelSource(filterOwner), spatialFilter},
+      source: {
+        ...source,
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter,
+      },
       params: {
         columns,
         dataType,
@@ -158,17 +213,30 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
     const {
       filterOwner,
       spatialFilter,
+      spatialFiltersMode,
+      spatialIndexReferenceViewState,
       abortController,
       operationExp,
       ...params
     } = options;
     const {column, operation} = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(
+      source,
+      spatialFilter,
+      spatialIndexReferenceViewState
+    );
 
     type FormulaModelResponse = {rows: {value: number}[]};
 
     return executeModel({
       model: 'formula',
-      source: {...this.getModelSource(filterOwner), spatialFilter},
+      source: {
+        ...source,
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter,
+      },
       params: {column: column ?? '*', operation, operationExp},
       opts: {abortController},
     }).then((res: FormulaModelResponse) => normalizeObjectKeys(res.rows[0]));
@@ -185,14 +253,32 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
   async getHistogram(
     options: HistogramRequestOptions
   ): Promise<HistogramResponse> {
-    const {filterOwner, spatialFilter, abortController, ...params} = options;
+    const {
+      filterOwner,
+      spatialFilter,
+      spatialFiltersMode,
+      spatialIndexReferenceViewState,
+      abortController,
+      ...params
+    } = options;
     const {column, operation, ticks} = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(
+      source,
+      spatialFilter,
+      spatialIndexReferenceViewState
+    );
 
     type HistogramModelResponse = {rows: {tick: number; value: number}[]};
 
     const data = await executeModel({
       model: 'histogram',
-      source: {...this.getModelSource(filterOwner), spatialFilter},
+      source: {
+        ...source,
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter,
+      },
       params: {column, operation, ticks},
       opts: {abortController},
     }).then((res: HistogramModelResponse) => normalizeObjectKeys(res.rows));
@@ -220,14 +306,32 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
    * or rendering a range slider UI for filtering.
    */
   async getRange(options: RangeRequestOptions): Promise<RangeResponse> {
-    const {filterOwner, spatialFilter, abortController, ...params} = options;
+    const {
+      filterOwner,
+      spatialFilter,
+      spatialFiltersMode,
+      spatialIndexReferenceViewState,
+      abortController,
+      ...params
+    } = options;
     const {column} = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(
+      source,
+      spatialFilter,
+      spatialIndexReferenceViewState
+    );
 
     type RangeModelResponse = {rows: {min: number; max: number}[]};
 
     return executeModel({
       model: 'range',
-      source: {...this.getModelSource(filterOwner), spatialFilter},
+      source: {
+        ...source,
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter,
+      },
       params: {column},
       opts: {abortController},
     }).then((res: RangeModelResponse) => normalizeObjectKeys(res.rows[0]));
@@ -242,10 +346,24 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
    * values. Suitable for rendering scatter plots.
    */
   async getScatter(options: ScatterRequestOptions): Promise<ScatterResponse> {
-    const {filterOwner, spatialFilter, abortController, ...params} = options;
+    const {
+      filterOwner,
+      spatialFilter,
+      spatialFiltersMode,
+      spatialIndexReferenceViewState,
+      abortController,
+      ...params
+    } = options;
     const {xAxisColumn, xAxisJoinOperation, 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;
 
@@ -253,7 +371,12 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
 
     return executeModel({
       model: 'scatterplot',
-      source: {...this.getModelSource(filterOwner), spatialFilter},
+      source: {
+        ...source,
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter,
+      },
       params: {
         xAxisColumn,
         xAxisJoinOperation,
@@ -276,8 +399,21 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
    * sorting. Suitable for displaying tables and lists.
    */
   async getTable(options: TableRequestOptions): Promise<TableResponse> {
-    const {filterOwner, spatialFilter, abortController, ...params} = options;
+    const {
+      filterOwner,
+      spatialFilter,
+      spatialFiltersMode,
+      spatialIndexReferenceViewState,
+      abortController,
+      ...params
+    } = options;
     const {columns, sortBy, sortDirection, offset = 0, limit = 10} = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(
+      source,
+      spatialFilter,
+      spatialIndexReferenceViewState
+    );
 
     type TableModelResponse = {
       rows: Record<string, number | string>[];
@@ -286,7 +422,12 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
 
     return executeModel({
       model: 'table',
-      source: {...this.getModelSource(filterOwner), spatialFilter},
+      source: {
+        ...source,
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter,
+      },
       params: {
         column: columns,
         sortBy,
@@ -313,7 +454,14 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
   async getTimeSeries(
     options: TimeSeriesRequestOptions
   ): Promise<TimeSeriesResponse> {
-    const {filterOwner, abortController, spatialFilter, ...params} = options;
+    const {
+      filterOwner,
+      abortController,
+      spatialFilter,
+      spatialFiltersMode,
+      spatialIndexReferenceViewState,
+      ...params
+    } = options;
     const {
       column,
       operationColumn,
@@ -326,6 +474,13 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
       splitByCategoryValues,
     } = params;
 
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(
+      source,
+      spatialFilter,
+      spatialIndexReferenceViewState
+    );
+
     type TimeSeriesModelResponse = {
       rows: {name: string; value: number}[];
       metadata: {categories: string[]};
@@ -333,7 +488,12 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
 
     return executeModel({
       model: 'timeseries',
-      source: {...this.getModelSource(filterOwner), spatialFilter},
+      source: {
+        ...source,
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter,
+      },
       params: {
         column,
         stepSize,