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

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

@@ -0,0 +1,75 @@
+import { TilesetSourceOptions } from '../sources/index.js';
+import type { ModelSource } from '../models/index.js';
+import { CategoryRequestOptions, CategoryResponse, FeaturesResponse, FormulaRequestOptions, FormulaResponse, HistogramRequestOptions, HistogramResponse, RangeRequestOptions, RangeResponse, ScatterRequestOptions, ScatterResponse, TableRequestOptions, TableResponse, TimeSeriesRequestOptions, TimeSeriesResponse } from './types.js';
+import { TileFormat } from '../constants.js';
+import { Filters, SpatialFilter } from '../types.js';
+import { TileFeatureExtractOptions } from '../filters/index.js';
+import { FeatureCollection } from 'geojson';
+import { SpatialDataType } from '../sources/types.js';
+import { WidgetSource, WidgetSourceProps } from './widget-source.js';
+export type WidgetTilesetSourceProps = WidgetSourceProps & Omit<TilesetSourceOptions, 'filters'> & {
+    tileFormat: TileFormat;
+    spatialDataType: SpatialDataType;
+};
+export type WidgetTilesetSourceResult = {
+    widgetSource: WidgetTilesetSource;
+};
+/**
+ * Source for Widget API requests on a data source defined by a tileset.
+ *
+ * Generally not intended to be constructed directly. Instead, call
+ * {@link vectorTilesetSource}, {@link h3TilesetSource}, or {@link quadbinTilesetSource},
+ * which can be shared with map layers. Sources contain a `widgetSource`
+ * property, for use by widget implementations.
+ *
+ * Example:
+ *
+ * ```javascript
+ * import { vectorTilesetSource } from '@carto/api-client';
+ *
+ * const data = vectorTilesetSource({
+ *   accessToken: '••••',
+ *   connectionName: 'carto_dw',
+ *   tableName: 'carto-demo-data.demo_rasters.my_tileset_source'
+ * });
+ *
+ * const { widgetSource } = await data;
+ * ```
+ */
+export declare class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps> {
+    private _tiles;
+    private _features;
+    private _tileFeatureExtractOptions;
+    private _tileFeatureExtractPreviousInputs;
+    protected getModelSource(filters: Filters | undefined, filterOwner: string): ModelSource;
+    /**
+     * Loads features as a list of tiles (typically provided by deck.gl).
+     * After tiles are loaded, {@link extractTileFeatures} must be called
+     * before computing statistics on the tiles.
+     */
+    loadTiles(tiles: unknown[]): void;
+    /** Configures options used to extract features from tiles. */
+    setTileFeatureExtractOptions(options: TileFeatureExtractOptions): void;
+    protected _extractTileFeatures(spatialFilter: SpatialFilter): void;
+    /**
+     * Loads features as GeoJSON (used for testing).
+     * @experimental
+     * @internal Not for public use. Spatial filters in other method calls will be ignored.
+     */
+    loadGeoJSON({ geojson, spatialFilter, }: {
+        geojson: FeatureCollection;
+        spatialFilter: SpatialFilter;
+    }): void;
+    getFeatures(): Promise<FeaturesResponse>;
+    getFormula({ column, operation, joinOperation, filters, filterOwner, spatialFilter, }: FormulaRequestOptions): Promise<FormulaResponse>;
+    getHistogram({ operation, ticks, column, joinOperation, filters, filterOwner, spatialFilter, }: HistogramRequestOptions): Promise<HistogramResponse>;
+    getCategories({ column, operation, operationColumn, joinOperation, filters, filterOwner, spatialFilter, }: CategoryRequestOptions): Promise<CategoryResponse>;
+    getScatter({ xAxisColumn, yAxisColumn, xAxisJoinOperation, yAxisJoinOperation, filters, filterOwner, spatialFilter, }: ScatterRequestOptions): Promise<ScatterResponse>;
+    getTable({ columns, searchFilterColumn, searchFilterText, sortBy, sortDirection, sortByColumnType, offset, limit, filters, filterOwner, spatialFilter, }: TableRequestOptions): Promise<TableResponse>;
+    getTimeSeries({ column, stepSize, operation, operationColumn, joinOperation, filters, filterOwner, spatialFilter, }: TimeSeriesRequestOptions): Promise<TimeSeriesResponse>;
+    getRange({ column, filters, filterOwner, spatialFilter, }: RangeRequestOptions): Promise<RangeResponse>;
+    /****************************************************************************
+     * INTERNAL
+     */
+    private _getFilteredFeatures;
+}

package/package.json

@@ -8,11 +8,10 @@
   "homepage": "https://github.com/CartoDB/carto-api-client#readme",
   "author": "Don McCurdy <donmccurdy@carto.com>",
   "packageManager": "yarn@4.3.1",
-  "version": "0.4.6",
+  "version": "0.4.7-alpha.0",
   "license": "MIT",
   "publishConfig": {
-    "access": "public",
-    "tag": "alpha"
+    "access": "public"
   },
   "type": "module",
   "sideEffects": false,
@@ -39,8 +38,10 @@
     "test": "vitest run --typecheck",
     "test:watch": "vitest watch --typecheck",
     "coverage": "vitest run --coverage.enabled --coverage.all false",
-    "lint": "prettier \"**/*.{cjs,html,js,json,md,ts}\" --ignore-path ./.eslintignore --check",
-    "format": "prettier \"**/*.{cjs,html,js,json,md,ts}\" --ignore-path ./.eslintignore --write",
+    "benchmark": "node scripts/benchmark.js",
+    "lint": "eslint .",
+    "format": "prettier \"**/*.{cjs,html,js,json,md,ts}\" --write",
+    "format:check": "prettier \"**/*.{cjs,html,js,json,md,ts}\" --check",
     "clean": "rimraf build/*",
     "postversion": "yarn postversion:check && yarn postversion:commit && yarn postversion:push",
     "postversion:check": "yarn lint && yarn test",
@@ -56,45 +57,61 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@turf/bbox-clip": "^7.1.0",
-    "@turf/bbox-polygon": "^7.1.0",
-    "@turf/helpers": "^7.1.0",
-    "@turf/invariant": "^7.1.0",
-    "@turf/union": "^7.1.0",
-    "@types/geojson": "^7946.0.15"
+    "@loaders.gl/schema": "^4.3.3",
+    "@turf/bbox-clip": "^7.2.0",
+    "@turf/bbox-polygon": "^7.2.0",
+    "@turf/boolean-equal": "^7.2.0",
+    "@turf/boolean-intersects": "^7.2.0",
+    "@turf/boolean-within": "^7.2.0",
+    "@turf/helpers": "^7.2.0",
+    "@turf/intersect": "^7.2.0",
+    "@turf/invariant": "^7.2.0",
+    "@turf/union": "^7.2.0",
+    "@types/geojson": "^7946.0.16",
+    "h3-js": "4.1.0"
   },
   "devDependencies": {
-    "@deck.gl/aggregation-layers": "^9.0.38",
-    "@deck.gl/carto": "^9.0.38",
-    "@deck.gl/core": "^9.0.38",
-    "@deck.gl/extensions": "^9.0.38",
-    "@deck.gl/geo-layers": "^9.0.38",
-    "@deck.gl/layers": "^9.0.38",
-    "@deck.gl/mesh-layers": "^9.0.38",
-    "@lit/react": "^1.0.6",
-    "@lit/task": "^1.0.1",
+    "@deck.gl/aggregation-layers": "~9.1.0",
+    "@deck.gl/carto": "~9.1.0",
+    "@deck.gl/core": "~9.1.0",
+    "@deck.gl/extensions": "~9.1.0",
+    "@deck.gl/geo-layers": "~9.1.0",
+    "@deck.gl/layers": "~9.1.0",
+    "@deck.gl/mesh-layers": "~9.1.0",
+    "@eslint/js": "^9.20.0",
+    "@lit/react": "^1.0.7",
+    "@lit/task": "^1.0.2",
     "@loaders.gl/core": "^4.3.3",
-    "@luma.gl/core": "9.0.28",
-    "@luma.gl/engine": "9.0.28",
+    "@luma.gl/core": "~9.1.0",
+    "@luma.gl/engine": "~9.1.0",
+    "@luma.gl/shadertools": "~9.1.0",
+    "@turf/buffer": "^7.2.0",
+    "@turf/random": "^7.2.0",
     "@types/json-schema": "^7.0.15",
     "@types/react": "^18.3.18",
     "@types/semver": "^7.5.8",
-    "@vitest/coverage-istanbul": "^3.0.2",
+    "@vitest/coverage-istanbul": "^3.0.5",
     "@webcomponents/webcomponentsjs": "^2.8.0",
     "concurrently": "^9.1.2",
     "echarts": "^5.6.0",
+    "eslint": "^9.20.1",
     "lit": "^3.2.1",
     "lit-analyzer": "^2.0.3",
-    "maplibre-gl": "^5.0.0",
+    "maplibre-gl": "^5.1.0",
     "microbundle": "^0.15.1",
     "prettier": "^3.4.2",
     "rimraf": "^6.0.1",
-    "semver": "^7.6.3",
-    "typescript": "~5.7.3",
-    "vite": "^6.0.7",
-    "vitest": "2.1.8"
+    "semver": "^7.7.1",
+    "thenby": "^1.3.4",
+    "tinybench": "^3.1.1",
+    "typescript": "~5.8.2",
+    "typescript-eslint": "^8.24.0",
+    "vite": "^6.1.0",
+    "vitest": "3.0.7"
   },
   "resolutions": {
+    "@carto/api-client": "portal:./",
     "rollup": "^4.20.0"
-  }
+  },
+  "stableVersion": "0.4.7"
 }

package/src/api/carto-api-error.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {MapType} from '../types';
+import {MapType} from '../types.js';
 
 export type APIRequestType =
   | 'Map data'

package/src/api/query.ts

@@ -2,15 +2,15 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {SOURCE_DEFAULTS} from '../sources/index';
+import {SOURCE_DEFAULTS} from '../sources/index.js';
 import type {
   SourceOptions,
   QuerySourceOptions,
   QueryResult,
-} from '../sources/types';
-import {buildQueryUrl} from './endpoints';
-import {requestWithParameters} from './request-with-parameters';
-import {APIErrorContext} from './carto-api-error';
+} from '../sources/types.js';
+import {buildQueryUrl} from './endpoints.js';
+import {requestWithParameters} from './request-with-parameters.js';
+import {APIErrorContext} from './carto-api-error.js';
 
 export type QueryOptions = SourceOptions & QuerySourceOptions;
 type UrlParameters = {q: string; queryParameters?: string};

package/src/api/request-with-parameters.ts

@@ -2,12 +2,12 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {isPureObject} from '../utils';
-import {CartoAPIError, APIErrorContext} from './carto-api-error';
-import {V3_MINOR_VERSION} from '../constants-internal';
-import {DEFAULT_MAX_LENGTH_URL} from '../constants-internal';
-import {getClient} from '../client';
-import {LocalCacheOptions} from '../sources/types';
+import {isPureObject} from '../utils.js';
+import {CartoAPIError, APIErrorContext} from './carto-api-error.js';
+import {V3_MINOR_VERSION} from '../constants-internal.js';
+import {DEFAULT_MAX_LENGTH_URL} from '../constants-internal.js';
+import {getClient} from '../client.js';
+import {LocalCacheOptions} from '../sources/types.js';
 
 const DEFAULT_HEADERS = {
   Accept: 'application/json',

package/src/client.ts

@@ -1,6 +1,6 @@
 /**
  * @internal
- * @internalRemarks Source: @carto/react-core, @carto/constants, @deck.gl/carto
+ * @privateRemarks Source: @carto/react-core, @carto/constants, @deck.gl/carto
  */
 let client = 'deck-gl-carto';
 
@@ -8,7 +8,7 @@ let client = 'deck-gl-carto';
  * Returns current client ID, used to categorize API requests. For internal use only.
  *
  * @internal
- * @internalRemarks Source: @carto/react-core
+ * @privateRemarks Source: @carto/react-core
  */
 export function getClient() {
   return client;
@@ -18,7 +18,7 @@ export function getClient() {
  * Sets current client ID, used to categorize API requests. For internal use only.
  *
  * @internal
- * @internalRemarks Source: @carto/react-core
+ * @privateRemarks Source: @carto/react-core
  */
 export function setClient(c: string) {
   client = c;

package/src/constants-internal.ts

@@ -7,26 +7,26 @@ export const API_CLIENT_VERSION = __CARTO_API_CLIENT_VERSION;
 /** @internal */
 export const V3_MINOR_VERSION = '3.4';
 
-/** @internalRemarks Source: @carto/constants, @deck.gl/carto */
+/** @privateRemarks Source: @carto/constants, @deck.gl/carto */
 export const DEFAULT_GEO_COLUMN = 'geom';
 
 /**
  * Fastly default limit is 8192; leave some padding.
- * @internalRemarks Source: @deck.gl/carto
+ * @privateRemarks Source: @deck.gl/carto
  */
 export const DEFAULT_MAX_LENGTH_URL = 7000;
 
-/** @internalRemarks Source: @deck.gl/carto */
+/** @privateRemarks Source: @deck.gl/carto */
 export const DEFAULT_TILE_RESOLUTION = 0.5;
 
 /**
- * @internalRemarks Source: @deck.gl/carto
+ * @privateRemarks Source: @deck.gl/carto
  * @internal
  */
 export const DEFAULT_AGGREGATION_RES_LEVEL_H3 = 4;
 
 /**
- * @internalRemarks Source: @deck.gl/carto
+ * @privateRemarks Source: @deck.gl/carto
  * @internal
  */
 export const DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN = 6;

package/src/constants.ts

@@ -10,7 +10,7 @@
  * };
  * ```
  *
- * @internalRemarks Source: @carto/react-api, @deck.gl/carto
+ * @privateRemarks Source: @carto/react-api, @deck.gl/carto
  */
 export enum FilterType {
   IN = 'in',
@@ -22,12 +22,37 @@ export enum FilterType {
   STRING_SEARCH = 'stringSearch',
 }
 
-/** @internalRemarks Source: @carto/constants */
+/** @privateRemarks Source: @carto/constants */
 export enum ApiVersion {
   V1 = 'v1',
   V2 = 'v2',
   V3 = 'v3',
 }
 
-/** @internalRemarks Source: @carto/constants, @deck.gl/carto */
+/** @privateRemarks Source: @carto/constants, @deck.gl/carto */
 export const DEFAULT_API_BASE_URL = 'https://gcp-us-east1.api.carto.com';
+
+/** @privateRemarks Source: @carto/react-core */
+export enum TileFormat {
+  MVT = 'mvt',
+  JSON = 'json',
+  GEOJSON = 'geojson',
+  BINARY = 'binary',
+}
+
+/** @privateRemarks Source: @carto/react-core */
+export enum SpatialIndex {
+  H3 = 'h3',
+  S2 = 's2',
+  QUADBIN = 'quadbin',
+}
+
+/** @privateRemarks Source: @carto/react-core */
+export enum Provider {
+  BIGQUERY = 'bigquery',
+  REDSHIFT = 'redshift',
+  POSTGRES = 'postgres',
+  SNOWFLAKE = 'snowflake',
+  DATABRICKS = 'databricks',
+  DATABRICKS_REST = 'databricksRest',
+}

package/src/deck/get-data-filter-extension-props.ts

@@ -0,0 +1,164 @@
+import {Feature} from 'geojson';
+import {FilterLogicalOperator, Filters} from '../types.js';
+import {FilterType} from '../constants.js';
+import {_buildFeatureFilter} from '../filters/index.js';
+import {FeatureData} from '../types-internal.js';
+
+type TimeFilter = Filters['string'][FilterType.TIME] & {
+  params?: {offsetBy?: number};
+};
+
+/**
+ * deck.gl's DataFilterExtension supports GPU filtering with 1–4 values. We
+ * allocate filters[0] to generic filters and filters[1] to time filters.
+ *
+ * getFilterValue() _must_ return an array of the same size as the filterSize
+ * used to initialize the DataFilterExtension. We document that users must use
+ * filterSize=4 for compatibility with @link {getDataFilterExtensionProps}.
+ */
+const DEFAULT_FILTER_SIZE = 4;
+
+/** @experimental Prefer type definition from deck.gl. */
+export type _DataFilterExtensionProps = {
+  filterRange: number[][];
+  updateTriggers: Record<string, string>;
+  getFilterValue: (feature: Feature | FeatureData) => number[];
+};
+
+/**
+ * Creates props for DataFilterExtension, from `@deck.gl/extensions`, given
+ * a set of filters. Requires that DataFilterExtension is initialized with
+ * filterSize=4, where the CARTO filters will occupy the first two slots.
+ *
+ * @example To create a deck.gl layer with GPU data filtering:
+ * ```typescript
+ * import {DataFilterExtension} from '@deck.gl/extensions';
+ * import {VectorTileLayer} from '@deck.gl/layers';
+ * import {getDataFilterExtensionProps} from '@carto/api-client';
+ *
+ * const layer = new VectorTileLayer({
+ *  data: data,
+ *  extensions: [new DataFilterExtension({filterSize: 4})],
+ *  ...getDataFilterExtensionProps(filters),
+ * });
+ * ```
+ */
+export function getDataFilterExtensionProps(
+  filters: Filters,
+  filtersLogicalOperator?: FilterLogicalOperator
+): _DataFilterExtensionProps {
+  const {filtersWithoutTimeType, timeColumn, timeFilter} =
+    getFiltersByType(filters);
+  return {
+    filterRange: getFilterRange(timeFilter, DEFAULT_FILTER_SIZE),
+    updateTriggers: getUpdateTriggers(
+      filtersWithoutTimeType,
+      timeColumn,
+      timeFilter
+    ),
+    getFilterValue: getFilterValue(
+      filtersWithoutTimeType,
+      timeColumn,
+      timeFilter,
+      DEFAULT_FILTER_SIZE,
+      filtersLogicalOperator
+    ),
+  };
+}
+
+/** @internal */
+function getFiltersByType(filters: Filters) {
+  const filtersWithoutTimeType: Filters = {};
+
+  let timeColumn: string | null = null;
+  let timeFilter: TimeFilter | null = null;
+
+  for (const [column, columnData] of Object.entries(filters)) {
+    for (const [type, typeData] of Object.entries(columnData) as [
+      FilterType,
+      unknown,
+    ][]) {
+      if (type === FilterType.TIME) {
+        timeColumn = column;
+        timeFilter = typeData as TimeFilter;
+      } else {
+        filtersWithoutTimeType[column] = {[type]: typeData};
+      }
+    }
+  }
+
+  return {
+    filtersWithoutTimeType,
+    timeColumn,
+    timeFilter,
+  };
+}
+
+/** @internal */
+function getFilterRange(
+  timeFilter: TimeFilter | null,
+  filterSize: number
+): number[][] {
+  const result = Array(filterSize).fill([0, 0]);
+  // According to getFilterValue all filters are resolved as 0 or 1 in the first position of the array
+  // except the time filter value that is resolved with the real value of the feature in the second position of the array
+  result[0] = [1, 1];
+  if (timeFilter) {
+    const offsetBy = timeFilter.params?.offsetBy || 0;
+    result[1] = timeFilter.values[0].map((v) => v - offsetBy);
+  }
+  return result;
+}
+
+/** @internal */
+function getUpdateTriggers(
+  filtersWithoutTimeType: Filters,
+  timeColumn: string | null,
+  timeFilter: TimeFilter | null
+) {
+  const result: Record<string, object> = {...filtersWithoutTimeType};
+
+  // We don't want to change the layer UpdateTriggers every time that the time filter changes
+  // because this filter is changed by the time series widget during its animation
+  // so we remove the time filter value from the `updateTriggers`
+  if (timeColumn && timeFilter) {
+    result[timeColumn] = {
+      ...result[timeColumn],
+      offsetBy: timeFilter.params?.offsetBy,
+      [FilterType.TIME]: {}, // Allows working with other filters, without an impact on performance.
+    };
+  }
+  return {
+    getFilterValue: JSON.stringify(result),
+  };
+}
+
+/** @internal */
+function getFilterValue(
+  filtersWithoutTimeType: Filters,
+  timeColumn: string | null,
+  timeFilter: TimeFilter | null,
+  filterSize: number,
+  filtersLogicalOperator?: FilterLogicalOperator
+) {
+  const result = Array(filterSize).fill(0);
+  const featureFilter = _buildFeatureFilter({
+    filters: filtersWithoutTimeType,
+    type: 'number',
+    filtersLogicalOperator,
+  });
+
+  // We evaluate all filters except the time filter using _buildFeatureFilter function.
+  // For the time filter, we return the value of the feature and we will change the getFilterRange result
+  // every time this filter changes
+  return (feature: Feature | FeatureData) => {
+    result[0] = featureFilter(feature);
+
+    if (timeColumn && timeFilter) {
+      const offsetBy = timeFilter.params?.offsetBy || 0;
+      const f = (feature.properties || feature) as Record<string, unknown>;
+      result[1] = (f[timeColumn] as number) - offsetBy;
+    }
+    return result;
+  };
+}

package/src/deck/index.ts

@@ -0,0 +1 @@
+export * from './get-data-filter-extension-props.js';