@carto/api-client 0.5.0-alpha.2 → 0.5.0-alpha.4

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

@@ -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,31 @@
-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 {RasterTile, 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 {RasterMetadata, SpatialDataType} from '../sources/types.js';
+import {isRasterTile, tileFeaturesRaster} from './tileFeaturesRaster.js';
+import {assert} from '../utils.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;
+  rasterMetadata?: RasterMetadata;
   options?: TileFeatureExtractOptions;
 };
 
-/** @internalRemarks Source: @carto/react-core */
+/** @privateRemarks Source: @carto/react-core */
 export type TileFeatureExtractOptions = {
   storeGeometry?: boolean;
 };
 
-/** @internalRemarks Source: @carto/react-core */
+/** @privateRemarks Source: @carto/react-core */
 export function tileFeatures({
   tiles,
   spatialFilter,
@@ -30,27 +33,34 @@ export function tileFeatures({
   tileFormat,
   spatialDataColumn = DEFAULT_GEO_COLUMN,
   spatialDataType,
+  rasterMetadata,
   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 tileFeaturesGeometries({
+      tiles,
+      tileFormat,
+      spatialFilter,
+      uniqueIdProperty,
+      options,
+    });
   }
 
-  if (spatialDataType !== 'geo') {
-    return tileFeaturesSpatialIndex({
-      tiles: tiles as SpatialIndexTile[],
+  if (tiles.some(isRasterTile)) {
+    assert(rasterMetadata, 'Missing raster metadata');
+    return tileFeaturesRaster({
+      tiles: tiles as RasterTile[],
       spatialFilter,
       spatialDataColumn,
       spatialDataType,
+      rasterMetadata,
     });
   }
-  return tileFeaturesGeometries({
-    tiles,
-    tileFormat,
+
+  return tileFeaturesSpatialIndex({
+    tiles: tiles as SpatialIndexTile[],
     spatialFilter,
-    uniqueIdProperty,
-    options,
+    spatialDataColumn,
+    spatialDataType,
   });
 }

package/src/filters/tileFeaturesRaster.ts

@@ -0,0 +1,111 @@
+import {
+  cellToChildren as _cellToChildren,
+  cellToTile,
+  geometryToCells,
+  getResolution,
+} from 'quadbin';
+import {RasterTile, SpatialFilter, Tile} from '../types.js';
+import {FeatureData} from '../types-internal.js';
+import {
+  RasterMetadata,
+  RasterMetadataBand,
+  SpatialDataType,
+} from '../sources/types.js';
+
+export type TileFeaturesRasterOptions = {
+  tiles: RasterTile[];
+  spatialFilter: SpatialFilter;
+  spatialDataColumn: string;
+  spatialDataType: SpatialDataType;
+  rasterMetadata: RasterMetadata;
+};
+
+export function tileFeaturesRaster({
+  tiles,
+  ...options
+}: TileFeaturesRasterOptions): FeatureData[] {
+  // Cache band metadata for faster lookup while iterating over pixels.
+  const bandMetadataByName: Record<string, RasterMetadataBand> = {};
+  for (const band of options.rasterMetadata.bands) {
+    bandMetadataByName[band.name] = band;
+  }
+
+  // Omit empty and invisible tiles for simpler processing and types.
+  tiles = tiles.filter(isRasterTileVisible);
+  if (tiles.length === 0) return [];
+
+  // Raster tiles, and all pixels, are quadbin cells. Resolution of a pixel is
+  // the resolution of the tile, plus the number of subdivisions. Block size
+  // must be square, N x N, where N is a power of two.
+  const tileResolution = getResolution(tiles[0].index.q);
+  const tileBlockSize = tiles[0].data!.blockSize;
+  const cellResolution = tileResolution + BigInt(Math.log2(tileBlockSize));
+
+  // Compute covering cells for the spatial filter, at same resolution as the
+  // raster pixels, to be used as a mask.
+  const spatialFilterCells = new Set(
+    geometryToCells(options.spatialFilter, cellResolution)
+  );
+
+  const data = new Map<bigint, FeatureData>();
+
+  for (const tile of tiles as Required<RasterTile>[]) {
+    const parent = tile.index.q;
+
+    const children = cellToChildrenSorted(parent, cellResolution);
+
+    // For each pixel/cell within the spatial filter, create a FeatureData.
+    // Order is row-major, starting from NW and ending at SE.
+    for (let i = 0; i < children.length; i++) {
+      if (!spatialFilterCells.has(children[i])) continue;
+
+      const cellData: FeatureData = {};
+      let cellDataExists = false;
+
+      for (const band in tile.data.cells.numericProps) {
+        const value = tile.data.cells.numericProps[band].value[i];
+        // TODO(cleanup): nodata should be a number, not a string.
+        if (Number(bandMetadataByName[band].nodata) !== value) {
+          cellData[band] = tile.data.cells.numericProps[band].value[i];
+          cellDataExists = true;
+        }
+      }
+
+      if (cellDataExists) {
+        data.set(children[i], cellData);
+      }
+    }
+  }
+
+  return Array.from(data.values());
+}
+
+/**
+ * Detects whether a given {@link Tile} is a {@link RasterTile}.
+ * @privateRemarks Method of detection is arbitrary, and may be changed.
+ */
+export function isRasterTile(tile: Tile): tile is RasterTile {
+  return !!(tile.data as Record<string, unknown>)?.cells;
+}
+
+function isRasterTileVisible(tile: RasterTile): tile is Required<RasterTile> {
+  return !!(tile.isVisible && tile.data?.cells?.numericProps);
+}
+
+/**
+ * For the raster format, children are sorted in row-major order, starting from
+ * NW and ending at SE. Order returned by quadbin's cellToChildren() is not
+ * defined (and not related to the raster format), so sort explicitly here.
+ */
+function cellToChildrenSorted(parent: bigint, resolution: bigint): bigint[] {
+  return _cellToChildren(parent, resolution).sort(
+    (cellA: bigint, cellB: bigint) => {
+      const tileA = cellToTile(cellA);
+      const tileB = cellToTile(cellB);
+      if (tileA.y !== tileB.y) {
+        return tileA.y > tileB.y ? 1 : -1;
+      }
+      return tileA.x > tileB.x ? 1 : -1;
+    }
+  );
+}

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/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,8 +1,9 @@
 import {InvalidColumnError} from '../utils.js';
 
-/** @internalRemarks Source: @carto/react-api */
+/** @privateRemarks Source: @carto/react-api */
 export interface ModelRequestOptions {
   method: 'GET' | 'POST';
+  headers?: Record<string, string>;
   abortController?: AbortController;
   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,6 +69,7 @@ export async function makeCall({
       headers: {
         Authorization: `Bearer ${accessToken}`,
         ...(isPost && {'Content-Type': 'application/json'}),
+        ...opts.headers,
       },
       ...(isPost && {
         method: opts?.method,
@@ -80,7 +82,7 @@ export async function makeCall({
   } 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[],