@carto/api-client 0.5.5-alpha.0 → 0.5.6-alpha.0

package/package.json

@@ -8,7 +8,7 @@
   "homepage": "https://github.com/CartoDB/carto-api-client#readme",
   "author": "Don McCurdy <donmccurdy@carto.com>",
   "packageManager": "yarn@4.3.1",
-  "version": "0.5.5-alpha.0",
+  "version": "0.5.6-alpha.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

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

@@ -1,4 +1,4 @@
-import {deviation, extent, groupSort, median, variance} from 'd3-array';
+import {extent, groupSort} from 'd3-array';
 import {rgb} from 'd3-color';
 import {
   scaleLinear,
@@ -38,7 +38,24 @@ import type {
 import type {ProviderType, SchemaField} from '../types.js';
 import {DEFAULT_AGGREGATION_EXP_ALIAS} from '../constants-internal.js';
 
-const SCALE_FUNCS: Record<string, () => any> = {
+export type D3Scale = {
+  domain: (d?: any) => any[];
+  range: (d?: any) => any[];
+  unknown?: (d?: string) => any;
+} & ((d: any) => any);
+type D3ScaleFactory = () => D3Scale;
+
+export type ScaleType =
+  | 'linear'
+  | 'ordinal'
+  | 'log'
+  | 'point'
+  | 'quantile'
+  | 'quantize'
+  | 'sqrt'
+  | 'custom'
+  | 'identity';
+const SCALE_FUNCS: Record<ScaleType, D3ScaleFactory> = {
   linear: scaleLinear,
   ordinal: scaleOrdinal,
   log: scaleLog,
@@ -49,7 +66,6 @@ const SCALE_FUNCS: Record<string, () => any> = {
   custom: scaleThreshold,
   identity: scaleIdentity,
 };
-export type SCALE_TYPE = keyof typeof SCALE_FUNCS;
 
 function identity<T>(v: T): T {
   return v;
@@ -57,30 +73,12 @@ function identity<T>(v: T): T {
 
 const UNKNOWN_COLOR = '#868d91';
 
-export const AGGREGATION: Record<string, string> = {
-  average: 'MEAN',
-  maximum: 'MAX',
-  minimum: 'MIN',
-  sum: 'SUM',
-};
-
 export const OPACITY_MAP: Record<string, string> = {
   getFillColor: 'opacity',
   getLineColor: 'strokeOpacity',
   getTextColor: 'opacity',
 };
 
-const AGGREGATION_FUNC: Record<string, (values: any, accessor: any) => any> = {
-  'count unique': (values: any, accessor: any) =>
-    groupSort(values, (v) => v.length, accessor).length,
-  median,
-  // Unfortunately mode() is only available in d3-array@3+ which is ESM only
-  mode: (values: any, accessor: any) =>
-    groupSort(values, (v) => v.length, accessor).pop(),
-  stddev: deviation,
-  variance,
-};
-
 const hexToRGBA = (c: any) => {
   const {r, g, b, opacity} = rgb(c);
   return [r, g, b, 255 * opacity];
@@ -197,7 +195,7 @@ export function getLayerProps(
 
 function domainFromAttribute(
   attribute: any,
-  scaleType: SCALE_TYPE,
+  scaleType: ScaleType,
   scaleLength: number
 ) {
   if (scaleType === 'ordinal' || scaleType === 'point') {
@@ -219,7 +217,7 @@ function domainFromAttribute(
   return [min, attribute.max];
 }
 
-function domainFromValues(values: any, scaleType: SCALE_TYPE) {
+function domainFromValues(values: any, scaleType: ScaleType) {
   if (scaleType === 'ordinal' || scaleType === 'point') {
     return groupSort(
       values,
@@ -238,7 +236,7 @@ function domainFromValues(values: any, scaleType: SCALE_TYPE) {
 function calculateDomain(
   data: any,
   name: any,
-  scaleType: SCALE_TYPE,
+  scaleType: ScaleType,
   scaleLength?: number
 ) {
   if (data.tilestats) {
@@ -295,23 +293,13 @@ function findAccessorKey(keys: string[], properties: any): string[] {
   return keys;
 }
 
-export function getColorValueAccessor(
-  {name}: VisualChannelField,
-  colorAggregation: string,
-  data: any
-) {
-  const aggregator = AGGREGATION_FUNC[colorAggregation];
-  const accessor = (values: any) => aggregator(values, (p: any) => p[name]);
-  return normalizeAccessor(accessor, data);
-}
-
 export function getColorAccessor(
   {name, colorColumn}: VisualChannelField,
-  scaleType: SCALE_TYPE,
+  scaleType: ScaleType,
   {aggregation, range}: {aggregation: string; range: any},
   opacity: number | undefined,
   data: any
-) {
+): {accessor: any; scale: any} {
   const scale = calculateLayerScale(
     colorColumn || name,
     scaleType,
@@ -329,12 +317,12 @@ export function getColorAccessor(
     const {r, g, b} = rgb(scale(propertyValue));
     return [r, g, b, propertyValue === null ? 0 : alpha];
   };
-  return normalizeAccessor(accessor, data);
+  return {accessor: normalizeAccessor(accessor, data), scale};
 }
 
 function calculateLayerScale(
   name: any,
-  scaleType: SCALE_TYPE,
+  scaleType: ScaleType,
   range: any,
   data: any
 ) {
@@ -362,7 +350,7 @@ function calculateLayerScale(
 
   scale.domain(domain);
   scale.range(scaleColor);
-  scale.unknown(UNKNOWN_COLOR);
+  scale.unknown!(UNKNOWN_COLOR);
 
   return scale;
 }
@@ -436,17 +424,17 @@ export function negateAccessor(accessor: Accessor): Accessor {
 
 export function getSizeAccessor(
   {name}: VisualChannelField,
-  scaleType: SCALE_TYPE | undefined,
+  scaleType: ScaleType | undefined,
   aggregation: string | null | undefined,
   range: Iterable<Range> | null | undefined,
   data: any
-) {
-  const scale = scaleType ? SCALE_FUNCS[scaleType as any]() : identity;
+): {accessor: any; scale: any} {
+  const scale = scaleType ? SCALE_FUNCS[scaleType]() : identity;
   if (scaleType) {
     if (aggregation !== 'count') {
-      scale.domain(calculateDomain(data, name, scaleType));
+      (scale as D3Scale).domain(calculateDomain(data, name, scaleType));
     }
-    scale.range(range);
+    (scale as D3Scale).range(range);
   }
 
   let accessorKeys = getAccessorKeys(name, aggregation);
@@ -457,7 +445,7 @@ export function getSizeAccessor(
     const propertyValue = properties[accessorKeys[0]];
     return scale(propertyValue);
   };
-  return normalizeAccessor(accessor, data);
+  return {accessor: normalizeAccessor(accessor, data), scale};
 }
 
 const FORMATS: Record<string, (value: any) => string> = {

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

@@ -5,7 +5,6 @@ import {
   getDefaultAggregationExpColumnAliasForLayerType,
   getLayerProps,
   getColorAccessor,
-  getColorValueAccessor,
   getSizeAccessor,
   getTextAccessor,
   opacityToAlpha,
@@ -13,11 +12,12 @@ import {
   negateAccessor,
   getMaxMarkerSize,
   type LayerType,
-  AGGREGATION,
   OPACITY_MAP,
   TEXT_NUMBER_FORMATTER,
   TEXT_LABEL_INDEX,
   TEXT_OUTLINE_OPACITY,
+  type D3Scale,
+  type ScaleType,
 } from './layer-map.js';
 
 import {assert, isEmptyObject} from '../utils.js';
@@ -29,13 +29,22 @@ import type {
   VisConfig,
   MapConfigLayer,
   Dataset,
+  VisualChannelField,
 } from './types.js';
 import {isRemoteCalculationSupported} from './utils.js';
 
+export type Scale = {
+  field: VisualChannelField;
+  domain: string[] | number[];
+  range: string[] | number[];
+  type: ScaleType;
+};
+
 export type LayerDescriptor = {
   type: LayerType;
   props: Record<string, any>;
   filters?: Filters;
+  scales: Record<ScaleKey, Scale>;
 };
 
 export type ParseMapResult = {
@@ -94,6 +103,14 @@ export function parseMap(json: any) {
 
           const styleProps = createStyleProps(config, propMap);
 
+          const {channelProps, scales} = createChannelProps(
+            id,
+            type,
+            config,
+            visualChannels,
+            data,
+            dataset
+          );
           const layer: LayerDescriptor = {
             type,
             filters:
@@ -106,20 +123,14 @@ export function parseMap(json: any) {
               ...defaultProps,
               ...createInteractionProps(interactionConfig),
               ...styleProps,
-              ...createChannelProps(
-                id,
-                type,
-                config,
-                visualChannels,
-                data,
-                dataset
-              ), // Must come after style
+              ...channelProps,
               ...createParametersProp(
                 layerBlending,
                 styleProps.parameters || {}
               ), // Must come after style
               ...createLoadOptions(token),
             },
+            scales,
           };
           return layer;
         } catch (e: any) {
@@ -205,79 +216,67 @@ function createStyleProps(config: MapLayerConfig, mapping: any) {
   return result;
 }
 
+function domainAndRangeFromScale(
+  scale: D3Scale
+): Pick<Scale, 'domain' | 'range'> {
+  return {
+    domain: scale.domain(),
+    range: scale.range(),
+  };
+}
+
+export type ScaleKey =
+  | 'fillColor'
+  | 'pointRadius'
+  | 'lineColor'
+  | 'elevation'
+  | 'weight';
+
 function createChannelProps(
   id: string,
-  type: string,
+  layerType: LayerType,
   config: MapLayerConfig,
   visualChannels: VisualChannels,
   data: any,
   dataset: Dataset
-) {
+): {channelProps: Record<string, any>; scales: Record<ScaleKey, Scale>} {
   const {
     colorField,
     colorScale,
     radiusField,
     radiusScale,
-    sizeField,
-    sizeScale,
     strokeColorField,
     strokeColorScale,
     weightField,
   } = visualChannels;
-  let {heightField, heightScale} = visualChannels;
-  if (type === 'hexagonId') {
-    heightField = sizeField;
-    heightScale = sizeScale;
-  }
+  const {heightField, heightScale} = visualChannels;
   const {textLabel, visConfig} = config;
   const result: Record<string, any> = {};
 
-  if (type === 'grid' || type === 'hexagon') {
-    result.colorScaleType = colorScale;
-    if (colorField) {
-      const {colorAggregation} = config.visConfig;
-      if (!AGGREGATION[colorAggregation]) {
-        result.getColorValue = getColorValueAccessor(
-          colorField,
-          colorAggregation,
-          data
-        );
-      } else {
-        result.getColorWeight = (d: any) => d[colorField.name];
-      }
-    }
-  } else if (colorField) {
+  const scales: Record<string, Scale> = {};
+
+  if (colorField) {
     const {colorAggregation: aggregation, colorRange: range} = visConfig;
-    result.getFillColor = getColorAccessor(
+    const {accessor, scale} = getColorAccessor(
       colorField,
-      // @ts-ignore
-      colorScale,
+      colorScale!,
       {aggregation, range},
       visConfig.opacity,
       data
     );
+    result.getFillColor = accessor;
+    scales.fillColor = {
+      field: colorField,
+      type: colorScale!,
+      ...domainAndRangeFromScale(scale),
+    };
+  } else if (visConfig.filled) {
+    scales.fillColor = {} as any;
   }
 
-  if (type === 'point') {
-    const altitude = config.columns?.altitude;
-    if (altitude) {
-      result.dataTransform = (data: any) => {
-        data.features.forEach(
-          ({geometry, properties}: {geometry: any; properties: any}) => {
-            const {type, coordinates} = geometry;
-            if (type === 'Point') {
-              coordinates[2] = properties[altitude];
-            }
-          }
-        );
-        return data;
-      };
-    }
-  }
-
-  if (type === 'clusterTile') {
+  if (layerType === 'clusterTile') {
     const aggregationExpAlias = getDefaultAggregationExpColumnAliasForLayerType(
-      type,
+      layerType,
       dataset.providerId,
       data.schema
     );
@@ -325,55 +324,71 @@ function createChannelProps(
     };
   }
 
-  if (radiusField || sizeField) {
-    result.getPointRadius = getSizeAccessor(
-      // @ts-ignore
-      radiusField || sizeField,
-      // @ts-ignore
-      radiusScale || sizeScale,
+  if (radiusField) {
+    const {accessor, scale} = getSizeAccessor(
+      radiusField,
+      radiusScale,
       visConfig.sizeAggregation,
       visConfig.radiusRange || visConfig.sizeRange,
       data
     );
+    result.getPointRadius = accessor;
+    scales.pointRadius = {
+      field: radiusField,
+      type: radiusScale || 'identity',
+      ...domainAndRangeFromScale(scale),
+    };
   }
 
   if (strokeColorField) {
-    const fallbackOpacity = type === 'point' ? visConfig.opacity : 1;
     const opacity =
-      visConfig.strokeOpacity !== undefined
-        ? visConfig.strokeOpacity
-        : fallbackOpacity;
+      visConfig.strokeOpacity !== undefined ? visConfig.strokeOpacity : 1;
     const {strokeColorAggregation: aggregation, strokeColorRange: range} =
       visConfig;
-    result.getLineColor = getColorAccessor(
+    const {accessor, scale} = getColorAccessor(
       strokeColorField,
-      // @ts-ignore
-      strokeColorScale,
-      // @ts-ignore
+      strokeColorScale!,
       {aggregation, range},
       opacity,
       data
     );
+    result.getLineColor = accessor;
+    scales.lineColor = {
+      field: strokeColorField,
+      type: strokeColorScale!,
+      ...domainAndRangeFromScale(scale),
+    };
   }
   if (heightField && visConfig.enable3d) {
-    result.getElevation = getSizeAccessor(
+    const {accessor, scale} = getSizeAccessor(
       heightField,
-      // @ts-ignore
       heightScale,
       visConfig.heightAggregation,
       visConfig.heightRange || visConfig.sizeRange,
       data
     );
+    result.getElevation = accessor;
+    scales.elevation = {
+      field: heightField,
+      type: heightScale || 'identity',
+      ...domainAndRangeFromScale(scale),
+    };
   }
 
   if (weightField) {
-    result.getWeight = getSizeAccessor(
+    const {accessor, scale} = getSizeAccessor(
       weightField,
       undefined,
       visConfig.weightAggregation,
       undefined,
       data
     );
+    result.getWeight = accessor;
+    scales.weight = {
+      field: weightField,
+      type: 'identity',
+      ...domainAndRangeFromScale(scale),
+    };
   }
 
   if (visConfig.customMarkers) {
@@ -416,17 +431,16 @@ function createChannelProps(
     }
 
     if (visualChannels.rotationField) {
-      result.getIconAngle = negateAccessor(
-        getSizeAccessor(
-          visualChannels.rotationField,
-          undefined,
-          null,
-          undefined,
-          data
-        )
+      const {accessor} = getSizeAccessor(
+        visualChannels.rotationField,
+        undefined,
+        null,
+        undefined,
+        data
       );
+      result.getIconAngle = negateAccessor(accessor);
     }
-  } else if (type === 'point' || type === 'tileset') {
+  } else if (layerType === 'tileset') {
     result.pointType = 'circle';
   }
 
@@ -480,7 +494,7 @@ function createChannelProps(
     };
   }
 
-  return result;
+  return {channelProps: result, scales};
 }
 
 function createLoadOptions(accessToken: string) {

package/src/fetch-map/types.ts

@@ -1,4 +1,4 @@
-import type {LayerType, SCALE_TYPE} from './layer-map.js';
+import type {LayerType, ScaleType} from './layer-map.js';
 import type {Format, MapType, ProviderType, QueryParameters} from '../types.js';
 import type {TilejsonResult} from '../sources/types.js';
 
@@ -10,25 +10,25 @@ export type VisualChannelField = {
 
 export type VisualChannels = {
   colorField?: VisualChannelField;
-  colorScale?: SCALE_TYPE;
+  colorScale?: ScaleType;
 
   customMarkersField?: VisualChannelField;
-  customMarkersScale?: SCALE_TYPE;
+  customMarkersScale?: ScaleType;
 
   radiusField?: VisualChannelField;
-  radiusScale?: SCALE_TYPE;
+  radiusScale?: ScaleType;
 
-  rotationScale?: SCALE_TYPE;
+  rotationScale?: ScaleType;
   rotationField?: VisualChannelField;
 
   sizeField?: VisualChannelField;
-  sizeScale?: SCALE_TYPE;
+  sizeScale?: ScaleType;
 
   strokeColorField?: VisualChannelField;
-  strokeColorScale?: SCALE_TYPE;
+  strokeColorScale?: ScaleType;
 
   heightField?: VisualChannelField;
-  heightScale?: SCALE_TYPE;
+  heightScale?: ScaleType;
 
   weightField?: VisualChannelField;
 };

package/src/widget-sources/types.ts

@@ -3,6 +3,7 @@ import type {
   TileResolution,
 } from '../sources/types.js';
 import type {
+  AggregationType,
   Filters,
   GroupDateType,
   SortColumnType,
@@ -30,10 +31,31 @@ export interface BaseRequestOptions {
   filterOwner?: string;
 }
 
-/** Options for {@link WidgetRemoteSource#getCategories}. */
+/**
+ * Examples:
+ *   * population by state
+ *      * column: 'state'
+ *      * operation: 'sum'
+ *      * operationColumn: 'population'
+ *   * average salary by department
+ *      * column: 'department'
+ *      * operation: 'avg'
+ *      * operationColumn: 'salary'
+ *   * custom aggregation by storetype
+ *      * column: 'storetype'
+ *      * operation: 'custom'
+ *      * operationExp: 'sum(sales)/sum(area)'
+ *
+ * Options for {@link WidgetRemoteSource#getCategories}.
+ */
 export interface CategoryRequestOptions extends BaseRequestOptions {
+  /** The column that to categorize by. */
   column: string;
-  operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
+  /** The type of aggregation to apply on data in scope of each category. */
+  operation: AggregationType;
+  /** Remote only. Only valid if operation is 'custom' */
+  operationExp?: string;
+  /** The aggregated column per each category. */
   operationColumn?: string;
   /** Local only. */
   joinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
@@ -82,11 +104,28 @@ export interface FeaturesRequestOptions extends BaseRequestOptions {
   tileResolution?: TileResolution;
 }
 
-/** Options for {@link WidgetRemoteSource#getFormula}. */
+/**
+ * Examples:
+ *   * sum of all sales
+ *      * column: 'sales'
+ *      * operation: 'sum'
+ *   * average salary
+ *      * column: 'salary'
+ *      * operation: 'avg'
+ *   * custom aggregation over all rows
+ *      * operation: 'custom'
+ *      * operationExp: 'sum(sales)/sum(area)'
+ *
+ * Options for {@link WidgetRemoteSource#getFormula}.
+ */
 export interface FormulaRequestOptions extends BaseRequestOptions {
-  column: string;
-  operation?: 'count' | 'avg' | 'min' | 'max' | 'sum' | 'custom';
+  /** The column to apply the aggregation operation on. Not needed for 'custom' operation. */
+  column?: string;
+  /** The type of aggregation to apply on data. */
+  operation: AggregationType;
+  /** Remote only. Only valid if operation is 'custom' */
   operationExp?: string;
+  /** Local only. */
   joinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
 }
 
@@ -126,12 +165,25 @@ export interface TableRequestOptions extends BaseRequestOptions {
   searchFilterText?: string;
 }
 
-/** Options for {@link WidgetRemoteSource#getTimeSeries}. */
+/**
+ * Examples:
+ *   * sum of all sales by month
+ *      * column: 'sales'
+ *      * stepSize: 'month'
+ *      * operation: 'sum'
+ *   * average salary by year
+ *      * column: 'salary'
+ *      * stepSize: 'year'
+ *      * operation: 'avg'
+ * Options for {@link WidgetRemoteSource#getTimeSeries}.
+ */
 export interface TimeSeriesRequestOptions extends BaseRequestOptions {
   column: string;
   stepSize: GroupDateType;
   stepMultiplier?: number;
-  operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
+  operation: AggregationType;
+  /** Remote only. Only valid if operation is 'custom' */
+  operationExp?: string;
   operationColumn?: string;
   joinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
   splitByCategory?: string;