@carto/api-client 0.4.6 → 0.4.7-alpha.0

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

@@ -16,112 +16,35 @@ import {
   TableResponse,
   TimeSeriesRequestOptions,
   TimeSeriesResponse,
-  ViewState,
 } from './types.js';
-import {FilterLogicalOperator, Filter, SpatialFilter} 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 {normalizeObjectKeys} from '../utils.js';
 import {DEFAULT_TILE_RESOLUTION} from '../constants-internal.js';
-import {getSpatialFiltersResolution} from '../spatial-index.js';
-import {AggregationOptions} from '../sources/types.js';
+import {WidgetSource, WidgetSourceProps} from './widget-source.js';
 
-export interface WidgetBaseSourceProps extends Omit<SourceOptions, 'filters'> {
-  apiVersion?: ApiVersion;
-  filters?: Record<string, Filter>;
-  filtersLogicalOperator?: FilterLogicalOperator;
-}
-
-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',
-  };
-
-  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,
-      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);
-  }
-
-  /****************************************************************************
-   * 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 {
+      signal,
+      filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
       spatialIndexReferenceViewState,
-      abortController,
       ...params
     } = options;
     const {column, operation, operationColumn} = params;
-    const source = this.getModelSource(filterOwner);
+    const source = this.getModelSource(filters, filterOwner);
     const spatialFiltersResolution = this._getSpatialFiltersResolution(
       source,
       spatialFilter,
@@ -143,35 +66,25 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
         operation,
         operationColumn: operationColumn || column,
       },
-      opts: {abortController},
+      opts: {signal, headers: this.props.headers},
     }).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 {
+      abortController,
+      signal = abortController?.signal,
+      filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
       spatialIndexReferenceViewState,
-      abortController,
       ...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,
@@ -196,31 +109,25 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
         limit: limit || 1000,
         tileResolution: tileResolution || DEFAULT_TILE_RESOLUTION,
       },
-      opts: {abortController},
+      opts: {signal, headers: this.props.headers},
       // Avoid `normalizeObjectKeys()`, which changes column names.
     }).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 {
+      abortController,
+      signal = abortController?.signal,
+      filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
       spatialIndexReferenceViewState,
-      abortController,
       operationExp,
       ...params
     } = options;
     const {column, operation} = params;
-    const source = this.getModelSource(filterOwner);
+    const source = this.getModelSource(filters, filterOwner);
     const spatialFiltersResolution = this._getSpatialFiltersResolution(
       source,
       spatialFilter,
@@ -237,32 +144,30 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
         spatialFiltersMode,
         spatialFilter,
       },
-      params: {column: column ?? '*', operation, operationExp},
-      opts: {abortController},
+      params: {
+        column: column ?? '*',
+        operation: operation ?? 'count',
+        operationExp,
+      },
+      opts: {signal, headers: this.props.headers},
     }).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 {
+      abortController,
+      signal = abortController?.signal,
+      filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
       spatialIndexReferenceViewState,
-      abortController,
       ...params
     } = options;
     const {column, operation, ticks} = params;
-    const source = this.getModelSource(filterOwner);
+    const source = this.getModelSource(filters, filterOwner);
     const spatialFiltersResolution = this._getSpatialFiltersResolution(
       source,
       spatialFilter,
@@ -280,7 +185,7 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
         spatialFilter,
       },
       params: {column, operation, ticks},
-      opts: {abortController},
+      opts: {signal, headers: this.props.headers},
     }).then((res: HistogramModelResponse) => normalizeObjectKeys(res.rows));
 
     if (data.length) {
@@ -296,26 +201,19 @@ 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 {
+      abortController,
+      signal = abortController?.signal,
+      filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
       spatialIndexReferenceViewState,
-      abortController,
       ...params
     } = options;
     const {column} = params;
-    const source = this.getModelSource(filterOwner);
+    const source = this.getModelSource(filters, filterOwner);
     const spatialFiltersResolution = this._getSpatialFiltersResolution(
       source,
       spatialFilter,
@@ -333,31 +231,25 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
         spatialFilter,
       },
       params: {column},
-      opts: {abortController},
+      opts: {signal, headers: this.props.headers},
     }).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 {
+      abortController,
+      signal = abortController?.signal,
+      filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
       spatialIndexReferenceViewState,
-      abortController,
       ...params
     } = options;
     const {xAxisColumn, xAxisJoinOperation, yAxisColumn, yAxisJoinOperation} =
       params;
 
-    const source = this.getModelSource(filterOwner);
+    const source = this.getModelSource(filters, filterOwner);
     const spatialFiltersResolution = this._getSpatialFiltersResolution(
       source,
       spatialFilter,
@@ -384,31 +276,25 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
         yAxisJoinOperation,
         limit: HARD_LIMIT,
       },
-      opts: {abortController},
+      opts: {signal, headers: this.props.headers},
     })
       .then((res: ScatterModelResponse) => normalizeObjectKeys(res.rows))
       .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 {
+      abortController,
+      signal = abortController?.signal,
+      filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
       spatialIndexReferenceViewState,
-      abortController,
       ...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,
@@ -435,7 +321,7 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
         limit,
         offset,
       },
-      opts: {abortController},
+      opts: {signal, headers: this.props.headers},
     }).then((res: TableModelResponse) => ({
       // Avoid `normalizeObjectKeys()`, which changes column names.
       rows: res.rows ?? (res as any).ROWS,
@@ -443,20 +329,14 @@ 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,
+      signal = abortController?.signal,
+      filters = this.props.filters,
+      filterOwner,
       spatialFilter,
       spatialFiltersMode,
       spatialIndexReferenceViewState,
@@ -474,7 +354,7 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
       splitByCategoryValues,
     } = params;
 
-    const source = this.getModelSource(filterOwner);
+    const source = this.getModelSource(filters, filterOwner);
     const spatialFiltersResolution = this._getSpatialFiltersResolution(
       source,
       spatialFilter,
@@ -505,7 +385,7 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
         splitByCategoryLimit,
         splitByCategoryValues,
       },
-      opts: {abortController},
+      opts: {signal, headers: this.props.headers},
     }).then((res: TimeSeriesModelResponse) => ({
       rows: normalizeObjectKeys(res.rows),
       categories: res.metadata?.categories,

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

@@ -0,0 +1,173 @@
+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,
+  Filters,
+} 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,
+      clientId: getClient(), // Refresh clientId, default may have changed.
+      ...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(
+    filters: Filters | undefined,
+    filterOwner?: string
+  ): ModelSource;
+
+  protected _getModelSource(
+    filters: Filters | undefined,
+    filterOwner?: 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(filterOwner, filters || 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,8 +3,12 @@ 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';
+import {Filters} from '../types.js';
 
 type LayerTableSourceOptions =
   | Omit<VectorTableSourceOptions, 'filters'>
@@ -35,12 +39,15 @@ 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 {
+  protected override getModelSource(
+    filters: Filters | undefined,
+    filterOwner?: string
+  ): ModelSource {
     return {
-      ...super._getModelSource(owner),
+      ...super._getModelSource(filters, filterOwner),
       type: 'table',
       data: this.props.tableName,
     };