@carto/api-client 0.5.2-alpha.0 → 0.5.2-alpha.2

package/package.json

@@ -8,11 +8,12 @@
   "homepage": "https://github.com/CartoDB/carto-api-client#readme",
   "author": "Don McCurdy <donmccurdy@carto.com>",
   "packageManager": "yarn@4.3.1",
-  "version": "0.5.2-alpha.0",
+  "version": "0.5.2-alpha.2",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
+  "main": "./build/api-client.cjs",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -39,7 +40,7 @@
   "scripts": {
     "build": "tsup",
     "build:watch": "tsup --watch",
-    "dev": "yarn build && concurrently --names tsup,vite \"yarn build:watch\" \"vite --config examples/vite.config.ts --open\"",
+    "dev": "yarn build && concurrently \"yarn build:watch\" \"vite --config examples/vite.config.ts --open\"",
     "test": "vitest run --typecheck",
     "test:watch": "vitest watch --typecheck",
     "coverage": "vitest run --coverage.enabled --coverage.all false",
@@ -66,7 +67,7 @@
     "@types/geojson": "^7946.0.16",
     "d3-format": "^3.1.0",
     "d3-scale": "^4.0.2",
-    "h3-js": "4.1.0",
+    "h3-js": "4.2.1",
     "quadbin": "^0.4.1-alpha.0"
   },
   "devDependencies": {
@@ -122,7 +123,7 @@
     "typescript": "~5.8.2",
     "typescript-eslint": "^8.26.1",
     "vite": "^6.2.2",
-    "vitest": "3.1.1"
+    "vitest": "3.1.2"
   },
   "resolutions": {
     "@carto/api-client": "portal:./",

package/src/api/carto-api-error.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {MapType} from '../types.js';
+import type {MapType} from '../types.js';
 
 export type APIRequestType =
   | 'Map data'

package/src/api/endpoints.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {MapType} from '../types.js';
+import type {MapType} from '../types.js';
 
 export type V3Endpoint = 'maps' | 'stats' | 'sql';
 

package/src/api/index.ts

@@ -4,8 +4,8 @@
 
 export {
   CartoAPIError,
-  APIErrorContext,
-  APIRequestType,
+  type APIErrorContext,
+  type APIRequestType,
 } from './carto-api-error.js';
 // Internal, but required for fetchMap().
 export {buildPublicMapUrl, buildStatsUrl} from './endpoints.js';

package/src/api/query.ts

@@ -10,7 +10,7 @@ import type {
 } from '../sources/types.js';
 import {buildQueryUrl} from './endpoints.js';
 import {requestWithParameters} from './request-with-parameters.js';
-import {APIErrorContext} from './carto-api-error.js';
+import type {APIErrorContext} from './carto-api-error.js';
 import {getClient} from '../client.js';
 
 export type QueryOptions = SourceOptions & QuerySourceOptions;

package/src/api/request-with-parameters.ts

@@ -3,11 +3,11 @@
 // Copyright (c) vis.gl contributors
 
 import {isPureObject} from '../utils.js';
-import {CartoAPIError, APIErrorContext} from './carto-api-error.js';
+import {CartoAPIError, type APIErrorContext} from './carto-api-error.js';
 import {V3_MINOR_VERSION} from '../constants-internal.js';
 import {DEFAULT_MAX_LENGTH_URL} from '../constants-internal.js';
 import {getClient} from '../client.js';
-import {LocalCacheOptions} from '../sources/types.js';
+import type {LocalCacheOptions} from '../sources/types.js';
 
 const DEFAULT_HEADERS = {
   Accept: 'application/json',

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

@@ -1,8 +1,8 @@
-import {Feature} from 'geojson';
-import {FilterLogicalOperator, Filters} from '../types.js';
+import type {Feature} from 'geojson';
+import type {FilterLogicalOperator, Filters} from '../types.js';
 import {FilterType} from '../constants.js';
 import {_buildFeatureFilter} from '../filters/index.js';
-import {FeatureData} from '../types-internal.js';
+import type {FeatureData} from '../types-internal.js';
 
 type TimeFilter = Filters['string'][FilterType.TIME] & {
   params?: {offsetBy?: number};

package/src/fetch-map/basemap-styles.ts

@@ -1,5 +1,5 @@
-import {CartoAPIError, APIErrorContext} from '../api/index.js';
-import {GoogleBasemapProps} from './types.js';
+import {CartoAPIError, type APIErrorContext} from '../api/index.js';
+import type {GoogleBasemapProps} from './types.js';
 
 const cartoStyleUrlTemplate =
   'https://basemaps.cartocdn.com/gl/{basemap}-gl-style/style.json';

package/src/fetch-map/basemap.ts

@@ -6,8 +6,8 @@ import {
   getStyleUrl,
   someLayerGroupsDisabled,
 } from './basemap-styles.js';
-import {Basemap, KeplerMapConfig, MapLibreBasemapProps} from './types.js';
-import {APIErrorContext} from '../api/index.js';
+import type {Basemap, KeplerMapConfig, MapLibreBasemapProps} from './types.js';
+import type {APIErrorContext} from '../api/index.js';
 
 const CUSTOM_STYLE_ID_PREFIX = 'custom:';
 const DEFAULT_CARTO_STYLE = 'positron';

package/src/fetch-map/fetch-map.ts

@@ -1,19 +1,19 @@
 import {DEFAULT_API_BASE_URL} from '../constants.js';
 
 import {
-  APIErrorContext,
+  type APIErrorContext,
   CartoAPIError,
   buildPublicMapUrl,
   buildStatsUrl,
   requestWithParameters,
 } from '../api/index.js';
 
-import {ParseMapResult, parseMap} from './parse-map.js';
+import {type ParseMapResult, parseMap} from './parse-map.js';
 import {assert} from '../utils.js';
 import type {Basemap, Dataset, KeplerMapConfig} from './types.js';
 import {fetchBasemapProps} from './basemap.js';
 import {configureSource} from './source.js';
-import {Filters} from '../types.js';
+import type {Filters} from '../types.js';
 import {isRemoteCalculationSupported} from './utils.js';
 
 /* global clearInterval, setInterval, URL */

package/src/fetch-map/layer-map.ts

@@ -23,7 +23,7 @@ export type LayerType =
   | 'tileset';
 
 import {createBinaryProxy, scaleIdentity} from './utils.js';
-import {
+import type {
   CustomMarkersRange,
   Dataset,
   MapLayerConfig,
@@ -31,6 +31,9 @@ import {
   VisualChannelField,
   VisualChannels,
 } from './types.js';
+import type {ProviderType} from '../types.js';
+import {DEFAULT_AGGREGATION_EXP_ALIAS} from '../constants-internal.js';
+import type {SchemaField} from '../types-internal.js';
 
 const SCALE_FUNCS: Record<string, () => any> = {
   linear: scaleLinear,
@@ -118,7 +121,8 @@ const customMarkersPropsMap = {
 const heatmapTilePropsMap = {
   visConfig: {
     colorRange: (x: any) => ({colorRange: x.colors.map(hexToRGBA)}),
-    radius: 'radiusPixels',
+    radius: (radius: number) => ({radiusPixels: 20 + radius}),
+    opacity: 'opacity',
   },
 };
 
@@ -146,6 +150,17 @@ const deprecatedLayerTypes = [
   'point',
 ];
 
+/** @privateRemarks Source: Builder */
+export const TEXT_LABEL_INDEX = 0;
+
+/** @privateRemarks Source: Builder */
+export const TEXT_OUTLINE_OPACITY = 64;
+
+export const TEXT_NUMBER_FORMATTER = new Intl.NumberFormat('en-US', {
+  maximumFractionDigits: 2,
+  notation: 'compact',
+});
+
 export function getLayerProps(
   type: LayerType,
   config: MapLayerConfig,
@@ -272,9 +287,9 @@ function findAccessorKey(keys: string[], properties: any): string[] {
     }
   }
 
-  throw new Error(
-    `Could not find property for any accessor key: ${keys.join(', ')}`
-  );
+  // If data doesn't contain any valid keys, return all keys to run search
+  // on next feature
+  return keys;
 }
 
 export function getColorValueAccessor(
@@ -459,3 +474,65 @@ export function getTextAccessor({name, type}: VisualChannelField, data: any) {
 }
 
 export {domainFromValues as _domainFromValues};
+
+/** @privateRemarks Source: Builder */
+export function calculateClusterRadius(
+  properties: {[column: string]: number},
+  stats: Record<string, {min: number; max: number}>,
+  radiusRange: [number, number],
+  column: string
+): number {
+  const {min, max} = stats[column];
+  const value = properties[column];
+
+  // When there's a single cluster on the screen, min and max are equivalent, so we should return the maximum radius
+  if (min === max) return radiusRange[1];
+
+  const normalizedValue = (value - min) / (max - min);
+  return radiusRange[0] + normalizedValue * (radiusRange[1] - radiusRange[0]);
+}
+
+/** @privateRemarks Source: Builder */
+export function getDefaultAggregationExpColumnAliasForLayerType(
+  layerType: LayerType,
+  provider: ProviderType,
+  schema: SchemaField[]
+): string {
+  if (schema && layerType === 'clusterTile') {
+    return getColumnAliasForAggregationExp(
+      getDefaultColumnFromSchemaForAggregationExp(schema),
+      'count',
+      provider
+    );
+  } else {
+    return DEFAULT_AGGREGATION_EXP_ALIAS;
+  }
+}
+
+/** @privateRemarks Source: Builder */
+function getColumnAliasForAggregationExp(
+  name: string,
+  aggregation: string,
+  provider: ProviderType
+) {
+  const columnAlias = `${name}_${aggregation}`;
+  return provider === 'snowflake' ? columnAlias.toUpperCase() : columnAlias;
+}
+
+/** @privateRemarks Source: Builder */
+function getDefaultColumnFromSchemaForAggregationExp(
+  schema: SchemaField[]
+): string {
+  return schema ? schema[0].name : '';
+}
+
+/** @privateRemarks Source: Builder */
+export function calculateClusterTextFontSize(radius: number): number {
+  if (radius >= 80) return 24;
+  if (radius >= 72) return 24;
+  if (radius >= 56) return 20;
+  if (radius >= 40) return 16;
+  if (radius >= 24) return 13;
+  if (radius >= 8) return 11;
+  return 11;
+}

package/src/fetch-map/parse-map.ts

@@ -1,22 +1,28 @@
 import type {ColorParameters} from '@luma.gl/core';
 import {
-  AGGREGATION,
+  calculateClusterRadius,
+  calculateClusterTextFontSize,
+  getDefaultAggregationExpColumnAliasForLayerType,
   getLayerProps,
   getColorAccessor,
   getColorValueAccessor,
   getSizeAccessor,
   getTextAccessor,
-  OPACITY_MAP,
   opacityToAlpha,
   getIconUrlAccessor,
   negateAccessor,
   getMaxMarkerSize,
-  LayerType,
+  type LayerType,
+  AGGREGATION,
+  OPACITY_MAP,
+  TEXT_NUMBER_FORMATTER,
+  TEXT_LABEL_INDEX,
+  TEXT_OUTLINE_OPACITY,
 } from './layer-map.js';
 
 import {assert, isEmptyObject} from '../utils.js';
-import {Filters} from '../types.js';
-import {
+import type {Filters} from '../types.js';
+import type {
   KeplerMapConfig,
   MapLayerConfig,
   VisualChannels,
@@ -100,7 +106,14 @@ export function parseMap(json: any) {
               ...defaultProps,
               ...createInteractionProps(interactionConfig),
               ...styleProps,
-              ...createChannelProps(id, type, config, visualChannels, data), // Must come after style
+              ...createChannelProps(
+                id,
+                type,
+                config,
+                visualChannels,
+                data,
+                dataset
+              ), // Must come after style
               ...createParametersProp(
                 layerBlending,
                 styleProps.parameters || {}
@@ -197,7 +210,8 @@ function createChannelProps(
   type: string,
   config: MapLayerConfig,
   visualChannels: VisualChannels,
-  data: any
+  data: any,
+  dataset: Dataset
 ) {
   const {
     colorField,
@@ -261,6 +275,56 @@ function createChannelProps(
     }
   }
 
+  if (type === 'clusterTile') {
+    const aggregationExpAlias = getDefaultAggregationExpColumnAliasForLayerType(
+      type,
+      dataset.providerId,
+      data.schema
+    );
+
+    result.pointType = visConfig.isTextVisible ? 'circle+text' : 'circle';
+    result.clusterLevel = visConfig.clusterLevel;
+
+    result.getWeight = (d: any) => {
+      return d.properties[aggregationExpAlias];
+    };
+
+    result.getPointRadius = (d: any, info: any) => {
+      return calculateClusterRadius(
+        d.properties,
+        info.data.attributes.stats,
+        visConfig.radiusRange as [number, number],
+        aggregationExpAlias
+      );
+    };
+
+    result.textCharacterSet = 'auto';
+    result.textFontFamily = 'Inter, sans';
+    result.textFontSettings = {sdf: true};
+    result.textFontWeight = 600;
+
+    result.getText = (d: any) =>
+      TEXT_NUMBER_FORMATTER.format(d.properties[aggregationExpAlias]);
+
+    result.getTextColor = config.textLabel[TEXT_LABEL_INDEX].color;
+    result.textOutlineColor = [
+      ...(config.textLabel[TEXT_LABEL_INDEX].outlineColor as number[]),
+      TEXT_OUTLINE_OPACITY,
+    ];
+    result.textOutlineWidth = 5;
+    result.textSizeUnits = 'pixels';
+
+    result.getTextSize = (d: any, info: any) => {
+      const radius = calculateClusterRadius(
+        d.properties,
+        info.data.attributes.stats,
+        visConfig.radiusRange as [number, number],
+        aggregationExpAlias
+      );
+      return calculateClusterTextFontSize(radius);
+    };
+  }
+
   if (radiusField || sizeField) {
     result.getPointRadius = getSizeAccessor(
       // @ts-ignore

package/src/fetch-map/source.ts

@@ -1,6 +1,6 @@
-import {Dataset} from './types.js';
+import type {Dataset} from './types.js';
 import {SpatialIndex, SpatialIndexColumn} from '../constants.js';
-import {
+import type {
   QuerySourceOptions,
   TableSourceOptions,
   TilejsonResult,
@@ -15,22 +15,22 @@ import {
 } from '../constants-internal.js';
 import {
   h3QuerySource,
-  H3QuerySourceOptions,
+  type H3QuerySourceOptions,
   h3TableSource,
-  H3TableSourceOptions,
+  type H3TableSourceOptions,
   quadbinQuerySource,
-  QuadbinQuerySourceOptions,
+  type QuadbinQuerySourceOptions,
   quadbinTableSource,
-  QuadbinTableSourceOptions,
+  type QuadbinTableSourceOptions,
   rasterSource,
   vectorQuerySource,
-  VectorQuerySourceOptions,
+  type VectorQuerySourceOptions,
   vectorTableSource,
-  VectorTableSourceOptions,
+  type VectorTableSourceOptions,
   vectorTilesetSource,
-  VectorTilesetSourceOptions,
+  type VectorTilesetSourceOptions,
 } from '../sources/index.js';
-import {Filter} from '../types.js';
+import type {Filter} from '../types.js';
 
 type FetchDatasetOptions = {
   accessToken: string;

package/src/fetch-map/types.ts

@@ -1,6 +1,6 @@
-import {LayerType, SCALE_TYPE} from './layer-map.js';
-import {Format, MapType, ProviderType, QueryParameters} from '../types.js';
-import {TilejsonResult} from '../sources/types.js';
+import type {LayerType, SCALE_TYPE} from './layer-map.js';
+import type {Format, MapType, ProviderType, QueryParameters} from '../types.js';
+import type {TilejsonResult} from '../sources/types.js';
 
 export type VisualChannelField = {
   name: string;
@@ -75,6 +75,10 @@ export type VisConfig = {
   heightAggregation?: any;
 
   weightAggregation?: any;
+
+  // type = clusterTile
+  clusterLevel?: number;
+  isTextVisible?: boolean;
 };
 
 export type TextLabel = {

package/src/filters/Filter.ts

@@ -1,9 +1,9 @@
 import {filterFunctions} from './FilterTypes.js';
-import {Filter, FilterLogicalOperator, Filters} from '../types.js';
-import {Feature} from 'geojson';
+import type {Filter, FilterLogicalOperator, Filters} from '../types.js';
+import type {Feature} from 'geojson';
 import {FilterType} from '../constants.js';
-import {FeatureData} from '../types-internal.js';
-import {BinaryFeature} from '@loaders.gl/schema';
+import type {FeatureData} from '../types-internal.js';
+import type {BinaryFeature} from '@loaders.gl/schema';
 
 const LOGICAL_OPERATOR_METHODS: Record<
   FilterLogicalOperator,

package/src/filters/FilterTypes.ts

@@ -1,5 +1,5 @@
 import {FilterType} from '../constants.js';
-import {FilterInterval, StringSearchOptions} from '../types.js';
+import type {FilterInterval, StringSearchOptions} from '../types.js';
 import {makeIntervalComplete} from '../utils/makeIntervalComplete.js';
 
 export type FilterFunction = (

package/src/filters/geosjonFeatures.ts

@@ -1,7 +1,7 @@
 import intersects from '@turf/boolean-intersects';
-import {FeatureCollection} from 'geojson';
-import {FeatureData} from '../types-internal.js';
-import {SpatialFilter} from '../types.js';
+import type {FeatureCollection} from 'geojson';
+import type {FeatureData} from '../types-internal.js';
+import type {SpatialFilter} from '../types.js';
 
 export function geojsonFeatures({
   geojson,

package/src/filters/tileFeatures.ts

@@ -1,10 +1,15 @@
-import {RasterTile, SpatialFilter, SpatialIndexTile, Tile} from '../types.js';
+import type {
+  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 {RasterMetadata, SpatialDataType} from '../sources/types.js';
+import type {FeatureData} from '../types-internal.js';
+import type {RasterMetadata, SpatialDataType} from '../sources/types.js';
 import {isRasterTile, tileFeaturesRaster} from './tileFeaturesRaster.js';
 import {assert} from '../utils.js';
 

package/src/filters/tileFeaturesGeometries.ts

@@ -5,7 +5,7 @@ import intersect from '@turf/intersect';
 import {transformToTileCoords} from '../utils/transformToTileCoords.js';
 import {transformTileCoordsToWGS84} from '../utils/transformTileCoordsToWGS84.js';
 import {TileFormat} from '../constants.js';
-import {
+import type {
   BBox,
   Feature,
   Geometry,
@@ -15,11 +15,11 @@ import {
   Polygon,
   Position,
 } from 'geojson';
-import {SpatialFilter, Tile} from '../types.js';
-import {TileFeatureExtractOptions} from './tileFeatures.js';
+import type {SpatialFilter, Tile} from '../types.js';
+import type {TileFeatureExtractOptions} from './tileFeatures.js';
 import {featureCollection} from '@turf/helpers';
-import {FeatureData} from '../types-internal.js';
-import {
+import type {FeatureData} from '../types-internal.js';
+import type {
   BinaryAttribute,
   BinaryFeature,
   BinaryGeometryType,

package/src/filters/tileFeaturesRaster.ts

@@ -4,9 +4,9 @@ import {
   geometryToCells,
   getResolution,
 } from 'quadbin';
-import {RasterTile, SpatialFilter, Tile} from '../types.js';
-import {FeatureData} from '../types-internal.js';
-import {
+import type {RasterTile, SpatialFilter, Tile} from '../types.js';
+import type {FeatureData} from '../types-internal.js';
+import type {
   RasterMetadata,
   RasterMetadataBand,
   SpatialDataType,

package/src/filters/tileFeaturesSpatialIndex.ts

@@ -1,11 +1,11 @@
 import {SpatialIndex} from '../constants.js';
 import {getResolution as quadbinGetResolution, geometryToCells} from 'quadbin';
 import bboxClip from '@turf/bbox-clip';
-import {SpatialFilter, SpatialIndexTile} from '../types.js';
-import {BBox, Feature} from 'geojson';
+import type {SpatialFilter, SpatialIndexTile} from '../types.js';
+import type {BBox, Feature} from 'geojson';
 import {getResolution as h3GetResolution, polygonToCells} from 'h3-js';
-import {FeatureData} from '../types-internal.js';
-import {SpatialDataType} from '../sources/types.js';
+import type {FeatureData} from '../types-internal.js';
+import type {SpatialDataType} from '../sources/types.js';
 
 export type TileFeaturesSpatialIndexOptions = {
   tiles: SpatialIndexTile[];

package/src/filters.ts

@@ -1,5 +1,5 @@
 import {FilterType} from './constants.js';
-import {Filter} from './types.js';
+import type {Filter} from './types.js';
 import {isEmptyObject} from './utils.js';
 
 const FILTER_TYPES = new Set(Object.values(FilterType));

package/src/geo.ts

@@ -4,7 +4,7 @@ import union from '@turf/union';
 import {getType} from '@turf/invariant';
 import {polygon, multiPolygon, feature, featureCollection} from '@turf/helpers';
 import type {BBox, Geometry, MultiPolygon, Polygon, Position} from 'geojson';
-import {SpatialFilter} from './types.js';
+import type {SpatialFilter} from './types.js';
 
 /**
  * Returns a {@link SpatialFilter} for a given viewport, typically obtained

package/src/index.ts

@@ -9,10 +9,10 @@ export * from './widget-sources/index.js';
 export * from './types.js';
 
 export {
-  APIErrorContext,
-  APIRequestType,
+  type APIErrorContext,
+  type APIRequestType,
   CartoAPIError,
-  QueryOptions,
+  type QueryOptions,
   buildPublicMapUrl, // Internal, but required for fetchMap().
   buildStatsUrl, // Internal, but required for fetchMap().
   query,

package/src/models/model.ts

@@ -1,5 +1,5 @@
 import {DEFAULT_GEO_COLUMN} from '../constants-internal.js';
-import {
+import type {
   Filter,
   FilterLogicalOperator,
   MapType,
@@ -7,9 +7,12 @@ import {
   SpatialFilter,
 } from '../types.js';
 import {assert, isPureObject} from '../utils.js';
-import {ModelRequestOptions, makeCall} from './common.js';
+import {type ModelRequestOptions, makeCall} from './common.js';
 import {ApiVersion} from '../constants.js';
-import {SpatialDataType, SpatialFilterPolyfillMode} from '../sources/types.js';
+import type {
+  SpatialDataType,
+  SpatialFilterPolyfillMode,
+} from '../sources/types.js';
 
 /** @privateRemarks Source: @carto/react-api */
 const AVAILABLE_MODELS = [

package/src/operations/aggregation.ts

@@ -1,5 +1,5 @@
-import {AggregationType} from '../types.js';
-import {FeatureData} from '../types-internal.js';
+import type {AggregationType} from '../types.js';
+import type {FeatureData} from '../types-internal.js';
 
 /** @privateRemarks Source: @carto/react-core */
 export type AggregationFunction = (
@@ -122,7 +122,12 @@ function min(
       Infinity
     );
   }
-  return Math.min(...(values as number[]));
+
+  let min = Number.POSITIVE_INFINITY;
+  for (const value of values as number[]) {
+    min = Math.min(min, value);
+  }
+  return min;
 }
 
 function max(
@@ -138,7 +143,12 @@ function max(
       -Infinity
     );
   }
-  return Math.max(...(values as number[]));
+
+  let max = Number.NEGATIVE_INFINITY;
+  for (const value of values as number[]) {
+    max = Math.max(max, value);
+  }
+  return max;
 }
 
 // Aux