@carto/api-client 0.5.5 → 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",
+  "version": "0.5.6-alpha.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

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;

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

@@ -17,7 +17,7 @@ import type {
   TimeSeriesRequestOptions,
   TimeSeriesResponse,
 } from './types.js';
-import {normalizeObjectKeys} from '../utils.js';
+import {assert, normalizeObjectKeys} from '../utils.js';
 import {DEFAULT_TILE_RESOLUTION} from '../constants-internal.js';
 import {WidgetSource, type WidgetSourceProps} from './widget-source.js';
 import type {Filters} from '../types.js';
@@ -74,7 +74,11 @@ export abstract class WidgetRemoteSource<
       spatialFiltersMode,
       ...params
     } = options;
-    const {column, operation, operationColumn} = params;
+    const {column, operation, operationColumn, operationExp} = params;
+
+    if (operation === 'custom') {
+      assert(operationExp, 'operationExp is required for custom operation');
+    }
 
     type CategoriesModelResponse = {rows: {name: string; value: number}[]};
 
@@ -88,6 +92,7 @@ export abstract class WidgetRemoteSource<
       params: {
         column,
         operation,
+        operationExp,
         operationColumn: operationColumn || column,
       },
       opts: {signal, headers: this.props.headers},
@@ -143,6 +148,10 @@ export abstract class WidgetRemoteSource<
 
     type FormulaModelResponse = {rows: {value: number}[]};
 
+    if (operation === 'custom') {
+      assert(operationExp, 'operationExp is required for custom operation');
+    }
+
     return executeModel({
       model: 'formula',
       source: {
@@ -314,6 +323,7 @@ export abstract class WidgetRemoteSource<
       operationColumn,
       joinOperation,
       operation,
+      operationExp,
       stepSize,
       stepMultiplier,
       splitByCategory,
@@ -321,6 +331,10 @@ export abstract class WidgetRemoteSource<
       splitByCategoryValues,
     } = params;
 
+    if (operation === 'custom') {
+      assert(operationExp, 'operationExp is required for custom operation');
+    }
+
     type TimeSeriesModelResponse = {
       rows: {name: string; value: number}[];
       metadata: {categories: string[]};
@@ -340,6 +354,7 @@ export abstract class WidgetRemoteSource<
         operationColumn: operationColumn || column,
         joinOperation,
         operation,
+        operationExp,
         splitByCategory,
         splitByCategoryLimit,
         splitByCategoryValues,

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

@@ -329,6 +329,10 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
     }
 
     assertColumn(this._features, column, operationColumn as string);
+    assert(
+      operation !== 'custom',
+      'Custom operation not supported for tilesets'
+    );
 
     const rows =
       groupValuesByDateColumn({