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

package/src/types.ts

@@ -6,10 +6,10 @@ import type {BinaryFeature, BinaryFeatureCollection} from '@loaders.gl/schema';
  * MAPS AND TILES
  */
 
-/** @internalRemarks Source: @deck.gl/carto */
+/** @privateRemarks Source: @deck.gl/carto */
 export type Format = 'json' | 'geojson' | 'tilejson';
 
-/** @internalRemarks Source: @carto/constants, @deck.gl/carto */
+/** @privateRemarks Source: @carto/constants, @deck.gl/carto */
 export type MapType = 'boundary' | 'query' | 'table' | 'tileset' | 'raster';
 
 /**
@@ -23,7 +23,7 @@ export type Viewport = [number, number, number, number];
  * required for local widget calculations. Deeper dependencies on deck.gl
  * APIs should be minimized within this library: @deck.gl/carto depends
  * on the API client, not the other way around.
- * @internalRemarks Source: @deck.gl/geo-layers
+ * @privateRemarks Source: @deck.gl/geo-layers
  */
 export type Tile = {
   index: {x: number; y: number; z: number};
@@ -40,7 +40,7 @@ export type SpatialIndexTile = Tile & {
   data?: (Feature & {id: bigint})[];
 };
 
-/** @internalRemarks Source: @deck.gl/carto */
+/** @privateRemarks Source: @deck.gl/carto */
 export type Raster = {
   blockSize: number;
   cells: {
@@ -56,8 +56,8 @@ export type Raster = {
 /**
  * Enum for the different types of aggregations available for widgets.
  *
- * @internalRemarks Source: @carto/constants
- * @internalRemarks Converted from enum to type union, for improved declarative API.
+ * @privateRemarks Source: @carto/constants
+ * @privateRemarks Converted from enum to type union, for improved declarative API.
  */
 export type AggregationType =
   | 'count'
@@ -71,15 +71,15 @@ export type AggregationType =
  * FILTERS
  */
 
-/** @internalRemarks Source: @carto/react-api */
+/** @privateRemarks Source: @carto/react-api */
 export type SpatialFilter = Polygon | MultiPolygon;
 
-/** @internalRemarks Source: @deck.gl/carto */
+/** @privateRemarks Source: @deck.gl/carto */
 export interface Filters {
   [column: string]: Filter;
 }
 
-/** @internalRemarks Source: @carto/react-api, @deck.gl/carto */
+/** @privateRemarks Source: @carto/react-api, @deck.gl/carto */
 export interface Filter {
   [FilterType.IN]?: {owner?: string; values: number[] | string[]};
   /** [a, b] both are included. */
@@ -94,7 +94,7 @@ export interface Filter {
   };
 }
 
-/** @internalRemarks Source: @carto/react-core */
+/** @privateRemarks Source: @carto/react-core */
 export type FilterLogicalOperator = 'and' | 'or';
 
 /**
@@ -120,7 +120,7 @@ export type StringSearchOptions = {
 /**
  * Defines a step size increment for use with {@link TimeSeriesRequestOptions}.
  *
- * @internalRemarks Source: @carto/react-core
+ * @privateRemarks Source: @carto/react-core
  */
 export type GroupDateType =
   | 'year'
@@ -142,7 +142,7 @@ export type SortColumnType = 'number' | 'string' | 'date';
  * SQL QUERY PARAMETERS
  */
 
-/** @internalRemarks Source: @deck.gl/carto */
+/** @privateRemarks Source: @deck.gl/carto */
 export type QueryParameterValue =
   | string
   | number
@@ -150,11 +150,11 @@ export type QueryParameterValue =
   | Array<QueryParameterValue>
   | object;
 
-/** @internalRemarks Source: @deck.gl/carto */
+/** @privateRemarks Source: @deck.gl/carto */
 export type NamedQueryParameter = Record<string, QueryParameterValue>;
 
-/** @internalRemarks Source: @deck.gl/carto */
+/** @privateRemarks Source: @deck.gl/carto */
 export type PositionalQueryParameter = QueryParameterValue[];
 
-/** @internalRemarks Source: @deck.gl/carto */
+/** @privateRemarks Source: @deck.gl/carto */
 export type QueryParameters = NamedQueryParameter | PositionalQueryParameter;

package/src/utils/makeIntervalComplete.ts

@@ -1,4 +1,4 @@
-import {FilterInterval, FilterIntervalComplete} from '../types';
+import {FilterInterval, FilterIntervalComplete} from '../types.js';
 
 export function makeIntervalComplete(
   intervals: FilterInterval[]

package/src/utils.ts

@@ -39,7 +39,7 @@ type Row<T> = Record<string, T> | Record<string, T>[] | T[] | T;
  * Due to each data warehouse having its own behavior with columns,
  * we need to normalize them and transform every key to lowercase.
  *
- * @internalRemarks Source: @carto/react-widgets
+ * @privateRemarks Source: @carto/react-widgets
  * @internal
  */
 export function normalizeObjectKeys<T, R extends Row<T>>(el: R): R {
@@ -59,7 +59,7 @@ export function normalizeObjectKeys<T, R extends Row<T>>(el: R): R {
   ) as R;
 }
 
-/** @internalRemarks Source: @carto/react-core */
+/** @privateRemarks Source: @carto/react-core */
 export function assert(condition: unknown, message: string): asserts condition {
   if (!condition) {
     throw new Error(message);
@@ -67,7 +67,7 @@ export function assert(condition: unknown, message: string): asserts condition {
 }
 
 /**
- * @internalRemarks Source: @carto/react-core
+ * @privateRemarks Source: @carto/react-core
  * @internal
  */
 export class InvalidColumnError extends Error {

package/src/widget-sources/index.ts

@@ -1,3 +1,4 @@
+export * from './widget-source.js';
 export * from './widget-query-source.js';
 export * from './widget-remote-source.js';
 export * from './widget-table-source.js';

package/src/widget-sources/types.ts

@@ -1,11 +1,11 @@
-import {SpatialFilterPolyfillMode, TileResolution} from '../sources/types';
+import {SpatialFilterPolyfillMode, TileResolution} from '../sources/types.js';
 import {
+  Filters,
   GroupDateType,
   SortColumnType,
   SortDirection,
   SpatialFilter,
-} from '../types';
-import type {WidgetRemoteSource} from './widget-remote-source';
+} from '../types.js';
 
 /******************************************************************************
  * WIDGET API REQUESTS
@@ -19,11 +19,13 @@ export interface ViewState {
 
 /** Common options for {@link WidgetRemoteSource} requests. */
 interface BaseRequestOptions {
+  signal?: AbortSignal;
   spatialFilter?: SpatialFilter;
   spatialFiltersMode?: SpatialFilterPolyfillMode;
   /** Required for table- and query-based spatial index sources (H3, Quadbin). */
   spatialIndexReferenceViewState?: ViewState;
-  abortController?: AbortController;
+  /** Overrides source filters, if any. */
+  filters?: Filters;
   filterOwner?: string;
 }
 

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

@@ -8,6 +8,7 @@ import {
   WidgetRemoteSourceProps,
 } from './widget-remote-source.js';
 import {ModelSource} from '../models/model.js';
+import {Filters} from '../types.js';
 
 type LayerQuerySourceOptions =
   | Omit<VectorQuerySourceOptions, 'filters'>
@@ -41,9 +42,12 @@ export type WidgetQuerySourceResult = {widgetSource: WidgetQuerySource};
 export class WidgetQuerySource extends WidgetRemoteSource<
   LayerQuerySourceOptions & 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: 'query',
       data: this.props.sqlQuery,
       queryParameters: this.props.queryParameters,

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

@@ -1,4 +1,4 @@
-import {executeModel} from '../models/index.js';
+import {executeModel, ModelSource} from '../models/index.js';
 import {
   CategoryRequestOptions,
   CategoryResponse,
@@ -17,9 +17,12 @@ import {
   TimeSeriesRequestOptions,
   TimeSeriesResponse,
 } from './types.js';
-import {normalizeObjectKeys} from '../utils.js';
+import {getApplicableFilters, normalizeObjectKeys} from '../utils.js';
 import {DEFAULT_TILE_RESOLUTION} from '../constants-internal.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 type WidgetRemoteSourceProps = WidgetSourceProps;
 
@@ -31,19 +34,50 @@ export type WidgetRemoteSourceProps = WidgetSourceProps;
 export abstract class WidgetRemoteSource<
   Props extends WidgetRemoteSourceProps,
 > extends WidgetSource<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,
+    };
+  }
+
   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,
@@ -65,7 +99,7 @@ export abstract class WidgetRemoteSource<
         operation,
         operationColumn: operationColumn || column,
       },
-      opts: {abortController},
+      opts: {signal, headers: this.props.headers},
     }).then((res: CategoriesModelResponse) => normalizeObjectKeys(res.rows));
   }
 
@@ -73,15 +107,16 @@ export abstract class WidgetRemoteSource<
     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,
@@ -106,23 +141,24 @@ export abstract class WidgetRemoteSource<
         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}));
   }
 
   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,
@@ -144,7 +180,7 @@ export abstract class WidgetRemoteSource<
         operation: operation ?? 'count',
         operationExp,
       },
-      opts: {abortController},
+      opts: {signal, headers: this.props.headers},
     }).then((res: FormulaModelResponse) => normalizeObjectKeys(res.rows[0]));
   }
 
@@ -152,15 +188,16 @@ export abstract class WidgetRemoteSource<
     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,
@@ -178,7 +215,7 @@ export abstract class WidgetRemoteSource<
         spatialFilter,
       },
       params: {column, operation, ticks},
-      opts: {abortController},
+      opts: {signal, headers: this.props.headers},
     }).then((res: HistogramModelResponse) => normalizeObjectKeys(res.rows));
 
     if (data.length) {
@@ -196,15 +233,16 @@ export abstract class WidgetRemoteSource<
 
   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,
@@ -222,23 +260,24 @@ export abstract class WidgetRemoteSource<
         spatialFilter,
       },
       params: {column},
-      opts: {abortController},
+      opts: {signal, headers: this.props.headers},
     }).then((res: RangeModelResponse) => normalizeObjectKeys(res.rows[0]));
   }
 
   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,
@@ -265,7 +304,7 @@ export abstract class WidgetRemoteSource<
         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]));
@@ -273,15 +312,16 @@ export abstract class WidgetRemoteSource<
 
   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,
@@ -308,7 +348,7 @@ export abstract class WidgetRemoteSource<
         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,
@@ -320,8 +360,9 @@ export abstract class WidgetRemoteSource<
     options: TimeSeriesRequestOptions
   ): Promise<TimeSeriesResponse> {
     const {
+      signal,
+      filters = this.props.filters,
       filterOwner,
-      abortController,
       spatialFilter,
       spatialFiltersMode,
       spatialIndexReferenceViewState,
@@ -339,7 +380,7 @@ export abstract class WidgetRemoteSource<
       splitByCategoryValues,
     } = params;
 
-    const source = this.getModelSource(filterOwner);
+    const source = this.getModelSource(filters, filterOwner);
     const spatialFiltersResolution = this._getSpatialFiltersResolution(
       source,
       spatialFilter,
@@ -370,7 +411,7 @@ export abstract class WidgetRemoteSource<
         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

@@ -18,13 +18,11 @@ import {
   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;
@@ -37,7 +35,9 @@ export interface WidgetSourceProps extends Omit<SourceOptions, 'filters'> {
  *
  * Abstract class. Use {@link WidgetQuerySource} or {@link WidgetTableSource}.
  */
-export abstract class WidgetSource<Props extends WidgetSourceProps> {
+export abstract class WidgetSource<
+  Props extends WidgetSourceProps = WidgetSourceProps,
+> {
   readonly props: Props;
 
   static defaultProps: Partial<WidgetSourceProps> = {
@@ -53,29 +53,14 @@ export abstract class WidgetSource<Props extends WidgetSourceProps> {
   }
 
   /**
-   * 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'.
+   * 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.
    */
-  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,
-    };
+  destroy() {
+    // no-op in most cases, but required for worker sources.
   }
 
   protected _getSpatialFiltersResolution(

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

@@ -8,6 +8,7 @@ import {
   WidgetRemoteSourceProps,
 } from './widget-remote-source.js';
 import {ModelSource} from '../models/model.js';
+import {Filters} from '../types.js';
 
 type LayerTableSourceOptions =
   | Omit<VectorTableSourceOptions, 'filters'>
@@ -41,9 +42,12 @@ export type WidgetTableSourceResult = {widgetSource: WidgetTableSource};
 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,
     };