@carto/api-client 0.4.3 → 0.5.0-alpha.0

package/src/widget-sources/{widget-base-source.ts → widget-remote-source.ts}

@@ -17,90 +17,49 @@ import {
   TimeSeriesRequestOptions,
   TimeSeriesResponse,
 } from './types.js';
-import {FilterLogicalOperator, Filter} 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';
-
-export interface WidgetBaseSourceProps extends Omit<SourceOptions, 'filters'> {
-  apiVersion?: ApiVersion;
-  geoColumn?: string;
-  filters?: Record<string, Filter>;
-  filtersLogicalOperator?: FilterLogicalOperator;
-}
+import {normalizeObjectKeys} from '../utils.js';
+import {DEFAULT_TILE_RESOLUTION} from '../constants-internal.js';
+import {WidgetSource, WidgetSourceProps} from './widget-source.js';
 
-export type WidgetSource = WidgetBaseSource<WidgetBaseSourceProps>;
+export type WidgetRemoteSourceProps = WidgetSourceProps;
 
 /**
- * Source for Widget API requests on a data source defined by a SQL query.
+ * Source for Widget API requests.
  *
  * Abstract class. Use {@link WidgetQuerySource} or {@link WidgetTableSource}.
  */
-export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
-  readonly props: Props;
-
-  static defaultProps: Partial<WidgetBaseSourceProps> = {
-    apiVersion: ApiVersion.V3,
-    apiBaseUrl: DEFAULT_API_BASE_URL,
-    clientId: getClient(),
-    filters: {},
-    filtersLogicalOperator: 'and',
-    geoColumn: DEFAULT_GEO_COLUMN,
-  };
-
-  constructor(props: Props) {
-    this.props = {...WidgetBaseSource.defaultProps, ...props};
-  }
-
-  /**
-   * Subclasses of {@link WidgetBaseSource} must implement this method, calling
-   * {@link WidgetBaseSource.prototype._getModelSource} for common source
-   * properties, and adding additional required properties including 'type' and
-   * 'data'.
-   */
-  protected abstract getModelSource(owner: string | undefined): ModelSource;
-
-  protected _getModelSource(
-    owner?: string
-  ): Omit<ModelSource, 'type' | 'data'> {
-    const props = this.props;
-    return {
-      apiVersion: props.apiVersion as ApiVersion,
-      apiBaseUrl: props.apiBaseUrl as string,
-      clientId: props.clientId as string,
-      accessToken: props.accessToken,
-      connectionName: props.connectionName,
-      filters: getApplicableFilters(owner, props.filters),
-      filtersLogicalOperator: props.filtersLogicalOperator,
-      geoColumn: props.geoColumn,
-    };
-  }
-
-  /****************************************************************************
-   * CATEGORIES
-   */
-
-  /**
-   * Returns a list of labeled datapoints for categorical data. Suitable for
-   * charts including grouped bar charts, pie charts, and tree charts.
-   */
+export abstract class WidgetRemoteSource<
+  Props extends WidgetRemoteSourceProps,
+> extends WidgetSource<Props> {
   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,
@@ -110,29 +69,35 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
     }).then((res: CategoriesModelResponse) => normalizeObjectKeys(res.rows));
   }
 
-  /****************************************************************************
-   * FEATURES
-   */
-
-  /**
-   * Given a list of feature IDs (as found in `_carto_feature_id`) returns all
-   * matching features. In datasets containing features with duplicate geometries,
-   * feature IDs may be duplicated (IDs are a hash of geometry) and so more
-   * results may be returned than IDs in the request.
-   * @internal
-   * @experimental
-   */
   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,
@@ -146,53 +111,72 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
     }).then(({rows}: FeaturesModelResponse) => ({rows}));
   }
 
-  /****************************************************************************
-   * FORMULA
-   */
-
-  /**
-   * Returns a scalar numerical statistic over all matching data. Suitable
-   * for 'headline' or 'scorecard' figures such as counts and sums.
-   */
   async getFormula(options: FormulaRequestOptions): Promise<FormulaResponse> {
     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},
-      params: {column: column ?? '*', operation, operationExp},
+      source: {
+        ...source,
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter,
+      },
+      params: {
+        column: column ?? '*',
+        operation: operation ?? 'count',
+        operationExp,
+      },
       opts: {abortController},
     }).then((res: FormulaModelResponse) => normalizeObjectKeys(res.rows[0]));
   }
 
-  /****************************************************************************
-   * HISTOGRAM
-   */
-
-  /**
-   * Returns a list of labeled datapoints for 'bins' of data defined as ticks
-   * over a numerical range. Suitable for histogram charts.
-   */
   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));
@@ -210,42 +194,57 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
     return [];
   }
 
-  /****************************************************************************
-   * RANGE
-   */
-
-  /**
-   * Returns a range (min and max) for a numerical column of matching rows.
-   * Suitable for displaying certain 'headline' or 'scorecard' statistics,
-   * 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]));
   }
 
-  /****************************************************************************
-   * SCATTER
-   */
-
-  /**
-   * Returns a list of bivariate datapoints defined as numerical 'x' and 'y'
-   * 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 +252,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,
@@ -267,17 +271,22 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
       .then((res) => res.map(({x, y}: {x: number; y: number}) => [x, y]));
   }
 
-  /****************************************************************************
-   * TABLE
-   */
-
-  /**
-   * Returns a list of arbitrary data rows, with support for pagination and
-   * 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 +295,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,
@@ -302,18 +316,17 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
     }));
   }
 
-  /****************************************************************************
-   * TIME SERIES
-   */
-
-  /**
-   * Returns a series of labeled numerical values, grouped into equally-sized
-   * time intervals. Suitable for rendering time series charts.
-   */
   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 +339,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 +353,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,

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

@@ -0,0 +1,160 @@
+import {
+  CategoryRequestOptions,
+  CategoryResponse,
+  FeaturesRequestOptions,
+  FeaturesResponse,
+  FormulaRequestOptions,
+  FormulaResponse,
+  HistogramRequestOptions,
+  HistogramResponse,
+  RangeRequestOptions,
+  RangeResponse,
+  ScatterRequestOptions,
+  ScatterResponse,
+  TableRequestOptions,
+  TableResponse,
+  TimeSeriesRequestOptions,
+  TimeSeriesResponse,
+  ViewState,
+} from './types.js';
+import {FilterLogicalOperator, Filter, SpatialFilter} from '../types.js';
+import {getApplicableFilters} 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 {getSpatialFiltersResolution} from '../spatial-index.js';
+import {AggregationOptions} from '../sources/types.js';
+
+export interface WidgetSourceProps extends Omit<SourceOptions, 'filters'> {
+  apiVersion?: ApiVersion;
+  filters?: Record<string, Filter>;
+  filtersLogicalOperator?: FilterLogicalOperator;
+}
+
+/**
+ * Source for Widget API requests on a data source defined by a SQL query.
+ *
+ * Abstract class. Use {@link WidgetQuerySource} or {@link WidgetTableSource}.
+ */
+export abstract class WidgetSource<Props extends WidgetSourceProps> {
+  readonly props: Props;
+
+  static defaultProps: Partial<WidgetSourceProps> = {
+    apiVersion: ApiVersion.V3,
+    apiBaseUrl: DEFAULT_API_BASE_URL,
+    clientId: getClient(),
+    filters: {},
+    filtersLogicalOperator: 'and',
+  };
+
+  constructor(props: Props) {
+    this.props = {...WidgetSource.defaultProps, ...props};
+  }
+
+  /**
+   * Subclasses of {@link WidgetRemoteSource} must implement this method, calling
+   * {@link WidgetRemoteSource.prototype._getModelSource} for common source
+   * properties, and adding additional required properties including 'type' and
+   * 'data'.
+   */
+  protected abstract getModelSource(owner: string | undefined): ModelSource;
+
+  protected _getModelSource(
+    owner?: string
+  ): Omit<ModelSource, 'type' | 'data'> {
+    const props = this.props;
+    return {
+      apiVersion: props.apiVersion as ApiVersion,
+      apiBaseUrl: props.apiBaseUrl as string,
+      clientId: props.clientId as string,
+      accessToken: props.accessToken,
+      connectionName: props.connectionName,
+      filters: getApplicableFilters(owner, props.filters),
+      filtersLogicalOperator: props.filtersLogicalOperator,
+      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);
+  }
+
+  /**
+   * Returns a list of labeled datapoints for categorical data. Suitable for
+   * charts including grouped bar charts, pie charts, and tree charts.
+   */
+  abstract getCategories(
+    options: CategoryRequestOptions
+  ): Promise<CategoryResponse>;
+
+  /**
+   * Given a list of feature IDs (as found in `_carto_feature_id`) returns all
+   * matching features. In datasets containing features with duplicate geometries,
+   * feature IDs may be duplicated (IDs are a hash of geometry) and so more
+   * results may be returned than IDs in the request.
+   * @internal
+   * @experimental
+   */
+  abstract getFeatures(
+    options: FeaturesRequestOptions
+  ): Promise<FeaturesResponse>;
+
+  /**
+   * Returns a scalar numerical statistic over all matching data. Suitable
+   * for 'headline' or 'scorecard' figures such as counts and sums.
+   */
+  abstract getFormula(options: FormulaRequestOptions): Promise<FormulaResponse>;
+
+  /**
+   * Returns a list of labeled datapoints for 'bins' of data defined as ticks
+   * over a numerical range. Suitable for histogram charts.
+   */
+  abstract getHistogram(
+    options: HistogramRequestOptions
+  ): Promise<HistogramResponse>;
+
+  /**
+   * Returns a range (min and max) for a numerical column of matching rows.
+   * Suitable for displaying certain 'headline' or 'scorecard' statistics,
+   * or rendering a range slider UI for filtering.
+   */
+  abstract getRange(options: RangeRequestOptions): Promise<RangeResponse>;
+
+  /**
+   * Returns a list of bivariate datapoints defined as numerical 'x' and 'y'
+   * values. Suitable for rendering scatter plots.
+   */
+  abstract getScatter(options: ScatterRequestOptions): Promise<ScatterResponse>;
+
+  /**
+   * Returns a list of arbitrary data rows, with support for pagination and
+   * sorting. Suitable for displaying tables and lists.
+   */
+  abstract getTable(options: TableRequestOptions): Promise<TableResponse>;
+
+  /**
+   * Returns a series of labeled numerical values, grouped into equally-sized
+   * time intervals. Suitable for rendering time series charts.
+   */
+  abstract getTimeSeries(
+    options: TimeSeriesRequestOptions
+  ): Promise<TimeSeriesResponse>;
+}

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

@@ -3,7 +3,10 @@ import {
   QuadbinTableSourceOptions,
   VectorTableSourceOptions,
 } from '../sources/index.js';
-import {WidgetBaseSource, WidgetBaseSourceProps} from './widget-base-source.js';
+import {
+  WidgetRemoteSource,
+  WidgetRemoteSourceProps,
+} from './widget-remote-source.js';
 import {ModelSource} from '../models/model.js';
 
 type LayerTableSourceOptions =
@@ -35,8 +38,8 @@ export type WidgetTableSourceResult = {widgetSource: WidgetTableSource};
  * const { widgetSource } = await data;
  * ```
  */
-export class WidgetTableSource extends WidgetBaseSource<
-  LayerTableSourceOptions & WidgetBaseSourceProps
+export class WidgetTableSource extends WidgetRemoteSource<
+  LayerTableSourceOptions & WidgetRemoteSourceProps
 > {
   protected override getModelSource(owner: string): ModelSource {
     return {