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

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

@@ -1,9 +1,8 @@
+/* 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 +17,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, SpatialFilter, Tile} from '../types.js';
 import {
   TileFeatureExtractOptions,
   applyFilters,
@@ -39,6 +38,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,19 +75,12 @@ export type WidgetTilesetSourceResult = {widgetSource: WidgetTilesetSource};
  * const { widgetSource } = await data;
  * ```
  */
-export class WidgetTilesetSource<
-  Props extends WidgetTilesetSourceProps = WidgetTilesetSourceProps,
-> extends WidgetSource<Props> {
-  protected _tiles: Tile[] = [];
-  protected _features: FeatureData[] = [];
-
-  protected override getModelSource(owner: string): ModelSource {
-    return {
-      ...super._getModelSource(owner),
-      type: 'tileset',
-      data: this.props.tableName,
-    };
-  }
+export class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps> {
+  private _tiles: Tile[] = [];
+  private _features: FeatureData[] = [];
+  private _tileFeatureExtractOptions: TileFeatureExtractOptions = {};
+  private _tileFeatureExtractPreviousInputs: {spatialFilter?: SpatialFilter} =
+    {};
 
   /**
    * Loads features as a list of tiles (typically provided by deck.gl).
@@ -96,50 +89,61 @@ 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({
       tiles: this._tiles,
-      options,
+      tileFormat: this.props.tileFormat,
+      ...this._tileFeatureExtractOptions,
+
       spatialFilter,
-      uniqueIdProperty,
-      ...this.props,
+      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');
   }
 
@@ -147,22 +151,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 +176,7 @@ export class WidgetTilesetSource<
 
     const targetOperation = aggregationFunctions[operation];
     return {
-      value: targetOperation(
-        filteredFeatures as FeatureData[],
-        column,
-        joinOperation
-      ),
+      value: targetOperation(filteredFeatures, column, joinOperation),
     };
   }
 
@@ -183,16 +185,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 +215,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 +247,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 +272,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 +339,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 +370,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 +398,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'
     );
   }

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

@@ -0,0 +1,238 @@
+import {
+  CategoryRequestOptions,
+  CategoryResponse,
+  FeaturesResponse,
+  FormulaRequestOptions,
+  FormulaResponse,
+  HistogramRequestOptions,
+  HistogramResponse,
+  RangeRequestOptions,
+  RangeResponse,
+  ScatterRequestOptions,
+  ScatterResponse,
+  TableRequestOptions,
+  TableResponse,
+  TimeSeriesRequestOptions,
+  TimeSeriesResponse,
+} from './types.js';
+import {SpatialFilter, Tile} from '../types.js';
+import {TileFeatureExtractOptions} from '../filters/index.js';
+import {FeatureCollection} from 'geojson';
+import {WidgetSource} from './widget-source.js';
+import {WidgetTilesetSourceProps} from './widget-tileset-source.js';
+import {Method} from '../workers/constants.js';
+import {WorkerRequest, WorkerResponse} from '../workers/types.js';
+
+/**
+ * TODO
+ */
+export class WidgetTilesetWorkerSource extends WidgetSource<WidgetTilesetSourceProps> {
+  constructor(props: WidgetTilesetSourceProps) {
+    super(props);
+
+    WidgetTilesetWorkerSource.init();
+    WidgetTilesetWorkerSource.WORKER.postMessage({
+      tableName: this.props.tableName,
+      method: Method.INIT,
+      params: [this.props],
+    } as WorkerRequest);
+  }
+
+  /**
+   * Loads features as a list of tiles (typically provided by deck.gl).
+   * After tiles are loaded, {@link extractTileFeatures} must be called
+   * before computing statistics on the tiles.
+   */
+  loadTiles(tiles: unknown[]) {
+    tiles = (tiles as Tile[]).map(({id, bbox, data}) => ({
+      id,
+      bbox,
+      data,
+    }));
+
+    WidgetTilesetWorkerSource.WORKER.postMessage({
+      tableName: this.props.tableName,
+      method: Method.LOAD_TILES,
+      params: [tiles],
+    } as WorkerRequest);
+  }
+
+  /** Configures options used to extract features from tiles. */
+  setTileFeatureExtractOptions(options: TileFeatureExtractOptions) {
+    WidgetTilesetWorkerSource.WORKER.postMessage({
+      tableName: this.props.tableName,
+      type: Method.SET_TILE_FEATURE_EXTRACT_OPTIONS,
+      params: [options],
+    });
+  }
+
+  /**
+   * 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,
+  }: {
+    geojson: FeatureCollection;
+    spatialFilter: SpatialFilter;
+  }) {
+    WidgetTilesetWorkerSource.WORKER.postMessage({
+      tableName: this.props.tableName,
+      method: Method.LOAD_GEOJSON,
+      params: [{geojson, spatialFilter}],
+    } as WorkerRequest);
+  }
+
+  // eslint-disable-next-line @typescript-eslint/require-await
+  override async getFeatures(): Promise<FeaturesResponse> {
+    throw new Error('getFeatures not supported for tilesets');
+  }
+
+  async getFormula({
+    abortController,
+    ...options
+  }: FormulaRequestOptions): Promise<FormulaResponse> {
+    return this._executeWorkerMethod(
+      this.props.tableName,
+      Method.GET_FORMULA,
+      [options],
+      abortController?.signal
+    );
+  }
+
+  override async getHistogram({
+    abortController,
+    ...options
+  }: HistogramRequestOptions): Promise<HistogramResponse> {
+    return this._executeWorkerMethod(
+      this.props.tableName,
+      Method.GET_HISTOGRAM,
+      [options],
+      abortController?.signal
+    );
+  }
+
+  override async getCategories({
+    abortController,
+    ...options
+  }: CategoryRequestOptions): Promise<CategoryResponse> {
+    return this._executeWorkerMethod(
+      this.props.tableName,
+      Method.GET_CATEGORIES,
+      [options],
+      abortController?.signal
+    );
+  }
+
+  override async getScatter({
+    abortController,
+    ...options
+  }: ScatterRequestOptions): Promise<ScatterResponse> {
+    return this._executeWorkerMethod(
+      this.props.tableName,
+      Method.GET_SCATTER,
+      [options],
+      abortController?.signal
+    );
+  }
+
+  override async getTable({
+    abortController,
+    ...options
+  }: TableRequestOptions): Promise<TableResponse> {
+    return this._executeWorkerMethod(
+      this.props.tableName,
+      Method.GET_TABLE,
+      [options],
+      abortController?.signal
+    );
+  }
+
+  override async getTimeSeries({
+    abortController,
+    ...options
+  }: TimeSeriesRequestOptions): Promise<TimeSeriesResponse> {
+    return this._executeWorkerMethod(
+      this.props.tableName,
+      Method.GET_TIME_SERIES,
+      [options],
+      abortController?.signal
+    );
+  }
+
+  override async getRange({
+    abortController,
+    ...options
+  }: RangeRequestOptions): Promise<RangeResponse> {
+    return this._executeWorkerMethod(
+      this.props.tableName,
+      Method.GET_RANGE,
+      [options],
+      abortController?.signal
+    );
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // WEB WORKER MANAGEMENT
+
+  // TODO: Singleton? Pool shared among datasets? One per dataset?
+  protected static WORKER: Worker;
+  protected static _nextRequestID = 1;
+
+  static init() {
+    WidgetTilesetWorkerSource.WORKER = new Worker(
+      new URL('@carto/api-client/worker', import.meta.url),
+      {
+        type: 'module',
+        name: 'cartowidgettileset',
+      }
+    );
+  }
+
+  _executeWorkerMethod<T>(
+    tableName: string,
+    method: Method,
+    params: unknown[],
+    signal?: AbortSignal
+  ): Promise<T> {
+    const worker = WidgetTilesetWorkerSource.WORKER;
+    const requestId = WidgetTilesetWorkerSource._nextRequestID++;
+
+    // TODO: ViewState may contain non-serializable data, which we do not need.
+    // Remove this sanitization after sc-469614 is fixed.
+    const options = params[0] as any;
+    if (options?.spatialIndexReferenceViewState) {
+      const {zoom, latitude, longitude} =
+        options.spatialIndexReferenceViewState;
+      options.spatialIndexReferenceViewState = {zoom, latitude, longitude};
+    }
+
+    worker.postMessage({
+      requestId,
+      tableName,
+      method,
+      params,
+    } as WorkerRequest);
+
+    return new Promise((resolve, reject) => {
+      function listener(e: MessageEvent) {
+        const response = e.data as WorkerResponse;
+        if (response.requestId !== requestId) return;
+
+        worker.removeEventListener('message', listener);
+
+        if (signal?.aborted) {
+          reject(new Error(signal.reason));
+        } else if (response.ok) {
+          resolve(response.result as T);
+        } else {
+          reject(new Error(response.error));
+        }
+      }
+
+      worker.addEventListener('message', listener);
+    });
+  }
+}

package/src/workers/constants.ts

@@ -0,0 +1,13 @@
+export enum Method {
+  INIT = 'init',
+  LOAD_TILES = 'loadTiles',
+  SET_TILE_FEATURE_EXTRACT_OPTIONS = 'setTileFeatureExtractOptions',
+  LOAD_GEOJSON = 'loadGeoJSON',
+  GET_FORMULA = 'getFormula',
+  GET_HISTOGRAM = 'getHistogram',
+  GET_CATEGORIES = 'getCategories',
+  GET_SCATTER = 'getScatter',
+  GET_TABLE = 'getTable',
+  GET_TIME_SERIES = 'getTimeSeries',
+  GET_RANGE = 'getRange',
+}

package/src/workers/types.ts

@@ -0,0 +1,20 @@
+import type {Method} from './constants.js';
+
+export type WorkerRequest = {
+  requestId?: number;
+  tableName: string; // TODO: Table name is not a unique identifier.
+  method: Method;
+  params: unknown[];
+};
+
+export type WorkerResponse =
+  | {
+      requestId: number;
+      ok: true;
+      result: unknown;
+    }
+  | {
+      requestId: number;
+      ok: false;
+      error: string;
+    };

package/src/workers/utils.ts

@@ -0,0 +1,33 @@
+let _isModuleWorkerSupported: boolean | null =
+  TSUP_FORMAT === 'cjs' ? false : null;
+
+/**
+ * Checks whether current environment supports ES Module Workers, by way of a
+ * two-part check:
+ * (1) If this is a CJS build, return false.
+ * (2) If this is an ESM build, return true if the runtime supports ESM Workers.
+ */
+export function isModuleWorkerSupported(): boolean {
+  if (_isModuleWorkerSupported !== null) {
+    return _isModuleWorkerSupported;
+  }
+
+  try {
+    // https://stackoverflow.com/a/62963963
+    new Worker('blob://', {
+      get type() {
+        _isModuleWorkerSupported = true;
+        return 'module' as const;
+      },
+    });
+  } catch {
+    // Do nothing. 'blob://' should always throw an error to prevent the
+    // browser from creating an (expensive) worker. We care whether the
+    // 'type' getter was called, not about the error.
+  } finally {
+    // If 'type' getter wasn't called, modules are unsupported.
+    _isModuleWorkerSupported ||= false;
+  }
+
+  return _isModuleWorkerSupported;
+}