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

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.1",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/src/sources/types.ts

@@ -188,6 +188,14 @@ export type TilesetSourceOptions = {
    * are used by default if the runtime environment supports ES Module Workers.
    */
   widgetWorker?: boolean;
+
+  /**
+   * Script URL used to create Web Workers for local widget calculations. In
+   * most cases a custom URL is not needed; bundlers will resolve the worker
+   * URL from a `@carto/api-client/worker` import internally. Advanced uses
+   * may require deploying the script manually and providing a custom URL.
+   */
+  widgetWorkerUrl?: string;
 };
 
 export type ColumnsOption = {

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({

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

@@ -99,13 +99,22 @@ export class WidgetTilesetSource<
       return this._workerImpl;
     }
 
-    this._workerImpl = new Worker(
-      new URL('@carto/api-client/worker', import.meta.url),
-      {
+    // For Vite (and perhaps other bundlers) to parse WorkerOptions, it
+    // must be a static, inline object – duplicated below.
+    if (this.props.widgetWorkerUrl) {
+      this._workerImpl = new Worker(this.props.widgetWorkerUrl, {
         type: 'module',
         name: 'cartowidgettileset',
-      }
-    );
+      });
+    } else {
+      this._workerImpl = new Worker(
+        new URL('@carto/api-client/worker', import.meta.url),
+        {
+          type: 'module',
+          name: 'cartowidgettileset',
+        }
+      );
+    }
 
     this._workerImpl.postMessage({
       method: Method.INIT,