@deck.gl/carto 9.0.0-beta.1 → 9.0.0-beta.11

package/src/layers/schema/carto-raster-tile.ts

@@ -36,11 +36,10 @@ export class BandReader {
 
 export class TileReader {
   static read(pbf, end) {
-    return pbf.readFields(TileReader._readField, {blockWidth: 0, blockHeight: 0, bands: []}, end);
+    return pbf.readFields(TileReader._readField, {blockSize: 0, bands: []}, end);
   }
   static _readField(this: void, tag, obj, pbf) {
-    if (tag === 1) obj.blockWidth = pbf.readVarint();
-    else if (tag === 2) obj.blockHeight = pbf.readVarint();
-    else if (tag === 3) obj.bands.push(BandReader.read(pbf, pbf.readVarint() + pbf.pos));
+    if (tag === 1) obj.blockSize = pbf.readVarint();
+    else if (tag === 2) obj.bands.push(BandReader.read(pbf, pbf.readVarint() + pbf.pos));
   }
 }

package/src/layers/spatial-index-tile-layer.ts

@@ -6,12 +6,15 @@ registerLoaders([CartoRasterTileLoader, CartoSpatialTileLoader]);
 
 import {PickingInfo} from '@deck.gl/core';
 import {TileLayer, _Tile2DHeader as Tile2DHeader, TileLayerProps} from '@deck.gl/geo-layers';
+import {DEFAULT_TILE_SIZE} from '../constants';
 
 function isFeatureIdDefined(value: unknown): boolean {
   return value !== undefined && value !== null && value !== '';
 }
 
-const defaultProps: DefaultProps<SpatialIndexTileLayerProps> = {};
+const defaultProps: DefaultProps<SpatialIndexTileLayerProps> = {
+  tileSize: DEFAULT_TILE_SIZE
+};
 
 /** All properties supported by SpatialIndexTileLayer. */
 export type SpatialIndexTileLayerProps<DataT = unknown> = _SpatialIndexTileLayerProps &
@@ -28,14 +31,14 @@ export default class SpatialIndexTileLayer<
   static defaultProps = defaultProps;
 
   state!: TileLayer<DataT>['state'] & {
-    hoveredFeatureId: number | null;
+    hoveredFeatureId: BigInt | number | null;
     highlightColor: number[];
   };
 
   protected _updateAutoHighlight(info: PickingInfo): void {
     const {hoveredFeatureId} = this.state;
     const hoveredFeature = info.object;
-    let newHoveredFeatureId;
+    let newHoveredFeatureId: BigInt | number | null = null;
 
     if (hoveredFeature) {
       newHoveredFeatureId = hoveredFeature.id;
@@ -79,6 +82,7 @@ export default class SpatialIndexTileLayer<
   }
 
   _featureInTile(tile: Tile2DHeader, featureId: BigInt | number) {
+    // TODO: Tile2DHeader index should be generic for H3TileIndex or QuadbinTileIndex
     const tileset = this.state.tileset!;
     const tileZoom = tileset.getTileZoom(tile.index);
     // @ts-ignore

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

@@ -16,30 +16,33 @@ import {
 import {GeoJsonLayer} from '@deck.gl/layers';
 import {binaryToGeojson} from '@loaders.gl/gis';
 import type {BinaryFeatureCollection} from '@loaders.gl/schema';
-import type {Feature} from 'geojson';
+import type {Feature, Geometry} from 'geojson';
 
 import type {TilejsonResult} from '../sources/types';
 import {TilejsonPropType, injectAccessToken, mergeBoundaryData} from './utils';
+import {DEFAULT_TILE_SIZE} from '../constants';
 
 const defaultProps: DefaultProps<VectorTileLayerProps> = {
   ...MVTLayer.defaultProps,
   data: TilejsonPropType,
-  dataComparator: TilejsonPropType.equal
+  dataComparator: TilejsonPropType.equal,
+  tileSize: DEFAULT_TILE_SIZE
 };
 
 /** All properties supported by VectorTileLayer. */
-export type VectorTileLayerProps = _VectorTileLayerProps & Omit<MVTLayerProps, 'data'>;
+export type VectorTileLayerProps<FeaturePropertiesT = unknown> = _VectorTileLayerProps &
+  Omit<MVTLayerProps<FeaturePropertiesT>, 'data'>;
 
 /** Properties added by VectorTileLayer. */
 type _VectorTileLayerProps = {
   data: null | TilejsonResult | Promise<TilejsonResult>;
 };
 
-// TODO Perhaps we can't subclass MVTLayer and keep types. Better to subclass TileLayer instead?
 // @ts-ignore
-export default class VectorTileLayer<ExtraProps extends {} = {}> extends MVTLayer<
-  Required<_VectorTileLayerProps> & ExtraProps
-> {
+export default class VectorTileLayer<
+  FeaturePropertiesT = any,
+  ExtraProps extends {} = {}
+> extends MVTLayer<FeaturePropertiesT, Required<_VectorTileLayerProps> & ExtraProps> {
   static layerName = 'VectorTileLayer';
   static defaultProps = defaultProps;
 
@@ -47,6 +50,12 @@ export default class VectorTileLayer<ExtraProps extends {} = {}> extends MVTLaye
     mvt: boolean;
   };
 
+  constructor(...propObjects: VectorTileLayerProps<FeaturePropertiesT>[]) {
+    // Force externally visible props type, as it is not possible modify via extension
+    // @ts-ignore
+    super(...propObjects);
+  }
+
   initializeState(): void {
     super.initializeState();
     this.setState({binary: true});
@@ -71,6 +80,7 @@ export default class VectorTileLayer<ExtraProps extends {} = {}> extends MVTLaye
     return loadOptions;
   }
 
+  /* eslint-disable camelcase */
   async getTileData(tile: TileLoadProps) {
     const tileJSON = this.props.data as TilejsonResult;
     const {tiles, properties_tiles} = tileJSON;
@@ -106,6 +116,7 @@ export default class VectorTileLayer<ExtraProps extends {} = {}> extends MVTLaye
 
     return attributes ? mergeBoundaryData(geometry, attributes) : geometry;
   }
+  /* eslint-enable camelcase */
 
   renderSubLayers(
     props: TileLayer['props'] & {
@@ -144,7 +155,7 @@ export default class VectorTileLayer<ExtraProps extends {} = {}> extends MVTLaye
       const {data} = params.sourceLayer!.props;
       info.object = binaryToGeojson(data as BinaryFeatureCollection, {
         globalFeatureId: info.index
-      }) as Feature;
+      }) as Feature<Geometry, FeaturePropertiesT>;
     }
 
     return info;

package/src/sources/base-source.ts

@@ -32,18 +32,19 @@ export async function baseSource<UrlParameters extends Record<string, string>>(
     }
   }
   const baseUrl = buildSourceUrl(mergedOptions);
-  const {format} = mergedOptions;
+  const {clientId, format} = mergedOptions;
   const headers = {Authorization: `Bearer ${options.accessToken}`, ...options.headers};
+  const parameters = {client: clientId, ...urlParameters};
 
   const errorContext: APIErrorContext = {
     requestType: 'Map instantiation',
     connection: options.connectionName,
     type: endpoint,
-    source: JSON.stringify(urlParameters, undefined, 2)
+    source: JSON.stringify(parameters, undefined, 2)
   };
   const mapInstantiation = await requestWithParameters<TilejsonMapInstantiation>({
     baseUrl,
-    parameters: urlParameters,
+    parameters,
     headers,
     errorContext
   });
@@ -55,12 +56,15 @@ export async function baseSource<UrlParameters extends Record<string, string>>(
   errorContext.requestType = 'Map data';
 
   if (format === 'tilejson') {
-    return await requestWithParameters<TilejsonResult>({
-      accessToken,
+    const json = await requestWithParameters<TilejsonResult>({
       baseUrl: dataUrl,
       headers,
       errorContext
     });
+    if (accessToken) {
+      json.accessToken = accessToken;
+    }
+    return json;
   }
 
   return await requestWithParameters<GeojsonResult | JsonResult>({

package/src/sources/boundary-query-source.ts

@@ -1,14 +1,18 @@
-import {QueryParameters} from '../api';
+import {QueryParameters} from '../api/index';
 import {baseSource} from './base-source';
-import type {SourceOptions, TilejsonResult} from './types';
+import type {FilterOptions, SourceOptions, TilejsonResult} from './types';
 
-export type BoundaryQuerySourceOptions = SourceOptions & {
-  tilesetTableName: string;
-  matchingColumn?: string;
-  propertiesSqlQuery: string;
-  queryParameters?: QueryParameters;
-};
+export type BoundaryQuerySourceOptions = SourceOptions &
+  FilterOptions & {
+    columns?: string[];
+    tilesetTableName: string;
+    matchingColumn?: string;
+    propertiesSqlQuery: string;
+    queryParameters?: QueryParameters;
+  };
 type UrlParameters = {
+  columns?: string;
+  filters?: string;
   tilesetTableName: string;
   matchingColumn: string;
   propertiesSqlQuery: string;
@@ -18,12 +22,26 @@ type UrlParameters = {
 export const boundaryQuerySource = async function (
   options: BoundaryQuerySourceOptions
 ): Promise<TilejsonResult> {
-  const {tilesetTableName, matchingColumn = 'id', propertiesSqlQuery, queryParameters} = options;
+  const {
+    columns,
+    filters,
+    tilesetTableName,
+    matchingColumn = 'id',
+    propertiesSqlQuery,
+    queryParameters
+  } = options;
   const urlParameters: UrlParameters = {
     tilesetTableName,
     matchingColumn,
     propertiesSqlQuery
   };
+
+  if (columns) {
+    urlParameters.columns = columns.join(',');
+  }
+  if (filters) {
+    urlParameters.filters = JSON.stringify(filters);
+  }
   if (queryParameters) {
     urlParameters.queryParameters = JSON.stringify(queryParameters);
   }

package/src/sources/boundary-table-source.ts

@@ -1,13 +1,15 @@
 import {baseSource} from './base-source';
-import type {SourceOptions, TilejsonResult} from './types';
+import type {FilterOptions, SourceOptions, TilejsonResult} from './types';
 
-export type BoundaryTableSourceOptions = SourceOptions & {
-  tilesetTableName: string;
-  columns?: string[];
-  matchingColumn?: string;
-  propertiesTableName: string;
-};
+export type BoundaryTableSourceOptions = SourceOptions &
+  FilterOptions & {
+    tilesetTableName: string;
+    columns?: string[];
+    matchingColumn?: string;
+    propertiesTableName: string;
+  };
 type UrlParameters = {
+  filters?: string;
   tilesetTableName: string;
   columns?: string;
   matchingColumn: string;
@@ -17,7 +19,7 @@ type UrlParameters = {
 export const boundaryTableSource = async function (
   options: BoundaryTableSourceOptions
 ): Promise<TilejsonResult> {
-  const {tilesetTableName, columns, matchingColumn = 'id', propertiesTableName} = options;
+  const {filters, tilesetTableName, columns, matchingColumn = 'id', propertiesTableName} = options;
   const urlParameters: UrlParameters = {
     tilesetTableName,
     matchingColumn,
@@ -27,5 +29,8 @@ export const boundaryTableSource = async function (
   if (columns) {
     urlParameters.columns = columns.join(',');
   }
+  if (filters) {
+    urlParameters.filters = JSON.stringify(filters);
+  }
   return baseSource<UrlParameters>('boundary', options, urlParameters) as Promise<TilejsonResult>;
 };

package/src/sources/h3-query-source.ts

@@ -1,4 +1,5 @@
 /* eslint-disable camelcase */
+import {DEFAULT_AGGREGATION_RES_LEVEL_H3} from '../constants';
 import {baseSource} from './base-source';
 import type {
   AggregationOptions,
@@ -23,7 +24,7 @@ export const h3QuerySource = async function (
 ): Promise<TilejsonResult> {
   const {
     aggregationExp,
-    aggregationResLevel = 4,
+    aggregationResLevel = DEFAULT_AGGREGATION_RES_LEVEL_H3,
     sqlQuery,
     spatialDataColumn = 'h3',
     queryParameters

package/src/sources/h3-table-source.ts

@@ -1,4 +1,5 @@
 /* eslint-disable camelcase */
+import {DEFAULT_AGGREGATION_RES_LEVEL_H3} from '../constants';
 import {baseSource} from './base-source';
 import type {
   AggregationOptions,
@@ -13,7 +14,6 @@ export type H3TableSourceOptions = SourceOptions & TableSourceOptions & Aggregat
 type UrlParameters = {
   aggregationExp: string;
   aggregationResLevel?: string;
-  columns?: string;
   spatialDataType: SpatialDataType;
   spatialDataColumn?: string;
   name: string;
@@ -24,8 +24,7 @@ export const h3TableSource = async function (
 ): Promise<TilejsonResult> {
   const {
     aggregationExp,
-    aggregationResLevel = 4,
-    columns,
+    aggregationResLevel = DEFAULT_AGGREGATION_RES_LEVEL_H3,
     spatialDataColumn = 'h3',
     tableName
   } = options;
@@ -39,8 +38,5 @@ export const h3TableSource = async function (
   if (aggregationResLevel) {
     urlParameters.aggregationResLevel = String(aggregationResLevel);
   }
-  if (columns) {
-    urlParameters.columns = columns.join(',');
-  }
   return baseSource<UrlParameters>('table', options, urlParameters) as Promise<TilejsonResult>;
 };

package/src/sources/index.ts

@@ -36,3 +36,10 @@ export type {VectorTableSourceOptions} from './vector-table-source';
 
 export {vectorTilesetSource} from './vector-tileset-source';
 export type {VectorTilesetSourceOptions} from './vector-tileset-source';
+
+export type {
+  SourceOptions,
+  QuerySourceOptions,
+  TableSourceOptions,
+  TilesetSourceOptions
+} from './types';

package/src/sources/quadbin-query-source.ts

@@ -1,4 +1,5 @@
 /* eslint-disable camelcase */
+import {DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN} from '../constants';
 import {baseSource} from './base-source';
 import type {
   AggregationOptions,
@@ -24,7 +25,7 @@ export const quadbinQuerySource = async function (
 ): Promise<TilejsonResult> {
   const {
     aggregationExp,
-    aggregationResLevel = 6,
+    aggregationResLevel = DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN,
     sqlQuery,
     spatialDataColumn = 'quadbin',
     queryParameters

package/src/sources/quadbin-table-source.ts

@@ -1,4 +1,5 @@
 /* eslint-disable camelcase */
+import {DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN} from '../constants';
 import {baseSource} from './base-source';
 import type {
   AggregationOptions,
@@ -13,7 +14,6 @@ export type QuadbinTableSourceOptions = SourceOptions & TableSourceOptions & Agg
 type UrlParameters = {
   aggregationExp: string;
   aggregationResLevel?: string;
-  columns?: string;
   spatialDataType: SpatialDataType;
   spatialDataColumn?: string;
   name: string;
@@ -24,8 +24,7 @@ export const quadbinTableSource = async function (
 ): Promise<TilejsonResult> {
   const {
     aggregationExp,
-    aggregationResLevel = 6,
-    columns,
+    aggregationResLevel = DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN,
     spatialDataColumn = 'quadbin',
     tableName
   } = options;
@@ -40,8 +39,5 @@ export const quadbinTableSource = async function (
   if (aggregationResLevel) {
     urlParameters.aggregationResLevel = String(aggregationResLevel);
   }
-  if (columns) {
-    urlParameters.columns = columns.join(',');
-  }
   return baseSource<UrlParameters>('table', options, urlParameters) as Promise<TilejsonResult>;
 };

package/src/sources/types.ts

@@ -1,5 +1,5 @@
 import type {Feature} from 'geojson';
-import type {Format, MapInstantiation, QueryParameters} from '../api/types';
+import type {Filters, Format, MapInstantiation, QueryParameters} from '../api/types';
 
 export type SourceRequiredOptions = {
   /** Carto platform access token. */
@@ -57,6 +57,13 @@ export type AggregationOptions = {
   aggregationResLevel?: number;
 };
 
+export type FilterOptions = {
+  /**
+   * Filters to apply to the data source on the server
+   */
+  filters?: Filters;
+};
+
 export type QuerySourceOptions = {
   /**
    * The column name and the type of geospatial support.
@@ -68,6 +75,21 @@ export type QuerySourceOptions = {
   /** SQL query. */
   sqlQuery: string;
 
+  /**
+   * Relative resolution of a tile. Higher values increase density and data size. At `tileResolution = 1`, tile geometry is
+   * quantized to a 1024x1024 grid. Increasing or decreasing the resolution will increase or decrease the dimensions of
+   * the quantization grid proportionately.
+   *
+   * Supported `tileResolution` values, with corresponding grid sizes:
+   *
+   * - 0.25: 256x256
+   * - 0.5: 512x512
+   * - 1: 1024x1024
+   * - 2: 2048x2048
+   * - 4: 4096x4096
+   */
+  tileResolution?: TileResolution;
+
   /**
    * Values for named or positional paramteres in the query.
    *
@@ -102,18 +124,26 @@ export type TableSourceOptions = {
   tableName: string;
 
   /**
-   * Columns to retrieve from the table.
+   * The column name and the type of geospatial support.
    *
-   * If not present, all columns are returned.
+   * If not present, defaults to `'geom'` for generic tables, `'quadbin'` for Quadbin sources and `'h3'` for H3 sources.
    */
-  columns?: string[];
+  spatialDataColumn?: string;
 
   /**
-   * The column name and the type of geospatial support.
+   * Relative resolution of a tile. Higher values increase density and data size. At `tileResolution = 1`, tile geometry is
+   * quantized to a 1024x1024 grid. Increasing or decreasing the resolution will increase or decrease the dimensions of
+   * the quantization grid proportionately.
    *
-   * If not present, defaults to `'geom'` for generic tables, `'quadbin'` for Quadbin sources and `'h3'` for H3 sources.
+   * Supported `tileResolution` values, with corresponding grid sizes:
+   *
+   * - 0.25: 256x256
+   * - 0.5: 512x512
+   * - 1: 1024x1024
+   * - 2: 2048x2048
+   * - 4: 4096x4096
    */
-  spatialDataColumn?: string;
+  tileResolution?: TileResolution;
 };
 
 export type TilesetSourceOptions = {
@@ -123,12 +153,23 @@ export type TilesetSourceOptions = {
   tableName: string;
 };
 
+export type ColumnsOption = {
+  /**
+   * Columns to retrieve from the table.
+   *
+   * If not present, all columns are returned.
+   */
+  columns?: string[];
+};
+
 export type SpatialDataType = 'geo' | 'h3' | 'quadbin';
 
 export type TilejsonMapInstantiation = MapInstantiation & {
   tilejson: {url: string[]};
 };
 
+export type TileResolution = 0.25 | 0.5 | 1 | 2 | 4;
+
 export interface Tilejson {
   tilejson: string;
   name: string;
@@ -146,6 +187,7 @@ export interface Tilejson {
   center: [number, number, number];
   vector_layers: VectorLayer[];
   tilestats: Tilestats;
+  tileResolution?: TileResolution;
 }
 
 export interface Tilestats {

package/src/sources/vector-query-source.ts

@@ -1,11 +1,26 @@
 /* eslint-disable camelcase */
+import {DEFAULT_TILE_RESOLUTION} from '../constants';
 import {baseSource} from './base-source';
-import type {SourceOptions, QuerySourceOptions, SpatialDataType, TilejsonResult} from './types';
+import type {
+  FilterOptions,
+  SourceOptions,
+  QuerySourceOptions,
+  SpatialDataType,
+  TilejsonResult,
+  ColumnsOption
+} from './types';
+
+export type VectorQuerySourceOptions = SourceOptions &
+  QuerySourceOptions &
+  FilterOptions &
+  ColumnsOption;
 
-export type VectorQuerySourceOptions = SourceOptions & QuerySourceOptions;
 type UrlParameters = {
+  columns?: string;
+  filters?: string;
   spatialDataType: SpatialDataType;
   spatialDataColumn?: string;
+  tileResolution?: string;
   q: string;
   queryParameters?: string;
 };
@@ -13,9 +28,28 @@ type UrlParameters = {
 export const vectorQuerySource = async function (
   options: VectorQuerySourceOptions
 ): Promise<TilejsonResult> {
-  const {spatialDataColumn = 'geom', sqlQuery, queryParameters} = options;
-  const urlParameters: UrlParameters = {spatialDataColumn, spatialDataType: 'geo', q: sqlQuery};
+  const {
+    columns,
+    filters,
+    spatialDataColumn = 'geom',
+    sqlQuery,
+    tileResolution = DEFAULT_TILE_RESOLUTION,
+    queryParameters
+  } = options;
+
+  const urlParameters: UrlParameters = {
+    spatialDataColumn,
+    spatialDataType: 'geo',
+    tileResolution: tileResolution.toString(),
+    q: sqlQuery
+  };
 
+  if (columns) {
+    urlParameters.columns = columns.join(',');
+  }
+  if (filters) {
+    urlParameters.filters = JSON.stringify(filters);
+  }
   if (queryParameters) {
     urlParameters.queryParameters = JSON.stringify(queryParameters);
   }

package/src/sources/vector-table-source.ts

@@ -1,23 +1,51 @@
 /* eslint-disable camelcase */
+import {DEFAULT_TILE_RESOLUTION} from '../constants';
 import {baseSource} from './base-source';
-import type {SourceOptions, SpatialDataType, TableSourceOptions, TilejsonResult} from './types';
+import type {
+  FilterOptions,
+  ColumnsOption,
+  SourceOptions,
+  SpatialDataType,
+  TableSourceOptions,
+  TilejsonResult
+} from './types';
 
-export type VectorTableSourceOptions = SourceOptions & TableSourceOptions;
+export type VectorTableSourceOptions = SourceOptions &
+  TableSourceOptions &
+  FilterOptions &
+  ColumnsOption;
 type UrlParameters = {
   columns?: string;
+  filters?: string;
   spatialDataType: SpatialDataType;
   spatialDataColumn?: string;
+  tileResolution?: string;
   name: string;
 };
 
 export const vectorTableSource = async function (
   options: VectorTableSourceOptions
 ): Promise<TilejsonResult> {
-  const {columns, spatialDataColumn = 'geom', tableName} = options;
-  const urlParameters: UrlParameters = {name: tableName, spatialDataColumn, spatialDataType: 'geo'};
+  const {
+    columns,
+    filters,
+    spatialDataColumn = 'geom',
+    tableName,
+    tileResolution = DEFAULT_TILE_RESOLUTION
+  } = options;
+
+  const urlParameters: UrlParameters = {
+    name: tableName,
+    spatialDataColumn,
+    spatialDataType: 'geo',
+    tileResolution: tileResolution.toString()
+  };
 
   if (columns) {
     urlParameters.columns = columns.join(',');
   }
+  if (filters) {
+    urlParameters.filters = JSON.stringify(filters);
+  }
   return baseSource<UrlParameters>('table', options, urlParameters) as Promise<TilejsonResult>;
 };

package/src/utils.ts

@@ -51,7 +51,11 @@ export function scaleIdentity() {
     return unknown;
   };
 
-  scale.copy = () => scaleIdentity().unknown(unknown);
+  scale.copy = () => {
+    const scaleCopy = scaleIdentity();
+    scaleCopy.unknown(unknown);
+    return scaleCopy;
+  };
 
   return scale;
 }