@carto/api-client 0.5.0-alpha.9 → 0.5.0

package/package.json

@@ -8,8 +8,11 @@
   "homepage": "https://github.com/CartoDB/carto-api-client#readme",
   "author": "Don McCurdy <donmccurdy@carto.com>",
   "packageManager": "yarn@4.3.1",
-  "version": "0.5.0-alpha.9",
+  "version": "0.5.0",
   "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -46,7 +49,7 @@
     "format:check": "prettier \"**/*.{cjs,html,js,json,md,ts}\" --check",
     "clean": "rimraf build/*",
     "postversion": "yarn postversion:check && yarn postversion:commit && yarn postversion:push",
-    "postversion:check": "yarn lint && yarn test",
+    "postversion:check": "yarn lint && yarn format:check && yarn test",
     "postversion:commit": "node scripts/postversion-commit.js",
     "postversion:push": "git push && git push --tags",
     "prepublish": "yarn lint && yarn test",
@@ -60,56 +63,69 @@
   ],
   "dependencies": {
     "@loaders.gl/schema": "^4.3.3",
+    "@types/geojson": "^7946.0.16",
+    "d3-format": "^3.1.0",
+    "d3-scale": "^4.0.2",
+    "h3-js": "4.1.0",
+    "quadbin": "^0.4.1-alpha.0"
+  },
+  "devDependencies": {
+    "@deck.gl/aggregation-layers": "~9.1.6",
+    "@deck.gl/carto": "~9.1.6",
+    "@deck.gl/core": "~9.1.6",
+    "@deck.gl/extensions": "~9.1.6",
+    "@deck.gl/geo-layers": "~9.1.6",
+    "@deck.gl/google-maps": "~9.1.6",
+    "@deck.gl/layers": "~9.1.6",
+    "@deck.gl/mapbox": "~9.1.6",
+    "@deck.gl/mesh-layers": "~9.1.6",
+    "@eslint/js": "^9.21.0",
+    "@googlemaps/js-api-loader": "^1.16.6",
+    "@lit/react": "^1.0.7",
+    "@lit/task": "^1.0.2",
+    "@loaders.gl/core": "^4.3.3",
+    "@luma.gl/core": "~9.1.5",
+    "@luma.gl/engine": "~9.1.5",
+    "@luma.gl/shadertools": "~9.1.5",
+    "@luma.gl/webgl": "~9.1.5",
     "@turf/bbox-clip": "^7.2.0",
     "@turf/bbox-polygon": "^7.2.0",
     "@turf/boolean-equal": "^7.2.0",
     "@turf/boolean-intersects": "^7.2.0",
     "@turf/boolean-within": "^7.2.0",
+    "@turf/buffer": "^7.2.0",
     "@turf/helpers": "^7.2.0",
     "@turf/intersect": "^7.2.0",
     "@turf/invariant": "^7.2.0",
-    "@turf/union": "^7.2.0",
-    "@types/geojson": "^7946.0.16",
-    "h3-js": "4.1.0"
-  },
-  "devDependencies": {
-    "@deck.gl/aggregation-layers": "~9.1.0",
-    "@deck.gl/carto": "~9.1.0",
-    "@deck.gl/core": "~9.1.0",
-    "@deck.gl/extensions": "~9.1.0",
-    "@deck.gl/geo-layers": "~9.1.0",
-    "@deck.gl/layers": "~9.1.0",
-    "@deck.gl/mesh-layers": "~9.1.0",
-    "@eslint/js": "^9.20.0",
-    "@lit/react": "^1.0.7",
-    "@lit/task": "^1.0.2",
-    "@loaders.gl/core": "^4.3.3",
-    "@luma.gl/core": "~9.1.0",
-    "@luma.gl/engine": "~9.1.0",
-    "@luma.gl/shadertools": "~9.1.0",
-    "@turf/buffer": "^7.2.0",
     "@turf/random": "^7.2.0",
+    "@turf/union": "^7.2.0",
+    "@types/d3-format": "^3.0.4",
+    "@types/d3-scale": "^4.0.9",
     "@types/json-schema": "^7.0.15",
     "@types/react": "^18.3.18",
     "@types/semver": "^7.5.8",
-    "@vitest/coverage-istanbul": "^3.0.5",
+    "@vitest/coverage-istanbul": "^3.0.9",
     "@webcomponents/webcomponentsjs": "^2.8.0",
     "concurrently": "^9.1.2",
     "echarts": "^5.6.0",
-    "eslint": "^9.20.1",
+    "eslint": "^9.22.0",
     "lit": "^3.2.1",
     "lit-analyzer": "^2.0.3",
-    "maplibre-gl": "^5.1.0",
-    "prettier": "^3.4.2",
+    "maplibre-gl": "^5.2.0",
+    "prettier": "^3.5.3",
+    "resolve-package-path": "^4.0.3",
     "rimraf": "^6.0.1",
     "semver": "^7.7.1",
     "thenby": "^1.3.4",
     "tinybench": "^3.1.1",
     "tsup": "^8.3.6",
-    "typescript": "~5.7.3",
-    "typescript-eslint": "^8.24.0",
-    "vite": "^6.1.0",
-    "vitest": "3.0.5"
+    "typescript": "~5.8.2",
+    "typescript-eslint": "^8.26.1",
+    "vite": "^6.2.2",
+    "vitest": "3.0.9"
   },
-  "stableVersion": "0.4.6"
+  "resolutions": {
+    "@carto/api-client": "portal:./",
+    "rollup": "^4.20.0"
+  }
 }

package/src/api/query.ts

@@ -11,6 +11,7 @@ import type {
 import {buildQueryUrl} from './endpoints.js';
 import {requestWithParameters} from './request-with-parameters.js';
 import {APIErrorContext} from './carto-api-error.js';
+import {getClient} from '../client.js';
 
 export type QueryOptions = SourceOptions & QuerySourceOptions;
 type UrlParameters = {q: string; queryParameters?: string};
@@ -20,8 +21,8 @@ export const query = async function (
 ): Promise<QueryResult> {
   const {
     apiBaseUrl = SOURCE_DEFAULTS.apiBaseUrl,
-    clientId = SOURCE_DEFAULTS.clientId,
     maxLengthURL = SOURCE_DEFAULTS.maxLengthURL,
+    clientId = getClient(),
     localCache,
     connectionName,
     sqlQuery,

package/src/constants-internal.ts

@@ -13,6 +13,12 @@ export const DEFAULT_MAX_LENGTH_URL = 7000;
 /** @privateRemarks Source: @deck.gl/carto */
 export const DEFAULT_TILE_RESOLUTION = 0.5;
 
+/**
+ * @todo TODO(v0.5): Update DEFAULT_TILE_RESOLUTION and remove this constant.
+ * @internal
+ */
+export const REDUCED_QUERIES_TILE_RESOLUTION = 1;
+
 /**
  * @privateRemarks Source: @deck.gl/carto
  * @internal
@@ -24,3 +30,7 @@ export const DEFAULT_AGGREGATION_RES_LEVEL_H3 = 4;
  * @internal
  */
 export const DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN = 6;
+
+/** @internal */
+export const DEFAULT_AGGREGATION_EXP_ALIAS = '__aggregationValue';
+export const DEFAULT_AGGREGATION_EXP = `1 AS ${DEFAULT_AGGREGATION_EXP_ALIAS}`;

package/src/constants.ts

@@ -43,7 +43,6 @@ export enum TileFormat {
 /** @privateRemarks Source: @carto/react-core */
 export enum SpatialIndex {
   H3 = 'h3',
-  S2 = 's2',
   QUADBIN = 'quadbin',
 }
 
@@ -56,3 +55,8 @@ export enum Provider {
   DATABRICKS = 'databricks',
   DATABRICKS_REST = 'databricksRest',
 }
+
+export const SpatialIndexColumn = Object.freeze({
+  [SpatialIndex.H3]: ['h3', 'hex', 'h3id', 'hex_id', 'h3hex'],
+  [SpatialIndex.QUADBIN]: ['quadbin'],
+});

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

@@ -8,6 +8,16 @@ type TimeFilter = Filters['string'][FilterType.TIME] & {
   params?: {offsetBy?: number};
 };
 
+/**
+ * deck.gl's DataFilterExtension supports GPU filtering with 1–4 values. We
+ * allocate filters[0] to generic filters and filters[1] to time filters.
+ *
+ * getFilterValue() _must_ return an array of the same size as the filterSize
+ * used to initialize the DataFilterExtension. We document that users must use
+ * filterSize=4 for compatibility with @link {getDataFilterExtensionProps}.
+ */
+const DEFAULT_FILTER_SIZE = 4;
+
 /** @experimental Prefer type definition from deck.gl. */
 export type _DataFilterExtensionProps = {
   filterRange: number[][];
@@ -17,22 +27,30 @@ export type _DataFilterExtensionProps = {
 
 /**
  * Creates props for DataFilterExtension, from `@deck.gl/extensions`, given
- * a set of filters.
+ * a set of filters. Requires that DataFilterExtension is initialized with
+ * filterSize=4, where the CARTO filters will occupy the first two slots.
+ *
+ * @example To create a deck.gl layer with GPU data filtering:
+ * ```typescript
+ * import {DataFilterExtension} from '@deck.gl/extensions';
+ * import {VectorTileLayer} from '@deck.gl/layers';
+ * import {getDataFilterExtensionProps} from '@carto/api-client';
  *
- * @privateRemarks DataFilterExtension accepts up to 4 values to filter. This
- *  implementation uses the 1st for all filters except the time filter, and the
- *  2nd for the time filter.
+ * const layer = new VectorTileLayer({
+ *  data: data,
+ *  extensions: [new DataFilterExtension({filterSize: 4})],
+ *  ...getDataFilterExtensionProps(filters),
+ * });
+ * ```
  */
 export function getDataFilterExtensionProps(
   filters: Filters,
-  filtersLogicalOperator?: FilterLogicalOperator,
-  filterSize?: 0 | 1 | 2 | 3 | 4
+  filtersLogicalOperator?: FilterLogicalOperator
 ): _DataFilterExtensionProps {
-  filterSize ??= 4;
   const {filtersWithoutTimeType, timeColumn, timeFilter} =
     getFiltersByType(filters);
   return {
-    filterRange: getFilterRange(timeFilter, filterSize),
+    filterRange: getFilterRange(timeFilter, DEFAULT_FILTER_SIZE),
     updateTriggers: getUpdateTriggers(
       filtersWithoutTimeType,
       timeColumn,
@@ -42,7 +60,7 @@ export function getDataFilterExtensionProps(
       filtersWithoutTimeType,
       timeColumn,
       timeFilter,
-      filterSize,
+      DEFAULT_FILTER_SIZE,
       filtersLogicalOperator
     ),
   };

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

@@ -0,0 +1,159 @@
+import {CartoAPIError, APIErrorContext} from '../api/index.js';
+import {GoogleBasemapProps} from './types.js';
+
+const cartoStyleUrlTemplate =
+  'https://basemaps.cartocdn.com/gl/{basemap}-gl-style/style.json';
+
+export const CARTO_MAP_STYLES = ['positron', 'dark-matter', 'voyager'];
+
+export const GOOGLE_BASEMAPS: Record<string, GoogleBasemapProps> = {
+  roadmap: {
+    mapTypeId: 'roadmap',
+    mapId: '3754c817b510f791',
+  },
+  'google-positron': {
+    mapTypeId: 'roadmap',
+    mapId: 'ea84ae4203ef21cd',
+  },
+  'google-dark-matter': {
+    mapTypeId: 'roadmap',
+    mapId: '2fccc3b36c22a0e2',
+  },
+  'google-voyager': {
+    mapTypeId: 'roadmap',
+    mapId: '885caf1e15bb9ef2',
+  },
+  satellite: {
+    mapTypeId: 'satellite',
+  },
+  hybrid: {
+    mapTypeId: 'hybrid',
+  },
+  terrain: {
+    mapTypeId: 'terrain',
+  },
+};
+
+type StyleLayerGroupSlug =
+  | 'label'
+  | 'road'
+  | 'border'
+  | 'building'
+  | 'water'
+  | 'land';
+type StyleLayerGroup = {
+  slug: StyleLayerGroupSlug;
+  filter: (layer: any) => boolean;
+  defaultVisibility: boolean;
+};
+
+export const STYLE_LAYER_GROUPS: StyleLayerGroup[] = [
+  {
+    slug: 'label',
+    filter: ({id}: {id: string}) =>
+      Boolean(
+        id.match(
+          /(?=(label|_label|place-|place_|poi-|poi_|watername_|roadname_|housenumber))/
+        )
+      ),
+    defaultVisibility: true,
+  },
+  {
+    slug: 'road',
+    filter: ({id}: {id: string}) =>
+      Boolean(id.match(/(?=(road|railway|tunnel|street|bridge))(?!.*label)/)),
+    defaultVisibility: true,
+  },
+  {
+    slug: 'border',
+    filter: ({id}: {id: string}) =>
+      Boolean(id.match(/border|boundaries|boundary_/)),
+    defaultVisibility: false,
+  },
+  {
+    slug: 'building',
+    filter: ({id}: {id: string}) => Boolean(id.match(/building/)),
+    defaultVisibility: true,
+  },
+  {
+    slug: 'water',
+    filter: ({id}: {id: string}) =>
+      Boolean(id.match(/(?=(water|stream|ferry))/)),
+    defaultVisibility: true,
+  },
+  {
+    slug: 'land',
+    filter: ({id}: {id: string}) =>
+      Boolean(
+        id.match(/(?=(parks|landcover|industrial|sand|hillshade|park_))/)
+      ),
+    defaultVisibility: true,
+  },
+];
+
+export function applyLayerGroupFilters(
+  style: any,
+  visibleLayerGroups: Record<StyleLayerGroupSlug, boolean>
+) {
+  if (!Array.isArray(style?.layers)) {
+    return style;
+  }
+
+  const removedLayerFilters = STYLE_LAYER_GROUPS.filter(
+    (lg) => !visibleLayerGroups[lg.slug]
+  ).map((lg) => lg.filter);
+
+  const visibleLayers = style.layers.filter((layer: any) =>
+    removedLayerFilters.every((match) => !match(layer))
+  );
+
+  return {
+    ...style,
+    layers: visibleLayers,
+  };
+}
+
+export function someLayerGroupsDisabled(
+  visibleLayerGroups?: Record<StyleLayerGroupSlug, boolean>
+) {
+  return (
+    visibleLayerGroups &&
+    Object.values(visibleLayerGroups).every(Boolean) === false
+  );
+}
+
+export function getStyleUrl(styleType: string) {
+  return cartoStyleUrlTemplate.replace('{basemap}', styleType);
+}
+
+export async function fetchStyle({
+  styleUrl,
+  errorContext,
+}: {
+  styleUrl: string;
+  errorContext?: APIErrorContext;
+}) {
+  /* global fetch */
+  let response: Response | undefined;
+  return await fetch(styleUrl, {mode: 'cors'})
+    .then((res) => {
+      response = res;
+      return res.json();
+    })
+    .catch((error) => {
+      throw new CartoAPIError(
+        error,
+        {...errorContext, requestType: 'Basemap style'},
+        response
+      );
+    });
+}
+
+export default {
+  VOYAGER: getStyleUrl('voyager'),
+  POSITRON: getStyleUrl('positron'),
+  DARK_MATTER: getStyleUrl('dark-matter'),
+  VOYAGER_NOLABELS: getStyleUrl('voyager-nolabels'),
+  POSITRON_NOLABELS: getStyleUrl('positron-nolabels'),
+  DARK_MATTER_NOLABELS: getStyleUrl('dark-matter-nolabels'),
+} as const;

package/src/fetch-map/basemap.ts

@@ -0,0 +1,120 @@
+import {
+  GOOGLE_BASEMAPS,
+  CARTO_MAP_STYLES,
+  applyLayerGroupFilters,
+  fetchStyle,
+  getStyleUrl,
+  someLayerGroupsDisabled,
+} from './basemap-styles.js';
+import {Basemap, KeplerMapConfig, MapLibreBasemapProps} from './types.js';
+import {APIErrorContext} from '../api/index.js';
+
+const CUSTOM_STYLE_ID_PREFIX = 'custom:';
+const DEFAULT_CARTO_STYLE = 'positron';
+
+// Subset of type from @deck.gl/core to avoid adding dependency
+type MapViewState = {
+  /** Longitude of the map center */
+  longitude: number;
+  /** Latitude of the map center */
+  latitude: number;
+  /** Zoom level */
+  zoom: number;
+  /** Pitch (tilt) of the map, in degrees. `0` looks top down */
+  pitch?: number;
+  /** Bearing (rotation) of the map, in degrees. `0` is north up */
+  bearing?: number;
+};
+
+function mapLibreViewpros(
+  config: KeplerMapConfig
+): Omit<MapLibreBasemapProps, 'style'> {
+  const {longitude, latitude, ...rest} = config.mapState as MapViewState;
+  return {
+    center: [longitude, latitude],
+    ...rest,
+  };
+}
+
+/**
+ * Get basemap properties for Carto map.
+ *
+ * For maplibre-based basemaps it returns style or style URL that can be used with  `maplibregl.Map` compatible component.
+ *  * style url is returned for non-filtered standard Carto basemaps or if user used style URL directly in configuration
+ *  * filtered style object returned for Carto basemaps with layer groups filtered
+ *
+ * For Google-maps base maps, it returns options that can be used with `google.maps.Map` constructor.
+ */
+export async function fetchBasemapProps({
+  config,
+  errorContext,
+
+  applyLayerFilters = true,
+}: {
+  config: KeplerMapConfig;
+
+  /** By default `fetchBasemapProps` applies layers filters to style. Set this to `false` to disable it. */
+  applyLayerFilters?: boolean;
+  errorContext?: APIErrorContext;
+}): Promise<Basemap | null> {
+  const {mapStyle} = config;
+  const styleType = mapStyle.styleType || DEFAULT_CARTO_STYLE;
+  if (styleType.startsWith(CUSTOM_STYLE_ID_PREFIX)) {
+    const currentCustomStyle = config.customBaseMaps?.customStyle;
+    if (currentCustomStyle) {
+      return {
+        type: 'maplibre',
+        props: {
+          style: currentCustomStyle.style || currentCustomStyle.url,
+          ...mapLibreViewpros(config),
+        },
+        attribution: currentCustomStyle.customAttribution,
+      };
+    }
+  }
+
+  if (CARTO_MAP_STYLES.includes(styleType)) {
+    const {visibleLayerGroups} = mapStyle;
+    const styleUrl = getStyleUrl(styleType);
+    let style = styleUrl;
+    let rawStyle = styleUrl;
+    if (
+      applyLayerFilters &&
+      visibleLayerGroups &&
+      someLayerGroupsDisabled(visibleLayerGroups)
+    ) {
+      rawStyle = await fetchStyle({styleUrl, errorContext});
+      style = applyLayerGroupFilters(rawStyle, visibleLayerGroups);
+    }
+    return {
+      type: 'maplibre',
+      props: {
+        style,
+        ...mapLibreViewpros(config),
+      },
+      visibleLayerGroups,
+      rawStyle,
+    };
+  }
+  const googleBasemapDef = GOOGLE_BASEMAPS[styleType];
+  if (googleBasemapDef) {
+    const {mapState} = config;
+    return {
+      type: 'google-maps',
+      props: {
+        ...googleBasemapDef,
+        center: {lat: mapState.latitude, lng: mapState.longitude},
+        zoom: mapState.zoom + 1,
+        tilt: mapState.pitch,
+        heading: mapState.bearing,
+      },
+    };
+  }
+  return {
+    type: 'maplibre',
+    props: {
+      style: getStyleUrl(DEFAULT_CARTO_STYLE),
+      ...mapLibreViewpros(config),
+    },
+  };
+}