@carto/api-client 0.4.6 → 0.4.7-0

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,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,146 @@
+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};
+};
+
+/** @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.
+ *
+ * @privateRemarks DataFilterExtension accepts up to 4 values to filter. This
+ *  implementation uses the 1st for all filters except the time filter, and the
+ *  2nd for the time filter.
+ */
+export function getDataFilterExtensionProps(
+  filters: Filters,
+  filtersLogicalOperator?: FilterLogicalOperator,
+  filterSize?: 0 | 1 | 2 | 3 | 4
+): _DataFilterExtensionProps {
+  filterSize ??= 4;
+  const {filtersWithoutTimeType, timeColumn, timeFilter} =
+    getFiltersByType(filters);
+  return {
+    filterRange: getFilterRange(timeFilter, filterSize),
+    updateTriggers: getUpdateTriggers(
+      filtersWithoutTimeType,
+      timeColumn,
+      timeFilter
+    ),
+    getFilterValue: getFilterValue(
+      filtersWithoutTimeType,
+      timeColumn,
+      timeFilter,
+      filterSize,
+      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

@@ -0,0 +1,179 @@
+import {filterFunctions} from './FilterTypes.js';
+import {Filter, FilterLogicalOperator, Filters} from '../types.js';
+import {Feature} from 'geojson';
+import {FilterType} from '../constants.js';
+import {FeatureData} from '../types-internal.js';
+import {BinaryFeature} from '@loaders.gl/schema';
+
+const LOGICAL_OPERATOR_METHODS: Record<
+  FilterLogicalOperator,
+  'every' | 'some'
+> = {
+  and: 'every',
+  or: 'some',
+};
+
+function passesFilter(
+  columns: string[],
+  filters: Filters,
+  feature: FeatureData,
+  filtersLogicalOperator: FilterLogicalOperator
+): boolean {
+  const method = LOGICAL_OPERATOR_METHODS[filtersLogicalOperator];
+  return columns[method]((column) => {
+    const columnFilters = filters[column];
+    const columnFilterTypes = Object.keys(columnFilters) as FilterType[];
+
+    if (!feature || feature[column] === null || feature[column] === undefined) {
+      return false;
+    }
+
+    return columnFilterTypes.every((filter) => {
+      const filterFunction = filterFunctions[filter];
+
+      if (!filterFunction) {
+        throw new Error(`"${filter}" filter is not implemented.`);
+      }
+
+      return filterFunction(
+        columnFilters[filter]!.values,
+        feature[column],
+        (columnFilters[filter] as Filter[FilterType.STRING_SEARCH])!.params
+      );
+    });
+  });
+}
+
+/**
+ * @internal
+ * @privateRemarks Exported for use in @deck.gl/carto's getDataFilterExtensionProps.
+ */
+export function _buildFeatureFilter({
+  filters = {},
+  type = 'boolean',
+  filtersLogicalOperator = 'and',
+}: {
+  filters?: Filters;
+  type?: 'number' | 'boolean';
+  filtersLogicalOperator?: FilterLogicalOperator;
+}) {
+  const columns = Object.keys(filters);
+
+  if (!columns.length) {
+    return () => (type === 'number' ? 1 : true);
+  }
+
+  return (feature: Feature | FeatureData) => {
+    const f = feature.properties || feature;
+    const featurePassesFilter = passesFilter(
+      columns,
+      filters,
+      f as FeatureData,
+      filtersLogicalOperator
+    );
+
+    return type === 'number'
+      ? Number(featurePassesFilter)
+      : featurePassesFilter;
+  };
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Binary.
+ * @internal
+ */
+export function buildBinaryFeatureFilter({filters = {}}: {filters: Filters}) {
+  const columns = Object.keys(filters);
+
+  if (!columns.length) {
+    return () => 1;
+  }
+
+  return (featureIdIdx: number, binaryData: BinaryFeature) =>
+    passesFilterUsingBinary(columns, filters, featureIdIdx, binaryData);
+}
+
+function getValueFromNumericProps(
+  featureIdIdx: number,
+  binaryData: BinaryFeature,
+  {column}: {column: string}
+) {
+  return binaryData.numericProps?.[column]?.value[featureIdIdx];
+}
+
+function getValueFromProperties(
+  featureIdIdx: number,
+  binaryData: BinaryFeature,
+  {column}: {column: string}
+) {
+  const propertyIdx = binaryData.featureIds.value[featureIdIdx];
+  return (binaryData.properties[propertyIdx] as Record<string, unknown>)?.[
+    column
+  ];
+}
+
+const GET_VALUE_BY_BINARY_PROP = {
+  properties: getValueFromProperties,
+  numericProps: getValueFromNumericProps,
+};
+
+function getBinaryPropertyByFilterValues(filterValues: unknown[]) {
+  return typeof filterValues.flat()[0] === 'string'
+    ? 'properties'
+    : 'numericProps';
+}
+
+function getFeatureValue(
+  featureIdIdx: number,
+  binaryData: any,
+  filter: {type: FilterType; column: string; values: unknown[]}
+) {
+  const {column, values} = filter;
+  const binaryProp = getBinaryPropertyByFilterValues(values);
+  const getFeatureValueFn = GET_VALUE_BY_BINARY_PROP[binaryProp];
+  return getFeatureValueFn(featureIdIdx, binaryData, {column});
+}
+
+function passesFilterUsingBinary(
+  columns: string[],
+  filters: Filters,
+  featureIdIdx: number,
+  binaryData: BinaryFeature
+) {
+  return columns.every((column) => {
+    const columnFilters = filters[column];
+
+    return Object.entries(columnFilters).every(([type, {values}]) => {
+      const filterFn = filterFunctions[type as FilterType];
+      if (!filterFn) {
+        throw new Error(`"${type}" filter is not implemented.`);
+      }
+
+      if (!values) return 0;
+
+      const featureValue = getFeatureValue(featureIdIdx, binaryData, {
+        type: type as FilterType,
+        column,
+        values,
+      });
+
+      if (featureValue === undefined || featureValue === null) return 0;
+
+      return filterFn(values, featureValue);
+    });
+  });
+}

package/src/filters/FilterTypes.ts

@@ -0,0 +1,109 @@
+import {FilterType} from '../constants.js';
+import {FilterInterval, StringSearchOptions} from '../types.js';
+import {makeIntervalComplete} from '../utils/makeIntervalComplete.js';
+
+export type FilterFunction = (
+  filterValues: unknown[],
+  featureValue: unknown,
+  params?: Record<string, unknown>
+) => boolean;
+
+export const filterFunctions: Record<FilterType, FilterFunction> = {
+  [FilterType.IN]: filterIn,
+  [FilterType.BETWEEN]: filterBetween,
+  [FilterType.TIME]: filterTime,
+  [FilterType.CLOSED_OPEN]: filterClosedOpen,
+  [FilterType.STRING_SEARCH]: filterStringSearch,
+};
+
+function filterIn(filterValues: unknown[], featureValue: unknown): boolean {
+  return filterValues.includes(featureValue);
+}
+
+// FilterTypes.BETWEEN
+function filterBetween(
+  filterValues: unknown[],
+  featureValue: unknown
+): boolean {
+  const checkRange = (range: [number, number]) => {
+    const [lowerBound, upperBound] = range;
+    return (
+      (featureValue as number) >= lowerBound &&
+      (featureValue as number) <= upperBound
+    );
+  };
+
+  return makeIntervalComplete(filterValues as FilterInterval[]).some(
+    checkRange
+  );
+}
+
+function filterTime(filterValues: unknown[], featureValue: unknown) {
+  const featureValueAsTimestamp = new Date(featureValue as number).getTime();
+  if (isFinite(featureValueAsTimestamp)) {
+    return filterBetween(filterValues, featureValueAsTimestamp);
+  } else {
+    throw new Error(`Column used to filter by time isn't well formatted.`);
+  }
+}
+
+// FilterTypes.CLOSED_OPEN
+function filterClosedOpen(
+  filterValues: unknown[],
+  featureValue: unknown
+): boolean {
+  const checkRange = (range: [number, number]) => {
+    const [lowerBound, upperBound] = range;
+    return (
+      (featureValue as number) >= lowerBound &&
+      (featureValue as number) < upperBound
+    );
+  };
+
+  return makeIntervalComplete(filterValues as [number, number][]).some(
+    checkRange
+  );
+}
+
+// FilterTypes.STRING_SEARCH
+function filterStringSearch(
+  filterValues: unknown[],
+  featureValue: unknown,
+  params: StringSearchOptions = {}
+): boolean {
+  const normalizedFeatureValue = normalize(featureValue, params);
+  const stringRegExp = params.useRegExp
+    ? filterValues
+    : filterValues.map((filterValue) => {
+        let stringRegExp = escapeRegExp(normalize(filterValue, params));
+
+        if (params.mustStart) stringRegExp = `^${stringRegExp}`;
+        if (params.mustEnd) stringRegExp = `${stringRegExp}$`;
+
+        return stringRegExp;
+      });
+
+  const regex = new RegExp(
+    stringRegExp.join('|'),
+    params.caseSensitive ? 'g' : 'gi'
+  );
+  return !!normalizedFeatureValue.match(regex);
+}
+
+// Aux
+const specialCharRegExp = /[.*+?^${}()|[\]\\]/g;
+const normalizeRegExp = /\p{Diacritic}/gu;
+
+function escapeRegExp(value: string) {
+  return value.replace(specialCharRegExp, '\\$&');
+}
+
+function normalize(data: unknown, params: StringSearchOptions) {
+  let normalizedData = String(data);
+  if (!params.keepSpecialCharacters)
+    normalizedData = normalizedData
+      .normalize('NFD')
+      .replace(normalizeRegExp, '');
+
+  return normalizedData;
+}

package/src/filters/geosjonFeatures.ts

@@ -0,0 +1,32 @@
+import intersects from '@turf/boolean-intersects';
+import {FeatureCollection} from 'geojson';
+import {FeatureData} from '../types-internal.js';
+import {SpatialFilter} from '../types.js';
+
+export function geojsonFeatures({
+  geojson,
+  spatialFilter,
+  uniqueIdProperty,
+}: {
+  geojson: FeatureCollection;
+  spatialFilter: SpatialFilter;
+  uniqueIdProperty?: string;
+}): FeatureData[] {
+  let uniqueIdx = 0;
+  const map = new Map();
+
+  if (!spatialFilter) {
+    return [];
+  }
+
+  for (const feature of geojson.features) {
+    const uniqueId = uniqueIdProperty
+      ? feature.properties![uniqueIdProperty]
+      : ++uniqueIdx;
+    if (!map.has(uniqueId) && intersects(spatialFilter, feature)) {
+      map.set(uniqueId, feature.properties);
+    }
+  }
+
+  return Array.from(map.values());
+}

package/src/filters/index.ts

@@ -0,0 +1,6 @@
+export * from './Filter.js';
+export * from './FilterTypes.js';
+export * from './geosjonFeatures.js';
+export * from './tileFeatures.js';
+export * from './tileFeaturesGeometries.js';
+export * from './tileFeaturesSpatialIndex.js';

package/src/filters/tileFeatures.ts

@@ -0,0 +1,51 @@
+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';
+
+/** @privateRemarks Source: @carto/react-core */
+export type TileFeatures = {
+  tiles: Tile[];
+  tileFormat: TileFormat;
+  spatialDataType: SpatialDataType;
+  spatialDataColumn?: string;
+  spatialFilter: SpatialFilter;
+  uniqueIdProperty?: string;
+  options?: TileFeatureExtractOptions;
+};
+
+/** @privateRemarks Source: @carto/react-core */
+export type TileFeatureExtractOptions = {
+  storeGeometry?: boolean;
+  uniqueIdProperty?: string;
+};
+
+/** @privateRemarks Source: @carto/react-core */
+export function tileFeatures({
+  tiles,
+  spatialFilter,
+  uniqueIdProperty,
+  tileFormat,
+  spatialDataColumn = DEFAULT_GEO_COLUMN,
+  spatialDataType,
+  options = {},
+}: TileFeatures): FeatureData[] {
+  if (spatialDataType !== 'geo') {
+    return tileFeaturesSpatialIndex({
+      tiles: tiles as SpatialIndexTile[],
+      spatialFilter,
+      spatialDataColumn,
+      spatialDataType,
+    });
+  }
+  return tileFeaturesGeometries({
+    tiles,
+    tileFormat,
+    spatialFilter,
+    uniqueIdProperty,
+    options,
+  });
+}