@carto/api-client 0.5.15 → 0.5.16

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.15",
+  "version": "0.5.16",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -121,7 +121,7 @@
     "rimraf": "^6.0.1",
     "semver": "^7.7.1",
     "thenby": "^1.3.4",
-    "tinybench": "^4.0.1",
+    "tinybench": "^5.0.1",
     "tsup": "^8.3.6",
     "typescript": "~5.9.2",
     "typescript-eslint": "^8.26.1",

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/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',
 }