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

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

@@ -1,16 +1,30 @@
-import {CompositeLayer, log} from '@deck.gl/core';
+import {CompositeLayer, Layer, log} from '@deck.gl/core';
 import CartoTileLayer from './carto-tile-layer';
+import H3TileLayer from './h3-tile-layer';
+import QuadkeyTileLayer from './quadkey-tile-layer';
 import {MVTLayer} from '@deck.gl/geo-layers';
 import {GeoJsonLayer} from '@deck.gl/layers';
 import {fetchLayerData, getDataV2, API_VERSIONS} from '../api';
 import {
   COLUMNS_SUPPORT,
+  Format,
   FORMATS,
   GEO_COLUMN_SUPPORT,
+  MapType,
   MAP_TYPES,
+  TileFormat,
   TILE_FORMATS
 } from '../api/maps-api-common';
-import {getDefaultCredentials} from '../config';
+import {
+  ClassicCredentials,
+  CloudNativeCredentials,
+  Credentials,
+  getDefaultCredentials
+} from '../config';
+import {CompositeLayerProps, LayerProps} from 'modules/core/src/types/layer-props';
+import {ChangeFlags} from 'modules/core/src/lib/layer-state';
+import {FetchLayerDataResult} from '../api/maps-v3-client';
+import {assert} from '../utils';
 
 const defaultProps = {
   // (String, required): data resource to load. table name, sql query or tileset name.
@@ -46,19 +60,105 @@ const defaultProps = {
   columns: {type: 'array', value: null}
 };
 
-export default class CartoLayer extends CompositeLayer {
-  initializeState() {
+export interface CartoLayerProps<DataT = any> extends CompositeLayerProps<DataT> {
+  /**
+   * Either a SQL query or a name of dataset/tileset.
+   */
+  data: string;
+
+  /**
+   * Data type.
+   *
+   * Possible values are:
+   *  * `MAP_TYPES.QUERY`, if data is a SQL query.
+   *  * `MAP_TYPES.TILESET`, if data is a tileset name.
+   *  * `MAP_TYPES.TABLE`, if data is a dataset name. Only supported with API v3.
+   */
+  type: MapType;
+
+  /**
+   * Name of the connection registered in the CARTO workspace.
+   *
+   * Required when apiVersion is `API_VERSIONS.V3`.
+   */
+  connection?: string;
+
+  /**
+   * Use to override the default data format.
+   *
+   * Only supported when apiVersion is `API_VERSIONS.V3`.
+   *
+   * Possible values are: `FORMATS.GEOJSON`, `FORMATS.JSON` and `FORMATS.TILEJSON`.
+   */
+  format?: Format;
+
+  /**
+   * Use to override the default tile data format.
+   *
+   * Only supported when apiVersion is `API_VERSIONS.V3` and format is `FORMATS.TILEJSON`.
+   *
+   * Possible values are: `TILE_FORMATS.BINARY`, `TILE_FORMATS.GEOJSON` and `TILE_FORMATS.MVT`.
+   */
+  formatTiles?: TileFormat;
+
+  /**
+   * Name of the geo_column in the CARTO platform.
+   *
+   * Use this override the default column (`'geom'`), from which the geometry information should be fetched.
+   *
+   * Only supported when apiVersion is `API_VERSIONS.V3` and type is `MAP_TYPES.TABLE`.
+   */
+  geoColumn?: string;
+
+  /**
+   * Names of columns to fetch.
+   *
+   * By default, all columns are fetched
+   *
+   * Only supported when apiVersion is `API_VERSIONS.V3` and type is `MAP_TYPES.TABLE`.
+   */
+  columns?: string[];
+
+  /**
+   * A string pointing to a unique attribute at the result of the query.
+   *
+   * A unique attribute is needed for highlighting with vector tiles when a feature is split across two or more tiles.
+   */
+  uniqueIdProperty?: string;
+
+  /**
+   * Optional. Overrides the configuration to connect with CARTO.
+   *
+   * @see Credentials
+   */
+  credentials?: Credentials;
+
+  /**
+   * Called when the request to the CARTO Maps API failed.
+   *
+   * By default the Error is thrown.
+   */
+  onDataError?: (err: unknown) => void;
+
+  clientId?: string;
+}
+
+export default class CartoLayer<DataT = any> extends CompositeLayer<CartoLayerProps<DataT>> {
+  static layerName = 'CartoLayer';
+  static defaultProps = defaultProps as any;
+
+  initializeState(): void {
     this.state = {
       data: null,
       apiVersion: null
     };
   }
 
-  get isLoaded() {
+  get isLoaded(): boolean {
     return this.getSubLayers().length > 0 && super.isLoaded;
   }
 
-  _checkProps(props) {
+  _checkProps(props: CartoLayerProps): void {
     const {type, credentials, connection, geoColumn, columns} = props;
     const localCreds = {...getDefaultCredentials(), ...credentials};
     const {apiVersion} = localCreds;
@@ -97,7 +197,16 @@ export default class CartoLayer extends CompositeLayer {
     }
   }
 
-  updateState({props, oldProps, changeFlags}) {
+  updateState({
+    props,
+    oldProps,
+    changeFlags
+  }: {
+    props: CartoLayerProps;
+    oldProps: CartoLayerProps;
+    context: any;
+    changeFlags: ChangeFlags;
+  }): void {
     this._checkProps(props);
     const shouldUpdateData =
       changeFlags.dataChanged ||
@@ -111,40 +220,57 @@ export default class CartoLayer extends CompositeLayer {
 
     if (shouldUpdateData) {
       this.setState({data: null, apiVersion: null});
+      // eslint-disable-next-line @typescript-eslint/no-floating-promises
       this._updateData();
     }
   }
 
-  async _updateData() {
+  async _updateData(): Promise<void> {
     try {
-      const {type, data: source, clientId, credentials, ...rest} = this.props;
+      const {type, data: source, clientId, credentials, connection, ...rest} = this.props;
       const localConfig = {...getDefaultCredentials(), ...credentials};
       const {apiVersion} = localConfig;
 
-      let result;
+      let result: FetchLayerDataResult;
       if (apiVersion === API_VERSIONS.V1 || apiVersion === API_VERSIONS.V2) {
-        result = {data: await getDataV2({type, source, credentials})};
+        result = {
+          data: await getDataV2({type, source, credentials: credentials as ClassicCredentials})
+        };
       } else {
-        result = await fetchLayerData({type, source, clientId, credentials, ...rest});
+        result = await fetchLayerData({
+          type,
+          source,
+          clientId,
+          credentials: credentials as CloudNativeCredentials,
+          connection,
+          ...rest
+        });
       }
 
       this.setState({...result, apiVersion});
-      this.props.onDataLoad(result.data);
+
+      this.props.onDataLoad?.(result.data, {
+        propName: 'data',
+        layer: this
+      });
     } catch (err) {
       if (this.props.onDataError) {
-        this.props.onDataError(err);
+        this.props.onDataError(err as Error);
       } else {
         throw err;
       }
     }
   }
 
-  _getSubLayerAndProps() {
+  _getSubLayerAndProps(): [any, LayerProps] {
+    assert(this.state);
+
     const {data, format, apiVersion} = this.state;
 
     const {uniqueIdProperty} = defaultProps;
-    const props = {uniqueIdProperty, ...this.props};
-    delete props.data;
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const {data: _notUsed, ...propsNoData} = this.props;
+    const props = {uniqueIdProperty, ...propsNoData};
 
     if (apiVersion === API_VERSIONS.V1 || apiVersion === API_VERSIONS.V2) {
       return [MVTLayer, props];
@@ -155,8 +281,16 @@ export default class CartoLayer extends CompositeLayer {
       const tileUrl = new URL(data.tiles[0]);
 
       props.formatTiles =
-        props.formatTiles || tileUrl.searchParams.get('formatTiles') || TILE_FORMATS.MVT;
+        props.formatTiles ||
+        (tileUrl.searchParams.get('formatTiles') as TileFormat) ||
+        TILE_FORMATS.MVT;
 
+      if (data.scheme === 'h3') {
+        return [H3TileLayer, props];
+      }
+      if (data.scheme === 'quadkey') {
+        return [QuadkeyTileLayer, props];
+      }
       return props.formatTiles === TILE_FORMATS.MVT ? [MVTLayer, props] : [CartoTileLayer, props];
     }
 
@@ -164,7 +298,9 @@ export default class CartoLayer extends CompositeLayer {
     return [GeoJsonLayer, props];
   }
 
-  renderLayers() {
+  renderLayers(): Layer | null {
+    assert(this.state);
+
     const {data} = this.state;
 
     if (!data) return null;
@@ -184,6 +320,3 @@ export default class CartoLayer extends CompositeLayer {
     );
   }
 }
-
-CartoLayer.layerName = 'CartoLayer';
-CartoLayer.defaultProps = defaultProps;

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

@@ -0,0 +1,44 @@
+import {CompositeLayer} from '@deck.gl/core';
+import {H3HexagonLayer, TileLayer} from '@deck.gl/geo-layers';
+import H3Tileset2D from './h3-tileset-2d';
+
+const renderSubLayers = props => {
+  const {data} = props;
+  const {index} = props.tile;
+  if (!data || !data.length) return null;
+
+  return new H3HexagonLayer(props, {
+    centerHexagon: index,
+    highPrecision: true
+  });
+};
+
+export default class H3TileLayer extends CompositeLayer {
+  initializeState() {
+    this.setState({data: null, tileJSON: null});
+  }
+
+  updateState({props, oldProps, context, changeFlags}) {
+    if (changeFlags.dataChanged) {
+      let {data} = this.props;
+      const tileJSON = data;
+      data = tileJSON.tiles;
+      this.setState({data, tileJSON});
+    }
+  }
+
+  renderLayers() {
+    const {data} = this.state;
+    return [
+      new TileLayer(this.props, {
+        id: 'h3-tile-layer',
+        data,
+        getHexagon: d => d.id,
+        TilesetClass: H3Tileset2D,
+        renderSubLayers
+      })
+    ];
+  }
+}
+
+H3TileLayer.layerName = 'H3TileLayer';

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

@@ -0,0 +1,82 @@
+import {_Tileset2D as Tileset2D} from '@deck.gl/geo-layers';
+import {polyfill, getRes0Indexes, h3GetResolution, h3ToGeoBoundary, h3ToParent} from 'h3-js';
+
+export function getHexagonsInBoundingBox({west, north, east, south}, resolution) {
+  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 = 1;
+  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;
+}
+
+export function tileToBoundingBox(index) {
+  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};
+}
+
+export default class H3Tileset2D extends Tileset2D {
+  getTileIndices({viewport, minZoom, maxZoom}) {
+    const [east, south, west, north] = viewport.getBounds();
+
+    // TODO ignores extent
+    let z = viewport.zoom;
+    if (typeof minZoom === 'number' && Number.isFinite(minZoom) && z < minZoom) {
+      z = minZoom;
+    }
+    if (typeof maxZoom === 'number' && Number.isFinite(maxZoom) && z > maxZoom) {
+      z = maxZoom;
+    }
+
+    // Heuristic to get h3 resolution
+    const resolution = Math.max(0, Math.floor((2 * z) / 3) - 2);
+    return getHexagonsInBoundingBox({west, north, east, south}, resolution).map(i => ({i}));
+  }
+
+  getTileId({i}) {
+    return i;
+  }
+
+  getTileMetadata({i}) {
+    return {bbox: tileToBoundingBox(i)};
+  }
+
+  getTileZoom({i}) {
+    return h3GetResolution(i);
+  }
+
+  getParentIndex(index) {
+    const resolution = h3GetResolution(index.i);
+    const i = h3ToParent(index.i, resolution - 1);
+    return {i};
+  }
+}

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

@@ -0,0 +1,42 @@
+import {CompositeLayer} from '@deck.gl/core';
+import {QuadkeyLayer, TileLayer} from '@deck.gl/geo-layers';
+import QuadkeyTileset2D from './quadkey-tileset-2d';
+
+const renderSubLayers = props => {
+  const {data} = props;
+  if (!data || !data.length) return null;
+  return new QuadkeyLayer(props);
+};
+
+export default class QuadkeyTileLayer extends CompositeLayer {
+  initializeState() {
+    this.setState({data: null, tileJSON: null});
+  }
+
+  updateState({props, oldProps, context, changeFlags}) {
+    if (changeFlags.dataChanged) {
+      let {data} = this.props;
+      const tileJSON = data;
+      data = tileJSON.tiles;
+      this.setState({data, tileJSON});
+    }
+  }
+
+  renderLayers() {
+    const {data, tileJSON} = this.state;
+    const {maxresolution} = tileJSON;
+    const maxZoom = maxresolution - this.props.aggregationResLevel;
+    return [
+      new TileLayer(this.props, {
+        id: 'quadkey-tile-layer',
+        data,
+        getQuadkey: d => d.id,
+        TilesetClass: QuadkeyTileset2D,
+        renderSubLayers,
+        maxZoom
+      })
+    ];
+  }
+}
+
+QuadkeyTileLayer.layerName = 'QuadkeyTileLayer';

package/src/layers/quadkey-tileset-2d.js

@@ -0,0 +1,36 @@
+import {_Tileset2D as Tileset2D} from '@deck.gl/geo-layers';
+
+function tileToQuadkey(tile) {
+  let index = '';
+  for (let z = tile.z; z > 0; z--) {
+    let b = 0;
+    const mask = 1 << (z - 1);
+    if ((tile.x & mask) !== 0) b++;
+    if ((tile.y & mask) !== 0) b += 2;
+    index += b.toString();
+  }
+  return {i: index};
+}
+
+export default class QuadkeyTileset2D extends Tileset2D {
+  getTileIndices(opts) {
+    return super.getTileIndices(opts).map(tileToQuadkey);
+  }
+
+  getTileId({i}) {
+    return i;
+  }
+
+  getTileMetadata() {
+    return {};
+  }
+
+  getTileZoom({i}) {
+    return i.length;
+  }
+
+  getParentIndex(index) {
+    const i = index.i.slice(0, -1);
+    return {i};
+  }
+}