feat(widgets): Improve aggregation types and getTable params

examples/components/widgets/category-widget.ts

@@ -3,13 +3,7 @@ import {Task, TaskStatus} from '@lit/task';
 import {Ref, createRef, ref} from 'lit/directives/ref.js';
 import {cache} from 'lit/directives/cache.js';
 import * as echarts from 'echarts';
-import {
-  AggregationType,
-  Filter,
-  FilterType,
-  addFilter,
-  removeFilter,
-} from '@carto/api-client';
+import {Filter, FilterType, addFilter, removeFilter} from '@carto/api-client';
 
 import {DEFAULT_PALETTE, DEFAULT_TEXT_STYLE} from './styles.js';
 import {DEBOUNCE_TIME_MS} from '../constants.js';
@@ -36,7 +30,7 @@ export class CategoryWidget extends BaseWidget {
   }
 
   declare column: string;
-  declare operation: AggregationType;
+  declare operation: 'count' | 'avg' | 'min' | 'max' | 'sum';
 
   protected _chart: echarts.ECharts | null = null;
   protected _chartRef: Ref<HTMLElement> = createRef();

examples/components/widgets/formula-widget.ts

@@ -1,6 +1,5 @@
 import {html, css} from 'lit';
 import {Task} from '@lit/task';
-import {AggregationType} from '@carto/api-client';
 import {DEBOUNCE_TIME_MS} from '../constants.js';
 import {sleep} from '../utils.js';
 import {BaseWidget} from './base-widget.js';
@@ -39,7 +38,7 @@ export class FormulaWidget extends BaseWidget {
     };
   }
 
-  declare operation: AggregationType;
+  declare operation: 'count' | 'avg' | 'min' | 'max' | 'sum';
   declare column: string;
 
   constructor() {

examples/components/widgets/histogram-widget.ts

@@ -4,7 +4,6 @@ import {Ref, createRef, ref} from 'lit/directives/ref.js';
 import {cache} from 'lit/directives/cache.js';
 import * as echarts from 'echarts';
 import {TaskStatus} from '@lit/task';
-import {AggregationType} from '@carto/api-client';
 
 import {DEBOUNCE_TIME_MS} from '../constants.js';
 import {sleep} from '../utils.js';
@@ -31,7 +30,7 @@ export class HistogramWidget extends BaseWidget {
   }
 
   declare column: string;
-  declare operation: AggregationType;
+  declare operation: 'count' | 'avg' | 'min' | 'max' | 'sum';
   declare ticks: number[];
 
   protected _chart: echarts.ECharts | null = null;

examples/components/widgets/scatter-widget.ts

@@ -4,7 +4,6 @@ import {Ref, createRef, ref} from 'lit/directives/ref.js';
 import {cache} from 'lit/directives/cache.js';
 import * as echarts from 'echarts';
 import {TaskStatus} from '@lit/task';
-import {AggregationType} from '@carto/api-client';
 
 import {DEBOUNCE_TIME_MS} from '../constants.js';
 import {sleep} from '../utils.js';
@@ -32,9 +31,9 @@ export class ScatterWidget extends BaseWidget {
   }
 
   declare xAxisColumn: string;
-  declare xAxisJoinOperation: AggregationType;
+  declare xAxisJoinOperation: 'count' | 'avg' | 'min' | 'max' | 'sum';
   declare yAxisColumn: string;
-  declare yAxisJoinOperation: AggregationType;
+  declare yAxisJoinOperation: 'count' | 'avg' | 'min' | 'max' | 'sum';
 
   protected _chart: echarts.ECharts | null = null;
   protected _chartRef: Ref<HTMLElement> = createRef();

src/constants.ts

@@ -1,18 +1,3 @@
-/**
- * Defines a step size increment for use with {@link TimeSeriesRequestOptions}.
- *
- * @internalRemarks Source: @carto/react-core
- */
-export enum GroupDateType {
-  YEARS = 'year',
-  MONTHS = 'month',
-  WEEKS = 'week',
-  DAYS = 'day',
-  HOURS = 'hour',
-  MINUTES = 'minute',
-  SECONDS = 'second',
-}
-
 /**
  * Defines a comparator used when matching a column's values against given filter values.
  *

src/sources/types.ts

@@ -1,6 +1,5 @@
-import {GroupDateType} from '../constants';
 import {
-  AggregationType,
+  GroupDateType,
   SortColumnType,
   SortDirection,
   SpatialFilter,
@@ -20,22 +19,22 @@ interface BaseRequestOptions {
 /** Options for {@link WidgetBaseSource#getCategories}. */
 export interface CategoryRequestOptions extends BaseRequestOptions {
   column: string;
-  operation?: AggregationType;
+  operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
   operationColumn?: string;
 }
 
 /** Options for {@link WidgetBaseSource#getFormula}. */
 export interface FormulaRequestOptions extends BaseRequestOptions {
   column: string;
-  operation?: AggregationType;
+  operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
   operationExp?: string;
 }
 
 /** Options for {@link WidgetBaseSource#getHistogram}. */
 export interface HistogramRequestOptions extends BaseRequestOptions {
   column: string;
   ticks: number[];
-  operation?: AggregationType;
+  operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
 }
 
 /** Options for {@link WidgetBaseSource#getRange}. */
@@ -46,9 +45,9 @@ export interface RangeRequestOptions extends BaseRequestOptions {
 /** Options for {@link WidgetBaseSource#getScatter}. */
 export interface ScatterRequestOptions extends BaseRequestOptions {
   xAxisColumn: string;
-  xAxisJoinOperation?: AggregationType;
+  xAxisJoinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
   yAxisColumn: string;
-  yAxisJoinOperation?: AggregationType;
+  yAxisJoinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
 }
 
 /** Options for {@link WidgetBaseSource#getTable}. */
@@ -57,18 +56,18 @@ export interface TableRequestOptions extends BaseRequestOptions {
   sortBy?: string;
   sortDirection?: SortDirection;
   sortByColumnType?: SortColumnType;
-  page?: number;
-  rowsPerPage?: number;
+  offset?: number;
+  limit?: number;
 }
 
 /** Options for {@link WidgetBaseSource#getTimeSeries}. */
 export interface TimeSeriesRequestOptions extends BaseRequestOptions {
   column: string;
   stepSize?: GroupDateType;
   stepMultiplier?: number;
-  operation?: AggregationType;
+  operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
   operationColumn?: string;
-  joinOperation?: AggregationType;
+  joinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
   splitByCategory?: string;
   splitByCategoryLimit?: number;
   splitByCategoryValues?: string[];

src/sources/widget-base-source.ts

@@ -239,7 +239,7 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
    */
   async getTable(options: TableRequestOptions): Promise<TableResponse> {
     const {filterOwner, spatialFilter, abortController, ...params} = options;
-    const {columns, sortBy, sortDirection, page = 0, rowsPerPage = 10} = params;
+    const {columns, sortBy, sortDirection, offset = 0, limit = 10} = params;
 
     type TableModelResponse = {
       rows: Record<string, number | string>[];
@@ -253,8 +253,8 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
         column: columns,
         sortBy,
         sortDirection,
-        limit: rowsPerPage,
-        offset: page * rowsPerPage,
+        limit,
+        offset,
       },
       opts: {abortController},
     }).then((res: TableModelResponse) => ({

src/types.ts

@@ -1,4 +1,4 @@
-import type {FilterType} from './constants';
+import type {FilterType} from './constants.js';
 
 /******************************************************************************
  * AGGREGATION
@@ -39,6 +39,24 @@ export interface Filter {
 /** @internalRemarks Source: @carto/react-core */
 export type FilterLogicalOperator = 'and' | 'or';
 
+/******************************************************************************
+ * GROUPING
+ */
+
+/**
+ * Defines a step size increment for use with {@link TimeSeriesRequestOptions}.
+ *
+ * @internalRemarks Source: @carto/react-core
+ */
+export type GroupDateType =
+  | 'year'
+  | 'month'
+  | 'week'
+  | 'day'
+  | 'hour'
+  | 'minute'
+  | 'second';
+
 /******************************************************************************
  * SORTING
  */

test/constants.test.ts

@@ -1,10 +1,5 @@
 import {expect, test} from 'vitest';
-import {GroupDateType, FilterType} from '@carto/api-client';
-
-test('GroupDateType', () => {
-  expect(GroupDateType.DAYS).toBe('day');
-  expect(GroupDateType.HOURS).toBe('hour');
-});
+import {FilterType} from '@carto/api-client';
 
 test('FilterType', () => {
   expect(FilterType.IN).toBe('in');

test/filters.test.ts

@@ -1,6 +1,5 @@
 import {expect, test} from 'vitest';
 import {
-  GroupDateType,
   FilterType,
   clearFilters,
   addFilter,

test/sources/widget-base-source.test.ts

@@ -321,6 +321,8 @@ test('getTable', async () => {
 
   const actualTable = await widgetSource.getTable({
     columns: ['name', 'revenue'],
+    limit: 20,
+    offset: 10,
   });
 
   expect(mockFetch).toHaveBeenCalledOnce();
@@ -335,8 +337,8 @@ test('getTable', async () => {
     source: 'test-data',
     params: JSON.stringify({
       column: ['name', 'revenue'],
-      limit: 10,
-      offset: 0,
+      limit: 20,
+      offset: 10,
     }),
     queryParameters: '',
     filters: JSON.stringify({}),

test/types.test.ts

@@ -4,6 +4,7 @@ import {
   Filter,
   FilterLogicalOperator,
   FilterType,
+  GroupDateType,
   SpatialFilter,
 } from '@carto/api-client';
 
@@ -77,3 +78,16 @@ test('FilterLogicalOperator', () => {
   // @ts-expect-error
   assertType<FilterLogicalOperator>('invalid');
 });
+
+test('GroupDateType', () => {
+  assertType<GroupDateType>('year');
+  assertType<GroupDateType>('month');
+  assertType<GroupDateType>('week');
+  assertType<GroupDateType>('day');
+  assertType<GroupDateType>('hour');
+  assertType<GroupDateType>('minute');
+  assertType<GroupDateType>('second');
+
+  // @ts-expect-error
+  assertType<GroupDateType>('invalid');
+});