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

package/build/api-client.d.cts

@@ -476,6 +476,13 @@ 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;
 };
 type ColumnsOption = {
     /**
@@ -1147,10 +1154,31 @@ interface BaseRequestOptions {
     filters?: Filters;
     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}.
+ */
 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';
@@ -1192,11 +1220,28 @@ 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}.
+ */
 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';
 }
 /** Options for {@link WidgetRemoteSource#getHistogram}. */
@@ -1231,12 +1276,25 @@ interface TableRequestOptions extends BaseRequestOptions {
     /** @deprecated Supported for tilesets only. Prefer `filters` (for all sources) instead. */
     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}.
+ */
 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/build/api-client.d.ts

@@ -476,6 +476,13 @@ 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;
 };
 type ColumnsOption = {
     /**
@@ -1147,10 +1154,31 @@ interface BaseRequestOptions {
     filters?: Filters;
     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}.
+ */
 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';
@@ -1192,11 +1220,28 @@ 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}.
+ */
 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';
 }
 /** Options for {@link WidgetRemoteSource#getHistogram}. */
@@ -1231,12 +1276,25 @@ interface TableRequestOptions extends BaseRequestOptions {
     /** @deprecated Supported for tilesets only. Prefer `filters` (for all sources) instead. */
     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}.
+ */
 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/build/api-client.js

@@ -6263,7 +6263,10 @@ var WidgetRemoteSource = class extends WidgetSource {
       spatialFiltersMode,
       ...params
     } = options;
-    const { column, operation: operation2, operationColumn } = params;
+    const { column, operation: operation2, operationColumn, operationExp } = params;
+    if (operation2 === "custom") {
+      assert2(operationExp, "operationExp is required for custom operation");
+    }
     return executeModel({
       model: "category",
       source: {
@@ -6274,6 +6277,7 @@ var WidgetRemoteSource = class extends WidgetSource {
       params: {
         column,
         operation: operation2,
+        operationExp,
         operationColumn: operationColumn || column
       },
       opts: { signal, headers: this.props.headers }
@@ -6319,6 +6323,9 @@ var WidgetRemoteSource = class extends WidgetSource {
       ...params
     } = options;
     const { column, operation: operation2 } = params;
+    if (operation2 === "custom") {
+      assert2(operationExp, "operationExp is required for custom operation");
+    }
     return executeModel({
       model: "formula",
       source: {
@@ -6457,12 +6464,16 @@ var WidgetRemoteSource = class extends WidgetSource {
       operationColumn,
       joinOperation,
       operation: operation2,
+      operationExp,
       stepSize,
       stepMultiplier,
       splitByCategory,
       splitByCategoryLimit,
       splitByCategoryValues
     } = params;
+    if (operation2 === "custom") {
+      assert2(operationExp, "operationExp is required for custom operation");
+    }
     return executeModel({
       model: "timeseries",
       source: {
@@ -6477,6 +6488,7 @@ var WidgetRemoteSource = class extends WidgetSource {
         operationColumn: operationColumn || column,
         joinOperation,
         operation: operation2,
+        operationExp,
         splitByCategory,
         splitByCategoryLimit,
         splitByCategoryValues
@@ -7362,6 +7374,10 @@ var WidgetTilesetSourceImpl = class extends WidgetSource {
       return { rows: [] };
     }
     assertColumn(this._features, column, operationColumn);
+    assert2(
+      operation2 !== "custom",
+      "Custom operation not supported for tilesets"
+    );
     const rows = groupValuesByDateColumn({
       data: filteredFeatures,
       valuesColumns: normalizeColumns(operationColumn || column),
@@ -7451,13 +7467,20 @@ var WidgetTilesetSource = class extends WidgetSource {
     if (this._workerImpl) {
       return this._workerImpl;
     }
-    this._workerImpl = new Worker(
-      new URL("@carto/api-client/worker", import.meta.url),
-      {
+    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: "init" /* INIT */,
       params: [this.props]