@deck.gl/carto 8.8.0-alpha.3 → 8.8.0-alpha.6

package/package.json

@@ -2,7 +2,7 @@
   "name": "@deck.gl/carto",
   "description": "CARTO official integration with Deck.gl. Build geospatial applications using CARTO and Deck.gl.",
   "license": "MIT",
-  "version": "8.8.0-alpha.3",
+  "version": "8.8.0-alpha.6",
   "publishConfig": {
     "access": "public"
   },
@@ -23,6 +23,7 @@
   "files": [
     "dist",
     "src",
+    "typed",
     "dist.min.js"
   ],
   "sideEffects": false,
@@ -35,17 +36,19 @@
     "@loaders.gl/loader-utils": "^3.2.0-alpha.4",
     "@loaders.gl/mvt": "^3.2.0-alpha.4",
     "@loaders.gl/tiles": "^3.2.0-alpha.4",
-    "@luma.gl/constants": "^8.5.10",
-    "@math.gl/web-mercator": "3.6.0-alpha.5",
+    "@luma.gl/constants": "^8.5.13",
+    "@math.gl/web-mercator": "3.6.0-alpha.8",
     "cartocolor": "^4.0.2",
     "d3-array": "^2.8.0",
     "d3-color": "^2.0.0",
     "d3-format": "^2.0.0",
     "d3-scale": "^3.2.3",
+    "h3-js": "^3.6.0",
     "moment-timezone": "^0.5.33",
     "pbf": "^3.2.1"
   },
   "devDependencies": {
+    "@loaders.gl/schema": "^3.2.0-alpha.4",
     "@types/d3-array": "^3.0.2",
     "@types/d3-color": "^1.4.2",
     "@types/d3-scale": "^3.0.0"
@@ -58,5 +61,5 @@
     "@deck.gl/layers": "^8.0.0",
     "@loaders.gl/core": "^3.0.0"
   },
-  "gitHead": "edad7cf75b75a137d63ec89d2d644727d3082e25"
+  "gitHead": "6885ccab01c91a7632385f566c9377f8ae387e7c"
 }

package/src/api/layer-map.ts

@@ -13,6 +13,7 @@ import {
 import {format as d3Format} from 'd3-format';
 import moment from 'moment-timezone';
 
+import {Layer, _ConstructorOf as ConstructorOf} from '@deck.gl/core';
 import {CPUGridLayer, HeatmapLayer, HexagonLayer} from '@deck.gl/aggregation-layers';
 import {GeoJsonLayer} from '@deck.gl/layers';
 import {H3HexagonLayer, MVTLayer} from '@deck.gl/geo-layers';
@@ -101,7 +102,7 @@ const defaultProps = {
   wrapLongitude: false
 };
 
-function mergePropMaps(a = {}, b = {}) {
+function mergePropMaps(a: Record<string, any> = {}, b: Record<string, any> = {}) {
   return {...a, ...b, visConfig: {...a.visConfig, ...b.visConfig}};
 }
 
@@ -109,7 +110,7 @@ export function getLayer(
   type: string,
   config,
   dataset
-): {Layer: any; propMap: any; defaultProps: any} {
+): {Layer: ConstructorOf<Layer>; propMap: any; defaultProps: any} {
   if (type === 'mvt' || type === 'tileset') {
     return getTileLayer(dataset);
   }
@@ -118,7 +119,11 @@ export function getLayer(
   const getPosition = d => d[geoColumn].coordinates;
 
   const hexagonId = config.columns?.hex_id;
-  const layer = {
+
+  const layerTypeDefs: Record<
+    string,
+    {Layer: ConstructorOf<Layer>; propMap?: any; defaultProps?: any}
+  > = {
     point: {
       Layer: GeoJsonLayer,
       propMap: {visConfig: {outline: 'stroked'}}
@@ -146,12 +151,16 @@ export function getLayer(
       propMap: {visConfig: {coverage: 'coverage'}},
       defaultProps: {getHexagon: d => d[hexagonId], stroked: false}
     }
-  }[type];
+  };
+
+  const layer = layerTypeDefs[type];
 
   assert(layer, `Unsupported layer type: ${type}`);
-  layer.propMap = mergePropMaps(sharedPropMap, layer.propMap);
-  layer.defaultProps = {...defaultProps, ...layer.defaultProps};
-  return layer;
+  return {
+    ...layer,
+    propMap: mergePropMaps(sharedPropMap, layer.propMap),
+    defaultProps: {...defaultProps, ...layer.defaultProps}
+  };
 }
 
 function getTileLayer(dataset) {

package/src/layers/carto-layer.ts

@@ -57,10 +57,20 @@ const defaultProps = {
   geoColumn: null,
 
   // (Array<String>, optional): names of columns to fetch. By default, all columns are fetched.
-  columns: {type: 'array', value: null}
+  columns: {type: 'array', value: null},
+
+  // (String, optional): aggregration SQL expression. Only used for spatial index datasets
+  aggregationExp: null,
+
+  // (Number, optional): aggregration resolution level. Only used for spatial index datasets, defaults to 6 for quadkeys, 4 for h3
+  aggregationResLevel: null
 };
 
-export interface CartoLayerProps<DataT = any> extends CompositeLayerProps<DataT> {
+/** All properties supported by CartoLayer. */
+export type CartoLayerProps<DataT = any> = _CartoLayerProps & CompositeLayerProps<DataT>;
+
+/** Properties added by CartoLayer. */
+type _CartoLayerProps = {
   /**
    * Either a SQL query or a name of dataset/tileset.
    */
@@ -141,9 +151,11 @@ export interface CartoLayerProps<DataT = any> extends CompositeLayerProps<DataT>
   onDataError?: (err: unknown) => void;
 
   clientId?: string;
-}
+};
 
-export default class CartoLayer<DataT = any> extends CompositeLayer<CartoLayerProps<DataT>> {
+export default class CartoLayer<ExtraProps = {}> extends CompositeLayer<
+  Required<_CartoLayerProps> & ExtraProps
+> {
   static layerName = 'CartoLayer';
   static defaultProps = defaultProps as any;
 
@@ -231,7 +243,7 @@ export default class CartoLayer<DataT = any> extends CompositeLayer<CartoLayerPr
       const localConfig = {...getDefaultCredentials(), ...credentials};
       const {apiVersion} = localConfig;
 
-      let result: FetchLayerDataResult;
+      let result: Partial<FetchLayerDataResult>;
       if (apiVersion === API_VERSIONS.V1 || apiVersion === API_VERSIONS.V2) {
         result = {
           data: await getDataV2({type, source, credentials: credentials as ClassicCredentials})
@@ -270,6 +282,7 @@ export default class CartoLayer<DataT = any> extends CompositeLayer<CartoLayerPr
     const {uniqueIdProperty} = defaultProps;
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     const {data: _notUsed, ...propsNoData} = this.props;
+    // @ts-expect-error 'uniqueIdProperty' is specified more than once, so this usage will be overwritten.
     const props = {uniqueIdProperty, ...propsNoData};
 
     if (apiVersion === API_VERSIONS.V1 || apiVersion === API_VERSIONS.V2) {

package/src/layers/{carto-tile-layer.js → carto-tile-layer.ts}

@@ -2,28 +2,38 @@
 import Protobuf from 'pbf';
 import {log} from '@deck.gl/core';
 import {ClipExtension} from '@deck.gl/extensions';
-import {MVTLayer, _getURLFromTemplate} from '@deck.gl/geo-layers';
+import {
+  MVTLayer,
+  MVTLayerProps,
+  TileLayer,
+  _getURLFromTemplate,
+  _Tile2DHeader,
+  _TileLoadProps as TileLoadProps
+} from '@deck.gl/geo-layers';
 import {GeoJsonLayer} from '@deck.gl/layers';
 import {geojsonToBinary} from '@loaders.gl/gis';
-import {Tile} from './schema/carto-tile';
-import {TILE_FORMATS} from '../api/maps-api-common';
+import {Properties, Tile, TileReader} from './schema/carto-tile';
+import {TileFormat, TILE_FORMATS} from '../api/maps-api-common';
+import {LoaderOptions, LoaderWithParser} from '@loaders.gl/loader-utils';
+import type {BinaryFeatures} from '@loaders.gl/schema';
+import type {Feature} from 'geojson';
 
-function parseJSON(arrayBuffer) {
+function parseJSON(arrayBuffer: ArrayBuffer): any {
   return JSON.parse(new TextDecoder().decode(arrayBuffer));
 }
 
-function parsePbf(buffer) {
+function parsePbf(buffer: ArrayBuffer): Tile {
   const pbf = new Protobuf(buffer);
-  const tile = Tile.read(pbf);
+  const tile = TileReader.read(pbf);
   return tile;
 }
 
-function unpackProperties(properties) {
+function unpackProperties(properties: Properties[]) {
   if (!properties || !properties.length) {
     return [];
   }
   return properties.map(item => {
-    const currentRecord = {};
+    const currentRecord: Record<string, unknown> = {};
     item.data.forEach(({key, value}) => {
       currentRecord[key] = value;
     });
@@ -31,7 +41,7 @@ function unpackProperties(properties) {
   });
 }
 
-function parseCartoTile(arrayBuffer, options) {
+function parseCartoTile(arrayBuffer: ArrayBuffer, options?: LoaderOptions): BinaryFeatures | null {
   if (!arrayBuffer) return null;
   const formatTiles = options && options.cartoTile && options.cartoTile.formatTiles;
   if (formatTiles === TILE_FORMATS.GEOJSON) return geojsonToBinary(parseJSON(arrayBuffer).features);
@@ -45,13 +55,15 @@ function parseCartoTile(arrayBuffer, options) {
     polygons: {...polygons, properties: unpackProperties(polygons.properties)}
   };
 
-  return data;
+  // Note: there is slight, difference in `numericProps` type, however geojson/mvtlayer can cope with this
+  return data as unknown as BinaryFeatures;
 }
 
 const defaultTileFormat = TILE_FORMATS.BINARY;
 
-const CartoTileLoader = {
+const CartoTileLoader: LoaderWithParser = {
   name: 'CARTO Tile',
+  version: '1',
   id: 'cartoTile',
   module: 'carto',
   extensions: ['pbf'],
@@ -73,8 +85,29 @@ const defaultProps = {
   loaders: [CartoTileLoader]
 };
 
-export default class CartoTileLayer extends MVTLayer {
-  getTileData(tile) {
+/** All properties supported by CartoTileLayer. */
+export type CartoTileLayerProps<DataT extends Feature = Feature> = _CartoTileLayerProps &
+  MVTLayerProps<DataT>;
+
+/** Properties added by CartoTileLayer. */
+type _CartoTileLayerProps = {
+  /** Use to override the default tile data format.
+   *
+   * Possible values are: `TILE_FORMATS.BINARY`, `TILE_FORMATS.GEOJSON` and `TILE_FORMATS.MVT`.
+   *
+   * Only supported when `apiVersion` is `API_VERSIONS.V3` and `format` is `FORMATS.TILEJSON`.
+   */
+  formatTiles?: TileFormat;
+};
+
+export default class CartoTileLayer<
+  DataT extends Feature = Feature,
+  ExtraProps = {}
+> extends MVTLayer<DataT, Required<_CartoTileLayerProps> & ExtraProps> {
+  static layerName = 'CartoTileLayer';
+  static defaultProps = defaultProps;
+
+  getTileData(tile: TileLoadProps) {
     const url = _getURLFromTemplate(this.state.data, tile);
     if (!url) {
       return Promise.reject('Invalid URL');
@@ -100,25 +133,29 @@ export default class CartoTileLayer extends MVTLayer {
     return fetch(url, {propName: 'data', layer: this, loadOptions, signal});
   }
 
-  renderSubLayers(props) {
+  renderSubLayers(
+    props: TileLayer['props'] & {
+      id: string;
+      data: any;
+      _offset: number;
+      tile: _Tile2DHeader;
+    }
+  ): GeoJsonLayer | null {
     if (props.data === null) {
       return null;
     }
 
-    props.autoHighlight = false;
+    const tileBbox = props.tile.bbox as any;
+    const {west, south, east, north} = tileBbox;
 
-    const {
-      bbox: {west, south, east, north}
-    } = props.tile;
-    props.extensions = [new ClipExtension(), ...(props.extensions || [])];
-    props.clipBounds = [west, south, east, north];
+    const subLayerProps = {
+      ...props,
+      autoHighlight: false,
+      extensions: [new ClipExtension(), ...(props.extensions || [])],
+      clipBounds: [west, south, east, north]
+    };
 
-    const subLayer = new GeoJsonLayer({
-      ...props
-    });
+    const subLayer = new GeoJsonLayer(subLayerProps);
     return subLayer;
   }
 }
-
-CartoTileLayer.layerName = 'CartoTileLayer';
-CartoTileLayer.defaultProps = defaultProps;

package/src/layers/h3-tile-layer.ts

@@ -0,0 +1,78 @@
+import {
+  CompositeLayer,
+  CompositeLayerProps,
+  Layer,
+  LayersList,
+  UpdateParameters
+} from '@deck.gl/core';
+import {H3HexagonLayer} from '@deck.gl/geo-layers';
+import H3Tileset2D from './h3-tileset-2d';
+import SpatialIndexTileLayer from './spatial-index-tile-layer';
+
+const renderSubLayers = props => {
+  const {data} = props;
+  const {index} = props.tile;
+  if (!data || !data.length) return null;
+
+  return new H3HexagonLayer(props, {
+    getHexagon: d => d.id,
+    centerHexagon: index,
+    highPrecision: true
+  });
+};
+
+const defaultProps = {
+  aggregationResLevel: 4
+};
+
+/** All properties supported by H3TileLayer. */
+export type H3TileLayerProps<DataT = any> = _H3TileLayerProps<DataT> & CompositeLayerProps<DataT>;
+
+// TODO: use type from h3-hexagon-layer when available
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type H3HexagonLayerProps<DataT = any> = Record<string, any>;
+
+/** Properties added by H3TileLayer. */
+type _H3TileLayerProps<DataT = any> = H3HexagonLayerProps<DataT> & {
+  aggregationResLevel?: number;
+};
+
+export default class H3TileLayer<DataT = any, ExtraPropsT = {}> extends CompositeLayer<
+  ExtraPropsT & Required<_H3TileLayerProps<DataT>>
+> {
+  static layerName = 'H3TileLayer';
+  static defaultProps = defaultProps;
+
+  state!: {
+    tileJSON: any;
+    data: any;
+  };
+
+  initializeState(): void {
+    this.setState({data: null, tileJSON: null});
+  }
+
+  updateState({changeFlags}: UpdateParameters<this>): void {
+    if (changeFlags.dataChanged) {
+      let {data} = this.props;
+      const tileJSON = data;
+      data = (tileJSON as any).tiles;
+      this.setState({data, tileJSON});
+    }
+  }
+
+  renderLayers(): Layer | null | LayersList {
+    const {data, tileJSON} = this.state;
+    const maxZoom = parseInt(tileJSON.maxresolution);
+    return [
+      new SpatialIndexTileLayer(this.props, {
+        id: `h3-tile-layer-${this.props.id}`,
+        data,
+        // @ts-expect-error Tileset2D should be generic over TileIndex
+        TilesetClass: H3Tileset2D,
+        renderSubLayers,
+        maxZoom
+      })
+    ];
+  }
+}

package/src/layers/h3-tileset-2d.ts

@@ -0,0 +1,118 @@
+import {_Tileset2D as Tileset2D, GeoBoundingBox} from '@deck.gl/geo-layers';
+import {
+  polyfill,
+  getRes0Indexes,
+  geoToH3,
+  h3GetResolution,
+  h3ToGeoBoundary,
+  h3ToParent,
+  kRing
+} from 'h3-js';
+
+export type H3TileIndex = {i: string};
+
+function getHexagonsInBoundingBox(
+  {west, north, east, south}: GeoBoundingBox,
+  resolution: number
+): string[] {
+  if (resolution === 0) {
+    return getRes0Indexes();
+  }
+  if (east - west > 180) {
+    // This is a known issue in h3-js: polyfill does not work correctly
+    // when longitude span is larger than 180 degrees.
+    return getHexagonsInBoundingBox({west, north, east: 0, south}, resolution).concat(
+      getHexagonsInBoundingBox({west: 0, north, east, south}, resolution)
+    );
+  }
+
+  // `polyfill()` fills based on hexagon center, which means tiles vanish
+  // prematurely. Get more accurate coverage by oversampling
+  const oversample = 2;
+  const h3Indices = polyfill(
+    [
+      [
+        [west, north],
+        [west, south],
+        [east, south],
+        [east, north],
+        [west, north]
+      ]
+    ],
+    resolution + oversample,
+    true
+  );
+
+  return oversample ? [...new Set(h3Indices.map(i => h3ToParent(i, resolution)))] : h3Indices;
+}
+
+function tileToBoundingBox(index: string): GeoBoundingBox {
+  const coordinates = h3ToGeoBoundary(index);
+  const latitudes = coordinates.map(c => c[0]);
+  const longitudes = coordinates.map(c => c[1]);
+  const west = Math.min(...longitudes);
+  const south = Math.min(...latitudes);
+  const east = Math.max(...longitudes);
+  const north = Math.max(...latitudes);
+  return {west, south, east, north};
+}
+
+// Resolution conversion function. Takes a WebMercatorViewport and returns
+// a H3 resolution such that the screen space size of the hexagons is
+// similar
+// Relative scale factor (0 = no biasing, 2 = a few hexagons cover view)
+const BIAS = 2;
+function getHexagonResolution(viewport): number {
+  const hexagonScaleFactor = (2 / 3) * viewport.zoom;
+  const latitudeScaleFactor = Math.log(1 / Math.cos((Math.PI * viewport.latitude) / 180));
+
+  // Clip and bias
+  return Math.max(0, Math.floor(hexagonScaleFactor + latitudeScaleFactor - BIAS));
+}
+
+export default class H3Tileset2D extends Tileset2D {
+  // @ts-expect-error Tileset2D should be generic over TileIndex
+  getTileIndices({viewport, minZoom, maxZoom}): H3TileIndex[] {
+    const [east, south, west, north] = viewport.getBounds();
+
+    let z = getHexagonResolution(viewport);
+    let indices: string[];
+    if (typeof minZoom === 'number' && Number.isFinite(minZoom) && z < minZoom) {
+      z = minZoom;
+    }
+    if (typeof maxZoom === 'number' && Number.isFinite(maxZoom) && z > maxZoom) {
+      z = maxZoom;
+
+      // Once we are at max zoom, getHexagonsInBoundingBox doesn't work, simply
+      // get a ring centered on the hexagon in the viewport center
+      const center = geoToH3(viewport.latitude, viewport.longitude, maxZoom);
+      indices = kRing(center, 1);
+    } else {
+      indices = getHexagonsInBoundingBox({west, north, east, south}, z);
+    }
+
+    return indices.map(i => ({i}));
+  }
+
+  // @ts-expect-error Tileset2D should be generic over TileIndex
+  getTileId({i}: H3TileIndex): string {
+    return i;
+  }
+
+  // @ts-expect-error Tileset2D should be generic over TileIndex
+  getTileMetadata({i}: H3TileIndex) {
+    return {bbox: tileToBoundingBox(i)};
+  }
+
+  // @ts-expect-error Tileset2D should be generic over TileIndex
+  getTileZoom({i}: H3TileIndex): number {
+    return h3GetResolution(i);
+  }
+
+  // @ts-expect-error Tileset2D should be generic over TileIndex
+  getParentIndex(index: H3TileIndex): H3TileIndex {
+    const resolution = h3GetResolution(index.i);
+    const i = h3ToParent(index.i, resolution - 1);
+    return {i};
+  }
+}

package/src/layers/quadkey-tile-layer.ts

@@ -0,0 +1,68 @@
+import {
+  CompositeLayer,
+  CompositeLayerProps,
+  Layer,
+  LayersList,
+  UpdateParameters
+} from '@deck.gl/core';
+import {QuadkeyLayer, QuadkeyLayerProps} from '@deck.gl/geo-layers';
+import QuadkeyTileset2D from './quadkey-tileset-2d';
+import SpatialIndexTileLayer from './spatial-index-tile-layer';
+
+const renderSubLayers = props => {
+  const {data} = props;
+  if (!data || !data.length) return null;
+  return new QuadkeyLayer(props, {getQuadkey: d => d.id});
+};
+
+const defaultProps = {
+  aggregationResLevel: 6
+};
+
+/** All properties supported by QuadkeyTileLayer. */
+export type QuadkeyTileLayerProps<DataT = any> = _QuadkeyTileLayerProps<DataT> &
+  CompositeLayerProps<DataT>;
+
+/** Properties added by QuadkeyTileLayer. */
+type _QuadkeyTileLayerProps<DataT> = QuadkeyLayerProps<DataT> & {
+  aggregationResLevel?: number;
+};
+
+export default class QuadkeyTileLayer<DataT = any, ExtraProps = {}> extends CompositeLayer<
+  ExtraProps & Required<_QuadkeyTileLayerProps<DataT>>
+> {
+  static layerName = 'QuadkeyTileLayer';
+  static defaultProps = defaultProps;
+
+  state!: {
+    tileJSON: any;
+    data: any;
+  };
+  initializeState(): void {
+    this.setState({data: null, tileJSON: null});
+  }
+
+  updateState({changeFlags}: UpdateParameters<this>): void {
+    if (changeFlags.dataChanged) {
+      let {data} = this.props;
+      const tileJSON = data;
+      data = (tileJSON as any).tiles;
+      this.setState({data, tileJSON});
+    }
+  }
+
+  renderLayers(): Layer | null | LayersList {
+    const {data, tileJSON} = this.state;
+    const maxZoom = parseInt(tileJSON?.maxresolution);
+    return [
+      new SpatialIndexTileLayer(this.props, {
+        id: `quadkey-tile-layer-${this.props.id}`,
+        data,
+        // TODO: Tileset2D should be generic over TileIndex type
+        TilesetClass: QuadkeyTileset2D as any,
+        renderSubLayers,
+        maxZoom
+      })
+    ];
+  }
+}

package/src/layers/{quadkey-tileset-2d.js → quadkey-tileset-2d.ts}

@@ -1,6 +1,7 @@
 import {_Tileset2D as Tileset2D} from '@deck.gl/geo-layers';
 
-function tileToQuadkey(tile) {
+type QuadkeyTileIndex = {i: string};
+function tileToQuadkey(tile): QuadkeyTileIndex {
   let index = '';
   for (let z = tile.z; z > 0; z--) {
     let b = 0;
@@ -13,11 +14,13 @@ function tileToQuadkey(tile) {
 }
 
 export default class QuadkeyTileset2D extends Tileset2D {
-  getTileIndices(opts) {
+  // @ts-expect-error for spatial indices, TileSet2d should be parametrized by TileIndexT
+  getTileIndices(opts): QuadkeyTileIndex[] {
     return super.getTileIndices(opts).map(tileToQuadkey);
   }
 
-  getTileId({i}) {
+  // @ts-expect-error TileIndex must be generic
+  getTileId({i}: QuadkeyTileIndex) {
     return i;
   }
 
@@ -25,11 +28,13 @@ export default class QuadkeyTileset2D extends Tileset2D {
     return {};
   }
 
-  getTileZoom({i}) {
+  // @ts-expect-error TileIndex must be generic
+  getTileZoom({i}: QuadkeyTileIndex) {
     return i.length;
   }
 
-  getParentIndex(index) {
+  // @ts-expect-error TileIndex must be generic
+  getParentIndex(index: QuadkeyTileIndex) {
     const i = index.i.slice(0, -1);
     return {i};
   }