@carto/api-client 0.4.5 → 0.4.6-0

package/src/operations/aggregation.ts

@@ -0,0 +1,154 @@
+import {AggregationType} from '../types';
+import {FeatureData} from '../types-internal';
+
+/** @internalRemarks Source: @carto/react-core */
+export type AggregationFunction = (
+  values: unknown[] | FeatureData[],
+  keys?: string[] | string,
+  joinOperation?: AggregationType
+) => number;
+
+/** @internalRemarks Source: @carto/react-core */
+export const aggregationFunctions: Record<
+  Exclude<AggregationType, 'custom'>,
+  AggregationFunction
+> = {
+  count: (values) => values.length,
+  min: (...args) => applyAggregationFunction(min, ...args),
+  max: (...args) => applyAggregationFunction(max, ...args),
+  sum: (...args) => applyAggregationFunction(sum, ...args),
+  avg: (...args) => applyAggregationFunction(avg, ...args),
+};
+
+/** @internalRemarks Source: @carto/react-core */
+export function aggregate(
+  feature: FeatureData,
+  keys?: string[],
+  operation?: AggregationType
+): unknown {
+  if (!keys?.length) {
+    throw new Error('Cannot aggregate a feature without having keys');
+  } else if (keys.length === 1) {
+    const value = feature[keys[0]];
+    return isPotentiallyValidNumber(value) ? Number(value) : value;
+  }
+
+  const aggregationFn =
+    aggregationFunctions[operation as Exclude<AggregationType, 'custom'>];
+
+  if (!aggregationFn) {
+    throw new Error(`${operation} isn't a valid aggregation function`);
+  }
+
+  return aggregationFn(
+    keys.map((column) => {
+      const value = feature[column];
+      return isPotentiallyValidNumber(value) ? Number(value) : value;
+    })
+  );
+}
+
+/*
+ * Forced casting to Number (just of non empty strings) allows to work-around
+ * some specific situations, where a big numeric field is transformed into a string when generating the tileset(eg.PG)
+ */
+function isPotentiallyValidNumber(value: unknown): boolean {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+const applyAggregationFunction = (
+  aggFn: AggregationFunction,
+  values: unknown[] | FeatureData[],
+  keys?: string[] | string,
+  operation?: AggregationType
+) => {
+  const normalizedKeys = normalizeKeys(keys);
+  const elements =
+    (normalizedKeys?.length || 0) <= 1
+      ? filterFalsyElements(values as unknown[], normalizedKeys || [])
+      : values;
+  return aggFn(elements, keys, operation);
+};
+
+function filterFalsyElements(
+  values: unknown[] | FeatureData[],
+  keys: string[]
+) {
+  const filterFn = (value: unknown) => value !== null && value !== undefined;
+
+  if (!keys?.length) {
+    return values.filter(filterFn);
+  }
+
+  return (values as FeatureData[]).filter((v) => filterFn(v[keys[0]]));
+}
+
+// Aggregation functions
+function avg(
+  values: unknown[] | FeatureData[],
+  keys?: string[] | string,
+  joinOperation?: AggregationType
+): number {
+  return sum(values, keys, joinOperation) / (values.length || 1);
+}
+
+function sum(
+  values: unknown[] | FeatureData[],
+  keys?: string[] | string,
+  joinOperation?: AggregationType
+): number {
+  const normalizedKeys = normalizeKeys(keys);
+
+  if (normalizedKeys) {
+    return (values as FeatureData[]).reduce(
+      (a, b) => a + (aggregate(b, normalizedKeys, joinOperation) as number),
+      0
+    );
+  }
+
+  return values.reduce((a: number, b: unknown) => a + (b as number), 0);
+}
+
+function min(
+  values: unknown[] | FeatureData[],
+  keys?: string[] | string,
+  joinOperation?: AggregationType
+): number {
+  const normalizedKeys = normalizeKeys(keys);
+  if (normalizedKeys) {
+    return (values as FeatureData[]).reduce(
+      (a, b) =>
+        Math.min(a, aggregate(b, normalizedKeys, joinOperation) as number),
+      Infinity
+    );
+  }
+  return Math.min(...(values as number[]));
+}
+
+function max(
+  values: unknown[] | FeatureData[],
+  keys?: string[] | string,
+  joinOperation?: AggregationType
+): number {
+  const normalizedKeys = normalizeKeys(keys);
+  if (normalizedKeys) {
+    return (values as FeatureData[]).reduce(
+      (a, b) =>
+        Math.max(a, aggregate(b, normalizedKeys, joinOperation) as number),
+      -Infinity
+    );
+  }
+  return Math.max(...(values as number[]));
+}
+
+// Aux
+
+// Keys can come as a string (one column) or a strings array (multiple column)
+// Use always an array to make the code easier
+function normalizeKeys(keys: unknown): string[] | undefined {
+  return Array.isArray(keys)
+    ? keys
+    : typeof keys === 'string'
+      ? [keys]
+      : undefined;
+}

package/src/operations/applySorting.ts

@@ -0,0 +1,109 @@
+import {firstBy} from 'thenby';
+import {SortDirection} from '../types';
+import {FeatureData} from '../types-internal';
+
+// TODO(cleanup): Could this be simplified?
+type SortColumns = string | string[] | object[];
+
+interface SortOptions {
+  sortBy?: SortColumns;
+  sortByDirection?: SortDirection;
+  sortByColumnType?: 'number' | 'string' | 'date';
+}
+
+/**
+ * Apply sort structure to a collection of features
+ * @param features
+ * @param [sortOptions]
+ * @param [sortOptions.sortBy] - One or more columns to sort by
+ * @param [sortOptions.sortByDirection] - Direction by the columns will be sorted
+ * @param [sortOptions.sortByColumnType] - Column type
+ * @internal
+ * @internalRemarks Source: @carto/react-core
+ */
+export function applySorting(
+  features: FeatureData[],
+  {
+    sortBy,
+    sortByDirection = 'asc',
+    sortByColumnType = 'string',
+  }: SortOptions = {}
+): FeatureData[] {
+  // If sortBy is undefined, pass all features
+  if (sortBy === undefined) {
+    return features;
+  }
+
+  // sortOptions exists, but are bad formatted
+  const isValidSortBy =
+    (Array.isArray(sortBy) && sortBy.length) || // sortBy can be an array of columns
+    typeof sortBy === 'string'; // or just one column
+
+  if (!isValidSortBy) {
+    throw new Error('Sorting options are bad formatted');
+  }
+  const sortFn = createSortFn({
+    sortBy,
+    sortByDirection,
+    sortByColumnType: sortByColumnType || 'string',
+  });
+  return features.sort(sortFn);
+}
+
+// Aux
+function createSortFn({
+  sortBy,
+  sortByDirection,
+  sortByColumnType,
+}: Required<SortOptions>) {
+  const [firstSortOption, ...othersSortOptions] = normalizeSortByOptions({
+    sortBy,
+    sortByDirection,
+    sortByColumnType,
+  }) as Parameters<typeof firstBy>[];
+
+  let sortFn = firstBy(...firstSortOption);
+  for (let sortOptions of othersSortOptions) {
+    sortFn = sortFn.thenBy(...sortOptions);
+  }
+
+  return sortFn;
+}
+
+function normalizeSortByOptions({
+  sortBy,
+  sortByDirection,
+  sortByColumnType,
+}: Required<SortOptions>) {
+  const numberFormat = sortByColumnType === 'number' && {
+    cmp: (a: number, b: number) => a - b,
+  };
+  if (!Array.isArray(sortBy)) {
+    sortBy = [sortBy];
+  }
+  return sortBy.map((sortByEl) => {
+    // sortByEl is 'column'
+    if (typeof sortByEl === 'string') {
+      return [sortByEl, {direction: sortByDirection, ...numberFormat}];
+    }
+
+    if (Array.isArray(sortByEl)) {
+      // sortBy is ['column']
+      if (sortByEl[1] === undefined) {
+        return [sortByEl, {direction: sortByDirection, ...numberFormat}];
+      }
+
+      // sortBy is ['column', { ... }]
+      if (typeof sortByEl[1] === 'object') {
+        const othersSortOptions = numberFormat
+          ? {...numberFormat, ...sortByEl[1]}
+          : sortByEl[1];
+        return [
+          sortByEl[0],
+          {direction: sortByDirection, ...othersSortOptions},
+        ];
+      }
+    }
+    return sortByEl;
+  });
+}

package/src/operations/groupBy.ts

@@ -0,0 +1,59 @@
+import {aggregationFunctions, aggregate} from './aggregation.js';
+import {AggregationType} from '../types';
+import {FeatureData} from '../types-internal';
+
+/** @internalRemarks Source: @carto/react-core */
+export type GroupByFeature = {
+  name: string;
+  value: number;
+}[];
+
+/** @internalRemarks Source: @carto/react-core */
+export function groupValuesByColumn({
+  data,
+  valuesColumns,
+  joinOperation,
+  keysColumn,
+  operation,
+}: {
+  data: FeatureData[];
+  valuesColumns?: string[];
+  joinOperation?: AggregationType;
+  keysColumn: string;
+  operation: AggregationType;
+}): GroupByFeature | null {
+  if (Array.isArray(data) && data.length === 0) {
+    return null;
+  }
+  const groups = data.reduce((accumulator, item) => {
+    const group = item[keysColumn];
+
+    const values = accumulator.get(group) || [];
+    accumulator.set(group, values);
+
+    const aggregatedValue = aggregate(item, valuesColumns, joinOperation);
+
+    const isValid =
+      (operation === 'count' ? true : aggregatedValue !== null) &&
+      aggregatedValue !== undefined;
+
+    if (isValid) {
+      values.push(aggregatedValue);
+      accumulator.set(group, values);
+    }
+
+    return accumulator;
+  }, new Map()); // We use a map to be able to maintain the type in the key value
+
+  const targetOperation =
+    aggregationFunctions[operation as Exclude<AggregationType, 'custom'>];
+
+  if (targetOperation) {
+    return Array.from(groups).map(([name, value]) => ({
+      name,
+      value: targetOperation(value),
+    }));
+  }
+
+  return [];
+}

package/src/operations/groupByDate.ts

@@ -0,0 +1,98 @@
+import {AggregationType, GroupDateType} from '../types.js';
+import {getUTCMonday} from '../utils/dateUtils.js';
+import {aggregate, aggregationFunctions} from './aggregation.js';
+import {GroupByFeature} from './groupBy.js';
+
+const GROUP_KEY_FN_MAPPING: Record<GroupDateType, (date: Date) => number> = {
+  year: (date: Date) => Date.UTC(date.getUTCFullYear()),
+  month: (date: Date) => Date.UTC(date.getUTCFullYear(), date.getUTCMonth()),
+  week: (date: Date) => getUTCMonday(date),
+  day: (date: Date) =>
+    Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()),
+  hour: (date: Date) =>
+    Date.UTC(
+      date.getUTCFullYear(),
+      date.getUTCMonth(),
+      date.getUTCDate(),
+      date.getUTCHours()
+    ),
+  minute: (date: Date) =>
+    Date.UTC(
+      date.getUTCFullYear(),
+      date.getUTCMonth(),
+      date.getUTCDate(),
+      date.getUTCHours(),
+      date.getUTCMinutes()
+    ),
+  second: (date: Date) =>
+    Date.UTC(
+      date.getUTCFullYear(),
+      date.getUTCMonth(),
+      date.getUTCDate(),
+      date.getUTCHours(),
+      date.getUTCMinutes(),
+      date.getUTCSeconds()
+    ),
+};
+
+/** @internalRemarks Source: @carto/react-core */
+export function groupValuesByDateColumn({
+  data,
+  valuesColumns,
+  joinOperation,
+  keysColumn,
+  groupType,
+  operation,
+}: {
+  data: Record<string, unknown>[];
+  valuesColumns?: string[];
+  joinOperation?: Exclude<AggregationType, 'custom'>;
+  keysColumn: string;
+  groupType: GroupDateType;
+  operation?: Exclude<AggregationType, 'custom'>;
+}): GroupByFeature | null {
+  if (Array.isArray(data) && data.length === 0) {
+    return null;
+  }
+
+  const groupKeyFn = GROUP_KEY_FN_MAPPING[groupType];
+
+  if (!groupKeyFn) {
+    return null;
+  }
+
+  const groups = data.reduce((acc, item) => {
+    const value = item[keysColumn];
+    const formattedValue = new Date(value as number);
+    const groupKey = groupKeyFn(formattedValue);
+
+    if (!isNaN(groupKey)) {
+      let groupedValues = acc.get(groupKey);
+      if (!groupedValues) {
+        groupedValues = [];
+        acc.set(groupKey, groupedValues);
+      }
+
+      const aggregatedValue = aggregate(item, valuesColumns, joinOperation);
+
+      const isValid = aggregatedValue !== null && aggregatedValue !== undefined;
+
+      if (isValid) {
+        groupedValues.push(aggregatedValue);
+        acc.set(groupKey, groupedValues);
+      }
+    }
+
+    return acc;
+  }, new Map());
+
+  const targetOperation =
+    aggregationFunctions[operation as Exclude<AggregationType, 'custom'>];
+
+  return [...groups.entries()]
+    .map(([name, value]) => ({
+      name,
+      value: targetOperation(value),
+    }))
+    .sort((a, b) => a.name - b.name);
+}

package/src/operations/histogram.ts

@@ -0,0 +1,66 @@
+import {aggregate, aggregationFunctions} from './aggregation';
+import {AggregationType} from '../types';
+import {FeatureData} from '../types-internal';
+
+/**
+ * Histogram computation.
+ * @internalRemarks Source: @carto/react-core
+ */
+export function histogram({
+  data,
+  valuesColumns,
+  joinOperation,
+  ticks,
+  operation,
+}: {
+  data: FeatureData[];
+  valuesColumns?: string[];
+  joinOperation?: Exclude<AggregationType, 'custom'>;
+  ticks: number[];
+  operation: Exclude<AggregationType, 'custom'>;
+}): number[] {
+  if (Array.isArray(data) && data.length === 0) {
+    return [];
+  }
+
+  const binsContainer = [Number.MIN_SAFE_INTEGER, ...ticks].map(
+    (tick, index, arr) => ({
+      bin: index,
+      start: tick,
+      end: index === arr.length - 1 ? Number.MAX_SAFE_INTEGER : arr[index + 1],
+      values: [] as number[],
+    })
+  );
+
+  data.forEach((feature) => {
+    const featureValue = aggregate(
+      feature,
+      valuesColumns,
+      joinOperation
+    ) as number;
+
+    const isValid = featureValue !== null && featureValue !== undefined;
+
+    if (!isValid) {
+      return;
+    }
+
+    const binContainer = binsContainer.find(
+      (bin) => bin.start <= featureValue && bin.end > featureValue
+    );
+
+    if (!binContainer) {
+      return;
+    }
+
+    binContainer.values.push(featureValue);
+  });
+
+  const targetOperation = aggregationFunctions[operation];
+  const transformedBins = binsContainer.map(
+    (binContainer) => binContainer.values
+  );
+  return transformedBins.map((values) =>
+    values.length ? targetOperation(values) : 0
+  );
+}

package/src/operations/index.ts

@@ -0,0 +1,6 @@
+export * from './aggregation.js';
+export * from './applySorting.js';
+export * from './groupBy.js';
+export * from './groupByDate.js';
+export * from './histogram.js';
+export * from './scatterPlot.js';

package/src/operations/scatterPlot.ts

@@ -0,0 +1,50 @@
+import {aggregate} from './aggregation';
+import {FeatureData} from '../types-internal';
+import {AggregationType} from '../types';
+
+export type ScatterPlotFeature = [number, number][];
+
+/**
+ * Filters invalid features and formats  data.
+ * @internalRemarks Source: @carto/react-core
+ */
+export function scatterPlot({
+  data,
+  xAxisColumns,
+  xAxisJoinOperation,
+  yAxisColumns,
+  yAxisJoinOperation,
+}: {
+  data: FeatureData[];
+  xAxisColumns: string[];
+  xAxisJoinOperation?: AggregationType;
+  yAxisColumns: string[];
+  yAxisJoinOperation?: AggregationType;
+}): ScatterPlotFeature {
+  return data.reduce(
+    (acc, feature) => {
+      const xValue = aggregate(
+        feature,
+        xAxisColumns,
+        xAxisJoinOperation
+      ) as number;
+
+      const xIsValid = xValue !== null && xValue !== undefined;
+
+      const yValue = aggregate(
+        feature,
+        yAxisColumns,
+        yAxisJoinOperation
+      ) as number;
+
+      const yIsValid = yValue !== null && yValue !== undefined;
+
+      if (xIsValid && yIsValid) {
+        acc.push([xValue, yValue]);
+      }
+
+      return acc;
+    },
+    [] as [number, number][]
+  );
+}

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

@@ -2,6 +2,11 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+import {getTileFormat} from '../utils/getTileFormat';
+import {
+  WidgetTilesetSource,
+  WidgetTilesetSourceResult,
+} from '../widget-sources';
 import {baseSource} from './base-source';
 import type {
   SourceOptions,
@@ -12,17 +17,24 @@ import type {
 export type H3TilesetSourceOptions = SourceOptions & TilesetSourceOptions;
 type UrlParameters = {name: string};
 
-export type H3TilesetSourceResponse = TilejsonResult;
+export type H3TilesetSourceResponse = TilejsonResult &
+  WidgetTilesetSourceResult;
 
 export const h3TilesetSource = async function (
   options: H3TilesetSourceOptions
 ): Promise<H3TilesetSourceResponse> {
-  const {tableName} = options;
+  const {tableName, spatialDataColumn = 'h3'} = options;
   const urlParameters: UrlParameters = {name: tableName};
 
-  return baseSource<UrlParameters>(
-    'tileset',
-    options,
-    urlParameters
+  return baseSource<UrlParameters>('tileset', options, urlParameters).then(
+    (result) => ({
+      ...(result as TilejsonResult),
+      widgetSource: new WidgetTilesetSource({
+        ...options,
+        tileFormat: getTileFormat(result as TilejsonResult),
+        spatialDataColumn,
+        spatialDataType: 'h3',
+      }),
+    })
   ) as Promise<H3TilesetSourceResponse>;
 };

package/src/sources/index.ts

@@ -52,7 +52,7 @@ export type {
 } from './h3-tileset-source';
 
 export {rasterSource} from './raster-source';
-export type {RasterSourceOptions, RasterSourceResponse} from './raster-source';
+export type {RasterSourceOptions} from './raster-source';
 
 export {quadbinQuerySource} from './quadbin-query-source';
 export type {

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

@@ -2,6 +2,11 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+import {getTileFormat} from '../utils/getTileFormat';
+import {
+  WidgetTilesetSource,
+  WidgetTilesetSourceResult,
+} from '../widget-sources';
 import {baseSource} from './base-source';
 import type {
   SourceOptions,
@@ -12,17 +17,24 @@ import type {
 export type QuadbinTilesetSourceOptions = SourceOptions & TilesetSourceOptions;
 type UrlParameters = {name: string};
 
-export type QuadbinTilesetSourceResponse = TilejsonResult;
+export type QuadbinTilesetSourceResponse = TilejsonResult &
+  WidgetTilesetSourceResult;
 
 export const quadbinTilesetSource = async function (
   options: QuadbinTilesetSourceOptions
 ): Promise<QuadbinTilesetSourceResponse> {
-  const {tableName} = options;
+  const {tableName, spatialDataColumn = 'quadbin'} = options;
   const urlParameters: UrlParameters = {name: tableName};
 
-  return baseSource<UrlParameters>(
-    'tileset',
-    options,
-    urlParameters
+  return baseSource<UrlParameters>('tileset', options, urlParameters).then(
+    (result) => ({
+      ...(result as TilejsonResult),
+      widgetSource: new WidgetTilesetSource({
+        ...options,
+        tileFormat: getTileFormat(result as TilejsonResult),
+        spatialDataColumn,
+        spatialDataType: 'quadbin',
+      }),
+    })
   ) as Promise<QuadbinTilesetSourceResponse>;
 };

package/src/sources/raster-source.ts

@@ -28,6 +28,7 @@ export const rasterSource = async function (
   if (filters) {
     urlParameters.filters = filters;
   }
+
   return baseSource<UrlParameters>(
     'raster',
     options,

package/src/sources/vector-query-source.ts

@@ -3,7 +3,10 @@
 // Copyright (c) vis.gl contributors
 
 /* eslint-disable camelcase */
-import {DEFAULT_TILE_RESOLUTION} from '../constants-internal.js';
+import {
+  DEFAULT_GEO_COLUMN,
+  DEFAULT_TILE_RESOLUTION,
+} from '../constants-internal.js';
 import {
   WidgetQuerySource,
   WidgetQuerySourceResult,
@@ -43,7 +46,7 @@ export const vectorQuerySource = async function (
   const {
     columns,
     filters,
-    spatialDataColumn = 'geom',
+    spatialDataColumn = DEFAULT_GEO_COLUMN,
     sqlQuery,
     tileResolution = DEFAULT_TILE_RESOLUTION,
     queryParameters,

package/src/sources/vector-table-source.ts

@@ -3,7 +3,10 @@
 // Copyright (c) vis.gl contributors
 
 /* eslint-disable camelcase */
-import {DEFAULT_TILE_RESOLUTION} from '../constants-internal.js';
+import {
+  DEFAULT_GEO_COLUMN,
+  DEFAULT_TILE_RESOLUTION,
+} from '../constants-internal.js';
 import {
   WidgetTableSource,
   WidgetTableSourceResult,
@@ -42,7 +45,7 @@ export const vectorTableSource = async function (
   const {
     columns,
     filters,
-    spatialDataColumn = 'geom',
+    spatialDataColumn = DEFAULT_GEO_COLUMN,
     tableName,
     tileResolution = DEFAULT_TILE_RESOLUTION,
     aggregationExp,