@carto/api-client 0.5.15 → 0.5.17

package/src/fetch-map/vec-expr-evaluator.ts

@@ -0,0 +1,374 @@
+import jsep from 'jsep';
+
+/**
+ * Create vector expresion evaluator.
+ *
+ * Used to calculate vector expressions, such as `(band_1 * 3) + band_2/2`,
+ * where `band_1` and `band_2` are arrays or typed arrays.
+ *
+ * Note that all vector operations are element-wise, in paricular `band_1 * band_2`
+ * is not "mathematical" dot or cross product, but just element-wise multiplication.
+ *
+ * Based on:
+ * - Copyright (c) 2013 Stephen Oney, http://jsep.from.so/, MIT License
+ * - Copyright (c) 2023 Don McCurdy, https://github.com/donmccurdy/expression-eval, MIT License
+ */
+export function createVecExprEvaluator(
+  expression: string | jsep.Expression
+): VecExprEvaluator | null {
+  try {
+    const parsed = compile(expression);
+    const evalFun = (context: Record<string, VecExprResult>) =>
+      evaluate(parsed, context);
+    evalFun.symbols = getSymbols(parsed);
+    return evalFun as VecExprEvaluator;
+  } catch {
+    return null;
+  }
+}
+
+export function evaluateVecExpr(
+  expression: string | jsep.Expression,
+  context: Record<string, VecExprResult>
+) {
+  try {
+    return createVecExprEvaluator(expression)?.(context);
+  } catch {
+    return null;
+  }
+}
+
+export enum ErrorCode {
+  InvalidSyntax,
+  UnknownIdentifier,
+}
+
+export type ValidationResult = {
+  valid: boolean;
+  errorCode?: ErrorCode;
+  errorMessage?: string;
+};
+
+export function validateVecExprSyntax(
+  expression: string | jsep.Expression,
+  context: Record<string, unknown>
+): ValidationResult {
+  let parsed: jsep.Expression;
+  try {
+    parsed = compile(expression);
+  } catch (e: any) {
+    return {
+      valid: false,
+      errorCode: ErrorCode.InvalidSyntax,
+      errorMessage: e && 'message' in e ? String(e.message) : String(e),
+    };
+  }
+  return validate(parsed, context);
+}
+
+export type VecExprVecLike =
+  | number[]
+  | Float32Array
+  | Float64Array
+  | Uint8Array
+  | Int8Array
+  | Int32Array
+  | Uint32Array
+  | Uint16Array
+  | Int16Array;
+
+export type VecExprResult = number | VecExprVecLike;
+
+export type VecExprEvaluator = {
+  (context: object): VecExprResult;
+
+  symbols?: string[];
+};
+
+function createResultArray(
+  typeTemplate: VecExprVecLike,
+  length: number = typeTemplate.length
+): number[] {
+  return new Array(length);
+}
+
+function isVecLike(a: unknown): a is number[] {
+  return Array.isArray(a) || ArrayBuffer.isView(a);
+}
+
+const createBinopVec =
+  (scalarBinOp: (a: number, b: number) => number) =>
+  (left: number[], right: number[]) => {
+    const length = Math.min(left.length, right.length);
+    const r = createResultArray(left, length);
+    for (let i = 0; i < length; i++) {
+      r[i] = scalarBinOp(left[i], right[i]);
+    }
+    return r;
+  };
+
+const createBinopVecNum =
+  (scalarBinOp: (a: number, b: number) => number) =>
+  (left: number[], right: number) => {
+    const length = left.length;
+    const r = createResultArray(left, length);
+    for (let i = 0; i < length; i++) {
+      r[i] = scalarBinOp(left[i], right);
+    }
+    return r;
+  };
+
+// number vec op
+const createBinopNumVec =
+  (scalarBinOp: (a: number, b: number) => number) =>
+  (left: number, right: number[]) => {
+    const length = right.length;
+    const r = createResultArray(right, length);
+    for (let i = 0; i < length; i++) {
+      r[i] = scalarBinOp(left, right[i]);
+    }
+    return r;
+  };
+
+const createUnopVec = (scalarUnop: (a: number) => number) => (a: number[]) => {
+  const length = a.length;
+  const r = createResultArray(a, length);
+  for (let i = 0; i < length; i++) {
+    r[i] = scalarUnop(a[i]);
+  }
+  return r;
+};
+
+function mapDictValues<V, NewV>(dict: Record<string, V>, fun: (v: V) => NewV) {
+  return Object.keys(dict).reduce(
+    (acc, key) => {
+      acc[key] = fun(dict[key]);
+      return acc;
+    },
+    {} as Record<string, NewV>
+  );
+}
+
+const binopsNum: Record<string, (a: number, b: number) => number> = {
+  '||': (a: number, b: number) => a || b,
+  '&&': (a: number, b: number) => a && b,
+  '|': (a: number, b: number) => a | b,
+  '^': (a: number, b: number) => a ^ b,
+  '&': (a: number, b: number) => a & b,
+  '==': (a: number, b: number) => Number(a == b),
+  '!=': (a: number, b: number) => Number(a != b),
+  '===': (a: number, b: number) => Number(a === b),
+  '!==': (a: number, b: number) => Number(a !== b),
+  '<': (a: number, b: number) => Number(a < b),
+  '>': (a: number, b: number) => Number(a > b),
+  '<=': (a: number, b: number) => Number(a <= b),
+  '>=': (a: number, b: number) => Number(a >= b),
+  '<<': (a: number, b: number) => a << b,
+  '>>': (a: number, b: number) => a >> b,
+  '>>>': (a: number, b: number) => a >>> b,
+  '+': (a: number, b: number) => a + b,
+  '-': (a: number, b: number) => a - b,
+  '*': (a: number, b: number) => a * b,
+  '/': (a: number, b: number) => a / b,
+  '%': (a: number, b: number) => a % b,
+};
+
+const unopsNum: Record<string, (a: number) => number> = {
+  '-': (a: number) => -a,
+  '+': (a: number) => +a,
+  '~': (a: number) => ~a,
+  '!': (a: number) => Number(!a),
+};
+
+const binopsVector = mapDictValues(binopsNum, createBinopVec) as Record<
+  string,
+  Binop
+>;
+const binopsNumVec = mapDictValues(binopsNum, createBinopNumVec) as Record<
+  string,
+  Binop
+>;
+const binopsVecNum = mapDictValues(binopsNum, createBinopVecNum) as Record<
+  string,
+  Binop
+>;
+
+const unopsVector = mapDictValues(unopsNum, createUnopVec) as Record<
+  string,
+  UnOp
+>;
+
+type UnOp = (a: VecExprResult) => VecExprResult;
+type Binop = (a: VecExprResult, b: VecExprResult) => VecExprResult;
+
+function getBinop(
+  operator: string,
+  left: VecExprResult,
+  right: VecExprResult
+): Binop {
+  const isLeftVec = isVecLike(left);
+  const isRightVec = isVecLike(right);
+  if (isLeftVec && isRightVec) {
+    return binopsVector[operator];
+  } else if (isLeftVec) {
+    return binopsVecNum[operator];
+  } else if (isRightVec) {
+    return binopsNumVec[operator];
+  } else {
+    return binopsNum[operator] as Binop;
+  }
+}
+
+type AnyExpression =
+  | jsep.ArrayExpression
+  | jsep.BinaryExpression
+  | jsep.MemberExpression
+  | jsep.CallExpression
+  | jsep.ConditionalExpression
+  | jsep.Identifier
+  | jsep.Literal
+  | jsep.ThisExpression
+  | jsep.UnaryExpression;
+
+export function evaluate(
+  _node: jsep.Expression,
+  context: Record<string, VecExprResult>
+): VecExprResult {
+  const node = _node as AnyExpression;
+
+  switch (node.type) {
+    case 'BinaryExpression': {
+      const left = evaluate(node.left, context);
+      const right = evaluate(node.right, context);
+      const binopFun = getBinop(node.operator, left, right);
+
+      return binopFun(left, right);
+    }
+
+    case 'ConditionalExpression': {
+      const val = evaluate(node.test, context);
+      if (isVecLike(val)) {
+        const length = val.length;
+        const consequentVal = evaluate(node.consequent, context);
+        const alternateVal = evaluate(node.alternate, context);
+        const r = createResultArray(val);
+        for (let i = 0; i < length; i++) {
+          const entryVal = val[i] ? consequentVal : alternateVal;
+          r[i] = isVecLike(entryVal)
+            ? (entryVal[i] ?? NaN)
+            : (entryVal as number);
+        }
+        return r;
+      } else {
+        return val
+          ? evaluate(node.consequent, context)
+          : evaluate(node.alternate, context);
+      }
+    }
+
+    case 'Identifier':
+      return context[node.name];
+
+    case 'Literal':
+      return node.value as number;
+
+    case 'UnaryExpression': {
+      const val = evaluate(node.argument, context);
+      const unopFun = isVecLike(val)
+        ? unopsVector[node.operator]
+        : (unopsNum[node.operator] as UnOp);
+      return unopFun(val);
+    }
+
+    default:
+      return undefined as unknown as VecExprResult;
+  }
+}
+
+const validResult = {valid: true};
+
+function visit(_node: jsep.Expression, visitor: (node: AnyExpression) => void) {
+  const node = _node as AnyExpression;
+
+  visitor(node);
+  switch (node.type) {
+    case 'BinaryExpression': {
+      visit(node.left, visitor);
+      visit(node.right, visitor);
+      break;
+    }
+
+    case 'ConditionalExpression': {
+      visit(node.test, visitor);
+      visit(node.consequent, visitor);
+      visit(node.alternate, visitor);
+      break;
+    }
+
+    case 'UnaryExpression': {
+      visit(node.argument, visitor);
+      break;
+    }
+  }
+}
+
+const supportedExpressionTypes = [
+  'BinaryExpression',
+  'UnaryExpression',
+  'ConditionalExpression',
+  'LogicalExpression',
+  'Identifier',
+  'Literal',
+];
+
+function validate(_node: jsep.Expression, context: object): ValidationResult {
+  const node = _node as AnyExpression;
+
+  const errors: ValidationResult[] = [];
+
+  visit(node, (node) => {
+    if (!supportedExpressionTypes.includes(node.type)) {
+      errors.push({
+        valid: false,
+        errorCode: ErrorCode.InvalidSyntax,
+        errorMessage: `Not allowed`,
+      });
+      return;
+    }
+    if (node.type === 'Identifier') {
+      if (!Object.prototype.hasOwnProperty.call(context, node.name)) {
+        return errors.push({
+          valid: false,
+          errorCode: ErrorCode.UnknownIdentifier,
+          errorMessage: `"${node.name}" not found`,
+        });
+      }
+    }
+    if (node.type === 'Literal') {
+      // we actually support only numbers
+      if (typeof node.value !== 'number') {
+        return errors.push({
+          valid: false,
+          errorCode: ErrorCode.InvalidSyntax,
+          errorMessage: `Only number literals are supported`,
+        });
+      }
+    }
+  });
+  return errors.length ? errors[0] : validResult;
+}
+
+function getSymbols(node: jsep.Expression): string[] {
+  const symbols = new Set<string>();
+
+  visit(node, (node) => {
+    if (node.type === 'Identifier') {
+      symbols.add(node.name);
+    }
+  });
+  return Array.from(symbols);
+}
+
+export function compile(expression: string | jsep.Expression) {
+  return jsep(expression);
+}

package/src/index.ts

@@ -2,7 +2,13 @@ export * from './client.js';
 export * from './constants.js';
 export * from './deck/index.js';
 export * from './fetch-map/index.js';
-export type {LayerDescriptor, LayerType} from './fetch-map/index.js';
+export {
+  createVecExprEvaluator as _createVecExprEvaluator,
+  evaluateVecExpr as _evaluateVecExpr,
+  validateVecExprSyntax as _validateVecExprSyntax,
+  type VecExprResult as _VecExprResult,
+  ErrorCode as _ErrorCode,
+} from './fetch-map/vec-expr-evaluator.js';
 export * from './filters.js';
 export * from './geo.js';
 export * from './sources/index.js';

package/src/models/model.ts

@@ -24,6 +24,7 @@ const AVAILABLE_MODELS = [
   'range',
   'scatterplot',
   'table',
+  'aggregations',
 ] as const;
 
 export type Model = (typeof AVAILABLE_MODELS)[number];

package/src/sources/types.ts

@@ -292,14 +292,64 @@ export interface Tilestats {
 
 export interface Layer {
   layer: string;
+  /** Number of features in the layer. */
   count: number;
+
+  /** Number of attributes in the layer. */
   attributeCount: number;
   attributes: Attribute[];
+
+  /** Type of geometry as in geojson geometry type (Point, LineString, Polygon, etc.) */
+  geometry?: string;
+}
+
+export interface AttributeCategoryItem {
+  category: string;
+  frequency: number;
+}
+
+/**
+ * Quantiles by number of buckets.
+ *
+ * Example:
+ * ```ts
+ *   {
+ *     // for 3 buckets, first 1/3 of items lies in range [min, 20], second 1/3 is in [20, 40], and last 1/3 is in [40, max]
+ *     3: [20, 40],
+ *     4: [20, 30, 50], for 4 buckets ...
+ *   }
+ * ```
+ */
+export interface QuantileStats {
+  [bucketCount: number]: number[];
 }
 
 export interface Attribute {
-  attribute: string;
+  /**
+   * String, Number, Timestamp, Boolean
+   */
   type: string;
+
+  /**
+   * Attribute name.
+   */
+  attribute: string;
+
+  // Stats for numeric attributes
+  min?: number;
+  max?: number;
+  sum?: number;
+
+  /** Quantiles by number of buckets */
+  quantiles?:
+    | {
+        // Quantile stats for numeric attributes in static spatial index tilesets are enclosed in extra global object
+        global: QuantileStats;
+      }
+    | QuantileStats;
+
+  // Stats for string/boolean attributes
+  categories?: AttributeCategoryItem[];
 }
 
 export interface VectorLayer {
@@ -325,17 +375,8 @@ export type RasterMetadataBandStats = {
 
   /**
    * Quantiles by number of buckets.
-   *
-   * Example:
-   * ```ts
-   *   {
-   *     // for 3 buckets, first 1/3 of items lies in range [min, 20], second 1/3 is in [20, 40], and last 1/3 is in [40, max]
-   *     3: [20, 40],
-   *     4: [20, 30, 50], for 4 buckets ...
-   *   }
-   * ```
    */
-  quantiles?: Record<number, number[]>;
+  quantiles?: QuantileStats;
 
   /**
    * Top values by number of values.

package/src/widget-sources/types.ts

@@ -207,6 +207,26 @@ export interface TimeSeriesRequestOptions extends BaseRequestOptions {
   splitByCategoryValues?: string[];
 }
 
+/**
+ * Examples:
+ *   * aggregations with array syntax
+ *      * aggregations: [{column: 'pop_high', operation: 'sum', alias: 'high_pop'}, {column: 'pop_low', operation: 'avg'}]
+ *   * aggregations with string syntax
+ *      * aggregations: 'sum(pop_high) as high_pop, avg(pop_low) as avg_low'
+ *
+ * Options for {@link WidgetRemoteSource#getAggregations}.
+ */
+export interface AggregationsRequestOptions extends BaseRequestOptions {
+  /** Aggregations to compute. Can be an array of objects or a SQL string expression. */
+  aggregations:
+    | {
+        column: string;
+        operation: Exclude<AggregationType, 'custom'>;
+        alias: string;
+      }[]
+    | string;
+}
+
 /** @experimental */
 export type ExtentRequestOptions = BaseRequestOptions;
 
@@ -264,5 +284,10 @@ export type TimeSeriesResponse = {
 /** Response from {@link WidgetRemoteSource#getHistogram}. */
 export type HistogramResponse = number[];
 
+/** Response from {@link WidgetRemoteSource#getAggregations}. */
+export type AggregationsResponse = {
+  rows: Record<string, number | string | null>[];
+};
+
 /** @experimental */
 export type ExtentResponse = {bbox: BBox};

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

@@ -1,5 +1,7 @@
 import {executeModel, type ModelSource} from '../models/index.js';
 import type {
+  AggregationsRequestOptions,
+  AggregationsResponse,
   CategoryRequestOptions,
   CategoryResponse,
   ExtentRequestOptions,
@@ -394,6 +396,34 @@ export abstract class WidgetRemoteSource<
     }));
   }
 
+  async getAggregations(
+    options: AggregationsRequestOptions
+  ): Promise<AggregationsResponse> {
+    const {
+      signal,
+      filters = this.props.filters,
+      filterOwner,
+      spatialFilter,
+      spatialFiltersMode,
+      aggregations,
+    } = options;
+
+    return executeModel({
+      model: 'aggregations',
+      source: {
+        ...this.getModelSource(filters, filterOwner),
+        spatialFiltersMode,
+        spatialFilter,
+      },
+      params: {
+        aggregations,
+      },
+      opts: {signal, headers: this.props.headers},
+    }).then((res: AggregationsResponse) => ({
+      rows: res.rows.map((row) => normalizeObjectKeys(row)),
+    }));
+  }
+
   /** @experimental */
   async getExtent(options: ExtentRequestOptions = {}): Promise<ExtentResponse> {
     const {signal, filters = this.props.filters, filterOwner} = options;

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

@@ -1,4 +1,6 @@
 import type {
+  AggregationsRequestOptions,
+  AggregationsResponse,
   CategoryRequestOptions,
   CategoryResponse,
   ExtentRequestOptions,
@@ -127,6 +129,15 @@ export abstract class WidgetSource<
     options: TimeSeriesRequestOptions
   ): Promise<TimeSeriesResponse>;
 
+  /**
+   * Returns multiple aggregated values computed over matching data. Suitable
+   * for aggregated statistics from pivoted tables, such as H3 tables with
+   * pre-computed aggregations across multiple columns.
+   */
+  abstract getAggregations(
+    options: AggregationsRequestOptions
+  ): Promise<AggregationsResponse>;
+
   /** @experimental */
   abstract getExtent(options?: ExtentRequestOptions): Promise<ExtentResponse>;
 }

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

@@ -1,5 +1,7 @@
 /* eslint-disable @typescript-eslint/require-await */
 import type {
+  AggregationsRequestOptions,
+  AggregationsResponse,
   CategoryRequestOptions,
   CategoryResponse,
   ExtentResponse,
@@ -148,6 +150,8 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
     }
 
     const targetOperation = aggregationFunctions[operation];
+    assert(targetOperation, `Unsupported aggregation operation: ${operation}`);
+
     return {
       value: targetOperation(filteredFeatures, column, joinOperation),
     };
@@ -391,6 +395,51 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
     };
   }
 
+  async getAggregations({
+    aggregations,
+    filters,
+    filterOwner,
+    spatialFilter,
+  }: AggregationsRequestOptions): Promise<AggregationsResponse> {
+    const filteredFeatures = this._getFilteredFeatures(
+      spatialFilter,
+      filters,
+      filterOwner
+    );
+
+    if (!this._features.length) {
+      return {rows: []};
+    }
+
+    // SQL aggregations require remote execution, and are not supported for tilesets.
+    assert(
+      typeof aggregations !== 'string',
+      'Unsupported tileset SQL aggregation'
+    );
+
+    // Handle array-based aggregations
+    const result: Record<string, number> = {};
+    const usedAliases = new Set<string>();
+
+    for (const {column, operation, alias} of aggregations) {
+      // Column is required except when operation is 'count'.
+      if ((column && column !== '*') || operation !== AggregationTypes.Count) {
+        assertColumn(this._features, column);
+      }
+
+      const aliasKey = alias.toLowerCase();
+      assert(!usedAliases.has(aliasKey), `Duplicate alias: ${aliasKey}`);
+      usedAliases.add(aliasKey);
+
+      const targetOperation = aggregationFunctions[operation];
+      assert(targetOperation, `Unsupported operation: ${operation}`);
+
+      result[alias] = targetOperation(filteredFeatures, column);
+    }
+
+    return {rows: [result]};
+  }
+
   /** @experimental */
   async getExtent(): Promise<ExtentResponse> {
     return Promise.reject(new Error('not implemented'));

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

@@ -1,4 +1,6 @@
 import type {
+  AggregationsRequestOptions,
+  AggregationsResponse,
   CategoryRequestOptions,
   CategoryResponse,
   ExtentResponse,
@@ -326,6 +328,17 @@ export class WidgetTilesetSource<
     return this._executeWorkerMethod(Method.GET_RANGE, [options], signal);
   }
 
+  async getAggregations({
+    signal,
+    ...options
+  }: AggregationsRequestOptions): Promise<AggregationsResponse> {
+    return this._executeWorkerMethod(
+      Method.GET_AGGREGATIONS,
+      [options],
+      signal
+    );
+  }
+
   /** @experimental */
   async getExtent(): Promise<ExtentResponse> {
     return Promise.resolve({

package/src/workers/constants.ts

@@ -10,4 +10,5 @@ export enum Method {
   GET_TABLE = 'getTable',
   GET_TIME_SERIES = 'getTimeSeries',
   GET_RANGE = 'getRange',
+  GET_AGGREGATIONS = 'getAggregations',
 }