@carto/api-client 0.5.0-alpha.1 → 0.5.0-alpha.13

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

@@ -1,9 +1,6 @@
-import {TilesetSourceOptions} from '../sources/index.js';
-import type {ModelSource} from '../models/index.js';
 import {
   CategoryRequestOptions,
   CategoryResponse,
-  FeaturesRequestOptions,
   FeaturesResponse,
   FormulaRequestOptions,
   FormulaResponse,
@@ -18,32 +15,15 @@ import {
   TimeSeriesRequestOptions,
   TimeSeriesResponse,
 } from './types.js';
-import {InvalidColumnError, getApplicableFilters} from '../utils.js';
-import {TileFormat} from '../constants.js';
 import {SpatialFilter, Tile} from '../types.js';
-import {
-  TileFeatureExtractOptions,
-  applyFilters,
-  geojsonFeatures,
-  tileFeatures,
-} from '../filters/index.js';
-import {
-  aggregationFunctions,
-  applySorting,
-  groupValuesByColumn,
-  groupValuesByDateColumn,
-  histogram,
-  scatterPlot,
-} from '../operations/index.js';
-import {FeatureData} from '../types-internal.js';
+import {TileFeatureExtractOptions} from '../filters/index.js';
 import {FeatureCollection} from 'geojson';
-import {SpatialDataType} from '../sources/types.js';
 import {WidgetSource, WidgetSourceProps} from './widget-source.js';
-
-// TODO(cleanup): Parameter defaults in source functions and widget API calls are
-// currently duplicated and possibly inconsistent. Consider consolidating and
-// operating on Required<T> objects. See:
-// https://github.com/CartoDB/carto-api-client/issues/39
+import {Method} from '../workers/constants.js';
+import {WorkerRequest, WorkerResponse} from '../workers/types.js';
+import {SpatialDataType, TilesetSourceOptions} from '../sources/types.js';
+import {TileFormat} from '../constants.js';
+import {WidgetTilesetSourceImpl} from './widget-tileset-source-impl.js';
 
 export type WidgetTilesetSourceProps = WidgetSourceProps &
   Omit<TilesetSourceOptions, 'filters'> & {
@@ -76,332 +56,252 @@ export type WidgetTilesetSourceResult = {widgetSource: WidgetTilesetSource};
  * ```
  */
 export class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps> {
-  private _tiles: Tile[] = [];
-  private _features: FeatureData[] = [];
-
-  protected override getModelSource(owner: string): ModelSource {
-    return {
-      ...super._getModelSource(owner),
-      type: 'tileset',
-      data: this.props.tableName,
-    };
-  }
+  protected _localImpl: WidgetTilesetSourceImpl | null = null;
 
-  /**
-   * 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[]) {
-    this._tiles = tiles as Tile[];
-  }
+  protected _workerImpl: Worker | null = null;
+  protected _workerEnabled: boolean;
+  protected _workerNextRequestId = 1;
 
-  /**
-   * 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;
-  }) {
-    this._features = tileFeatures({
-      tiles: this._tiles,
-      options,
-      spatialFilter,
-      uniqueIdProperty,
-      tileFormat: this.props.tileFormat,
-      spatialDataColumn: this.props.spatialDataColumn,
-      spatialDataType: this.props.spatialDataType,
-    });
-  }
+  constructor(props: WidgetTilesetSourceProps) {
+    super(props);
 
-  /** Loads features as GeoJSON (used for testing). */
-  loadGeoJSON({
-    geojson,
-    spatialFilter,
-    uniqueIdProperty,
-  }: {
-    geojson: FeatureCollection;
-    spatialFilter: SpatialFilter;
-    uniqueIdProperty?: string;
-  }) {
-    this._features = geojsonFeatures({
-      geojson,
-      spatialFilter,
-      uniqueIdProperty,
-    });
-  }
+    this._workerEnabled =
+      (props.widgetWorker ?? true) &&
+      TSUP_FORMAT !== 'cjs' &&
+      typeof Worker !== 'undefined';
 
-  override async getFeatures(
-    options: FeaturesRequestOptions
-  ): Promise<FeaturesResponse> {
-    throw new Error('getFeatures not supported for tilesets');
+    if (!this._workerEnabled) {
+      this._localImpl = new WidgetTilesetSourceImpl(this.props);
+    }
   }
 
-  async getFormula({
-    column = '*',
-    operation = 'count',
-    joinOperation,
-    filterOwner,
-  }: FormulaRequestOptions): Promise<FormulaResponse> {
-    if (operation === 'custom') {
-      throw new Error('Custom aggregation not supported for tilesets');
-    }
+  destroy() {
+    this._localImpl?.destroy();
+    this._localImpl = null;
 
-    if (!this._features.length) {
-      return {value: null};
-    }
+    this._workerImpl?.terminate();
+    this._workerImpl = null;
 
-    // Column is required except when operation is 'count'.
-    if ((column && column !== '*') || operation !== 'count') {
-      assertColumn(this._features, column);
-    }
+    super.destroy();
+  }
 
-    const filteredFeatures = this._getFilteredFeatures(filterOwner);
+  /////////////////////////////////////////////////////////////////////////////
+  // WEB WORKER MANAGEMENT
 
-    if (filteredFeatures.length === 0 && operation !== 'count') {
-      return {value: null};
+  /**
+   * Returns an initialized Worker, to be reused for the lifecycle of this
+   * source instance.
+   */
+  protected _getWorker(): Worker {
+    if (this._workerImpl) {
+      return this._workerImpl;
     }
 
-    const targetOperation = aggregationFunctions[operation];
-    return {
-      value: targetOperation(
-        filteredFeatures as FeatureData[],
-        column,
-        joinOperation
-      ),
-    };
+    this._workerImpl = new Worker(
+      new URL('@carto/api-client/worker', import.meta.url),
+      {
+        type: 'module',
+        name: 'cartowidgettileset',
+      }
+    );
+
+    this._workerImpl.postMessage({
+      method: Method.INIT,
+      params: [this.props],
+    } as WorkerRequest);
+
+    return this._workerImpl;
   }
 
-  override async getHistogram({
-    operation = 'count',
-    ticks,
-    column,
-    joinOperation,
-    filterOwner,
-  }: HistogramRequestOptions): Promise<HistogramResponse> {
-    if (!this._features.length) {
-      return [];
+  /** Executes a given method on the worker. */
+  protected _executeWorkerMethod<T>(
+    method: Method,
+    params: unknown[],
+    signal?: AbortSignal
+  ): Promise<T> {
+    if (!this._workerEnabled) {
+      // @ts-expect-error No type-checking dynamic method name.
+      return this._localImpl[method](...params);
     }
 
-    const filteredFeatures = this._getFilteredFeatures(filterOwner);
+    const worker = this._getWorker();
+    const requestId = this._workerNextRequestId++;
 
-    assertColumn(this._features, column);
+    // 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};
+    }
 
-    return histogram({
-      data: filteredFeatures,
-      valuesColumns: normalizeColumns(column),
-      joinOperation,
-      ticks,
-      operation,
-    });
-  }
+    let resolve: ((value: T) => void) | null = null;
+    let reject: ((reason: any) => void) | null = null;
+
+    // If worker sends message to main process, check whether it's a response
+    // to this request, and whether the request can been aborted. Then resolve
+    // or reject the Promise.
+    function onMessage(e: MessageEvent) {
+      const response = e.data as WorkerResponse;
+      if (response.requestId !== requestId) return;
+      if (signal?.aborted) return; // handled by 'abort' listener
+
+      if (response.ok) {
+        resolve!(response.result as T);
+      } else {
+        reject!(new Error(response.error));
+      }
+    }
 
-  override async getCategories({
-    column,
-    operation = 'count',
-    operationColumn,
-    joinOperation,
-    filterOwner,
-  }: CategoryRequestOptions): Promise<CategoryResponse> {
-    if (!this._features.length) {
-      return [];
+    // If request is aborted by user, immediately reject the Promise.
+    function onAbort() {
+      reject!(new Error(signal!.reason));
     }
 
-    const filteredFeatures = this._getFilteredFeatures(filterOwner);
+    worker.addEventListener('message', onMessage);
+    signal?.addEventListener('abort', onAbort);
 
-    assertColumn(this._features, column as string, operationColumn as string);
+    // Send the task to the worker, creating a Promise to resolve/reject later.
+    const promise = new Promise<T>((_resolve, _reject) => {
+      resolve = _resolve;
+      reject = _reject;
 
-    const groups = groupValuesByColumn({
-      data: filteredFeatures,
-      valuesColumns: normalizeColumns(operationColumn || column),
-      joinOperation,
-      keysColumn: column,
-      operation,
+      worker.postMessage({
+        requestId,
+        method,
+        params,
+      } as WorkerRequest);
     });
 
-    return groups || [];
+    // Whether the task completes, fails, or aborts: clean up afterward.
+    void promise.finally(() => {
+      worker.removeEventListener('message', onMessage);
+      signal?.removeEventListener('abort', onAbort);
+    });
+
+    return promise;
   }
 
-  override async getScatter({
-    xAxisColumn,
-    yAxisColumn,
-    xAxisJoinOperation,
-    yAxisJoinOperation,
-    filterOwner,
-  }: ScatterRequestOptions): Promise<ScatterResponse> {
-    if (!this._features.length) {
-      return [];
+  /////////////////////////////////////////////////////////////////////////////
+  // DATA LOADING
+
+  /**
+   * 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[]) {
+    if (!this._workerEnabled) {
+      return this._localImpl!.loadTiles(tiles);
     }
 
-    const filteredFeatures = this._getFilteredFeatures(filterOwner);
+    const worker = this._getWorker();
 
-    assertColumn(this._features, xAxisColumn, yAxisColumn);
+    tiles = (tiles as Tile[]).map(({id, bbox, data}) => ({
+      id,
+      bbox,
+      data,
+    }));
 
-    return scatterPlot({
-      data: filteredFeatures,
-      xAxisColumns: normalizeColumns(xAxisColumn),
-      xAxisJoinOperation,
-      yAxisColumns: normalizeColumns(yAxisColumn),
-      yAxisJoinOperation,
-    });
+    worker.postMessage({
+      method: Method.LOAD_TILES,
+      params: [tiles],
+    } as WorkerRequest);
   }
 
-  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;
-
-    if (!this._features.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])
-            .toLowerCase()
-            .includes(String(searchFilterText).toLowerCase())
-      );
+  /** Configures options used to extract features from tiles. */
+  setTileFeatureExtractOptions(options: TileFeatureExtractOptions) {
+    if (!this._workerEnabled) {
+      return this._localImpl?.setTileFeatureExtractOptions(options);
     }
 
-    // Sort.
-    let rows = applySorting(filteredFeatures, {
-      sortBy,
-      sortByDirection: sortDirection,
-      sortByColumnType,
-    });
-    const totalCount = rows.length;
+    const worker = this._getWorker();
 
-    // Offset and limit.
-    rows = rows.slice(
-      Math.min(offset, totalCount),
-      Math.min(offset + limit, totalCount)
-    );
-
-    // Select columns.
-    rows = rows.map((srcRow: FeatureData) => {
-      const dstRow: FeatureData = {};
-      for (const column of columns) {
-        dstRow[column] = srcRow[column];
-      }
-      return dstRow;
+    worker.postMessage({
+      type: Method.SET_TILE_FEATURE_EXTRACT_OPTIONS,
+      params: [options],
     });
-
-    return {rows, totalCount} as TableResponse;
   }
 
-  override async getTimeSeries({
-    column,
-    stepSize,
-    operation,
-    operationColumn,
-    joinOperation,
-    filterOwner,
-  }: TimeSeriesRequestOptions): Promise<TimeSeriesResponse> {
-    if (!this._features.length) {
-      return {rows: []};
+  /**
+   * 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;
+  }) {
+    if (!this._workerEnabled) {
+      return this._localImpl!.loadGeoJSON({geojson, spatialFilter});
     }
 
-    const filteredFeatures = this._getFilteredFeatures(filterOwner);
-
-    assertColumn(this._features, column as string, operationColumn as string);
-
-    const rows =
-      groupValuesByDateColumn({
-        data: filteredFeatures,
-        valuesColumns: normalizeColumns(operationColumn || column),
-        keysColumn: column,
-        groupType: stepSize,
-        operation,
-        joinOperation,
-      }) || [];
+    const worker = this._getWorker();
 
-    return {rows};
+    worker.postMessage({
+      method: Method.LOAD_GEOJSON,
+      params: [{geojson, spatialFilter}],
+    } as WorkerRequest);
   }
 
-  override async getRange({
-    column,
-    filterOwner,
-  }: RangeRequestOptions): Promise<RangeResponse> {
-    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);
+  /////////////////////////////////////////////////////////////////////////////
+  // WIDGETS API
 
-    const filteredFeatures = this._getFilteredFeatures(filterOwner);
-    return {
-      min: aggregationFunctions.min(filteredFeatures, column),
-      max: aggregationFunctions.max(filteredFeatures, column),
-    };
+  // eslint-disable-next-line @typescript-eslint/require-await
+  override async getFeatures(): Promise<FeaturesResponse> {
+    throw new Error('getFeatures not supported for tilesets');
   }
 
-  /****************************************************************************
-   * INTERNAL
-   */
-
-  private _getFilteredFeatures(filterOwner: string | undefined): FeatureData[] {
-    return applyFilters(
-      this._features,
-      getApplicableFilters(filterOwner, this.props.filters),
-      this.props.filtersLogicalOperator || 'and'
-    );
+  async getFormula({
+    signal,
+    ...options
+  }: FormulaRequestOptions): Promise<FormulaResponse> {
+    return this._executeWorkerMethod(Method.GET_FORMULA, [options], signal);
   }
-}
 
-function assertColumn(
-  features: FeatureData[],
-  ...columnArgs: string[] | string[][]
-) {
-  // TODO(cleanup): Can drop support for multiple column shapes here?
+  override async getHistogram({
+    signal,
+    ...options
+  }: HistogramRequestOptions): Promise<HistogramResponse> {
+    return this._executeWorkerMethod(Method.GET_HISTOGRAM, [options], signal);
+  }
 
-  // Due to the multiple column shape, we normalise it as an array with normalizeColumns
-  const columns = Array.from(new Set(columnArgs.map(normalizeColumns).flat()));
+  override async getCategories({
+    signal,
+    ...options
+  }: CategoryRequestOptions): Promise<CategoryResponse> {
+    return this._executeWorkerMethod(Method.GET_CATEGORIES, [options], signal);
+  }
 
-  const featureKeys = Object.keys(features[0]);
+  override async getScatter({
+    signal,
+    ...options
+  }: ScatterRequestOptions): Promise<ScatterResponse> {
+    return this._executeWorkerMethod(Method.GET_SCATTER, [options], signal);
+  }
 
-  const invalidColumns = columns.filter(
-    (column) => !featureKeys.includes(column)
-  );
+  override async getTable({
+    signal,
+    ...options
+  }: TableRequestOptions): Promise<TableResponse> {
+    return this._executeWorkerMethod(Method.GET_TABLE, [options], signal);
+  }
 
-  if (invalidColumns.length) {
-    throw new InvalidColumnError(
-      `Missing column(s): ${invalidColumns.join(', ')}`
-    );
+  override async getTimeSeries({
+    signal,
+    ...options
+  }: TimeSeriesRequestOptions): Promise<TimeSeriesResponse> {
+    return this._executeWorkerMethod(Method.GET_TIME_SERIES, [options], signal);
   }
-}
 
-function normalizeColumns(columns: string | string[]): string[] {
-  return Array.isArray(columns)
-    ? columns
-    : typeof columns === 'string'
-      ? [columns]
-      : [];
+  override async getRange({
+    signal,
+    ...options
+  }: RangeRequestOptions): Promise<RangeResponse> {
+    return this._executeWorkerMethod(Method.GET_RANGE, [options], signal);
+  }
 }

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,19 @@
+import type {Method} from './constants.js';
+
+export type WorkerRequest = {
+  requestId?: number;
+  method: Method;
+  params: unknown[];
+};
+
+export type WorkerResponse =
+  | {
+      requestId: number;
+      ok: true;
+      result: unknown;
+    }
+  | {
+      requestId: number;
+      ok: false;
+      error: string;
+    };

package/src/workers/widget-tileset-worker.ts

@@ -0,0 +1,40 @@
+import {WidgetTilesetSourceImpl} from '../widget-sources/widget-tileset-source-impl.js';
+import {type WidgetTilesetSourceProps} from '../widget-sources/widget-tileset-source.js';
+import {Method} from './constants.js';
+import type {WorkerRequest, WorkerResponse} from './types.js';
+
+/*
+ * Web Worker, compiled as a separate `@carto/api-client/worker` entrypoint.
+ *
+ * Workers are scoped to the lifecycle of a single WidgetTilesetSource instance,
+ * representing and executing calculations on a single datasource.
+ */
+
+let source: WidgetTilesetSourceImpl;
+
+addEventListener('message', (e) => {
+  const {method, params, requestId} = e.data as WorkerRequest;
+
+  if (method === Method.INIT) {
+    source = new WidgetTilesetSourceImpl({
+      ...(params[0] as WidgetTilesetSourceProps),
+      widgetWorker: false,
+    });
+    return;
+  }
+
+  if (!source) {
+    const error = `Cannot execute "${method}" on uninitialized source.`;
+    postMessage({ok: false, error, requestId} as WorkerResponse);
+    return;
+  }
+
+  // @ts-expect-error No type-checking dynamic method name.
+  Promise.resolve(source[method](...params))
+    .then((result) => {
+      postMessage({ok: true, result, requestId} as WorkerResponse);
+    })
+    .catch((error) => {
+      postMessage({ok: false, error, requestId} as WorkerResponse);
+    });
+});

package/build/api/carto-api-error.d.ts

@@ -1,26 +0,0 @@
-import { MapType } from '../types';
-export type APIRequestType = 'Map data' | 'Map instantiation' | 'Public map' | 'Tile stats' | 'SQL' | 'Basemap style';
-export type APIErrorContext = {
-    requestType: APIRequestType;
-    mapId?: string;
-    connection?: string;
-    source?: string;
-    type?: MapType;
-};
-/**
- *
- * Custom error for reported errors in CARTO Maps API.
- * Provides useful debugging information in console and context for applications.
- *
- */
-export declare class CartoAPIError extends Error {
-    /** Source error from server */
-    error: Error;
-    /** Context (API call & parameters) in which error occured */
-    errorContext: APIErrorContext;
-    /** Response from server */
-    response?: Response;
-    /** JSON Response from server */
-    responseJson?: any;
-    constructor(error: Error, errorContext: APIErrorContext, response?: Response, responseJson?: any);
-}