@carto/api-client 0.5.0-alpha.11 → 0.5.0-alpha.14

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.5.0-alpha.11",
+  "version": "0.5.0-alpha.14",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -49,7 +49,7 @@
     "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",
+    "postversion:check": "yarn lint && yarn format:check && yarn test",
     "postversion:commit": "node scripts/postversion-commit.js",
     "postversion:push": "git push && git push --tags",
     "prepublish": "yarn lint && yarn test",
@@ -73,46 +73,47 @@
     "@turf/invariant": "^7.2.0",
     "@turf/union": "^7.2.0",
     "@types/geojson": "^7946.0.16",
-    "h3-js": "4.1.0"
+    "h3-js": "4.1.0",
+    "quadbin": "^0.4.0-alpha.2"
   },
   "devDependencies": {
-    "@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",
+    "@deck.gl/aggregation-layers": "~9.1.4",
+    "@deck.gl/carto": "~9.1.4",
+    "@deck.gl/core": "~9.1.4",
+    "@deck.gl/extensions": "~9.1.4",
+    "@deck.gl/geo-layers": "~9.1.4",
+    "@deck.gl/layers": "~9.1.4",
+    "@deck.gl/mesh-layers": "~9.1.4",
+    "@eslint/js": "^9.21.0",
     "@lit/react": "^1.0.7",
     "@lit/task": "^1.0.2",
     "@loaders.gl/core": "^4.3.3",
-    "@luma.gl/core": "~9.1.0",
-    "@luma.gl/engine": "~9.1.0",
-    "@luma.gl/shadertools": "~9.1.0",
+    "@luma.gl/core": "~9.1.4",
+    "@luma.gl/engine": "~9.1.4",
+    "@luma.gl/shadertools": "~9.1.4",
     "@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.5",
+    "@vitest/coverage-istanbul": "^3.0.7",
     "@webcomponents/webcomponentsjs": "^2.8.0",
     "concurrently": "^9.1.2",
     "echarts": "^5.6.0",
-    "eslint": "^9.20.1",
+    "eslint": "^9.21.0",
     "lit": "^3.2.1",
     "lit-analyzer": "^2.0.3",
-    "maplibre-gl": "^5.1.0",
-    "prettier": "^3.4.2",
+    "maplibre-gl": "^5.2.0",
+    "prettier": "^3.5.3",
     "rimraf": "^6.0.1",
     "semver": "^7.7.1",
     "thenby": "^1.3.4",
     "tinybench": "^3.1.1",
     "tsup": "^8.3.6",
-    "typescript": "~5.7.3",
-    "typescript-eslint": "^8.24.0",
-    "vite": "^6.1.0",
-    "vitest": "3.0.5"
+    "typescript": "~5.8.2",
+    "typescript-eslint": "^8.26.0",
+    "vite": "^6.2.0",
+    "vitest": "3.0.7"
   },
   "stableVersion": "0.4.6"
 }

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

@@ -8,6 +8,16 @@ 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[][];
@@ -17,22 +27,30 @@ export type _DataFilterExtensionProps = {
 
 /**
  * Creates props for DataFilterExtension, from `@deck.gl/extensions`, given
- * a set of filters.
+ * 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';
  *
- * @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.
+ * const layer = new VectorTileLayer({
+ *  data: data,
+ *  extensions: [new DataFilterExtension({filterSize: 4})],
+ *  ...getDataFilterExtensionProps(filters),
+ * });
+ * ```
  */
 export function getDataFilterExtensionProps(
   filters: Filters,
-  filtersLogicalOperator?: FilterLogicalOperator,
-  filterSize?: 0 | 1 | 2 | 3 | 4
+  filtersLogicalOperator?: FilterLogicalOperator
 ): _DataFilterExtensionProps {
-  filterSize ??= 4;
   const {filtersWithoutTimeType, timeColumn, timeFilter} =
     getFiltersByType(filters);
   return {
-    filterRange: getFilterRange(timeFilter, filterSize),
+    filterRange: getFilterRange(timeFilter, DEFAULT_FILTER_SIZE),
     updateTriggers: getUpdateTriggers(
       filtersWithoutTimeType,
       timeColumn,
@@ -42,7 +60,7 @@ export function getDataFilterExtensionProps(
       filtersWithoutTimeType,
       timeColumn,
       timeFilter,
-      filterSize,
+      DEFAULT_FILTER_SIZE,
       filtersLogicalOperator
     ),
   };

package/src/filters/tileFeatures.ts

@@ -1,10 +1,12 @@
-import {SpatialFilter, SpatialIndexTile, Tile} from '../types.js';
+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 {SpatialDataType} from '../sources/types.js';
+import {RasterMetadata, SpatialDataType} from '../sources/types.js';
+import {isRasterTile, tileFeaturesRaster} from './tileFeaturesRaster.js';
+import {assert} from '../utils.js';
 
 /** @privateRemarks Source: @carto/react-core */
 export type TileFeatures = {
@@ -14,6 +16,7 @@ export type TileFeatures = {
   spatialDataColumn?: string;
   spatialFilter: SpatialFilter;
   uniqueIdProperty?: string;
+  rasterMetadata?: RasterMetadata;
   options?: TileFeatureExtractOptions;
 };
 
@@ -31,21 +34,34 @@ export function tileFeatures({
   tileFormat,
   spatialDataColumn = DEFAULT_GEO_COLUMN,
   spatialDataType,
+  rasterMetadata,
   options = {},
 }: TileFeatures): FeatureData[] {
-  if (spatialDataType !== 'geo') {
-    return tileFeaturesSpatialIndex({
-      tiles: tiles as SpatialIndexTile[],
+  if (spatialDataType === 'geo') {
+    return tileFeaturesGeometries({
+      tiles,
+      tileFormat,
+      spatialFilter,
+      uniqueIdProperty,
+      options,
+    });
+  }
+
+  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,122 @@
+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 metadataByBand: Record<string, RasterMetadataBand & {nodata: number}> =
+    {};
+  for (const band of options.rasterMetadata.bands) {
+    // TODO(cleanup): Remove copy and cast after API is updated to return 'nodata' as a number.
+    metadataByBand[band.name] = {...band, nodata: Number(band.nodata)};
+  }
+
+  // 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];
+        const bandMetadata = metadataByBand[band];
+
+        if (isValidBandValue(value, bandMetadata.nodata)) {
+          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;
+    }
+  );
+}
+
+/**
+ * Returns true if the given value is valid (not NaN, not 'nodata')
+ * for the given raster band.
+ */
+function isValidBandValue(value: unknown, nodata: number): value is number {
+  return Number.isNaN(value) ? false : nodata !== value;
+}

package/src/sources/raster-source.ts

@@ -3,6 +3,12 @@
 // Copyright (c) vis.gl contributors
 
 import {baseSource} from './base-source.js';
+import {getTileFormat} from '../utils/getTileFormat.js';
+import {
+  WidgetRasterSource,
+  WidgetRasterSourceResult,
+} from '../widget-sources/index.js';
+
 import type {
   FilterOptions,
   SourceOptions,
@@ -18,7 +24,7 @@ type UrlParameters = {
   filters?: Record<string, unknown>;
 };
 
-export type RasterSourceResponse = TilejsonResult;
+export type RasterSourceResponse = TilejsonResult & WidgetRasterSourceResult;
 
 export const rasterSource = async function (
   options: RasterSourceOptions
@@ -29,9 +35,16 @@ export const rasterSource = async function (
     urlParameters.filters = filters;
   }
 
-  return baseSource<UrlParameters>(
-    'raster',
-    options,
-    urlParameters
+  return baseSource<UrlParameters>('raster', options, urlParameters).then(
+    (result) => ({
+      ...(result as TilejsonResult),
+      widgetSource: new WidgetRasterSource({
+        ...options,
+        tileFormat: getTileFormat(result as TilejsonResult),
+        spatialDataColumn: 'quadbin',
+        spatialDataType: 'quadbin',
+        rasterMetadata: (result as TilejsonResult).raster_metadata!,
+      }),
+    })
   ) as Promise<RasterSourceResponse>;
 };

package/src/sources/types.ts

@@ -364,8 +364,20 @@ export enum RasterBandColorinterp {
   Palette = 'palette',
 }
 
+export type RasterBandType =
+  | 'uint8'
+  | 'int8'
+  | 'uint16'
+  | 'int16'
+  | 'uint32'
+  | 'int32'
+  | 'uint64'
+  | 'int64'
+  | 'float32'
+  | 'float64';
+
 export type RasterMetadataBand = {
-  type: string;
+  type: RasterBandType;
   name: string;
   stats: RasterMetadataBandStats;
   /**
@@ -379,7 +391,7 @@ export type RasterMetadataBand = {
   /**
    * Default color mapping for unique values (or if coloprinterp is `palette`)
    */
-  colortable?: Record<string, number[]>;
+  colortable?: Record<string, [number, number, number, number]>;
 
   /**
    * No value representation.

package/src/types.ts

@@ -28,8 +28,6 @@ export type Viewport = [number, number, number, number];
 export type Tile = {
   index: {x: number; y: number; z: number};
   id: string;
-  content: unknown;
-  zoom: number;
   bbox: {west: number; east: number; north: number; south: number};
   isVisible: boolean;
   data?: BinaryFeatureCollection;
@@ -40,6 +38,12 @@ export type SpatialIndexTile = Tile & {
   data?: (Feature & {id: bigint})[];
 };
 
+export type RasterTile = Tile & {
+  id: string;
+  index: {q: bigint; i: string};
+  data?: Raster;
+};
+
 /** @privateRemarks Source: @deck.gl/carto */
 export type Raster = {
   blockSize: number;

package/src/widget-sources/index.ts

@@ -1,5 +1,6 @@
 export * from './widget-source.js';
 export * from './widget-query-source.js';
+export * from './widget-raster-source.js';
 export * from './widget-remote-source.js';
 export * from './widget-table-source.js';
 export * from './widget-tileset-source.js';

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

@@ -0,0 +1,14 @@
+import {RasterMetadata} from '../sources/index.js';
+import {
+  WidgetTilesetSource,
+  WidgetTilesetSourceProps,
+} from './widget-tileset-source.js';
+
+export type WidgetRasterSourceProps = WidgetTilesetSourceProps & {
+  rasterMetadata: RasterMetadata;
+  spatialDataType: 'quadbin';
+};
+
+export type WidgetRasterSourceResult = {widgetSource: WidgetRasterSource};
+
+export class WidgetRasterSource extends WidgetTilesetSource<WidgetRasterSourceProps> {}

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

@@ -84,13 +84,10 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
     }
 
     this._features = tileFeatures({
-      tiles: this._tiles,
-      tileFormat: this.props.tileFormat,
+      ...this.props,
       ...this._tileFeatureExtractOptions,
-
+      tiles: this._tiles,
       spatialFilter,
-      spatialDataColumn: this.props.spatialDataColumn,
-      spatialDataType: this.props.spatialDataType,
     });
 
     prevInputs.spatialFilter = spatialFilter;
@@ -128,15 +125,6 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
     filterOwner,
     spatialFilter,
   }: FormulaRequestOptions): Promise<FormulaResponse> {
-    if (operation === 'custom') {
-      throw new Error('Custom aggregation not supported for tilesets');
-    }
-
-    // Column is required except when operation is 'count'.
-    if ((column && column !== '*') || operation !== 'count') {
-      assertColumn(this._features, column);
-    }
-
     const filteredFeatures = this._getFilteredFeatures(
       spatialFilter,
       filters,
@@ -147,6 +135,15 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
       return {value: null};
     }
 
+    if (operation === 'custom') {
+      throw new Error('Custom aggregation not supported for tilesets');
+    }
+
+    // Column is required except when operation is 'count'.
+    if ((column && column !== '*') || operation !== 'count') {
+      assertColumn(this._features, column);
+    }
+
     const targetOperation = aggregationFunctions[operation];
     return {
       value: targetOperation(filteredFeatures, column, joinOperation),
@@ -347,8 +344,6 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
     filterOwner,
     spatialFilter,
   }: RangeRequestOptions): Promise<RangeResponse> {
-    assertColumn(this._features, column);
-
     const filteredFeatures = this._getFilteredFeatures(
       spatialFilter,
       filters,
@@ -361,6 +356,8 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
       return null;
     }
 
+    assertColumn(this._features, column);
+
     return {
       min: aggregationFunctions.min(filteredFeatures, column),
       max: aggregationFunctions.max(filteredFeatures, column),

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

@@ -55,14 +55,16 @@ export type WidgetTilesetSourceResult = {widgetSource: WidgetTilesetSource};
  * const { widgetSource } = await data;
  * ```
  */
-export class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps> {
+export class WidgetTilesetSource<
+  Props extends WidgetTilesetSourceProps = WidgetTilesetSourceProps,
+> extends WidgetSource<Props> {
   protected _localImpl: WidgetTilesetSourceImpl | null = null;
 
   protected _workerImpl: Worker | null = null;
   protected _workerEnabled: boolean;
   protected _workerNextRequestId = 1;
 
-  constructor(props: WidgetTilesetSourceProps) {
+  constructor(props: Props) {
     super(props);
 
     this._workerEnabled =
@@ -145,10 +147,9 @@ export class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps>
     function onMessage(e: MessageEvent) {
       const response = e.data as WorkerResponse;
       if (response.requestId !== requestId) return;
+      if (signal?.aborted) return; // handled by 'abort' listener
 
-      if (signal?.aborted) {
-        reject!(new Error(signal.reason));
-      } else if (response.ok) {
+      if (response.ok) {
         resolve!(response.result as T);
       } else {
         reject!(new Error(response.error));
@@ -199,11 +200,22 @@ export class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps>
 
     const worker = this._getWorker();
 
-    tiles = (tiles as Tile[]).map(({id, bbox, data}) => ({
-      id,
-      bbox,
-      data,
-    }));
+    // We cannot pass an instance of Tile2DHeader to a Web Worker, and must
+    // extract properties required for widget calculations. Note that the
+    // `tile: Tile = {...}` assignment is structured so TS will warn if any
+    // types required by the internal 'Tile' type are missing.
+    tiles = (tiles as Tile[]).map(
+      ({id, index, bbox, isVisible, data}: Tile) => {
+        const tile: Tile = {
+          id,
+          index,
+          isVisible,
+          data,
+          bbox,
+        };
+        return tile;
+      }
+    );
 
     worker.postMessage({
       method: Method.LOAD_TILES,