@carto/api-client 0.5.7 → 0.5.8-alpha-others-orderby.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.7",
+  "version": "0.5.8-alpha-others-orderby.1",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/src/operations/groupBy.ts

@@ -1,12 +1,12 @@
 import {aggregationFunctions, aggregate} from './aggregation.js';
+import {OTHERS_CATEGORY_NAME} from '../widget-sources/constants.js';
 import type {AggregationType} from '../types.js';
 import type {FeatureData} from '../types-internal.js';
-
-/** @privateRemarks Source: @carto/react-core */
-export type GroupByFeature = {
-  name: string;
-  value: number;
-}[];
+import type {
+  CategoryOrderBy,
+  CategoryResponseEntry,
+  CategoryResponseRaw,
+} from '../widget-sources/types.js';
 
 /** @privateRemarks Source: @carto/react-core */
 export function groupValuesByColumn({
@@ -15,15 +15,19 @@ export function groupValuesByColumn({
   joinOperation,
   keysColumn,
   operation,
+  othersThreshold,
+  orderBy = 'frequency_desc',
 }: {
   data: FeatureData[];
   valuesColumns?: string[];
   joinOperation?: AggregationType;
   keysColumn: string;
   operation: AggregationType;
-}): GroupByFeature | null {
+  othersThreshold?: number;
+  orderBy?: CategoryOrderBy;
+}): CategoryResponseRaw | null {
   if (Array.isArray(data) && data.length === 0) {
-    return null;
+    return {rows: null};
   }
   const groups = data.reduce((accumulator, item) => {
     const group = item[keysColumn];
@@ -48,12 +52,57 @@ export function groupValuesByColumn({
   const targetOperation =
     aggregationFunctions[operation as Exclude<AggregationType, 'custom'>];
 
-  if (targetOperation) {
-    return Array.from(groups).map(([name, value]) => ({
+  if (!targetOperation) {
+    return {rows: []};
+  }
+
+  const allCategories = Array.from(groups)
+    .map(([name, value]) => ({
       name,
       value: targetOperation(value),
-    }));
+    }))
+    .sort(getSorter(orderBy));
+
+  if (othersThreshold && allCategories.length > othersThreshold) {
+    const otherValue = allCategories
+      .slice(othersThreshold)
+      .flatMap(({name}) => groups.get(name));
+    allCategories.push({
+      name: OTHERS_CATEGORY_NAME,
+      value: targetOperation(otherValue),
+    });
+    return {
+      rows: allCategories,
+      metadata: {
+        others: targetOperation(otherValue),
+      },
+    };
   }
 
-  return [];
+  return {
+    rows: allCategories,
+  };
+}
+
+export function getSorter(
+  orderBy: CategoryOrderBy
+): (a: CategoryResponseEntry, b: CategoryResponseEntry) => number {
+  switch (orderBy) {
+    case 'frequency_asc':
+      // 'value ASC, name ASC'
+      return (a, b) => a.value - b.value || localeCompare(a.name, b.name);
+    case 'frequency_desc':
+      // 'value DESC, name ASC'
+      return (a, b) => b.value - a.value || localeCompare(a.name, b.name);
+    case 'alphabetical_asc':
+      // 'name ASC, value DESC'
+      return (a, b) => localeCompare(a.name, b.name) || b.value - a.value;
+    case 'alphabetical_desc':
+      // 'name DESC, value DESC'
+      return (a, b) => localeCompare(b.name, a.name) || b.value - a.value;
+  }
+}
+
+function localeCompare(a?: string | null, b?: string | null) {
+  return (a ?? 'null').localeCompare(b ?? 'null');
 }

package/src/operations/groupByDate.ts

@@ -1,7 +1,12 @@
 import type {AggregationType, GroupDateType} from '../types.js';
 import {getUTCMonday} from '../utils/dateUtils.js';
 import {aggregate, aggregationFunctions} from './aggregation.js';
-import type {GroupByFeature} from './groupBy.js';
+
+/** @privateRemarks Source: @carto/react-core */
+export type GroupByFeature = {
+  name: string;
+  value: number;
+}[];
 
 const GROUP_KEY_FN_MAPPING: Record<GroupDateType, (date: Date) => number> = {
   year: (date: Date) => Date.UTC(date.getUTCFullYear()),

package/src/widget-sources/constants.ts

@@ -0,0 +1,6 @@
+/**
+ * Name of the category that represents the "Others" category.
+ *
+ * See `WidgetSource.getCategories` for more information.
+ */
+export const OTHERS_CATEGORY_NAME = '_carto_others';

package/src/widget-sources/index.ts

@@ -5,3 +5,4 @@ export * from './widget-remote-source.js';
 export * from './widget-table-source.js';
 export * from './widget-tileset-source.js';
 export * from './types.js';
+export * from './constants.js';

package/src/widget-sources/types.ts

@@ -31,6 +31,12 @@ export interface BaseRequestOptions {
   filterOwner?: string;
 }
 
+export type CategoryOrderBy =
+  | 'frequency_asc' // sort by aggregate value ascending, then by name ascending
+  | 'frequency_desc' // sort by aggregate value descending, then by name ascending
+  | 'alphabetical_asc' // sort by category name ascending, then by value descending
+  | 'alphabetical_desc'; // sort by category name descending, then by value descending
+
 /**
  * Examples:
  *   * population by state
@@ -59,6 +65,15 @@ export interface CategoryRequestOptions extends BaseRequestOptions {
   operationColumn?: string;
   /** Local only. */
   joinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
+  /** Calculate `_carto_others` category for all categories after first N (N is threshold). */
+  othersThreshold?: number;
+  /**
+   * Order categories by frequency or alphabetically.
+   * @default 'frequency_desc'
+   */
+  orderBy?: CategoryOrderBy;
+  /** Return raw result (CategoryResponseRaw). */
+  rawResult?: boolean;
 }
 
 /**
@@ -205,8 +220,17 @@ export type FeaturesResponse = {rows: Record<string, unknown>[]};
 /** Response from {@link WidgetRemoteSource#getFormula}. */
 export type FormulaResponse = {value: number | null};
 
+/** Entry in the category widget response, see  {@link WidgetRemoteSource#getCategories}. */
+export type CategoryResponseEntry = {name: string | null; value: number};
 /** Response from {@link WidgetRemoteSource#getCategories}. */
-export type CategoryResponse = {name: string; value: number}[];
+export type CategoryResponse = CategoryResponseEntry[];
+
+export type CategoryResponseRaw = {
+  rows: CategoryResponseEntry[] | null;
+  metadata?: {
+    others?: number;
+  };
+};
 
 /** Response from {@link WidgetRemoteSource#getRange}. */
 export type RangeResponse = {min: number; max: number} | null;

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

@@ -23,6 +23,7 @@ import {WidgetSource, type WidgetSourceProps} from './widget-source.js';
 import type {Filters} from '../types.js';
 import {AggregationTypes, ApiVersion} from '../constants.js';
 import {getApplicableFilters} from '../filters.js';
+import {OTHERS_CATEGORY_NAME} from './constants.js';
 
 export type WidgetRemoteSourceProps = WidgetSourceProps;
 
@@ -72,17 +73,23 @@ export abstract class WidgetRemoteSource<
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
+      rawResult,
       ...params
     } = options;
-    const {column, operation, operationColumn, operationExp} = params;
+    const {
+      column,
+      operation,
+      operationColumn,
+      operationExp,
+      othersThreshold,
+      orderBy,
+    } = params;
 
     if (operation === AggregationTypes.Custom) {
       assert(operationExp, 'operationExp is required for custom operation');
     }
 
-    type CategoriesModelResponse = {rows: {name: string; value: number}[]};
-
-    return executeModel({
+    const result = await executeModel({
       model: 'category',
       source: {
         ...this.getModelSource(filters, filterOwner),
@@ -94,9 +101,25 @@ export abstract class WidgetRemoteSource<
         operation,
         operationExp,
         operationColumn: operationColumn || column,
+        othersThreshold,
+        orderBy,
       },
       opts: {signal, headers: this.props.headers},
-    }).then((res: CategoriesModelResponse) => normalizeObjectKeys(res.rows));
+    });
+
+    const normalizedRows = normalizeObjectKeys(result.rows || []);
+    if (rawResult) {
+      return result as unknown as CategoryResponse;
+    }
+
+    if (!othersThreshold) {
+      return normalizedRows;
+    }
+
+    return [
+      ...normalizedRows,
+      {name: OTHERS_CATEGORY_NAME, value: result?.metadata?.others as number},
+    ];
   }
 
   async getFeatures(

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

@@ -40,6 +40,7 @@ import {booleanEqual} from '@turf/boolean-equal';
 import type {WidgetTilesetSourceProps} from './widget-tileset-source.js';
 import {getApplicableFilters} from '../filters.js';
 import {AggregationTypes} from '../constants.js';
+import {OTHERS_CATEGORY_NAME} from './constants.js';
 
 // TODO(cleanup): Parameter defaults in source functions and widget API calls are
 // currently duplicated and possibly inconsistent. Consider consolidating and
@@ -189,6 +190,9 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
     filters,
     filterOwner,
     spatialFilter,
+    othersThreshold,
+    orderBy = 'frequency_desc',
+    rawResult,
   }: CategoryRequestOptions): Promise<CategoryResponse> {
     const filteredFeatures = this._getFilteredFeatures(
       spatialFilter,
@@ -202,15 +206,28 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
 
     assertColumn(this._features, column, operationColumn as string);
 
-    const groups = groupValuesByColumn({
+    const result = groupValuesByColumn({
       data: filteredFeatures,
       valuesColumns: normalizeColumns(operationColumn || column),
       joinOperation,
       keysColumn: column,
       operation,
+      othersThreshold,
+      orderBy,
     });
 
-    return groups || [];
+    if (rawResult) {
+      return result as unknown as CategoryResponse;
+    }
+
+    if (!othersThreshold) {
+      return result?.rows || [];
+    }
+
+    return [
+      ...(result?.rows || []),
+      {name: OTHERS_CATEGORY_NAME, value: result?.metadata?.others as number},
+    ];
   }
 
   override async getScatter({