@carto/api-client 0.0.1-0

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

@@ -0,0 +1,255 @@
+import {executeModel} from '../models/index.js';
+import {
+  CategoryRequestOptions,
+  CategoryResponse,
+  FormulaRequestOptions,
+  FormulaResponse,
+  HistogramRequestOptions,
+  HistogramResponse,
+  RangeRequestOptions,
+  RangeResponse,
+  ScatterRequestOptions,
+  ScatterResponse,
+  TableRequestOptions,
+  TableResponse,
+  TimeSeriesRequestOptions,
+  TimeSeriesResponse,
+} from './types.js';
+import {Source, FilterLogicalOperator, Credentials, Filter} from '../types.js';
+import {SourceOptions} from '@deck.gl/carto';
+import {getApplicableFilters, normalizeObjectKeys} from '../utils.js';
+import {ApiVersion, MapType} from '../constants.js';
+import {
+  DEFAULT_API_BASE_URL,
+  DEFAULT_GEO_COLUMN,
+} from '../constants-internal.js';
+import {getClient} from '../client.js';
+import {$TODO} from '../types-internal.js';
+
+/**
+ * TODO(cleanup): Consolidate {@link SourceOptions} and {@link Source}.
+ */
+export interface WidgetBaseSourceProps extends SourceOptions, Credentials {
+  type?: MapType;
+  filters?: Record<string, Filter>;
+  filtersLogicalOperator?: FilterLogicalOperator;
+  queryParameters?: unknown[];
+  provider?: string;
+}
+
+export type WidgetSource = WidgetBaseSource<WidgetBaseSourceProps>;
+
+export class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
+  readonly props: Props;
+  readonly credentials: Required<Credentials> & {clientId: string};
+  readonly connectionName: string;
+
+  static defaultProps: Partial<WidgetBaseSourceProps> = {
+    filters: {},
+    filtersLogicalOperator: 'and',
+  };
+
+  constructor(props: Props) {
+    this.props = {...WidgetBaseSource.defaultProps, ...props};
+    this.connectionName = props.connectionName;
+    this.credentials = {
+      apiVersion: props.apiVersion || ApiVersion.V3,
+      apiBaseUrl: props.apiBaseUrl || DEFAULT_API_BASE_URL,
+      clientId: props.clientId || getClient(),
+      accessToken: props.accessToken,
+      geoColumn: props.geoColumn || DEFAULT_GEO_COLUMN,
+    };
+  }
+
+  protected getSource(owner?: string): Source {
+    return {
+      ...(this.props as $TODO),
+      credentials: this.credentials,
+      connection: this.connectionName,
+      filters: getApplicableFilters(owner, this.props.filters),
+    };
+  }
+
+  async getFormula(props: FormulaRequestOptions): Promise<FormulaResponse> {
+    const {
+      filterOwner,
+      spatialFilter,
+      abortController,
+      operationExp,
+      ...params
+    } = props;
+    const {column, operation} = params;
+
+    type FormulaModelResponse = {rows: {value: number}[]};
+
+    return executeModel({
+      model: 'formula',
+      source: this.getSource(filterOwner),
+      spatialFilter,
+      params: {column: column ?? '*', operation, operationExp},
+      opts: {abortController},
+    }).then((res: FormulaModelResponse) => normalizeObjectKeys(res.rows[0]));
+  }
+
+  async getCategories(
+    props: CategoryRequestOptions
+  ): Promise<CategoryResponse> {
+    const {filterOwner, spatialFilter, abortController, ...params} = props;
+    const {column, operation, operationColumn} = params;
+
+    type CategoriesModelResponse = {rows: {name: string; value: number}[]};
+
+    return executeModel({
+      model: 'category',
+      source: this.getSource(filterOwner),
+      spatialFilter,
+      params: {
+        column,
+        operation,
+        operationColumn: operationColumn || column,
+      },
+      opts: {abortController},
+    }).then((res: CategoriesModelResponse) => normalizeObjectKeys(res.rows));
+  }
+
+  async getRange(props: RangeRequestOptions): Promise<RangeResponse> {
+    const {filterOwner, spatialFilter, abortController, ...params} = props;
+    const {column} = params;
+
+    type RangeModelResponse = {rows: {min: number; max: number}[]};
+
+    return executeModel({
+      model: 'range',
+      source: this.getSource(filterOwner),
+      spatialFilter,
+      params: {column},
+      opts: {abortController},
+    }).then((res: RangeModelResponse) => normalizeObjectKeys(res.rows[0]));
+  }
+
+  async getTable(props: TableRequestOptions): Promise<TableResponse> {
+    const {filterOwner, spatialFilter, abortController, ...params} = props;
+    const {columns, sortBy, sortDirection, page = 0, rowsPerPage = 10} = params;
+
+    type TableModelResponse = {
+      rows: Record<string, number | string>[];
+      metadata: {total: number};
+    };
+
+    return executeModel({
+      model: 'table',
+      source: this.getSource(filterOwner),
+      spatialFilter,
+      params: {
+        column: columns,
+        sortBy,
+        sortDirection,
+        limit: rowsPerPage,
+        offset: page * rowsPerPage,
+      },
+      opts: {abortController},
+    }).then((res: TableModelResponse) => ({
+      rows: normalizeObjectKeys(res.rows),
+      totalCount: res.metadata.total,
+    }));
+  }
+
+  async getScatter(props: ScatterRequestOptions): Promise<ScatterResponse> {
+    const {filterOwner, spatialFilter, abortController, ...params} = props;
+    const {xAxisColumn, xAxisJoinOperation, yAxisColumn, yAxisJoinOperation} =
+      params;
+
+    // Make sure this is sync with the same constant in cloud-native/maps-api
+    const HARD_LIMIT = 500;
+
+    type ScatterModelResponse = {rows: {x: number; y: number}[]};
+
+    return executeModel({
+      model: 'scatterplot',
+      source: this.getSource(filterOwner),
+      spatialFilter,
+      params: {
+        xAxisColumn,
+        xAxisJoinOperation,
+        yAxisColumn,
+        yAxisJoinOperation,
+        limit: HARD_LIMIT,
+      },
+      opts: {abortController},
+    })
+      .then((res: ScatterModelResponse) => normalizeObjectKeys(res.rows))
+      .then((res) => res.map(({x, y}: {x: number; y: number}) => [x, y]));
+  }
+
+  async getTimeSeries(
+    props: TimeSeriesRequestOptions
+  ): Promise<TimeSeriesResponse> {
+    const {filterOwner, abortController, spatialFilter, ...params} = props;
+    const {
+      column,
+      operationColumn,
+      joinOperation,
+      operation,
+      stepSize,
+      stepMultiplier,
+      splitByCategory,
+      splitByCategoryLimit,
+      splitByCategoryValues,
+    } = params;
+
+    type TimeSeriesModelResponse = {
+      rows: {name: string; value: number}[];
+      metadata: {categories: string[]};
+    };
+
+    return executeModel({
+      model: 'timeseries',
+      source: this.getSource(filterOwner),
+      spatialFilter,
+      params: {
+        column,
+        stepSize,
+        stepMultiplier,
+        operationColumn: operationColumn || column,
+        joinOperation,
+        operation,
+        splitByCategory,
+        splitByCategoryLimit,
+        splitByCategoryValues,
+      },
+      opts: {abortController},
+    }).then((res: TimeSeriesModelResponse) => ({
+      rows: normalizeObjectKeys(res.rows),
+      categories: res.metadata?.categories,
+    }));
+  }
+
+  async getHistogram(
+    props: HistogramRequestOptions
+  ): Promise<HistogramResponse> {
+    const {filterOwner, spatialFilter, abortController, ...params} = props;
+    const {column, operation, ticks} = params;
+
+    type HistogramModelResponse = {rows: {tick: number; value: number}[]};
+
+    const data = await executeModel({
+      model: 'histogram',
+      source: this.getSource(filterOwner),
+      spatialFilter,
+      params: {column, operation, ticks},
+      opts: {abortController},
+    }).then((res: HistogramModelResponse) => normalizeObjectKeys(res.rows));
+
+    if (data.length) {
+      // Given N ticks the API returns up to N+1 bins, omitting any empty bins. Bins
+      // include 1 bin below the lowest tick, N-1 between ticks, and 1 bin above the highest tick.
+      const result = Array(ticks.length + 1).fill(0);
+      data.forEach(
+        ({tick, value}: {tick: number; value: number}) => (result[tick] = value)
+      );
+      return result;
+    }
+
+    return [];
+  }
+}

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

@@ -0,0 +1,25 @@
+import {
+  H3QuerySourceOptions,
+  QuadbinQuerySourceOptions,
+  VectorQuerySourceOptions,
+} from '@deck.gl/carto';
+import {MapType} from '../constants.js';
+import {WidgetBaseSource, WidgetBaseSourceProps} from './widget-base-source.js';
+import {Source} from '../types.js';
+
+type LayerQuerySourceOptions =
+  | VectorQuerySourceOptions
+  | H3QuerySourceOptions
+  | QuadbinQuerySourceOptions;
+
+export class WidgetQuerySource extends WidgetBaseSource<
+  LayerQuerySourceOptions & WidgetBaseSourceProps
+> {
+  protected override getSource(owner: string): Source {
+    return {
+      ...super.getSource(owner),
+      type: MapType.QUERY,
+      data: this.props.sqlQuery,
+    };
+  }
+}

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

@@ -0,0 +1,25 @@
+import {
+  H3TableSourceOptions,
+  QuadbinTableSourceOptions,
+  VectorTableSourceOptions,
+} from '@deck.gl/carto';
+import {WidgetBaseSource, WidgetBaseSourceProps} from './widget-base-source.js';
+import {MapType} from '../constants.js';
+import {Source} from '../types.js';
+
+type LayerTableSourceOptions =
+  | VectorTableSourceOptions
+  | H3TableSourceOptions
+  | QuadbinTableSourceOptions;
+
+export class WidgetTableSource extends WidgetBaseSource<
+  LayerTableSourceOptions & WidgetBaseSourceProps
+> {
+  protected override getSource(owner: string): Source {
+    return {
+      ...super.getSource(owner),
+      type: MapType.TABLE,
+      data: this.props.tableName,
+    };
+  }
+}

package/src/sources/wrappers.ts

@@ -0,0 +1,114 @@
+import {
+  h3TableSource as _h3TableSource,
+  h3QuerySource as _h3QuerySource,
+  vectorTableSource as _vectorTableSource,
+  vectorQuerySource as _vectorQuerySource,
+  quadbinTableSource as _quadbinTableSource,
+  quadbinQuerySource as _quadbinQuerySource,
+  VectorTableSourceOptions,
+  VectorQuerySourceOptions,
+  H3TableSourceOptions,
+  H3QuerySourceOptions,
+  QuadbinQuerySourceOptions,
+  QuadbinTableSourceOptions,
+} from '@deck.gl/carto';
+import {WidgetBaseSourceProps} from './widget-base-source.js';
+import {WidgetQuerySource} from './widget-query-source.js';
+import {WidgetTableSource} from './widget-table-source.js';
+
+/******************************************************************************
+ * RESPONSE OBJECTS
+ */
+
+type WidgetTableSourceResponse = {widgetSource: WidgetTableSource};
+type WidgetQuerySourceResponse = {widgetSource: WidgetQuerySource};
+
+export type VectorTableSourceResponse = WidgetTableSourceResponse &
+  Awaited<ReturnType<typeof _vectorTableSource>>;
+export type VectorQuerySourceResponse = WidgetQuerySourceResponse &
+  Awaited<ReturnType<typeof _vectorQuerySource>>;
+
+export type H3TableSourceResponse = WidgetTableSourceResponse &
+  Awaited<ReturnType<typeof _h3TableSource>>;
+export type H3QuerySourceResponse = WidgetQuerySourceResponse &
+  Awaited<ReturnType<typeof _h3QuerySource>>;
+
+export type QuadbinTableSourceResponse = WidgetTableSourceResponse &
+  Awaited<ReturnType<typeof _quadbinTableSource>>;
+export type QuadbinQuerySourceResponse = WidgetQuerySourceResponse &
+  Awaited<ReturnType<typeof _quadbinQuerySource>>;
+
+/******************************************************************************
+ * VECTOR SOURCES
+ */
+
+/** Wrapper adding widget support to {@link _vectorTableSource}. */
+export async function vectorTableSource(
+  props: VectorTableSourceOptions & WidgetBaseSourceProps
+): Promise<VectorTableSourceResponse> {
+  const response = await _vectorTableSource(props);
+  return {...response, widgetSource: new WidgetTableSource(props)};
+}
+
+/** Wrapper adding widget support to {@link _vectorQuerySource}. */
+export async function vectorQuerySource(
+  props: VectorQuerySourceOptions & WidgetBaseSourceProps
+): Promise<VectorQuerySourceResponse> {
+  const response = await _vectorQuerySource(props);
+  return {...response, widgetSource: new WidgetQuerySource(props)};
+}
+
+/** Wrapper adding widget support to {@link _vectorTilesetSource}. */
+export async function vectorTilesetSource() {
+  throw new Error('not implemented');
+}
+
+/******************************************************************************
+ * H3 SOURCES
+ */
+
+/** Wrapper adding widget support to {@link _h3TableSource}. */
+export async function h3TableSource(
+  props: H3TableSourceOptions & WidgetBaseSourceProps
+): Promise<H3TableSourceResponse> {
+  const response = await _h3TableSource(props);
+  return {...response, widgetSource: new WidgetTableSource(props)};
+}
+
+/** Wrapper adding widget support to {@link _h3QuerySource}. */
+export async function h3QuerySource(
+  props: H3QuerySourceOptions & WidgetBaseSourceProps
+): Promise<H3QuerySourceResponse> {
+  const response = await _h3QuerySource(props);
+  return {...response, widgetSource: new WidgetQuerySource(props)};
+}
+
+/** Wrapper adding widget support to {@link _h3TilesetSource}. */
+export async function h3TilesetSource() {
+  throw new Error('not implemented');
+}
+
+/******************************************************************************
+ * QUADBIN SOURCES
+ */
+
+/** Wrapper adding widget support to {@link _quadbinTableSource}. */
+export async function quadbinTableSource(
+  props: QuadbinTableSourceOptions & WidgetBaseSourceProps
+): Promise<QuadbinTableSourceResponse> {
+  const response = await _quadbinTableSource(props);
+  return {...response, widgetSource: new WidgetTableSource(props)};
+}
+
+/** Wrapper adding widget support to {@link _quadbinQuerySource}. */
+export async function quadbinQuerySource(
+  props: QuadbinQuerySourceOptions & WidgetBaseSourceProps
+): Promise<QuadbinQuerySourceResponse> {
+  const response = await _quadbinQuerySource(props);
+  return {...response, widgetSource: new WidgetQuerySource(props)};
+}
+
+/** Wrapper adding widget support to {@link _quadbinTilesetSource}. */
+export async function quadbinTilesetSource() {
+  throw new Error('not implemented');
+}

package/src/types-internal.ts

@@ -0,0 +1,9 @@
+/******************************************************************************
+ * INTERNAL
+ */
+
+/** @internal */
+export type $TODO = any;
+
+/** @internal */
+export type $IntentionalAny = any;

package/src/types.ts

@@ -0,0 +1,76 @@
+import type {ApiVersion, MapType, FilterType} from './constants';
+
+/******************************************************************************
+ * AUTHENTICATION
+ */
+
+/** @internalRemarks Source: @carto/react-api */
+export type Credentials = {
+  apiVersion?: ApiVersion;
+  apiBaseUrl?: string;
+  geoColumn?: string;
+  accessToken: string;
+};
+
+/******************************************************************************
+ * SOURCES
+ */
+
+/** @internalRemarks Source: @carto/react-api */
+export type Source = {
+  type: MapType;
+  connection: string;
+  credentials: Credentials;
+  data: string;
+  geoColumn?: string;
+  queryParameters?: unknown[];
+  filters?: Record<string, Filter>;
+  filtersLogicalOperator?: 'and' | 'or';
+};
+
+/******************************************************************************
+ * AGGREGATION
+ */
+
+/**
+ * Enum for the different types of aggregations available for widgets
+ * @enum {string}
+ * @readonly
+ * @internalRemarks Source: @carto/constants
+ * @internalRemarks Converted from enum to type union, for improved declarative API.
+ */
+export type AggregationType =
+  | 'count'
+  | 'avg'
+  | 'min'
+  | 'max'
+  | 'sum'
+  | 'custom';
+
+/******************************************************************************
+ * FILTERS
+ */
+
+/** @internalRemarks Source: @carto/react-api */
+export type SpatialFilter = GeoJSON.Polygon | GeoJSON.MultiPolygon;
+
+/** @internalRemarks Source: @carto/react-api, @deck.gl/carto */
+export interface Filter {
+  [FilterType.IN]?: {owner?: string; values: number[]};
+  /** [a, b] both are included. */
+  [FilterType.BETWEEN]?: {owner?: string; values: number[][]};
+  /** [a, b) a is included, b is not. */
+  [FilterType.CLOSED_OPEN]?: {owner?: string; values: number[][]};
+  [FilterType.TIME]?: {owner?: string; values: number[][]};
+  [FilterType.STRING_SEARCH]?: {owner?: string; values: string[]};
+}
+
+/** @internalRemarks Source: @carto/react-core */
+export type FilterLogicalOperator = 'and' | 'or';
+
+/******************************************************************************
+ * SORTING
+ */
+
+export type SortDirection = 'asc' | 'desc';
+export type SortColumnType = 'number' | 'string' | 'date';

package/src/utils.ts

@@ -0,0 +1,84 @@
+import {Filter} from './types.js';
+import {FilterType} from './constants.js';
+import {$TODO} from './types-internal.js';
+
+const FILTER_TYPES = new Set(Object.values(FilterType));
+const isFilterType = (type: string): type is FilterType =>
+  FILTER_TYPES.has(type as FilterType);
+
+/**
+ * @privateRemarks Source: @carto/react-widgets
+ * @internal
+ */
+export function getApplicableFilters(
+  owner?: string,
+  filters?: Record<string, Filter>
+): Record<string, Filter> {
+  if (!filters) return {};
+
+  const applicableFilters: Record<string, Filter> = {};
+
+  for (const column in filters) {
+    for (const type in filters[column]) {
+      if (!isFilterType(type)) continue;
+
+      const filter = filters[column][type];
+      if (filter && filter.owner !== owner) {
+        applicableFilters[column] ||= {};
+        applicableFilters[column][type] = filter as $TODO;
+      }
+    }
+  }
+
+  return applicableFilters;
+}
+
+type Row<T> = Record<string, T> | Record<string, T>[] | T[] | T;
+
+/**
+ * Due to each data warehouse having its own behavior with columns,
+ * we need to normalize them and transform every key to lowercase.
+ *
+ * @internalRemarks Source: @carto/react-widgets
+ * @internal
+ */
+export function normalizeObjectKeys<T, R extends Row<T>>(el: R): R {
+  if (Array.isArray(el)) {
+    return el.map((value) => normalizeObjectKeys(value)) as R;
+  } else if (typeof el !== 'object') {
+    return el;
+  }
+
+  return Object.entries(el as Record<string, T>).reduce((acc, [key, value]) => {
+    acc[key.toLowerCase()] =
+      typeof value === 'object' && value ? normalizeObjectKeys(value) : value;
+    return acc;
+  }, {} as Record<string, T>) as R;
+}
+
+/** @internalRemarks Source: @carto/react-core */
+export function assert(condition: unknown, message: string) {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+
+/**
+ * @internalRemarks Source: @carto/react-core
+ * @internal
+ */
+export class InvalidColumnError extends Error {
+  protected static readonly NAME = 'InvalidColumnError';
+
+  constructor(message: string) {
+    super(`${InvalidColumnError.NAME}: ${message}`);
+    this.name = InvalidColumnError.NAME;
+  }
+
+  static is(error: unknown) {
+    return (
+      error instanceof InvalidColumnError ||
+      (error as Error).message?.includes(InvalidColumnError.NAME)
+    );
+  }
+}