@carto/api-client 0.4.9-alpha.0 → 0.4.10-alpha.0

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),
+    },
+  };
+}

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

@@ -0,0 +1,331 @@
+import {TilejsonResult} from '../sources/index.js';
+
+import {DEFAULT_API_BASE_URL} from '../constants.js';
+
+import {
+  APIErrorContext,
+  CartoAPIError,
+  buildPublicMapUrl,
+  buildStatsUrl,
+  requestWithParameters,
+} from '../api/index.js';
+
+import {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 {isRemoteCalculationSupported} from './utils.js';
+
+/* global clearInterval, setInterval, URL */
+async function _fetchMapDataset(
+  dataset: Dataset,
+  filters: Filters,
+  context: _FetchMapContext
+) {
+  const {connectionName} = dataset;
+  const cache: {value?: number} = {};
+  const configuredSource = configureSource({
+    dataset,
+    filters: isRemoteCalculationSupported(dataset) ? filters : undefined,
+    options: {
+      ...context,
+      connection: connectionName,
+      headers: context.headers,
+      accessToken: context.accessToken!,
+      apiBaseUrl: context.apiBaseUrl,
+      maxLengthURL: context.maxLengthURL,
+    },
+  });
+  dataset.data = await configuredSource;
+
+  let cacheChanged = true;
+  if (cache.value) {
+    cacheChanged = dataset.cache !== cache.value;
+    dataset.cache = cache.value;
+  }
+
+  return cacheChanged;
+}
+
+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,
+  };
+  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, keplerMapConfig}: {datasets: Dataset[]; keplerMapConfig: any},
+  context: _FetchMapContext
+) {
+  const {filters} = keplerMapConfig.config as KeplerMapConfig;
+  const promises = datasets.map((dataset) =>
+    _fetchMapDataset(dataset, filters[dataset.id], 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().
+ */
+type _FetchMapContext = {apiBaseUrl: string} & Pick<
+  FetchMapOptions,
+  'accessToken' | 'clientId' | 'headers' | 'maxLengthURL'
+>;
+
+export type FetchMapResult = ParseMapResult & {
+  /**
+   * Basemap properties.
+   */
+  basemap: Basemap | null;
+  stopAutoRefresh?: () => void;
+};
+
+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,
+  };
+
+  // Periodically check if the data has changed. Note that this
+  // will not update when a map is published.
+  let stopAutoRefresh: (() => void) | undefined;
+  if (autoRefresh) {
+    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: string}) => type === 'geojson' || type === 'point'
+  );
+  const geojsonDatasetIds = geojsonLayers.map(
+    ({config}: {config: any}) => config.dataId
+  );
+  map.datasets.forEach((dataset: any) => {
+    if (geojsonDatasetIds.includes(dataset.id)) {
+      const {config} = geojsonLayers.find(
+        ({config}: {config: any}) => 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: any) => {
+    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 as FetchMapResult;
+}

package/src/fetch-map/index.ts

@@ -0,0 +1,13 @@
+export {default as BASEMAP} from './basemap-styles.js';
+export {fetchMap} from './fetch-map.js';
+export type {FetchMapOptions, FetchMapResult} from './fetch-map.js';
+export type {
+  Basemap,
+  MapLibreBasemap,
+  GoogleBasemap,
+  KeplerMapConfig,
+} from './types.js';
+
+export * from './basemap.js';
+export * from './layer-map.js';
+export * from './parse-map.js';