@deck.gl/carto 9.1.12 → 9.2.0-alpha.2

package/package.json

@@ -3,7 +3,7 @@
   "description": "CARTO official integration with Deck.gl. Build geospatial applications using CARTO and Deck.gl.",
   "license": "MIT",
   "type": "module",
-  "version": "9.1.12",
+  "version": "9.2.0-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -42,15 +42,15 @@
     "prepublishOnly": "npm run build-bundle && npm run build-bundle -- --env=dev"
   },
   "dependencies": {
-    "@carto/api-client": "^0.4.4",
+    "@carto/api-client": "^0.5.6",
     "@loaders.gl/compression": "^4.2.0",
     "@loaders.gl/gis": "^4.2.0",
     "@loaders.gl/loader-utils": "^4.2.0",
     "@loaders.gl/mvt": "^4.2.0",
     "@loaders.gl/schema": "^4.2.0",
     "@loaders.gl/tiles": "^4.2.0",
-    "@luma.gl/core": "^9.1.5",
-    "@luma.gl/shadertools": "^9.1.5",
+    "@luma.gl/core": "^9.1.9",
+    "@luma.gl/shadertools": "^9.1.9",
     "@math.gl/web-mercator": "^4.1.0",
     "@types/d3-array": "^3.0.2",
     "@types/d3-color": "^1.4.2",
@@ -73,7 +73,7 @@
     "@deck.gl/geo-layers": "^9.1.0",
     "@deck.gl/layers": "^9.1.0",
     "@loaders.gl/core": "^4.2.0",
-    "@luma.gl/core": "^9.1.5"
+    "@luma.gl/core": "^9.1.9"
   },
-  "gitHead": "ed876a5eee0f612cd876244b0b2835ab871733ac"
+  "gitHead": "f9ca91bb15011ff5552ca8966b4207ada03a08fc"
 }

package/src/api/fetch-map.ts

@@ -1,359 +1,72 @@
-// deck.gl
-// SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
-
-/* eslint-disable @typescript-eslint/no-shadow */
+import {_ConstructorOf, Layer} from '@deck.gl/core';
+import ClusterTileLayer from '../layers/cluster-tile-layer';
+import H3TileLayer from '../layers/h3-tile-layer';
+import HeatmapTileLayer from '../layers/heatmap-tile-layer';
+import VectorTileLayer from '../layers/vector-tile-layer';
+import QuadbinTileLayer from '../layers/quadbin-tile-layer';
+import RasterTileLayer from '../layers/raster-tile-layer';
 
 import {
-  DEFAULT_API_BASE_URL,
-  APIErrorContext,
-  CartoAPIError,
-  GeojsonResult,
-  JsonResult,
-  TilejsonResult,
-  Format,
-  MapType,
-  QueryParameters,
-  SourceOptions,
-  buildPublicMapUrl,
-  buildStatsUrl,
-  h3QuerySource,
-  h3TableSource,
-  quadbinQuerySource,
-  quadbinTableSource,
-  vectorQuerySource,
-  vectorTableSource,
-  vectorTilesetSource,
-  requestWithParameters
+  fetchMap as _fetchMap,
+  FetchMapOptions as _FetchMapOptions,
+  FetchMapResult as _FetchMapResult,
+  LayerDescriptor,
+  LayerType
 } from '@carto/api-client';
-import {ParseMapResult, parseMap} from './parse-map';
-import {assert} from '../utils';
-import type {Basemap} from './types';
-import {fetchBasemapProps} from './basemap';
 
-type Dataset = {
-  id: string;
-  type: MapType;
-  source: string;
-  cache?: number;
-  connectionName: string;
-  geoColumn: string;
-  data: TilejsonResult | GeojsonResult | JsonResult;
-  columns: string[];
-  format: Format;
-  aggregationExp: string;
-  aggregationResLevel: number;
-  queryParameters: QueryParameters;
+export type FetchMapResult = Omit<_FetchMapResult, 'layers'> & {
+  layers: Layer[];
 };
 
-/* global clearInterval, setInterval, URL */
-/* eslint-disable complexity, max-statements, max-params */
-async function _fetchMapDataset(dataset: Dataset, context: _FetchMapContext) {
-  const {
-    aggregationExp,
-    aggregationResLevel,
-    connectionName,
-    columns,
-    format,
-    geoColumn,
-    source,
-    type,
-    queryParameters
-  } = dataset;
-
-  const cache: {value?: number} = {};
-  const globalOptions = {
-    ...context,
-    cache,
-    connectionName,
-    format
-  } as SourceOptions;
+export type FetchMapOptions = Omit<_FetchMapOptions, 'onNewData'> & {
+  onNewData?: (result: FetchMapResult) => void;
+};
 
-  if (type === 'tileset') {
-    // TODO do we want a generic tilesetSource?
-    // @ts-ignore
-    dataset.data = await vectorTilesetSource({...globalOptions, tableName: source});
-  } else {
-    const [spatialDataType, spatialDataColumn] = geoColumn ? geoColumn.split(':') : ['geom'];
-    if (spatialDataType === 'geom') {
-      const options = {...globalOptions, spatialDataColumn};
-      if (type === 'table') {
-        dataset.data = await vectorTableSource({...options, columns, tableName: source});
-      } else if (type === 'query') {
-        dataset.data = await vectorQuerySource({
-          ...options,
-          columns,
-          sqlQuery: source,
-          queryParameters
-        });
-      }
-    } else if (spatialDataType === 'h3') {
-      const options = {...globalOptions, aggregationExp, aggregationResLevel, spatialDataColumn};
-      if (type === 'table') {
-        dataset.data = await h3TableSource({...options, tableName: source});
-      } else if (type === 'query') {
-        dataset.data = await h3QuerySource({...options, sqlQuery: source, queryParameters});
-      }
-    } else if (spatialDataType === 'quadbin') {
-      const options = {...globalOptions, aggregationExp, aggregationResLevel, spatialDataColumn};
-      if (type === 'table') {
-        dataset.data = await quadbinTableSource({...options, tableName: source});
-      } else if (type === 'query') {
-        dataset.data = await quadbinQuerySource({...options, sqlQuery: source, queryParameters});
-      }
-    }
+// Layer factory to create deck.gl layers from layer descriptors
+const layerClasses: Record<LayerType, _ConstructorOf<Layer>> = {
+  clusterTile: ClusterTileLayer,
+  h3: H3TileLayer,
+  heatmapTile: HeatmapTileLayer,
+  mvt: VectorTileLayer,
+  quadbin: QuadbinTileLayer,
+  raster: RasterTileLayer,
+  tileset: VectorTileLayer
+} as const;
+
+export function LayerFactory(descriptor: LayerDescriptor): Layer {
+  const LayerClass = layerClasses[descriptor.type];
+  if (!LayerClass) {
+    throw new Error(`No layer class found for type: ${descriptor.type}`);
   }
-  let cacheChanged = true;
-  if (cache.value) {
-    cacheChanged = dataset.cache !== cache.value;
-    dataset.cache = cache.value;
-  }
-
-  return cacheChanged;
+  return new LayerClass(descriptor.props);
 }
 
-async function _fetchTilestats(attribute: string, dataset: Dataset, context: _FetchMapContext) {
-  const {connectionName, data, id, source, type, queryParameters} = dataset;
-  const {apiBaseUrl} = context;
-  const errorContext: APIErrorContext = {
-    requestType: 'Tile stats',
-    connection: connectionName,
-    type,
-    source
+function createResult(result: _FetchMapResult): FetchMapResult {
+  return {
+    ...result,
+    layers: result.layers.map(descriptor => LayerFactory(descriptor))
   };
-  if (!('tilestats' in data)) {
-    throw new CartoAPIError(new Error(`Invalid dataset for tilestats: ${id}`), errorContext);
-  }
-
-  const baseUrl = buildStatsUrl({attribute, apiBaseUrl, ...dataset});
-  const client = new URLSearchParams(data.tiles[0]).get('client');
-  const headers = {Authorization: `Bearer ${context.accessToken}`};
-  const parameters: Record<string, string> = {};
-  if (client) {
-    parameters.client = client;
-  }
-  if (type === 'query') {
-    parameters.q = source;
-    if (queryParameters) {
-      parameters.queryParameters = JSON.stringify(queryParameters);
-    }
-  }
-  const stats = await requestWithParameters({
-    baseUrl,
-    headers,
-    parameters,
-    errorContext,
-    maxLengthURL: context.maxLengthURL
-  });
-
-  // Replace tilestats for attribute with value from API
-  const {attributes} = data.tilestats.layers[0];
-  const index = attributes.findIndex(d => d.attribute === attribute);
-  attributes[index] = stats;
-  return true;
-}
-
-async function fillInMapDatasets({datasets}: {datasets: Dataset[]}, context: _FetchMapContext) {
-  const promises = datasets.map(dataset => _fetchMapDataset(dataset, context));
-  return await Promise.all(promises);
-}
-
-async function fillInTileStats(
-  {datasets, keplerMapConfig}: {datasets: Dataset[]; keplerMapConfig: any},
-  context: _FetchMapContext
-) {
-  const attributes: {attribute: string; dataset: any}[] = [];
-  const {layers} = keplerMapConfig.config.visState;
-  for (const layer of layers) {
-    for (const channel of Object.keys(layer.visualChannels)) {
-      const attribute = layer.visualChannels[channel]?.name;
-      if (attribute) {
-        const dataset = datasets.find(d => d.id === layer.config.dataId);
-        if (dataset && dataset.type !== 'tileset' && (dataset.data as TilejsonResult).tilestats) {
-          // Only fetch stats for QUERY & TABLE map types
-          attributes.push({attribute, dataset});
-        }
-      }
-    }
-  }
-  // Remove duplicates to avoid repeated requests
-  const filteredAttributes: {attribute: string; dataset: any}[] = [];
-  for (const a of attributes) {
-    if (
-      !filteredAttributes.find(
-        ({attribute, dataset}) => attribute === a.attribute && dataset === a.dataset
-      )
-    ) {
-      filteredAttributes.push(a);
-    }
-  }
-
-  const promises = filteredAttributes.map(({attribute, dataset}) =>
-    _fetchTilestats(attribute, dataset, context)
-  );
-  return await Promise.all(promises);
 }
 
-export type FetchMapOptions = {
-  /**
-   * CARTO platform access token. Only required for private maps.
-   */
-  accessToken?: string;
-
-  /**
-   * Base URL of the CARTO Maps API.
-   *
-   * Example for account located in EU-west region: `https://gcp-eu-west1.api.carto.com`
-   *
-   * @default https://gcp-us-east1.api.carto.com
-   */
-  apiBaseUrl?: string;
-
-  /**
-   * Identifier of map created in CARTO Builder.
-   */
-  cartoMapId: string;
-  clientId?: string;
-
-  /**
-   * Custom HTTP headers added to map instantiation and data requests.
-   */
-  headers?: Record<string, string>;
-
-  /**
-   * Interval in seconds at which to autoRefresh the data. If provided, `onNewData` must also be provided.
-   */
-  autoRefresh?: number;
-
-  /**
-   * Callback function that will be invoked whenever data in layers is changed. If provided, `autoRefresh` must also be provided.
-   */
-  onNewData?: (map: any) => void;
-
-  /**
-   * Maximum URL character length. Above this limit, requests use POST.
-   * Used to avoid browser and CDN limits.
-   * @default {@link DEFAULT_MAX_LENGTH_URL}
-   */
-  maxLengthURL?: number;
-};
-
 /**
- * Context reused while fetching and updating a map with fetchMap().
+ * fetchMap is a wrapper around the @carto/api-client fetchMap function, with additions for convenience and backward-compatibility.
+ * Where @carto/api-client fetchMap returns layer props, @deck.gl/carto fetchMap returns Layer instances ready for use.
+ * For greater control, use the @carto/api-client fetchMap function directly and use LayerFactory to create layers manually.
  */
-type _FetchMapContext = {apiBaseUrl: string} & Pick<
-  FetchMapOptions,
-  'accessToken' | 'clientId' | 'headers' | 'maxLengthURL'
->;
-
-export type FetchMapResult = ParseMapResult & {
-  /**
-   * Basemap properties.
-   */
-  basemap: Basemap | null;
-  stopAutoRefresh?: () => void;
-};
-
-/* eslint-disable max-statements */
-export async function fetchMap({
-  accessToken,
-  apiBaseUrl = DEFAULT_API_BASE_URL,
-  cartoMapId,
-  clientId,
-  headers,
-  autoRefresh,
-  onNewData,
-  maxLengthURL
-}: FetchMapOptions): Promise<FetchMapResult> {
-  assert(cartoMapId, 'Must define CARTO map id: fetchMap({cartoMapId: "XXXX-XXXX-XXXX"})');
-
-  if (accessToken) {
-    headers = {Authorization: `Bearer ${accessToken}`, ...headers};
-  }
-
-  if (autoRefresh || onNewData) {
-    assert(onNewData, 'Must define `onNewData` when using autoRefresh');
-    assert(typeof onNewData === 'function', '`onNewData` must be a function');
-    assert(
-      typeof autoRefresh === 'number' && autoRefresh > 0,
-      '`autoRefresh` must be a positive number'
-    );
-  }
-
-  const baseUrl = buildPublicMapUrl({apiBaseUrl, cartoMapId});
-  const errorContext: APIErrorContext = {requestType: 'Public map', mapId: cartoMapId};
-  const map = await requestWithParameters({baseUrl, headers, errorContext, maxLengthURL});
-  const context: _FetchMapContext = {
-    accessToken: map.token || accessToken,
-    apiBaseUrl,
-    clientId,
-    headers,
-    maxLengthURL
+export async function fetchMap(options: FetchMapOptions): Promise<FetchMapResult> {
+  const {onNewData, ...rest} = options;
+  const _options: _FetchMapOptions = {
+    ...rest,
+    onNewData:
+      typeof onNewData === 'function'
+        ? result => {
+            onNewData(createResult(result));
+          }
+        : undefined
   };
 
-  // Periodically check if the data has changed. Note that this
-  // will not update when a map is published.
-  let stopAutoRefresh: (() => void) | undefined;
-  if (autoRefresh) {
-    // eslint-disable-next-line @typescript-eslint/no-misused-promises
-    const intervalId = setInterval(async () => {
-      const changed = await fillInMapDatasets(map, {
-        ...context,
-        headers: {
-          ...headers,
-          'If-Modified-Since': new Date().toUTCString()
-        }
-      });
-      if (onNewData && changed.some(v => v === true)) {
-        onNewData(parseMap(map));
-      }
-    }, autoRefresh * 1000);
-    stopAutoRefresh = () => {
-      clearInterval(intervalId);
-    };
-  }
-
-  const geojsonLayers = map.keplerMapConfig.config.visState.layers.filter(
-    ({type}) => type === 'geojson' || type === 'point'
-  );
-  const geojsonDatasetIds = geojsonLayers.map(({config}) => config.dataId);
-  map.datasets.forEach(dataset => {
-    if (geojsonDatasetIds.includes(dataset.id)) {
-      const {config} = geojsonLayers.find(({config}) => config.dataId === dataset.id);
-      dataset.format = 'geojson';
-      // Support for very old maps. geoColumn was not stored in the past
-      if (!dataset.geoColumn && config.columns.geojson) {
-        dataset.geoColumn = config.columns.geojson;
-      }
-    }
-  });
-
-  const [basemap] = await Promise.all([
-    fetchBasemapProps({config: map.keplerMapConfig.config, errorContext}),
-
-    // Mutates map.datasets so that dataset.data contains data
-    fillInMapDatasets(map, context)
-  ]);
-
-  // Mutates attributes in visualChannels to contain tile stats
-  await fillInTileStats(map, context);
-
-  const out = {...parseMap(map), basemap, ...{stopAutoRefresh}};
-
-  const textLayers = out.layers.filter(layer => {
-    const pointType = layer.props.pointType || '';
-    return pointType.includes('text');
-  });
-
-  /* global FontFace, window, document */
-  if (textLayers.length && window.FontFace && !document.fonts.check('12px Inter')) {
-    // Fetch font needed for labels
-    const font = new FontFace(
-      'Inter',
-      'url(https://fonts.gstatic.com/s/inter/v12/UcC73FwrK3iLTeHuS_fvQtMwCp50KnMa1ZL7W0Q5nw.woff2)'
-    );
-    await font.load().then(f => document.fonts.add(f));
-  }
-
-  return out;
+  // For backwards compatibility, provide a shim for the old API
+  const _result: _FetchMapResult = await _fetchMap(_options);
+  const result: FetchMapResult = createResult(_result);
+  return result;
 }

package/src/api/index.ts

@@ -2,6 +2,6 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-export {fetchMap} from './fetch-map';
+export {fetchMap, LayerFactory} from './fetch-map';
 export type {FetchMapOptions, FetchMapResult} from './fetch-map';
 export type {Basemap, MapLibreBasemap, GoogleBasemap} from './types';

package/src/index.ts

@@ -61,7 +61,7 @@ export {
 export {default as colorBins} from './style/color-bins-style';
 export {default as colorCategories} from './style/color-categories-style';
 export {default as colorContinuous} from './style/color-continuous-style';
-export {fetchMap} from './api/index';
+export {fetchMap, LayerFactory} from './api/fetch-map';
 export {fetchBasemapProps} from './api/basemap';
 export type {
   FetchMapOptions,
@@ -70,76 +70,3 @@ export type {
   MapLibreBasemap as _MapLibreBasemap,
   GoogleBasemap as _GoogleBasemap
 } from './api/index';
-
-// TODO(v10): Consider removing re-exports from '@carto/api-client' below.
-
-import {
-  boundaryQuerySource,
-  boundaryTableSource,
-  h3QuerySource,
-  h3TableSource,
-  h3TilesetSource,
-  rasterSource,
-  quadbinQuerySource,
-  quadbinTableSource,
-  quadbinTilesetSource,
-  vectorQuerySource,
-  vectorTableSource,
-  vectorTilesetSource
-} from '@carto/api-client';
-
-export const CARTO_SOURCES = {
-  boundaryQuerySource,
-  boundaryTableSource,
-  h3QuerySource,
-  h3TableSource,
-  h3TilesetSource,
-  rasterSource,
-  quadbinQuerySource,
-  quadbinTableSource,
-  quadbinTilesetSource,
-  vectorQuerySource,
-  vectorTableSource,
-  vectorTilesetSource
-};
-
-export {
-  boundaryQuerySource,
-  boundaryTableSource,
-  h3QuerySource,
-  h3TableSource,
-  h3TilesetSource,
-  rasterSource,
-  quadbinQuerySource,
-  quadbinTableSource,
-  quadbinTilesetSource,
-  vectorQuerySource,
-  vectorTableSource,
-  vectorTilesetSource,
-  query,
-  CartoAPIError,
-  SOURCE_DEFAULTS
-} from '@carto/api-client';
-
-export type {
-  GeojsonResult,
-  JsonResult,
-  TilejsonResult,
-  SourceOptions,
-  QuerySourceOptions,
-  TableSourceOptions,
-  TilesetSourceOptions,
-  BoundaryQuerySourceOptions,
-  BoundaryTableSourceOptions,
-  H3QuerySourceOptions,
-  H3TableSourceOptions,
-  H3TilesetSourceOptions,
-  RasterSourceOptions,
-  QuadbinQuerySourceOptions,
-  QuadbinTableSourceOptions,
-  QuadbinTilesetSourceOptions,
-  VectorQuerySourceOptions,
-  VectorTableSourceOptions,
-  VectorTilesetSourceOptions,
-  QueryParameters
-} from '@carto/api-client';

package/src/layers/schema/spatialjson-utils.ts

@@ -6,7 +6,6 @@ import {bigIntToHex} from 'quadbin';
 import {BinaryPointFeature} from '@loaders.gl/schema';
 
 export type IndexScheme = 'h3' | 'quadbin';
-type TypedArray = Float32Array | Float64Array;
 
 export type Indices = {value: BigUint64Array};
 export type NumericProps = BinaryPointFeature['numericProps'];

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

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 import {registerLoaders} from '@loaders.gl/core';
-import {BinaryFeatureCollection, BinaryPointFeature} from '@loaders.gl/schema';
+import {BinaryPointFeature} from '@loaders.gl/schema';
 import CartoPropertiesTileLoader from './schema/carto-properties-tile-loader';
 import CartoVectorTileLoader from './schema/carto-vector-tile-loader';
 registerLoaders([CartoPropertiesTileLoader, CartoVectorTileLoader]);
@@ -13,7 +13,6 @@ import {ClipExtension, CollisionFilterExtension} from '@deck.gl/extensions';
 import {
   MVTLayer,
   MVTLayerProps,
-  TileLayer,
   _getURLFromTemplate,
   _Tile2DHeader,
   _TileLoadProps as TileLoadProps,

package/src/utils.ts

@@ -2,12 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {
-  BinaryAttribute,
-  BinaryFeature,
-  BinaryFeatureCollection,
-  BinaryPointFeature
-} from '@loaders.gl/schema';
+import {BinaryFeatureCollection, BinaryPointFeature} from '@loaders.gl/schema';
 import {log} from '@deck.gl/core';
 import type {Properties, NumericProps} from './layers/schema/spatialjson-utils';