@carto/api-client 0.4.8 → 0.4.9

package/build/models/model.d.ts

@@ -19,7 +19,6 @@ export interface ModelSource {
     queryParameters?: QueryParameters;
     spatialDataColumn?: string;
     spatialDataType?: SpatialDataType;
-    spatialFiltersResolution?: number;
     spatialFiltersMode?: SpatialFilterPolyfillMode;
     /** original resolution of the spatial index data as stored in the DW */
     dataResolution?: number;

package/build/spatial-index.d.ts

@@ -1,12 +1,9 @@
-import type { ModelSource } from './models/model.js';
-import type { AggregationOptions } from './sources/types.js';
-import type { ViewState } from './widget-sources/index.js';
-export declare function getSpatialFiltersResolution(source: Partial<ModelSource & AggregationOptions>, viewState: ViewState): number | undefined;
 /**
  * Resolution conversion function. Takes a WebMercatorViewport and returns
  * a H3 resolution such that the screen space size of the hexagons is
  * "similar" to the given tileSize on screen. Intended for use with deck.gl.
  * @internal
+ * @privateRemarks Source: https://github.com/visgl/deck.gl/blob/master/modules/carto/src/layers/h3-tileset-2d.ts
  */
 export declare function _getHexagonResolution(viewport: {
     zoom: number;

package/build/widget-sources/types.d.ts

@@ -15,7 +15,12 @@ interface BaseRequestOptions {
     signal?: AbortSignal;
     spatialFilter?: SpatialFilter;
     spatialFiltersMode?: SpatialFilterPolyfillMode;
-    /** Required for table- and query-based spatial index sources (H3, Quadbin). */
+    /**
+     * Deprecated parameter previously used for H3 and Quadbin widgets. Now has
+     * no effect and will be removed in a future version.
+     * @deprecated Parameter has no effect.
+     * @todo TODO(v0.5): Remove spatialIndexReferenceViewState parameter.
+     */
     spatialIndexReferenceViewState?: ViewState;
     /** Overrides source filters, if any. */
     filters?: Filters;

package/build/widget-sources/widget-source.d.ts

@@ -1,5 +1,5 @@
-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 { CategoryRequestOptions, CategoryResponse, FeaturesRequestOptions, FeaturesResponse, FormulaRequestOptions, FormulaResponse, HistogramRequestOptions, HistogramResponse, RangeRequestOptions, RangeResponse, ScatterRequestOptions, ScatterResponse, TableRequestOptions, TableResponse, TimeSeriesRequestOptions, TimeSeriesResponse } from './types.js';
+import { FilterLogicalOperator, Filter, Filters } from '../types.js';
 import { ModelSource } from '../models/model.js';
 import { SourceOptions } from '../sources/index.js';
 import { ApiVersion } from '../constants.js';
@@ -25,7 +25,6 @@ export declare abstract class WidgetSource<Props extends WidgetSourceProps> {
      */
     protected abstract getModelSource(filters: Filters | undefined, filterOwner?: string): ModelSource;
     protected _getModelSource(filters: Filters | undefined, filterOwner?: string): Omit<ModelSource, 'type' | 'data'>;
-    protected _getSpatialFiltersResolution(source: Omit<ModelSource, 'type' | 'data'>, spatialFilter?: SpatialFilter, referenceViewState?: ViewState): number | undefined;
     /**
      * Returns a list of labeled datapoints for categorical data. Suitable for
      * charts including grouped bar charts, pie charts, and tree charts.

package/package.json

@@ -8,7 +8,7 @@
   "homepage": "https://github.com/CartoDB/carto-api-client#readme",
   "author": "Don McCurdy <donmccurdy@carto.com>",
   "packageManager": "yarn@4.3.1",
-  "version": "0.4.8",
+  "version": "0.4.9",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -68,6 +68,7 @@
     "@turf/invariant": "^7.2.0",
     "@turf/union": "^7.2.0",
     "@types/geojson": "^7946.0.16",
+    "d3-scale": "^4.0.2",
     "h3-js": "4.1.0"
   },
   "devDependencies": {
@@ -76,9 +77,12 @@
     "@deck.gl/core": "~9.1.0",
     "@deck.gl/extensions": "~9.1.0",
     "@deck.gl/geo-layers": "~9.1.0",
+    "@deck.gl/google-maps": "~9.1.0",
     "@deck.gl/layers": "~9.1.0",
+    "@deck.gl/mapbox": "~9.1.0",
     "@deck.gl/mesh-layers": "~9.1.0",
     "@eslint/js": "^9.20.0",
+    "@googlemaps/js-api-loader": "^1.16.6",
     "@lit/react": "^1.0.7",
     "@lit/task": "^1.0.2",
     "@loaders.gl/core": "^4.3.3",
@@ -87,6 +91,7 @@
     "@luma.gl/shadertools": "~9.1.0",
     "@turf/buffer": "^7.2.0",
     "@turf/random": "^7.2.0",
+    "@types/d3-scale": "^4.0.9",
     "@types/json-schema": "^7.0.15",
     "@types/react": "^18.3.18",
     "@types/semver": "^7.5.8",

package/src/models/model.ts

@@ -39,7 +39,6 @@ export interface ModelSource {
   queryParameters?: QueryParameters;
   spatialDataColumn?: string;
   spatialDataType?: SpatialDataType;
-  spatialFiltersResolution?: number;
   spatialFiltersMode?: SpatialFilterPolyfillMode;
   /** original resolution of the spatial index data as stored in the DW */
   dataResolution?: number;
@@ -86,7 +85,6 @@ export function executeModel(props: {
     filtersLogicalOperator = 'and',
     spatialDataType = 'geo',
     spatialFiltersMode = 'intersects',
-    spatialFiltersResolution = 0,
   } = source;
 
   const queryParams: Record<string, unknown> = {
@@ -118,9 +116,6 @@ export function executeModel(props: {
   }
 
   if (spatialDataType !== 'geo') {
-    if (spatialFiltersResolution > 0) {
-      queryParams.spatialFiltersResolution = spatialFiltersResolution;
-    }
     queryParams.spatialFiltersMode = spatialFiltersMode;
   }
 

package/src/spatial-index.ts

@@ -1,88 +1,6 @@
-import {
-  DEFAULT_AGGREGATION_RES_LEVEL_H3,
-  DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN,
-} from './constants-internal.js';
-import type {ModelSource} from './models/model.js';
-import type {AggregationOptions} from './sources/types.js';
-import type {ViewState} from './widget-sources/index.js';
-
+// Default tile display size in deck.gl, in viewport pixels. May differ
+// from size or resolution assumed when generating the tile data,
 const DEFAULT_TILE_SIZE = 512;
-const QUADBIN_ZOOM_MAX_OFFSET = 4;
-
-export function getSpatialFiltersResolution(
-  source: Partial<ModelSource & AggregationOptions>,
-  viewState: ViewState
-): number | undefined {
-  const dataResolution = source.dataResolution ?? Number.MAX_VALUE;
-
-  const aggregationResLevel =
-    source.aggregationResLevel ??
-    (source.spatialDataType === 'h3'
-      ? DEFAULT_AGGREGATION_RES_LEVEL_H3
-      : DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN);
-
-  const aggregationResLevelOffset = Math.max(
-    0,
-    Math.floor(aggregationResLevel)
-  );
-
-  const currentZoomInt = Math.ceil(viewState.zoom);
-  if (source.spatialDataType === 'h3') {
-    const tileSize = DEFAULT_TILE_SIZE;
-    const maxResolutionForZoom =
-      maxH3SpatialFiltersResolutions.find(
-        ([zoom]) => zoom === currentZoomInt
-      )?.[1] ?? Math.max(0, currentZoomInt - 3);
-
-    const maxSpatialFiltersResolution = maxResolutionForZoom
-      ? Math.min(dataResolution, maxResolutionForZoom)
-      : dataResolution;
-
-    const hexagonResolution =
-      _getHexagonResolution(viewState, tileSize) + aggregationResLevelOffset;
-
-    return Math.min(hexagonResolution, maxSpatialFiltersResolution);
-  }
-
-  if (source.spatialDataType === 'quadbin') {
-    const maxResolutionForZoom = currentZoomInt + QUADBIN_ZOOM_MAX_OFFSET;
-    const maxSpatialFiltersResolution = Math.min(
-      dataResolution,
-      maxResolutionForZoom
-    );
-
-    const quadsResolution =
-      Math.floor(viewState.zoom) + aggregationResLevelOffset;
-    return Math.min(quadsResolution, maxSpatialFiltersResolution);
-  }
-
-  return undefined;
-}
-
-const maxH3SpatialFiltersResolutions = [
-  [20, 14],
-  [19, 13],
-  [18, 12],
-  [17, 11],
-  [16, 10],
-  [15, 9],
-  [14, 8],
-  [13, 7],
-  [12, 7],
-  [11, 7],
-  [10, 6],
-  [9, 6],
-  [8, 5],
-  [7, 4],
-  [6, 4],
-  [5, 3],
-  [4, 2],
-  [3, 1],
-  [2, 1],
-  [1, 0],
-];
-
-// stolen from https://github.com/visgl/deck.gl/blob/master/modules/carto/src/layers/h3-tileset-2d.ts
 
 // Relative scale factor (0 = no biasing, 2 = a few hexagons cover view)
 const BIAS = 2;
@@ -92,6 +10,7 @@ const BIAS = 2;
  * a H3 resolution such that the screen space size of the hexagons is
  * "similar" to the given tileSize on screen. Intended for use with deck.gl.
  * @internal
+ * @privateRemarks Source: https://github.com/visgl/deck.gl/blob/master/modules/carto/src/layers/h3-tileset-2d.ts
  */
 export function _getHexagonResolution(
   viewport: {zoom: number; latitude: number},

package/src/widget-sources/types.ts

@@ -24,7 +24,12 @@ interface BaseRequestOptions {
   signal?: AbortSignal;
   spatialFilter?: SpatialFilter;
   spatialFiltersMode?: SpatialFilterPolyfillMode;
-  /** Required for table- and query-based spatial index sources (H3, Quadbin). */
+  /**
+   * Deprecated parameter previously used for H3 and Quadbin widgets. Now has
+   * no effect and will be removed in a future version.
+   * @deprecated Parameter has no effect.
+   * @todo TODO(v0.5): Remove spatialIndexReferenceViewState parameter.
+   */
   spatialIndexReferenceViewState?: ViewState;
   /** Overrides source filters, if any. */
   filters?: Filters;

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

@@ -40,24 +40,16 @@ export abstract class WidgetRemoteSource<
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
-      spatialIndexReferenceViewState,
       ...params
     } = options;
     const {column, operation, operationColumn} = params;
-    const source = this.getModelSource(filters, filterOwner);
-    const spatialFiltersResolution = this._getSpatialFiltersResolution(
-      source,
-      spatialFilter,
-      spatialIndexReferenceViewState
-    );
 
     type CategoriesModelResponse = {rows: {name: string; value: number}[]};
 
     return executeModel({
       model: 'category',
       source: {
-        ...source,
-        spatialFiltersResolution,
+        ...this.getModelSource(filters, filterOwner),
         spatialFiltersMode,
         spatialFilter,
       },
@@ -80,24 +72,16 @@ export abstract class WidgetRemoteSource<
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
-      spatialIndexReferenceViewState,
       ...params
     } = options;
     const {columns, dataType, featureIds, z, limit, tileResolution} = params;
-    const source = this.getModelSource(filters, filterOwner);
-    const spatialFiltersResolution = this._getSpatialFiltersResolution(
-      source,
-      spatialFilter,
-      spatialIndexReferenceViewState
-    );
 
     type FeaturesModelResponse = {rows: Record<string, unknown>[]};
 
     return executeModel({
       model: 'pick',
       source: {
-        ...source,
-        spatialFiltersResolution,
+        ...this.getModelSource(filters, filterOwner),
         spatialFiltersMode,
         spatialFilter,
       },
@@ -122,25 +106,17 @@ export abstract class WidgetRemoteSource<
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
-      spatialIndexReferenceViewState,
       operationExp,
       ...params
     } = options;
     const {column, operation} = params;
-    const source = this.getModelSource(filters, filterOwner);
-    const spatialFiltersResolution = this._getSpatialFiltersResolution(
-      source,
-      spatialFilter,
-      spatialIndexReferenceViewState
-    );
 
     type FormulaModelResponse = {rows: {value: number}[]};
 
     return executeModel({
       model: 'formula',
       source: {
-        ...source,
-        spatialFiltersResolution,
+        ...this.getModelSource(filters, filterOwner),
         spatialFiltersMode,
         spatialFilter,
       },
@@ -163,24 +139,16 @@ export abstract class WidgetRemoteSource<
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
-      spatialIndexReferenceViewState,
       ...params
     } = options;
     const {column, operation, ticks} = params;
-    const source = this.getModelSource(filters, filterOwner);
-    const spatialFiltersResolution = this._getSpatialFiltersResolution(
-      source,
-      spatialFilter,
-      spatialIndexReferenceViewState
-    );
 
     type HistogramModelResponse = {rows: {tick: number; value: number}[]};
 
     const data = await executeModel({
       model: 'histogram',
       source: {
-        ...source,
-        spatialFiltersResolution,
+        ...this.getModelSource(filters, filterOwner),
         spatialFiltersMode,
         spatialFilter,
       },
@@ -209,24 +177,16 @@ export abstract class WidgetRemoteSource<
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
-      spatialIndexReferenceViewState,
       ...params
     } = options;
     const {column} = params;
-    const source = this.getModelSource(filters, filterOwner);
-    const spatialFiltersResolution = this._getSpatialFiltersResolution(
-      source,
-      spatialFilter,
-      spatialIndexReferenceViewState
-    );
 
     type RangeModelResponse = {rows: {min: number; max: number}[]};
 
     return executeModel({
       model: 'range',
       source: {
-        ...source,
-        spatialFiltersResolution,
+        ...this.getModelSource(filters, filterOwner),
         spatialFiltersMode,
         spatialFilter,
       },
@@ -243,19 +203,11 @@ export abstract class WidgetRemoteSource<
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
-      spatialIndexReferenceViewState,
       ...params
     } = options;
     const {xAxisColumn, xAxisJoinOperation, yAxisColumn, yAxisJoinOperation} =
       params;
 
-    const source = this.getModelSource(filters, 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;
 
@@ -264,8 +216,7 @@ export abstract class WidgetRemoteSource<
     return executeModel({
       model: 'scatterplot',
       source: {
-        ...source,
-        spatialFiltersResolution,
+        ...this.getModelSource(filters, filterOwner),
         spatialFiltersMode,
         spatialFilter,
       },
@@ -290,16 +241,9 @@ export abstract class WidgetRemoteSource<
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
-      spatialIndexReferenceViewState,
       ...params
     } = options;
     const {columns, sortBy, sortDirection, offset = 0, limit = 10} = params;
-    const source = this.getModelSource(filters, filterOwner);
-    const spatialFiltersResolution = this._getSpatialFiltersResolution(
-      source,
-      spatialFilter,
-      spatialIndexReferenceViewState
-    );
 
     type TableModelResponse = {
       rows: Record<string, number | string>[];
@@ -309,8 +253,7 @@ export abstract class WidgetRemoteSource<
     return executeModel({
       model: 'table',
       source: {
-        ...source,
-        spatialFiltersResolution,
+        ...this.getModelSource(filters, filterOwner),
         spatialFiltersMode,
         spatialFilter,
       },
@@ -339,7 +282,6 @@ export abstract class WidgetRemoteSource<
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
-      spatialIndexReferenceViewState,
       ...params
     } = options;
     const {
@@ -354,13 +296,6 @@ export abstract class WidgetRemoteSource<
       splitByCategoryValues,
     } = params;
 
-    const source = this.getModelSource(filters, filterOwner);
-    const spatialFiltersResolution = this._getSpatialFiltersResolution(
-      source,
-      spatialFilter,
-      spatialIndexReferenceViewState
-    );
-
     type TimeSeriesModelResponse = {
       rows: {name: string; value: number}[];
       metadata: {categories: string[]};
@@ -369,8 +304,7 @@ export abstract class WidgetRemoteSource<
     return executeModel({
       model: 'timeseries',
       source: {
-        ...source,
-        spatialFiltersResolution,
+        ...this.getModelSource(filters, filterOwner),
         spatialFiltersMode,
         spatialFilter,
       },

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

@@ -15,20 +15,13 @@ import {
   TableResponse,
   TimeSeriesRequestOptions,
   TimeSeriesResponse,
-  ViewState,
 } from './types.js';
-import {
-  FilterLogicalOperator,
-  Filter,
-  SpatialFilter,
-  Filters,
-} from '../types.js';
+import {FilterLogicalOperator, Filter, 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'> {
@@ -91,25 +84,6 @@ export abstract class WidgetSource<Props extends WidgetSourceProps> {
     };
   }
 
-  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.