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

package/src/fetch-map/types.ts

@@ -0,0 +1,268 @@
+import {LayerType, SCALE_TYPE} from './layer-map.js';
+import {Format, MapType, ProviderType, QueryParameters} from '../types.js';
+import {TilejsonResult, GeojsonResult, JsonResult} from '../sources/types.js';
+
+export type VisualChannelField = {
+  name: string;
+  type: string;
+  colorColumn?: string;
+};
+
+export type VisualChannels = {
+  colorField?: VisualChannelField;
+  colorScale?: SCALE_TYPE;
+
+  customMarkersField?: VisualChannelField;
+  customMarkersScale?: SCALE_TYPE;
+
+  radiusField?: VisualChannelField;
+  radiusScale?: SCALE_TYPE;
+
+  rotationScale?: SCALE_TYPE;
+  rotationField?: VisualChannelField;
+
+  sizeField?: VisualChannelField;
+  sizeScale?: SCALE_TYPE;
+
+  strokeColorField?: VisualChannelField;
+  strokeColorScale?: SCALE_TYPE;
+
+  heightField?: VisualChannelField;
+  heightScale?: SCALE_TYPE;
+
+  weightField?: VisualChannelField;
+};
+
+export type ColorRange = {
+  category: string;
+  colors: string[];
+  colorMap: string[][] | undefined;
+  name: string;
+  type: string;
+};
+
+export type CustomMarkersRange = {
+  markerMap: {
+    value: string;
+    markerUrl?: string;
+  }[];
+  othersMarker?: string;
+};
+
+export type VisConfig = {
+  filled?: boolean;
+  opacity?: number;
+  enable3d?: boolean;
+
+  colorAggregation?: any;
+  colorRange: ColorRange;
+
+  customMarkers?: boolean;
+  customMarkersRange?: CustomMarkersRange | null;
+  customMarkersUrl?: string | null;
+
+  radius: number;
+  radiusRange?: number[];
+
+  sizeAggregation?: any;
+  sizeRange?: any;
+
+  strokeColorAggregation?: any;
+  strokeOpacity?: number;
+  strokeColorRange?: ColorRange;
+
+  heightRange?: any;
+  heightAggregation?: any;
+
+  weightAggregation?: any;
+};
+
+export type TextLabel = {
+  field: VisualChannelField | null | undefined;
+  alignment?: 'center' | 'bottom' | 'top';
+  anchor?: 'middle' | 'start' | 'end';
+  size: number;
+  color?: number[];
+  offset?: [number, number];
+  outlineColor?: number[];
+};
+
+export type MapLayerConfig = {
+  columns?: Record<string, any>;
+  color?: number[];
+  label?: string;
+  dataId: string;
+  textLabel: TextLabel[];
+  visConfig: VisConfig;
+};
+
+export type MapConfigLayer = {
+  type: LayerType;
+  id: string;
+  config: MapLayerConfig;
+  visualChannels: VisualChannels;
+};
+
+export interface CustomStyle {
+  url?: string;
+  style?: any;
+  customAttribution?: string;
+}
+
+// TODO replace with more complete type from Builder
+export type KeplerMapConfig = {
+  filters: any;
+  mapState: any;
+  mapStyle: {
+    styleType: string;
+    visibleLayerGroups: Record<string, boolean>;
+  };
+  popupSettings: any;
+  visState: {
+    layers: MapConfigLayer[];
+    layerBlending: any;
+    interactionConfig: any;
+  };
+  customBaseMaps?: {
+    customStyle?: CustomStyle;
+  };
+};
+
+export type BasemapType = 'maplibre' | 'google-maps';
+
+export type Basemap = MapLibreBasemap | GoogleBasemap;
+
+export type BasemapCommon = {
+  /**
+   * Type of basemap.
+   */
+  type: BasemapType;
+
+  /**
+   * Custom attribution for style data if not provided by style definition.
+   */
+  attribution?: string;
+
+  /**
+   * Properties of the basemap. These properties are specific to the basemap type.
+   */
+  props: Record<string, any>;
+};
+
+export type MapLibreBasemap = BasemapCommon & {
+  type: 'maplibre';
+
+  /**
+   * MapLibre map properties.
+   *
+   * Meant to be passed to directly to `maplibregl.Map` object.
+   */
+  props: MapLibreBasemapProps;
+
+  /**
+   * Layer groups to be displayed in the basemap.
+   */
+  visibleLayerGroups?: Record<string, boolean>;
+
+  /**
+   * If `style` has been filtered by `visibleLayerGroups` then this property contains original style object, so user
+   * can use `applyLayerGroupFilters` again with new settings.
+   */
+  rawStyle?: string | Record<string, any>;
+};
+
+// Cherry-pick of maplibregl Map API props that are supported/provided by fetchMap interface
+export type MapLibreBasemapProps = {
+  style: string | Record<string, any>;
+  center: [number, number];
+  zoom: number;
+  pitch?: number;
+  bearing?: number;
+};
+
+export type GoogleBasemap = BasemapCommon & {
+  type: 'google-maps';
+
+  /**
+   * Google map properties.
+   *
+   * Meant to be passed to directly to `google.maps.Map` object.
+   */
+  props: GoogleBasemapProps;
+};
+
+// Cherry-pick of Google Map API props that are supported/provided by fetchMap interface
+export type GoogleBasemapProps = {
+  mapTypeId: string;
+  mapId?: string;
+  center?: {lat: number; lng: number};
+  zoom?: number;
+  tilt?: number;
+  heading?: number;
+};
+
+export 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;
+  connectionId?: string;
+  providerId: ProviderType;
+  createdAt?: string;
+  updatedAt?: string;
+  label?: string;
+  color?: string;
+  uniqueIdProperty?: string;
+  queryTemplate?: string | null;
+  name?: string | null;
+  spatialIndex?: string | null;
+  exportToBucketAvailable?: boolean;
+};
+
+export type AttributeType = 'String' | 'Number' | 'Timestamp' | 'Boolean';
+
+export type AttributeStatsBase = {
+  attribute: string;
+  type: AttributeType;
+};
+
+export type AttributeStatsNumber = AttributeStatsBase & {
+  type: 'Number';
+  min: number;
+  avg: number;
+  max: number;
+  sum: number;
+  quantiles: number[][];
+};
+
+export type AttributeStatsTimestamp = AttributeStatsBase & {
+  type: 'Timestamp';
+  min: string;
+  max: string;
+};
+
+export interface AttributeStatsStringCategory {
+  category: string;
+  frequency: number;
+}
+
+export type AttributeStatsString = AttributeStatsBase & {
+  type: 'String' | 'Boolean';
+  categories: AttributeStatsStringCategory[];
+};
+
+/**
+ * Result of getAttributeStats request to backend.
+ */
+export type AttributeStats =
+  | AttributeStatsString
+  | AttributeStatsNumber
+  | AttributeStatsTimestamp;

package/src/fetch-map/utils.ts

@@ -0,0 +1,69 @@
+import type {BinaryFeature} from '@loaders.gl/schema';
+import type {Dataset} from './types.js';
+type Properties = BinaryFeature['properties'];
+type NumericProps = BinaryFeature['numericProps'];
+
+// Returns a Proxy object that allows accessing binary data
+// as if it were JSON properties
+export function createBinaryProxy(
+  data: {numericProps: NumericProps; properties: Properties[]},
+  index: number
+) {
+  const {properties, numericProps} = data;
+  return new Proxy(properties[index] || {}, {
+    get(target, property) {
+      if (property in numericProps) {
+        return numericProps[property as string].value[index];
+      }
+      return target[property as any];
+    },
+
+    has(target, property) {
+      return property in numericProps || property in target;
+    },
+
+    ownKeys(target) {
+      return [...Object.keys(numericProps), ...Reflect.ownKeys(target)];
+    },
+
+    getOwnPropertyDescriptor() {
+      return {enumerable: true, configurable: true};
+    },
+  });
+}
+
+export function scaleIdentity() {
+  let unknown: any;
+
+  function scale(x: any) {
+    return x === null ? unknown : x;
+  }
+
+  scale.invert = scale;
+
+  scale.domain = scale.range = (d: any) => d;
+
+  scale.unknown = (u: any) => {
+    if (u) {
+      unknown = u;
+    }
+
+    return unknown;
+  };
+
+  scale.copy = () => {
+    const scaleCopy = scaleIdentity();
+    scaleCopy.unknown(unknown);
+    return scaleCopy;
+  };
+
+  return scale;
+}
+
+export function isRemoteCalculationSupported(dataset: Dataset) {
+  if (dataset?.type === 'tileset' || dataset.providerId === 'databricks') {
+    return false;
+  }
+
+  return true;
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from './client.js';
 export * from './constants.js';
 export * from './deck/index.js';
+export * from './fetch-map/index.js';
 export * from './filters.js';
 export * from './geo.js';
 export * from './sources/index.js';

package/src/models/model.ts

@@ -40,8 +40,6 @@ export interface ModelSource {
   spatialDataColumn?: string;
   spatialDataType?: SpatialDataType;
   spatialFiltersMode?: SpatialFilterPolyfillMode;
-  /** original resolution of the spatial index data as stored in the DW */
-  dataResolution?: number;
 }
 
 const {V3} = ApiVersion;

package/src/sources/types.ts

@@ -118,7 +118,10 @@ export type AggregationOptions = {
   aggregationResLevel?: number;
 
   /**
-   * Original resolution of the spatial index data as stored in the DW
+   * Deprecated parameter previously used for H3 and Quadbin widgets. Now has
+   * no effect and will be removed in a future version.
+   * @deprecated Parameter has no effect.
+   * @todo TODO(v0.5): Remove spatialIndexReferenceViewState parameter.
    */
   dataResolution?: number;
 };

package/src/types.ts

@@ -12,6 +12,16 @@ export type Format = 'json' | 'geojson' | 'tilejson';
 /** @privateRemarks Source: @carto/constants, @deck.gl/carto */
 export type MapType = 'boundary' | 'query' | 'table' | 'tileset' | 'raster';
 
+/** @privateRemarks Source: cloud-native */
+export type ProviderType =
+  | 'bigquery'
+  | 'postgres'
+  | 'snowflake'
+  | 'redshift'
+  | 'databricks'
+  | 'carto'
+  | 'carto_dw';
+
 /**
  * Alias for GeoJSON 'BBox' type, semantically representing a viewport.
  * Order of values is "west", "south", "east", "north".

package/src/widget-sources/widget-source.ts

@@ -22,7 +22,6 @@ import {getClient} from '../client.js';
 import {ModelSource} from '../models/model.js';
 import {SourceOptions} from '../sources/index.js';
 import {ApiVersion, DEFAULT_API_BASE_URL} from '../constants.js';
-import {AggregationOptions} from '../sources/types.js';
 
 export interface WidgetSourceProps extends Omit<SourceOptions, 'filters'> {
   apiVersion?: ApiVersion;
@@ -80,7 +79,6 @@ export abstract class WidgetSource<Props extends WidgetSourceProps> {
       filtersLogicalOperator: props.filtersLogicalOperator,
       spatialDataType: props.spatialDataType,
       spatialDataColumn: props.spatialDataColumn,
-      dataResolution: (props as Partial<AggregationOptions>).dataResolution,
     };
   }