@carto/api-client 0.5.0-alpha.2 → 0.5.0-alpha.4

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

@@ -1,9 +1,9 @@
+/* eslint-disable @typescript-eslint/require-await */
 import {TilesetSourceOptions} from '../sources/index.js';
 import type {ModelSource} from '../models/index.js';
 import {
   CategoryRequestOptions,
   CategoryResponse,
-  FeaturesRequestOptions,
   FeaturesResponse,
   FormulaRequestOptions,
   FormulaResponse,
@@ -18,9 +18,9 @@ import {
   TimeSeriesRequestOptions,
   TimeSeriesResponse,
 } from './types.js';
-import {InvalidColumnError, getApplicableFilters} from '../utils.js';
+import {InvalidColumnError, assert, getApplicableFilters} from '../utils.js';
 import {TileFormat} from '../constants.js';
-import {SpatialFilter, Tile} from '../types.js';
+import {Filter, Filters, SpatialFilter, Tile} from '../types.js';
 import {
   TileFeatureExtractOptions,
   applyFilters,
@@ -39,6 +39,7 @@ import {FeatureData} from '../types-internal.js';
 import {FeatureCollection} from 'geojson';
 import {SpatialDataType} from '../sources/types.js';
 import {WidgetSource, WidgetSourceProps} from './widget-source.js';
+import {booleanEqual} from '@turf/boolean-equal';
 
 // TODO(cleanup): Parameter defaults in source functions and widget API calls are
 // currently duplicated and possibly inconsistent. Consider consolidating and
@@ -75,13 +76,21 @@ export type WidgetTilesetSourceResult = {widgetSource: WidgetTilesetSource};
  * const { widgetSource } = await data;
  * ```
  */
-export class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps> {
+export class WidgetTilesetSource<
+  Props extends WidgetTilesetSourceProps = WidgetTilesetSourceProps,
+> extends WidgetSource<Props> {
   private _tiles: Tile[] = [];
   private _features: FeatureData[] = [];
-
-  protected override getModelSource(owner: string): ModelSource {
+  private _tileFeatureExtractOptions: TileFeatureExtractOptions = {};
+  private _tileFeatureExtractPreviousInputs: {spatialFilter?: SpatialFilter} =
+    {};
+
+  protected override getModelSource(
+    filters: Filters | undefined,
+    filterOwner: string
+  ): ModelSource {
     return {
-      ...super._getModelSource(owner),
+      ...super._getModelSource(filters, filterOwner),
       type: 'tileset',
       data: this.props.tableName,
     };
@@ -94,55 +103,58 @@ export class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps>
    */
   loadTiles(tiles: unknown[]) {
     this._tiles = tiles as Tile[];
+    this._features.length = 0;
   }
 
-  /**
-   * Extracts feature data from tiles previously loaded with {@link loadTiles}.
-   * Must be called before computing statistics on tiles.
-   */
-  extractTileFeatures({
-    spatialFilter,
-    uniqueIdProperty,
-    options,
-  }: {
-    spatialFilter: SpatialFilter;
-    // TODO(cleanup): As an optional property, 'uniqueIdProperty' will be easy to forget.
-    // Would it be better to configure it on the source function, rather than separately
-    // on the layer and in 'loadTiles()'?
-    uniqueIdProperty?: string;
-    options?: TileFeatureExtractOptions;
-  }) {
+  /** Configures options used to extract features from tiles. */
+  setTileFeatureExtractOptions(options: TileFeatureExtractOptions) {
+    this._tileFeatureExtractOptions = options;
+    this._features.length = 0;
+  }
+
+  protected _extractTileFeatures(spatialFilter: SpatialFilter) {
+    // When spatial filter has not changed, don't redo extraction. If tiles or
+    // tile extract options change, features will have been cleared already.
+    const prevInputs = this._tileFeatureExtractPreviousInputs;
+    if (
+      this._features.length &&
+      prevInputs.spatialFilter &&
+      booleanEqual(prevInputs.spatialFilter, spatialFilter)
+    ) {
+      return;
+    }
+
     this._features = tileFeatures({
+      ...this.props,
+      ...this._tileFeatureExtractOptions,
       tiles: this._tiles,
-      options,
       spatialFilter,
-      uniqueIdProperty,
-      tileFormat: this.props.tileFormat,
-      spatialDataColumn: this.props.spatialDataColumn,
-      spatialDataType: this.props.spatialDataType,
     });
+
+    prevInputs.spatialFilter = spatialFilter;
   }
 
-  /** Loads features as GeoJSON (used for testing). */
+  /**
+   * Loads features as GeoJSON (used for testing).
+   * @experimental
+   * @internal Not for public use. Spatial filters in other method calls will be ignored.
+   */
   loadGeoJSON({
     geojson,
     spatialFilter,
-    uniqueIdProperty,
   }: {
     geojson: FeatureCollection;
     spatialFilter: SpatialFilter;
-    uniqueIdProperty?: string;
   }) {
     this._features = geojsonFeatures({
       geojson,
       spatialFilter,
-      uniqueIdProperty,
+      ...this._tileFeatureExtractOptions,
     });
+    this._tileFeatureExtractPreviousInputs.spatialFilter = spatialFilter;
   }
 
-  override async getFeatures(
-    options: FeaturesRequestOptions
-  ): Promise<FeaturesResponse> {
+  override async getFeatures(): Promise<FeaturesResponse> {
     throw new Error('getFeatures not supported for tilesets');
   }
 
@@ -150,22 +162,24 @@ export class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps>
     column = '*',
     operation = 'count',
     joinOperation,
+    filters,
     filterOwner,
+    spatialFilter,
   }: FormulaRequestOptions): Promise<FormulaResponse> {
     if (operation === 'custom') {
       throw new Error('Custom aggregation not supported for tilesets');
     }
 
-    if (!this._features.length) {
-      return {value: null};
-    }
-
     // Column is required except when operation is 'count'.
     if ((column && column !== '*') || operation !== 'count') {
       assertColumn(this._features, column);
     }
 
-    const filteredFeatures = this._getFilteredFeatures(filterOwner);
+    const filteredFeatures = this._getFilteredFeatures(
+      spatialFilter,
+      filters,
+      filterOwner
+    );
 
     if (filteredFeatures.length === 0 && operation !== 'count') {
       return {value: null};
@@ -173,11 +187,7 @@ export class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps>
 
     const targetOperation = aggregationFunctions[operation];
     return {
-      value: targetOperation(
-        filteredFeatures as FeatureData[],
-        column,
-        joinOperation
-      ),
+      value: targetOperation(filteredFeatures, column, joinOperation),
     };
   }
 
@@ -186,16 +196,22 @@ export class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps>
     ticks,
     column,
     joinOperation,
+    filters,
     filterOwner,
+    spatialFilter,
   }: HistogramRequestOptions): Promise<HistogramResponse> {
+    const filteredFeatures = this._getFilteredFeatures(
+      spatialFilter,
+      filters,
+      filterOwner
+    );
+
+    assertColumn(this._features, column);
+
     if (!this._features.length) {
       return [];
     }
 
-    const filteredFeatures = this._getFilteredFeatures(filterOwner);
-
-    assertColumn(this._features, column);
-
     return histogram({
       data: filteredFeatures,
       valuesColumns: normalizeColumns(column),
@@ -210,15 +226,21 @@ export class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps>
     operation = 'count',
     operationColumn,
     joinOperation,
+    filters,
     filterOwner,
+    spatialFilter,
   }: CategoryRequestOptions): Promise<CategoryResponse> {
-    if (!this._features.length) {
+    const filteredFeatures = this._getFilteredFeatures(
+      spatialFilter,
+      filters,
+      filterOwner
+    );
+
+    if (!filteredFeatures.length) {
       return [];
     }
 
-    const filteredFeatures = this._getFilteredFeatures(filterOwner);
-
-    assertColumn(this._features, column as string, operationColumn as string);
+    assertColumn(this._features, column, operationColumn as string);
 
     const groups = groupValuesByColumn({
       data: filteredFeatures,
@@ -236,14 +258,20 @@ export class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps>
     yAxisColumn,
     xAxisJoinOperation,
     yAxisJoinOperation,
+    filters,
     filterOwner,
+    spatialFilter,
   }: ScatterRequestOptions): Promise<ScatterResponse> {
-    if (!this._features.length) {
+    const filteredFeatures = this._getFilteredFeatures(
+      spatialFilter,
+      filters,
+      filterOwner
+    );
+
+    if (!filteredFeatures.length) {
       return [];
     }
 
-    const filteredFeatures = this._getFilteredFeatures(filterOwner);
-
     assertColumn(this._features, xAxisColumn, yAxisColumn);
 
     return scatterPlot({
@@ -255,35 +283,36 @@ export class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps>
     });
   }
 
-  override async getTable(
-    options: TableRequestOptions
-  ): Promise<TableResponse> {
-    const {filterOwner, spatialFilter, abortController, ...params} = options;
-    const {
-      columns,
-      searchFilterColumn,
-      searchFilterText,
-      sortBy,
-      sortDirection,
-      sortByColumnType,
-      offset = 0,
-      limit = 10,
-    } = params;
+  override async getTable({
+    columns,
+    searchFilterColumn,
+    searchFilterText,
+    sortBy,
+    sortDirection,
+    sortByColumnType,
+    offset = 0,
+    limit = 10,
+    filters,
+    filterOwner,
+    spatialFilter,
+  }: TableRequestOptions): Promise<TableResponse> {
+    // Filter.
+    let filteredFeatures = this._getFilteredFeatures(
+      spatialFilter,
+      filters,
+      filterOwner
+    );
 
-    if (!this._features.length) {
+    if (!filteredFeatures.length) {
       return {rows: [], totalCount: 0};
     }
 
-    // Filter.
-    let filteredFeatures = this._getFilteredFeatures(filterOwner);
-
     // Search.
-    // TODO: Could we get the same behavior by applying filters in loadTiles()?
     if (searchFilterColumn && searchFilterText) {
       filteredFeatures = filteredFeatures.filter(
         (row) =>
           row[searchFilterColumn] &&
-          String(row[searchFilterColumn])
+          String(row[searchFilterColumn] as unknown)
             .toLowerCase()
             .includes(String(searchFilterText).toLowerCase())
       );
@@ -321,15 +350,21 @@ export class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps>
     operation,
     operationColumn,
     joinOperation,
+    filters,
     filterOwner,
+    spatialFilter,
   }: TimeSeriesRequestOptions): Promise<TimeSeriesResponse> {
-    if (!this._features.length) {
+    const filteredFeatures = this._getFilteredFeatures(
+      spatialFilter,
+      filters,
+      filterOwner
+    );
+
+    if (!filteredFeatures.length) {
       return {rows: []};
     }
 
-    const filteredFeatures = this._getFilteredFeatures(filterOwner);
-
-    assertColumn(this._features, column as string, operationColumn as string);
+    assertColumn(this._features, column, operationColumn as string);
 
     const rows =
       groupValuesByDateColumn({
@@ -346,17 +381,24 @@ export class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps>
 
   override async getRange({
     column,
+    filters,
     filterOwner,
+    spatialFilter,
   }: RangeRequestOptions): Promise<RangeResponse> {
+    assertColumn(this._features, column);
+
+    const filteredFeatures = this._getFilteredFeatures(
+      spatialFilter,
+      filters,
+      filterOwner
+    );
+
     if (!this._features.length) {
       // TODO: Is this the only nullable response in the Widgets API? If so,
       // can we do something more consistent?
       return null;
     }
 
-    assertColumn(this._features, column);
-
-    const filteredFeatures = this._getFilteredFeatures(filterOwner);
     return {
       min: aggregationFunctions.min(filteredFeatures, column),
       max: aggregationFunctions.max(filteredFeatures, column),
@@ -367,10 +409,16 @@ export class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps>
    * INTERNAL
    */
 
-  private _getFilteredFeatures(filterOwner: string | undefined): FeatureData[] {
+  private _getFilteredFeatures(
+    spatialFilter?: SpatialFilter,
+    filters?: Record<string, Filter>,
+    filterOwner?: string
+  ): FeatureData[] {
+    assert(spatialFilter, 'spatialFilter required for tilesets');
+    this._extractTileFeatures(spatialFilter);
     return applyFilters(
       this._features,
-      getApplicableFilters(filterOwner, this.props.filters),
+      getApplicableFilters(filterOwner, filters || this.props.filters),
       this.props.filtersLogicalOperator || 'and'
     );
   }