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

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

@@ -1,32 +1,26 @@
-/**
- * Current version of @carto/api-client.
- * @internal
- */
-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,17 +22,17 @@ 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';
 
-/** @internalRemarks Source: @carto/react-core */
+/** @privateRemarks Source: @carto/react-core */
 export enum TileFormat {
   MVT = 'mvt',
   JSON = 'json',
@@ -40,14 +40,14 @@ export enum TileFormat {
   BINARY = 'binary',
 }
 
-/** @internalRemarks Source: @carto/react-core */
+/** @privateRemarks Source: @carto/react-core */
 export enum SpatialIndex {
   H3 = 'h3',
   S2 = 's2',
   QUADBIN = 'quadbin',
 }
 
-/** @internalRemarks Source: @carto/react-core */
+/** @privateRemarks Source: @carto/react-core */
 export enum Provider {
   BIGQUERY = 'bigquery',
   REDSHIFT = 'redshift',

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';

package/src/filters/Filter.ts

@@ -1,8 +1,8 @@
-import {filterFunctions} from './FilterTypes';
-import {Filter, FilterLogicalOperator, Filters} from '../types';
+import {filterFunctions} from './FilterTypes.js';
+import {Filter, FilterLogicalOperator, Filters} from '../types.js';
 import {Feature} from 'geojson';
-import {FilterType} from '../constants';
-import {FeatureData} from '../types-internal';
+import {FilterType} from '../constants.js';
+import {FeatureData} from '../types-internal.js';
 import {BinaryFeature} from '@loaders.gl/schema';
 
 const LOGICAL_OPERATOR_METHODS: Record<
@@ -44,7 +44,11 @@ function passesFilter(
   });
 }
 
-export function buildFeatureFilter({
+/**
+ * @internal
+ * @privateRemarks Exported for use in @deck.gl/carto's getDataFilterExtensionProps.
+ */
+export function _buildFeatureFilter({
   filters = {},
   type = 'boolean',
   filtersLogicalOperator = 'and',
@@ -74,18 +78,24 @@ export function buildFeatureFilter({
   };
 }
 
-// Apply certain filters to a collection of features
+/**
+ * Apply certain filters to a collection of features.
+ * @internal
+ */
 export function applyFilters(
   features: FeatureData[],
   filters: Filters,
   filtersLogicalOperator: FilterLogicalOperator
 ) {
   return Object.keys(filters).length
-    ? features.filter(buildFeatureFilter({filters, filtersLogicalOperator}))
+    ? features.filter(_buildFeatureFilter({filters, filtersLogicalOperator}))
     : features;
 }
 
-// Binary
+/**
+ * Binary.
+ * @internal
+ */
 export function buildBinaryFeatureFilter({filters = {}}: {filters: Filters}) {
   const columns = Object.keys(filters);
 

package/src/filters/FilterTypes.ts

@@ -1,5 +1,5 @@
-import {FilterType} from '../constants';
-import {FilterInterval, StringSearchOptions} from '../types';
+import {FilterType} from '../constants.js';
+import {FilterInterval, StringSearchOptions} from '../types.js';
 import {makeIntervalComplete} from '../utils/makeIntervalComplete.js';
 
 export type FilterFunction = (

package/src/filters/geosjonFeatures.ts

@@ -1,7 +1,7 @@
 import intersects from '@turf/boolean-intersects';
 import {FeatureCollection} from 'geojson';
-import {SpatialFilter} from '..';
-import {FeatureData} from '../types-internal';
+import {FeatureData} from '../types-internal.js';
+import {SpatialFilter} from '../types.js';
 
 export function geojsonFeatures({
   geojson,

package/src/filters/tileFeatures.ts

@@ -1,28 +1,29 @@
-import {SpatialFilter, SpatialIndexTile, Tile} from '../types';
-import {tileFeaturesGeometries} from './tileFeaturesGeometries';
-import {tileFeaturesSpatialIndex} from './tileFeaturesSpatialIndex';
-import {SpatialIndex, TileFormat} from '../constants';
-import {DEFAULT_GEO_COLUMN} from '../constants-internal';
-import {FeatureData} from '../types-internal';
-import {SpatialDataType} from '../sources/types';
+import {SpatialFilter, SpatialIndexTile, Tile} from '../types.js';
+import {tileFeaturesGeometries} from './tileFeaturesGeometries.js';
+import {tileFeaturesSpatialIndex} from './tileFeaturesSpatialIndex.js';
+import {TileFormat} from '../constants.js';
+import {DEFAULT_GEO_COLUMN} from '../constants-internal.js';
+import {FeatureData} from '../types-internal.js';
+import {SpatialDataType} from '../sources/types.js';
 
-/** @internalRemarks Source: @carto/react-core */
+/** @privateRemarks Source: @carto/react-core */
 export type TileFeatures = {
   tiles: Tile[];
   tileFormat: TileFormat;
   spatialDataType: SpatialDataType;
   spatialDataColumn?: string;
-  spatialFilter?: SpatialFilter;
+  spatialFilter: SpatialFilter;
   uniqueIdProperty?: string;
   options?: TileFeatureExtractOptions;
 };
 
-/** @internalRemarks Source: @carto/react-core */
+/** @privateRemarks Source: @carto/react-core */
 export type TileFeatureExtractOptions = {
   storeGeometry?: boolean;
+  uniqueIdProperty?: string;
 };
 
-/** @internalRemarks Source: @carto/react-core */
+/** @privateRemarks Source: @carto/react-core */
 export function tileFeatures({
   tiles,
   spatialFilter,
@@ -32,12 +33,6 @@ export function tileFeatures({
   spatialDataType,
   options = {},
 }: TileFeatures): FeatureData[] {
-  // TODO(cleanup): Is an empty response the expected result when spatialFilter
-  // is omitted? Why not make the parameter required, or return the full input?
-  if (!spatialFilter) {
-    return [];
-  }
-
   if (spatialDataType !== 'geo') {
     return tileFeaturesSpatialIndex({
       tiles: tiles as SpatialIndexTile[],

package/src/filters.ts

@@ -1,6 +1,6 @@
-import {FilterType} from './constants';
-import {Filter} from './types';
-import {isEmptyObject} from './utils';
+import {FilterType} from './constants.js';
+import {Filter} from './types.js';
+import {isEmptyObject} from './utils.js';
 
 type FilterTypeOptions<T extends FilterType> = {
   type: T;
@@ -121,7 +121,7 @@ export function getFilter<T extends FilterType>(
     return null;
   }
 
-  if (!owner || owner === filter[type as FilterType]?.owner) {
+  if (!owner || owner === filter[type]?.owner) {
     return filter[type] || null;
   }
 

package/src/geo.ts

@@ -4,7 +4,7 @@ import union from '@turf/union';
 import {getType} from '@turf/invariant';
 import {polygon, multiPolygon, feature, featureCollection} from '@turf/helpers';
 import type {BBox, Geometry, MultiPolygon, Polygon, Position} from 'geojson';
-import {SpatialFilter} from './types';
+import {SpatialFilter} from './types.js';
 
 /**
  * Returns a {@link SpatialFilter} for a given viewport, typically obtained
@@ -40,7 +40,7 @@ export function createPolygonSpatialFilter(
  * Check if a viewport is large enough to represent a global coverage.
  * In this case the spatial filter parameter for widget calculation is removed.
  *
- * @internalRemarks Source: @carto/react-core
+ * @privateRemarks Source: @carto/react-core
  */
 function _isGlobalViewport(viewport: BBox) {
   const [minx, miny, maxx, maxy] = viewport;
@@ -54,7 +54,7 @@ function _isGlobalViewport(viewport: BBox) {
  *
  * It results in a Polygon or MultiPolygon strictly inside the validity range.
  *
- * @internalRemarks Source: @carto/react-core
+ * @privateRemarks Source: @carto/react-core
  */
 function _normalizeGeometry(
   geometry: Polygon | MultiPolygon
@@ -100,19 +100,19 @@ function _normalizeGeometry(
   return result;
 }
 
-/** @internalRemarks Source: @carto/react-core */
+/** @privateRemarks Source: @carto/react-core */
 function _cleanPolygonCoords(cc: Position[][]) {
   const coords = cc.filter((c) => c.length > 0);
   return coords.length > 0 ? coords : null;
 }
 
-/** @internalRemarks Source: @carto/react-core */
+/** @privateRemarks Source: @carto/react-core */
 function _cleanMultiPolygonCoords(ccc: Position[][][]) {
   const coords = ccc.map(_cleanPolygonCoords).filter((cc) => cc);
   return coords.length > 0 ? coords : null;
 }
 
-/** @internalRemarks Source: @carto/react-core */
+/** @privateRemarks Source: @carto/react-core */
 function _clean(
   geometry: Polygon | MultiPolygon | null
 ): Polygon | MultiPolygon | null {
@@ -121,36 +121,34 @@ function _clean(
   }
 
   if (_isPolygon(geometry)) {
-    const coords = _cleanPolygonCoords((geometry as Polygon).coordinates);
+    const coords = _cleanPolygonCoords(geometry.coordinates);
     return coords ? polygon(coords).geometry : null;
   }
 
   if (_isMultiPolygon(geometry)) {
-    const coords = _cleanMultiPolygonCoords(
-      (geometry as MultiPolygon).coordinates
-    );
+    const coords = _cleanMultiPolygonCoords(geometry.coordinates);
     return coords ? multiPolygon(coords as Position[][][]).geometry : null;
   }
 
   return null;
 }
 
-/** @internalRemarks Source: @carto/react-core */
+/** @privateRemarks Source: @carto/react-core */
 function _txContourCoords(cc: Position[], distance: number) {
   return cc.map((c) => [c[0] + distance, c[1]]);
 }
 
-/** @internalRemarks Source: @carto/react-core */
+/** @privateRemarks Source: @carto/react-core */
 function _txPolygonCoords(ccc: Position[][], distance: number) {
   return ccc.map((cc) => _txContourCoords(cc, distance));
 }
 
-/** @internalRemarks Source: @carto/react-core */
+/** @privateRemarks Source: @carto/react-core */
 function _txMultiPolygonCoords(cccc: Position[][][], distance: number) {
   return cccc.map((ccc) => _txPolygonCoords(ccc, distance));
 }
 
-/** @internalRemarks Source: @carto/react-core */
+/** @privateRemarks Source: @carto/react-core */
 function _tx(geometry: Polygon | MultiPolygon, distance: number) {
   if (geometry && getType(geometry) === 'Polygon') {
     const coords = _txPolygonCoords(

package/src/global.d.ts

@@ -1,10 +1,5 @@
-/**
- * Injected by microbundle, with:
- * ```
- * --define __CARTO_API_CLIENT_VERSION=$npm_package_version
- * ```
- */
-declare const __CARTO_API_CLIENT_VERSION: string;
-
 /** Defined by @deck.gl/core. */
 declare const deck: {VERSION: string | undefined} | undefined;
+
+/** Defined by tsup. */
+declare const TSUP_FORMAT: 'esm' | 'cjs';

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from './client.js';
 export * from './constants.js';
+export * from './deck/index.js';
 export * from './filters.js';
 export * from './geo.js';
 export * from './sources/index.js';
@@ -17,6 +18,8 @@ export {
   requestWithParameters,
 } from './api/index.js';
 
+export {_getHexagonResolution} from './spatial-index.js';
+
 // For unit testing only.
 export * from './filters/index.js';
 export * from './operations/index.js';

package/src/models/common.ts

@@ -1,9 +1,10 @@
 import {InvalidColumnError} from '../utils.js';
 
-/** @internalRemarks Source: @carto/react-api */
+/** @privateRemarks Source: @carto/react-api */
 export interface ModelRequestOptions {
   method: 'GET' | 'POST';
-  abortController?: AbortController;
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
   otherOptions?: Record<string, unknown>;
   body?: string;
 }
@@ -16,7 +17,7 @@ interface ModelErrorResponse {
 
 /**
  * Return more descriptive error from API
- * @internalRemarks Source: @carto/react-api
+ * @privateRemarks Source: @carto/react-api
  */
 export function dealWithApiError({
   response,
@@ -42,15 +43,15 @@ export function dealWithApiError({
     case 403:
       throw new Error('Forbidden access to the requested data');
     default:
-      const msg =
+      throw new Error(
         data && data.error && typeof data.error === 'string'
           ? data.error
-          : JSON.stringify(data?.hint || data.error?.[0]);
-      throw new Error(msg);
+          : JSON.stringify(data?.hint || data.error?.[0])
+      );
   }
 }
 
-/** @internalRemarks Source: @carto/react-api */
+/** @privateRemarks Source: @carto/react-api */
 export async function makeCall({
   url,
   accessToken,
@@ -68,19 +69,20 @@ export async function makeCall({
       headers: {
         Authorization: `Bearer ${accessToken}`,
         ...(isPost && {'Content-Type': 'application/json'}),
+        ...opts.headers,
       },
       ...(isPost && {
         method: opts?.method,
         body: opts?.body,
       }),
-      signal: opts?.abortController?.signal,
+      signal: opts?.signal,
       ...opts?.otherOptions,
     });
     data = await response.json();
   } catch (error) {
     if ((error as Error).name === 'AbortError') throw error;
 
-    throw new Error(`Failed request: ${error}`);
+    throw new Error(`Failed request: ${error as Error}`);
   }
 
   if (!response.ok) {

package/src/models/model.ts

@@ -6,13 +6,12 @@ import {
   QueryParameters,
   SpatialFilter,
 } from '../types.js';
-import {$TODO} from '../types-internal.js';
 import {assert, isPureObject} from '../utils.js';
 import {ModelRequestOptions, makeCall} from './common.js';
 import {ApiVersion} from '../constants.js';
 import {SpatialDataType, SpatialFilterPolyfillMode} from '../sources/types.js';
 
-/** @internalRemarks Source: @carto/react-api */
+/** @privateRemarks Source: @carto/react-api */
 const AVAILABLE_MODELS = [
   'category',
   'histogram',
@@ -51,7 +50,7 @@ const REQUEST_GET_MAX_URL_LENGTH = 2048;
 
 /**
  * Execute a SQL model request.
- * @internalRemarks Source: @carto/react-api
+ * @privateRemarks Source: @carto/react-api
  */
 export function executeModel(props: {
   model: Model;
@@ -152,7 +151,7 @@ function objectToURLSearchParams(object: Record<string, unknown>) {
     } else if (object[key] === null) {
       params.append(key, 'null');
     } else if (object[key] !== undefined) {
-      params.append(key, String(object[key]));
+      params.append(key, String(object[key] as unknown));
     }
   }
   return params;

package/src/operations/aggregation.ts

@@ -1,14 +1,14 @@
-import {AggregationType} from '../types';
-import {FeatureData} from '../types-internal';
+import {AggregationType} from '../types.js';
+import {FeatureData} from '../types-internal.js';
 
-/** @internalRemarks Source: @carto/react-core */
+/** @privateRemarks Source: @carto/react-core */
 export type AggregationFunction = (
   values: unknown[] | FeatureData[],
   keys?: string[] | string,
   joinOperation?: AggregationType
 ) => number;
 
-/** @internalRemarks Source: @carto/react-core */
+/** @privateRemarks Source: @carto/react-core */
 export const aggregationFunctions: Record<
   Exclude<AggregationType, 'custom'>,
   AggregationFunction
@@ -20,7 +20,7 @@ export const aggregationFunctions: Record<
   avg: (...args) => applyAggregationFunction(avg, ...args),
 };
 
-/** @internalRemarks Source: @carto/react-core */
+/** @privateRemarks Source: @carto/react-core */
 export function aggregate(
   feature: FeatureData,
   keys?: string[],