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

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

@@ -8,6 +8,7 @@ import {
   WidgetRemoteSourceProps,
 } from './widget-remote-source.js';
 import {ModelSource} from '../models/model.js';
+import {Filters} from '../types.js';
 
 type LayerQuerySourceOptions =
   | Omit<VectorQuerySourceOptions, 'filters'>
@@ -41,9 +42,12 @@ export type WidgetQuerySourceResult = {widgetSource: WidgetQuerySource};
 export class WidgetQuerySource extends WidgetRemoteSource<
   LayerQuerySourceOptions & WidgetRemoteSourceProps
 > {
-  protected override getModelSource(owner: string): ModelSource {
+  protected override getModelSource(
+    filters: Filters | undefined,
+    filterOwner?: string
+  ): ModelSource {
     return {
-      ...super._getModelSource(owner),
+      ...super._getModelSource(filters, filterOwner),
       type: 'query',
       data: this.props.sqlQuery,
       queryParameters: this.props.queryParameters,

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

@@ -31,10 +31,18 @@ export type WidgetRemoteSourceProps = WidgetSourceProps;
 export abstract class WidgetRemoteSource<
   Props extends WidgetRemoteSourceProps,
 > extends WidgetSource<Props> {
+  protected _headers: Record<string, string> = {};
+
+  /** Assigns HTTP headers to be included on API requests from this source. */
+  setRequestHeaders(headers: Record<string, string>): void {
+    this._headers = headers;
+  }
+
   async getCategories(
     options: CategoryRequestOptions
   ): Promise<CategoryResponse> {
     const {
+      filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
@@ -43,7 +51,7 @@ export abstract class WidgetRemoteSource<
       ...params
     } = options;
     const {column, operation, operationColumn} = params;
-    const source = this.getModelSource(filterOwner);
+    const source = this.getModelSource(filters, filterOwner);
     const spatialFiltersResolution = this._getSpatialFiltersResolution(
       source,
       spatialFilter,
@@ -65,7 +73,7 @@ export abstract class WidgetRemoteSource<
         operation,
         operationColumn: operationColumn || column,
       },
-      opts: {abortController},
+      opts: {abortController, headers: this._headers},
     }).then((res: CategoriesModelResponse) => normalizeObjectKeys(res.rows));
   }
 
@@ -73,6 +81,7 @@ export abstract class WidgetRemoteSource<
     options: FeaturesRequestOptions
   ): Promise<FeaturesResponse> {
     const {
+      filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
@@ -81,7 +90,7 @@ export abstract class WidgetRemoteSource<
       ...params
     } = options;
     const {columns, dataType, featureIds, z, limit, tileResolution} = params;
-    const source = this.getModelSource(filterOwner);
+    const source = this.getModelSource(filters, filterOwner);
     const spatialFiltersResolution = this._getSpatialFiltersResolution(
       source,
       spatialFilter,
@@ -106,13 +115,14 @@ export abstract class WidgetRemoteSource<
         limit: limit || 1000,
         tileResolution: tileResolution || DEFAULT_TILE_RESOLUTION,
       },
-      opts: {abortController},
+      opts: {abortController, headers: this._headers},
       // Avoid `normalizeObjectKeys()`, which changes column names.
     }).then(({rows}: FeaturesModelResponse) => ({rows}));
   }
 
   async getFormula(options: FormulaRequestOptions): Promise<FormulaResponse> {
     const {
+      filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
@@ -122,7 +132,7 @@ export abstract class WidgetRemoteSource<
       ...params
     } = options;
     const {column, operation} = params;
-    const source = this.getModelSource(filterOwner);
+    const source = this.getModelSource(filters, filterOwner);
     const spatialFiltersResolution = this._getSpatialFiltersResolution(
       source,
       spatialFilter,
@@ -144,7 +154,7 @@ export abstract class WidgetRemoteSource<
         operation: operation ?? 'count',
         operationExp,
       },
-      opts: {abortController},
+      opts: {abortController, headers: this._headers},
     }).then((res: FormulaModelResponse) => normalizeObjectKeys(res.rows[0]));
   }
 
@@ -152,6 +162,7 @@ export abstract class WidgetRemoteSource<
     options: HistogramRequestOptions
   ): Promise<HistogramResponse> {
     const {
+      filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
@@ -160,7 +171,7 @@ export abstract class WidgetRemoteSource<
       ...params
     } = options;
     const {column, operation, ticks} = params;
-    const source = this.getModelSource(filterOwner);
+    const source = this.getModelSource(filters, filterOwner);
     const spatialFiltersResolution = this._getSpatialFiltersResolution(
       source,
       spatialFilter,
@@ -178,7 +189,7 @@ export abstract class WidgetRemoteSource<
         spatialFilter,
       },
       params: {column, operation, ticks},
-      opts: {abortController},
+      opts: {abortController, headers: this._headers},
     }).then((res: HistogramModelResponse) => normalizeObjectKeys(res.rows));
 
     if (data.length) {
@@ -196,6 +207,7 @@ export abstract class WidgetRemoteSource<
 
   async getRange(options: RangeRequestOptions): Promise<RangeResponse> {
     const {
+      filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
@@ -204,7 +216,7 @@ export abstract class WidgetRemoteSource<
       ...params
     } = options;
     const {column} = params;
-    const source = this.getModelSource(filterOwner);
+    const source = this.getModelSource(filters, filterOwner);
     const spatialFiltersResolution = this._getSpatialFiltersResolution(
       source,
       spatialFilter,
@@ -222,12 +234,13 @@ export abstract class WidgetRemoteSource<
         spatialFilter,
       },
       params: {column},
-      opts: {abortController},
+      opts: {abortController, headers: this._headers},
     }).then((res: RangeModelResponse) => normalizeObjectKeys(res.rows[0]));
   }
 
   async getScatter(options: ScatterRequestOptions): Promise<ScatterResponse> {
     const {
+      filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
@@ -238,7 +251,7 @@ export abstract class WidgetRemoteSource<
     const {xAxisColumn, xAxisJoinOperation, yAxisColumn, yAxisJoinOperation} =
       params;
 
-    const source = this.getModelSource(filterOwner);
+    const source = this.getModelSource(filters, filterOwner);
     const spatialFiltersResolution = this._getSpatialFiltersResolution(
       source,
       spatialFilter,
@@ -265,7 +278,7 @@ export abstract class WidgetRemoteSource<
         yAxisJoinOperation,
         limit: HARD_LIMIT,
       },
-      opts: {abortController},
+      opts: {abortController, headers: this._headers},
     })
       .then((res: ScatterModelResponse) => normalizeObjectKeys(res.rows))
       .then((res) => res.map(({x, y}: {x: number; y: number}) => [x, y]));
@@ -273,6 +286,7 @@ export abstract class WidgetRemoteSource<
 
   async getTable(options: TableRequestOptions): Promise<TableResponse> {
     const {
+      filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
@@ -281,7 +295,7 @@ export abstract class WidgetRemoteSource<
       ...params
     } = options;
     const {columns, sortBy, sortDirection, offset = 0, limit = 10} = params;
-    const source = this.getModelSource(filterOwner);
+    const source = this.getModelSource(filters, filterOwner);
     const spatialFiltersResolution = this._getSpatialFiltersResolution(
       source,
       spatialFilter,
@@ -308,7 +322,7 @@ export abstract class WidgetRemoteSource<
         limit,
         offset,
       },
-      opts: {abortController},
+      opts: {abortController, headers: this._headers},
     }).then((res: TableModelResponse) => ({
       // Avoid `normalizeObjectKeys()`, which changes column names.
       rows: res.rows ?? (res as any).ROWS,
@@ -320,6 +334,7 @@ export abstract class WidgetRemoteSource<
     options: TimeSeriesRequestOptions
   ): Promise<TimeSeriesResponse> {
     const {
+      filters = this.props.filters,
       filterOwner,
       abortController,
       spatialFilter,
@@ -339,7 +354,7 @@ export abstract class WidgetRemoteSource<
       splitByCategoryValues,
     } = params;
 
-    const source = this.getModelSource(filterOwner);
+    const source = this.getModelSource(filters, filterOwner);
     const spatialFiltersResolution = this._getSpatialFiltersResolution(
       source,
       spatialFilter,
@@ -370,7 +385,7 @@ export abstract class WidgetRemoteSource<
         splitByCategoryLimit,
         splitByCategoryValues,
       },
-      opts: {abortController},
+      opts: {abortController, headers: this._headers},
     }).then((res: TimeSeriesModelResponse) => ({
       rows: normalizeObjectKeys(res.rows),
       categories: res.metadata?.categories,

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

@@ -17,7 +17,12 @@ import {
   TimeSeriesResponse,
   ViewState,
 } from './types.js';
-import {FilterLogicalOperator, Filter, SpatialFilter} from '../types.js';
+import {
+  FilterLogicalOperator,
+  Filter,
+  SpatialFilter,
+  Filters,
+} from '../types.js';
 import {getApplicableFilters} from '../utils.js';
 import {getClient} from '../client.js';
 import {ModelSource} from '../models/model.js';
@@ -58,10 +63,14 @@ export abstract class WidgetSource<Props extends WidgetSourceProps> {
    * properties, and adding additional required properties including 'type' and
    * 'data'.
    */
-  protected abstract getModelSource(owner: string | undefined): ModelSource;
+  protected abstract getModelSource(
+    filters: Filters | undefined,
+    filterOwner?: string
+  ): ModelSource;
 
   protected _getModelSource(
-    owner?: string
+    filters: Filters | undefined,
+    filterOwner?: string
   ): Omit<ModelSource, 'type' | 'data'> {
     const props = this.props;
     return {
@@ -70,7 +79,7 @@ export abstract class WidgetSource<Props extends WidgetSourceProps> {
       clientId: props.clientId as string,
       accessToken: props.accessToken,
       connectionName: props.connectionName,
-      filters: getApplicableFilters(owner, props.filters),
+      filters: getApplicableFilters(filterOwner, filters || props.filters),
       filtersLogicalOperator: props.filtersLogicalOperator,
       spatialDataType: props.spatialDataType,
       spatialDataColumn: props.spatialDataColumn,

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

@@ -8,6 +8,7 @@ import {
   WidgetRemoteSourceProps,
 } from './widget-remote-source.js';
 import {ModelSource} from '../models/model.js';
+import {Filters} from '../types.js';
 
 type LayerTableSourceOptions =
   | Omit<VectorTableSourceOptions, 'filters'>
@@ -41,9 +42,12 @@ export type WidgetTableSourceResult = {widgetSource: WidgetTableSource};
 export class WidgetTableSource extends WidgetRemoteSource<
   LayerTableSourceOptions & WidgetRemoteSourceProps
 > {
-  protected override getModelSource(owner: string): ModelSource {
+  protected override getModelSource(
+    filters: Filters | undefined,
+    filterOwner?: string
+  ): ModelSource {
     return {
-      ...super._getModelSource(owner),
+      ...super._getModelSource(filters, filterOwner),
       type: 'table',
       data: this.props.tableName,
     };

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
@@ -78,12 +79,18 @@ export type WidgetTilesetSourceResult = {widgetSource: WidgetTilesetSource};
 export class WidgetTilesetSource<
   Props extends WidgetTilesetSourceProps = WidgetTilesetSourceProps,
 > extends WidgetSource<Props> {
-  protected _tiles: Tile[] = [];
-  protected _features: FeatureData[] = [];
-
-  protected override getModelSource(owner: string): ModelSource {
+  private _tiles: Tile[] = [];
+  private _features: FeatureData[] = [];
+  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,
     };
@@ -96,50 +103,58 @@ export class WidgetTilesetSource<
    */
   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;
-    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,
-      ...this.props,
     });
+
+    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');
   }
 
@@ -147,22 +162,24 @@ export class WidgetTilesetSource<
     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};
@@ -170,11 +187,7 @@ export class WidgetTilesetSource<
 
     const targetOperation = aggregationFunctions[operation];
     return {
-      value: targetOperation(
-        filteredFeatures as FeatureData[],
-        column,
-        joinOperation
-      ),
+      value: targetOperation(filteredFeatures, column, joinOperation),
     };
   }
 
@@ -183,16 +196,22 @@ export class WidgetTilesetSource<
     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),
@@ -207,15 +226,21 @@ export class WidgetTilesetSource<
     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,
@@ -233,14 +258,20 @@ export class WidgetTilesetSource<
     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({
@@ -252,35 +283,36 @@ export class WidgetTilesetSource<
     });
   }
 
-  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())
       );
@@ -318,15 +350,21 @@ export class WidgetTilesetSource<
     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({
@@ -343,17 +381,24 @@ export class WidgetTilesetSource<
 
   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),
@@ -364,10 +409,16 @@ export class WidgetTilesetSource<
    * 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'
     );
   }