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

package/src/api/query.ts

@@ -13,17 +13,7 @@ import {requestWithParameters} from './request-with-parameters.js';
 import type {APIErrorContext} from './carto-api-error.js';
 import {getClient} from '../client.js';
 
-export type QueryOptions = SourceOptions &
-  QuerySourceOptions & {
-    /**
-     * @internal
-     * @experimental
-     * Used to append additional parameters to the SQL API request for features specific to providers or integrations.
-     */
-    internalParameters?: Record<string, string | boolean | number>;
-    /** Used to abort the request. */
-    signal?: AbortSignal;
-  };
+export type QueryOptions = SourceOptions & QuerySourceOptions;
 type UrlParameters = {q: string; queryParameters?: string};
 
 export const query = async function (
@@ -37,7 +27,6 @@ export const query = async function (
     connectionName,
     sqlQuery,
     queryParameters,
-    internalParameters,
   } = options;
   const urlParameters: UrlParameters = {q: sqlQuery};
 
@@ -50,12 +39,7 @@ export const query = async function (
     Authorization: `Bearer ${options.accessToken}`,
     ...options.headers,
   };
-  const parameters = {
-    client: clientId,
-    ...options.tags,
-    ...internalParameters,
-    ...urlParameters,
-  };
+  const parameters = {client: clientId, ...urlParameters};
 
   const errorContext: APIErrorContext = {
     requestType: 'SQL',
@@ -70,6 +54,5 @@ export const query = async function (
     errorContext,
     maxLengthURL,
     localCache,
-    signal: options.signal,
   });
 };

package/src/api/request-with-parameters.ts

@@ -23,7 +23,6 @@ export async function requestWithParameters<T = any>({
   errorContext,
   maxLengthURL = DEFAULT_MAX_LENGTH_URL,
   localCache,
-  signal,
 }: {
   baseUrl: string;
   parameters?: Record<string, unknown>;
@@ -31,7 +30,6 @@ export async function requestWithParameters<T = any>({
   errorContext: APIErrorContext;
   maxLengthURL?: number;
   localCache?: LocalCacheOptions;
-  signal?: AbortSignal;
 }): Promise<T> {
   // Parameters added to all requests issued with `requestWithParameters()`.
   // These parameters override parameters already in the base URL, but not
@@ -67,9 +65,8 @@ export async function requestWithParameters<T = any>({
           method: 'POST',
           body: JSON.stringify(parameters),
           headers,
-          signal,
         })
-      : fetch(url, {headers, signal});
+      : fetch(url, {headers});
 
   let response: Response | undefined;
   let responseJson: unknown;
@@ -146,12 +143,10 @@ function createURLWithParameters(
     if (isPureObject(value) || Array.isArray(value)) {
       baseUrl.searchParams.set(key, JSON.stringify(value));
     } else {
-      if (value !== null && value !== undefined) {
-        baseUrl.searchParams.set(
-          key,
-          (value as string | boolean | number).toString()
-        );
-      }
+      baseUrl.searchParams.set(
+        key,
+        (value as string | boolean | number).toString()
+      );
     }
   }
   return baseUrl.toString();

package/src/models/model.ts

@@ -43,7 +43,6 @@ export interface ModelSource {
   spatialDataColumn?: string;
   spatialDataType?: SpatialDataType;
   spatialFiltersMode?: SpatialFilterPolyfillMode;
-  tags?: Record<string, string>;
 }
 
 const {V3} = ApiVersion;
@@ -88,7 +87,6 @@ export function executeModel(props: {
     spatialDataType = 'geo',
     spatialDataColumn = DEFAULT_GEO_COLUMN,
     spatialFiltersMode = 'intersects',
-    tags,
   } = source;
 
   const queryParams: Record<string, unknown> = {
@@ -99,7 +97,6 @@ export function executeModel(props: {
     queryParameters: source.queryParameters || '',
     filters,
     filtersLogicalOperator,
-    ...(tags ?? {}),
   };
 
   queryParams.spatialDataType = spatialDataType;

package/src/operations/groupBy.ts

@@ -1,7 +1,11 @@
 import {aggregationFunctions, aggregate} from './aggregation.js';
 import type {AggregationType} from '../types.js';
 import type {FeatureData} from '../types-internal.js';
-import type {CategoryResponseRaw} from '../widget-sources/types.js';
+import type {
+  CategoryOrderBy,
+  CategoryResponseEntry,
+  CategoryResponseRaw,
+} from '../widget-sources/types.js';
 
 /** @privateRemarks Source: @carto/react-core */
 export function groupValuesByColumn({
@@ -11,6 +15,7 @@ export function groupValuesByColumn({
   keysColumn,
   operation,
   othersThreshold,
+  orderBy = 'frequency_desc',
 }: {
   data: FeatureData[];
   valuesColumns?: string[];
@@ -18,6 +23,7 @@ export function groupValuesByColumn({
   keysColumn: string;
   operation: AggregationType;
   othersThreshold?: number;
+  orderBy?: CategoryOrderBy;
 }): CategoryResponseRaw | null {
   if (Array.isArray(data) && data.length === 0) {
     return {rows: null};
@@ -54,7 +60,7 @@ export function groupValuesByColumn({
       name,
       value: targetOperation(value),
     }))
-    .sort((a, b) => b.value - a.value);
+    .sort(getSorter(orderBy));
 
   if (othersThreshold && allCategories.length > othersThreshold) {
     const otherValue = allCategories
@@ -72,3 +78,26 @@ export function groupValuesByColumn({
     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/sources/base-source.ts

@@ -47,7 +47,7 @@ export async function baseSource<UrlParameters extends Record<string, unknown>>(
     Authorization: `Bearer ${options.accessToken}`,
     ...options.headers,
   };
-  const parameters = {client: clientId, ...options.tags, ...urlParameters};
+  const parameters = {client: clientId, ...urlParameters};
 
   const errorContext: APIErrorContext = {
     requestType: 'Map instantiation',

package/src/sources/types.ts

@@ -75,9 +75,6 @@ export type SourceOptionalOptions = {
    * By default, local in-memory caching is enabled.
    */
   localCache?: LocalCacheOptions;
-
-  /** Additional tags appended to HTTP requests, available for analytics and audits. */
-  tags?: Record<string, string>;
 };
 
 export type LocalCacheOptions = {

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
@@ -61,6 +67,11 @@ export interface CategoryRequestOptions extends BaseRequestOptions {
   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;
 }
@@ -209,6 +220,7 @@ 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 = CategoryResponseEntry[];

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

@@ -61,7 +61,6 @@ export abstract class WidgetRemoteSource<
       filtersLogicalOperator: props.filtersLogicalOperator,
       spatialDataType: props.spatialDataType,
       spatialDataColumn: props.spatialDataColumn,
-      tags: props.tags,
     };
   }
 
@@ -77,8 +76,14 @@ export abstract class WidgetRemoteSource<
       rawResult,
       ...params
     } = options;
-    const {column, operation, operationColumn, operationExp, othersThreshold} =
-      params;
+    const {
+      column,
+      operation,
+      operationColumn,
+      operationExp,
+      othersThreshold,
+      orderBy,
+    } = params;
 
     if (operation === AggregationTypes.Custom) {
       assert(operationExp, 'operationExp is required for custom operation');
@@ -97,6 +102,7 @@ export abstract class WidgetRemoteSource<
         operationExp,
         operationColumn: operationColumn || column,
         othersThreshold,
+        orderBy,
       },
       opts: {signal, headers: this.props.headers},
     });

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

@@ -191,6 +191,7 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
     filterOwner,
     spatialFilter,
     othersThreshold,
+    orderBy = 'frequency_desc',
     rawResult,
   }: CategoryRequestOptions): Promise<CategoryResponse> {
     const filteredFeatures = this._getFilteredFeatures(
@@ -212,6 +213,7 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
       keysColumn: column,
       operation,
       othersThreshold,
+      orderBy,
     });
 
     if (rawResult) {