@carto/api-client 0.4.6 → 0.4.7-alpha.0

package/src/models/common.ts

@@ -1,9 +1,10 @@
 import {InvalidColumnError} from '../utils.js';
 
-/** @internalRemarks Source: @carto/react-api */
+/** @privateRemarks Source: @carto/react-api */
 export interface ModelRequestOptions {
   method: 'GET' | 'POST';
-  abortController?: AbortController;
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
   otherOptions?: Record<string, unknown>;
   body?: string;
 }
@@ -16,7 +17,7 @@ interface ModelErrorResponse {
 
 /**
  * Return more descriptive error from API
- * @internalRemarks Source: @carto/react-api
+ * @privateRemarks Source: @carto/react-api
  */
 export function dealWithApiError({
   response,
@@ -42,15 +43,15 @@ export function dealWithApiError({
     case 403:
       throw new Error('Forbidden access to the requested data');
     default:
-      const msg =
+      throw new Error(
         data && data.error && typeof data.error === 'string'
           ? data.error
-          : JSON.stringify(data?.hint || data.error?.[0]);
-      throw new Error(msg);
+          : JSON.stringify(data?.hint || data.error?.[0])
+      );
   }
 }
 
-/** @internalRemarks Source: @carto/react-api */
+/** @privateRemarks Source: @carto/react-api */
 export async function makeCall({
   url,
   accessToken,
@@ -68,19 +69,20 @@ export async function makeCall({
       headers: {
         Authorization: `Bearer ${accessToken}`,
         ...(isPost && {'Content-Type': 'application/json'}),
+        ...opts.headers,
       },
       ...(isPost && {
         method: opts?.method,
         body: opts?.body,
       }),
-      signal: opts?.abortController?.signal,
+      signal: opts?.signal,
       ...opts?.otherOptions,
     });
     data = await response.json();
   } catch (error) {
     if ((error as Error).name === 'AbortError') throw error;
 
-    throw new Error(`Failed request: ${error}`);
+    throw new Error(`Failed request: ${error as Error}`);
   }
 
   if (!response.ok) {

package/src/models/index.ts

@@ -1,3 +1,3 @@
 export {executeModel} from './model.js';
-export type {Model} from './model.js';
+export type {Model, ModelSource} from './model.js';
 export type {ModelRequestOptions} from './common.js';

package/src/models/model.ts

@@ -6,13 +6,12 @@ import {
   QueryParameters,
   SpatialFilter,
 } from '../types.js';
-import {$TODO} from '../types-internal.js';
 import {assert, isPureObject} from '../utils.js';
 import {ModelRequestOptions, makeCall} from './common.js';
 import {ApiVersion} from '../constants.js';
 import {SpatialDataType, SpatialFilterPolyfillMode} from '../sources/types.js';
 
-/** @internalRemarks Source: @carto/react-api */
+/** @privateRemarks Source: @carto/react-api */
 const AVAILABLE_MODELS = [
   'category',
   'histogram',
@@ -51,7 +50,7 @@ const REQUEST_GET_MAX_URL_LENGTH = 2048;
 
 /**
  * Execute a SQL model request.
- * @internalRemarks Source: @carto/react-api
+ * @privateRemarks Source: @carto/react-api
  */
 export function executeModel(props: {
   model: Model;
@@ -152,7 +151,7 @@ function objectToURLSearchParams(object: Record<string, unknown>) {
     } else if (object[key] === null) {
       params.append(key, 'null');
     } else if (object[key] !== undefined) {
-      params.append(key, String(object[key]));
+      params.append(key, String(object[key] as unknown));
     }
   }
   return params;

package/src/operations/aggregation.ts

@@ -0,0 +1,154 @@
+import {AggregationType} from '../types.js';
+import {FeatureData} from '../types-internal.js';
+
+/** @privateRemarks Source: @carto/react-core */
+export type AggregationFunction = (
+  values: unknown[] | FeatureData[],
+  keys?: string[] | string,
+  joinOperation?: AggregationType
+) => number;
+
+/** @privateRemarks 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),
+};
+
+/** @privateRemarks 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.js';
+import {FeatureData} from '../types-internal.js';
+
+// 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
+ * @privateRemarks 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 (const 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.js';
+import {FeatureData} from '../types-internal.js';
+
+/** @privateRemarks Source: @carto/react-core */
+export type GroupByFeature = {
+  name: string;
+  value: number;
+}[];
+
+/** @privateRemarks 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()
+    ),
+};
+
+/** @privateRemarks 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.js';
+import {AggregationType} from '../types.js';
+import {FeatureData} from '../types-internal.js';
+
+/**
+ * Histogram computation.
+ * @privateRemarks 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.js';
+import {FeatureData} from '../types-internal.js';
+import {AggregationType} from '../types.js';
+
+export type ScatterPlotFeature = [number, number][];
+
+/**
+ * Filters invalid features and formats  data.
+ * @privateRemarks 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/base-source.ts

@@ -2,10 +2,10 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {DEFAULT_API_BASE_URL} from '../constants';
-import {DEFAULT_MAX_LENGTH_URL} from '../constants-internal';
-import {buildSourceUrl} from '../api/endpoints';
-import {requestWithParameters} from '../api/request-with-parameters';
+import {DEFAULT_API_BASE_URL} from '../constants.js';
+import {DEFAULT_MAX_LENGTH_URL} from '../constants-internal.js';
+import {buildSourceUrl} from '../api/endpoints.js';
+import {requestWithParameters} from '../api/request-with-parameters.js';
 import type {
   GeojsonResult,
   JsonResult,
@@ -13,10 +13,10 @@ import type {
   SourceRequiredOptions,
   TilejsonMapInstantiation,
   TilejsonResult,
-} from './types';
-import {MapType} from '../types';
-import {APIErrorContext} from '../api';
-import {getClient} from '../client';
+} from './types.js';
+import {MapType} from '../types.js';
+import {APIErrorContext} from '../api/index.js';
+import {getClient} from '../client.js';
 
 export const SOURCE_DEFAULTS: SourceOptionalOptions = {
   apiBaseUrl: DEFAULT_API_BASE_URL,

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

@@ -3,8 +3,8 @@
 // Copyright (c) vis.gl contributors
 
 import {QueryParameters} from '../types.js';
-import {baseSource} from './base-source';
-import type {FilterOptions, SourceOptions, TilejsonResult} from './types';
+import {baseSource} from './base-source.js';
+import type {FilterOptions, SourceOptions, TilejsonResult} from './types.js';
 
 export type BoundaryQuerySourceOptions = SourceOptions &
   FilterOptions & {