@carto/api-client 0.4.6 → 0.4.7-0

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

@@ -1,4 +1,4 @@
-import {executeModel} from '../models/index.js';
+import {executeModel, ModelSource} from '../models/index.js';
 import {
   CategoryRequestOptions,
   CategoryResponse,
@@ -16,56 +16,38 @@ 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 {DEFAULT_TILE_RESOLUTION} from '../constants-internal.js';
-import {getSpatialFiltersResolution} from '../spatial-index.js';
+import {WidgetSource, WidgetSourceProps} from './widget-source.js';
+import {Filters} from '../types.js';
+import {ApiVersion} from '../constants.js';
 import {AggregationOptions} from '../sources/types.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};
-  }
-
+export abstract class WidgetRemoteSource<
+  Props extends WidgetRemoteSourceProps,
+> extends WidgetSource<Props> {
   /**
-   * Subclasses of {@link WidgetBaseSource} must implement this method, calling
-   * {@link WidgetBaseSource.prototype._getModelSource} for common source
+   * 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 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 {
@@ -74,7 +56,7 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
       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,
@@ -82,46 +64,20 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
     };
   }
 
-  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.
-   */
   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 +99,24 @@ 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 {
+      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 +141,24 @@ 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 {
+      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 +175,29 @@ 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 {
+      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 +215,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 +231,18 @@ 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 {
+      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 +260,24 @@ 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 {
+      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 +304,24 @@ 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 {
+      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 +348,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 +356,13 @@ 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 {
+      signal,
+      filters = this.props.filters,
       filterOwner,
-      abortController,
       spatialFilter,
       spatialFiltersMode,
       spatialIndexReferenceViewState,
@@ -474,7 +380,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 +411,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,145 @@
+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 {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';
+
+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 = 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};
+  }
+
+  /**
+   * Destroys the widget source and releases allocated resources.
+   *
+   * For remote sources (tables, queries) this has no effect, but for local
+   * sources (tilesets, rasters) these resources will affect performance
+   * and stability if many (10+) sources are created and not released.
+   */
+  destroy() {
+    // no-op in most cases, but required for worker sources.
+  }
+
+  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,
     };