@carto/api-client 0.3.1 → 0.4.0-alpha.1

package/src/sources/types.ts

@@ -1,105 +1,237 @@
-import {
-  GroupDateType,
-  SortColumnType,
-  SortDirection,
-  SpatialFilter,
-} from '../types';
-
-/******************************************************************************
- * WIDGET API REQUESTS
- */
-
-/** Common options for {@link WidgetBaseSource} requests. */
-interface BaseRequestOptions {
-  spatialFilter?: SpatialFilter;
-  abortController?: AbortController;
-  filterOwner?: string;
-}
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
 
-/** Options for {@link WidgetBaseSource#getCategories}. */
-export interface CategoryRequestOptions extends BaseRequestOptions {
-  column: string;
-  operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
-  operationColumn?: string;
-}
+import type {Feature} from 'geojson';
+import {Filters, Format, QueryParameters} from '../types';
+import {MapInstantiation} from '../types-internal';
 
-/** Options for {@link WidgetBaseSource#getFormula}. */
-export interface FormulaRequestOptions extends BaseRequestOptions {
-  column: string;
-  operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
-  operationExp?: string;
-}
+export type SourceRequiredOptions = {
+  /** Carto platform access token. */
+  accessToken: string;
 
-/** Options for {@link WidgetBaseSource#getHistogram}. */
-export interface HistogramRequestOptions extends BaseRequestOptions {
-  column: string;
-  ticks: number[];
-  operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
-}
+  /** Data warehouse connection name in Carto platform. */
+  connectionName: string;
+};
 
-/** Options for {@link WidgetBaseSource#getRange}. */
-export interface RangeRequestOptions extends BaseRequestOptions {
-  column: string;
-}
+export type SourceOptionalOptions = {
+  /**
+   * Base URL of the CARTO Maps API.
+   *
+   * Example for account located in EU-west region: `https://gcp-eu-west1.api.carto.com`
+   *
+   * @default https://gcp-us-east1.api.carto.com
+   */
+  apiBaseUrl: string;
+
+  /**
+   * Custom HTTP headers added to map instantiation and data requests.
+   */
+  headers: Record<string, string>;
+
+  /**
+   * Cache buster value returned by map instantiation.
+   *
+   * Carto source saves `cache` value of map instantiation response in `cache.value`, so it can be used to
+   * check if underlying map data has changed between distinct source requests.
+   */
+  cache?: {value?: number};
+
+  clientId: string;
+  /** @deprecated  use `query` instead **/
+  format: Format;
+
+  /**
+   * Maximum URL character length. Above this limit, requests use POST.
+   * Used to avoid browser and CDN limits.
+   * @default {@link DEFAULT_MAX_LENGTH_URL}
+   */
+  maxLengthURL?: number;
+};
 
-/** Options for {@link WidgetBaseSource#getScatter}. */
-export interface ScatterRequestOptions extends BaseRequestOptions {
-  xAxisColumn: string;
-  xAxisJoinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
-  yAxisColumn: string;
-  yAxisJoinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
-}
+export type SourceOptions = SourceRequiredOptions &
+  Partial<SourceOptionalOptions>;
+
+export type AggregationOptions = {
+  /**
+   * Defines the aggregation expressions that will be calculated from the resulting columns on each grid cell.
+   *
+   * Example:
+   *
+   *     sum(pop) as total_population, avg(rev) as average_revenue
+   */
+  aggregationExp: string;
+
+  /**
+   * Defines the tile aggregation resolution.
+   *
+   * @default 6 for quadbin and 4 for h3 sources
+   */
+  aggregationResLevel?: number;
+};
 
-/** Options for {@link WidgetBaseSource#getTable}. */
-export interface TableRequestOptions extends BaseRequestOptions {
-  columns: string[];
-  sortBy?: string;
-  sortDirection?: SortDirection;
-  sortByColumnType?: SortColumnType;
-  offset?: number;
-  limit?: number;
-}
+export type FilterOptions = {
+  /**
+   * Filters to apply to the data source on the server
+   */
+  filters?: Filters;
+};
 
-/** Options for {@link WidgetBaseSource#getTimeSeries}. */
-export interface TimeSeriesRequestOptions extends BaseRequestOptions {
-  column: string;
-  stepSize?: GroupDateType;
-  stepMultiplier?: number;
-  operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
-  operationColumn?: string;
-  joinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
-  splitByCategory?: string;
-  splitByCategoryLimit?: number;
-  splitByCategoryValues?: string[];
-}
+export type QuerySourceOptions = {
+  /**
+   * The column name and the type of geospatial support.
+   *
+   * If not present, defaults to `'geom'` for generic queries, `'quadbin'` for Quadbin sources and `'h3'` for H3 sources.
+   */
+  spatialDataColumn?: string;
+
+  /** SQL query. */
+  sqlQuery: string;
+
+  /**
+   * Relative resolution of a tile. Higher values increase density and data size. At `tileResolution = 1`, tile geometry is
+   * quantized to a 1024x1024 grid. Increasing or decreasing the resolution will increase or decrease the dimensions of
+   * the quantization grid proportionately.
+   *
+   * Supported `tileResolution` values, with corresponding grid sizes:
+   *
+   * - 0.25: 256x256
+   * - 0.5: 512x512
+   * - 1: 1024x1024
+   * - 2: 2048x2048
+   * - 4: 4096x4096
+   */
+  tileResolution?: TileResolution;
+
+  /**
+   * Values for named or positional paramteres in the query.
+   *
+   * The way query parameters are determined by data warehouse.
+   *
+   *  * BigQuery has named query parameters, specified with a dictionary, and referenced by key (`@key`)
+   *
+   *     ```
+   *     sqlQuery: "SELECT * FROM carto-demo-data.demo_tables.retail_stores WHERE storetype = ⁣@type AND revenue > ⁣@minRevenue"
+   *     queryParameters: { type: 'Supermarket', minRevenue: 1000000 }
+   *     ```
+   * * Snowflake supports positional parameters, in the form `:1`, `:2`, etc.
+   *
+   *     ```
+   *     sqlQuery: "SELECT * FROM demo_db.public.import_retail_stores WHERE storetype = :2 AND revenue > :1
+   *     queryParameters: [100000, "Supermarket"]
+   *     ```
+   * * Postgres and Redhisft supports positional parameters, but in the form `$1`, `$2`, etc.
+   *
+   *     ```
+   *     sqlQuery: "SELECT * FROM carto_demo_data.demo_tables.retail_stores WHERE storetype = $2 AND revenue > $1
+   *     queryParameters: [100000, "Supermarket"]
+   *     ```
+   */
+  queryParameters?: QueryParameters;
+};
 
-/******************************************************************************
- * WIDGET API RESPONSES
- */
+export type TableSourceOptions = {
+  /**
+   * Fully qualified name of table.
+   */
+  tableName: string;
+
+  /**
+   * The column name and the type of geospatial support.
+   *
+   * If not present, defaults to `'geom'` for generic tables, `'quadbin'` for Quadbin sources and `'h3'` for H3 sources.
+   */
+  spatialDataColumn?: string;
+
+  /**
+   * Relative resolution of a tile. Higher values increase density and data size. At `tileResolution = 1`, tile geometry is
+   * quantized to a 1024x1024 grid. Increasing or decreasing the resolution will increase or decrease the dimensions of
+   * the quantization grid proportionately.
+   *
+   * Supported `tileResolution` values, with corresponding grid sizes:
+   *
+   * - 0.25: 256x256
+   * - 0.5: 512x512
+   * - 1: 1024x1024
+   * - 2: 2048x2048
+   * - 4: 4096x4096
+   */
+  tileResolution?: TileResolution;
+};
 
-/** Response from {@link WidgetBaseSource#getFormula}. */
-export type FormulaResponse = {value: number};
+export type TilesetSourceOptions = {
+  /**
+   * Fully qualified name of tileset.
+   */
+  tableName: string;
+};
 
-/** Response from {@link WidgetBaseSource#getCategories}. */
-export type CategoryResponse = {name: string; value: number}[];
+export type ColumnsOption = {
+  /**
+   * Columns to retrieve from the table.
+   *
+   * If not present, all columns are returned.
+   */
+  columns?: string[];
+};
 
-/** Response from {@link WidgetBaseSource#getRange}. */
-export type RangeResponse = {min: number; max: number};
+export type SpatialDataType = 'geo' | 'h3' | 'quadbin';
 
-/** Response from {@link WidgetBaseSource#getTable}. */
-export type TableResponse = {
-  totalCount: number;
-  rows: Record<string, number | string>[];
+export type TilejsonMapInstantiation = MapInstantiation & {
+  tilejson: {url: string[]};
 };
 
-/** Response from {@link WidgetBaseSource#getScatter}. */
-export type ScatterResponse = [number, number][];
+export type TileResolution = 0.25 | 0.5 | 1 | 2 | 4;
+
+export interface Tilejson {
+  tilejson: string;
+  name: string;
+  description: string;
+  version: string;
+  attribution: string;
+  scheme: string;
+  tiles: string[];
+  properties_tiles: string[];
+  minresolution: number;
+  maxresolution: number;
+  minzoom: number;
+  maxzoom: number;
+  bounds: [number, number, number, number];
+  center: [number, number, number];
+  vector_layers: VectorLayer[];
+  tilestats: Tilestats;
+  tileResolution?: TileResolution;
+}
 
-/** Response from {@link WidgetBaseSource#getTimeSeries}. */
-export type TimeSeriesResponse = {
-  rows: {name: string; value: number}[];
-  categories: string[];
-};
+export interface Tilestats {
+  layerCount: number;
+  layers: Layer[];
+}
 
-/** Response from {@link WidgetBaseSource#getHistogram}. */
-export type HistogramResponse = number[];
+export interface Layer {
+  layer: string;
+  count: number;
+  attributeCount: number;
+  attributes: Attribute[];
+}
+
+export interface Attribute {
+  attribute: string;
+  type: string;
+}
+
+export interface VectorLayer {
+  id: string;
+  minzoom: number;
+  maxzoom: number;
+  fields: Record<string, string>;
+}
+
+export type TilejsonResult = Tilejson & {accessToken: string};
+export type GeojsonResult = {type: 'FeatureCollection'; features: Feature[]};
+export type JsonResult = any[];
+export type QueryResult = {
+  meta: {cacheHit: boolean; location: string; totalBytesProcessed: string};
+  rows: Record<string, any>[];
+  schema: {name: string; type: string}[];
+};

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

@@ -0,0 +1,65 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/* eslint-disable camelcase */
+import {DEFAULT_TILE_RESOLUTION} from '../constants.js';
+import {baseSource} from './base-source';
+import type {
+  FilterOptions,
+  SourceOptions,
+  QuerySourceOptions,
+  SpatialDataType,
+  TilejsonResult,
+  ColumnsOption,
+} from './types';
+
+export type VectorQuerySourceOptions = SourceOptions &
+  QuerySourceOptions &
+  FilterOptions &
+  ColumnsOption;
+
+type UrlParameters = {
+  columns?: string;
+  filters?: Record<string, unknown>;
+  spatialDataType: SpatialDataType;
+  spatialDataColumn?: string;
+  tileResolution?: string;
+  q: string;
+  queryParameters?: Record<string, unknown> | unknown[];
+};
+
+export const vectorQuerySource = async function (
+  options: VectorQuerySourceOptions
+): Promise<TilejsonResult> {
+  const {
+    columns,
+    filters,
+    spatialDataColumn = 'geom',
+    sqlQuery,
+    tileResolution = DEFAULT_TILE_RESOLUTION,
+    queryParameters,
+  } = options;
+
+  const urlParameters: UrlParameters = {
+    spatialDataColumn,
+    spatialDataType: 'geo',
+    tileResolution: tileResolution.toString(),
+    q: sqlQuery,
+  };
+
+  if (columns) {
+    urlParameters.columns = columns.join(',');
+  }
+  if (filters) {
+    urlParameters.filters = filters;
+  }
+  if (queryParameters) {
+    urlParameters.queryParameters = queryParameters;
+  }
+  return baseSource<UrlParameters>(
+    'query',
+    options,
+    urlParameters
+  ) as Promise<TilejsonResult>;
+};

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

@@ -0,0 +1,59 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/* eslint-disable camelcase */
+import {DEFAULT_TILE_RESOLUTION} from '../constants.js';
+import {baseSource} from './base-source';
+import type {
+  FilterOptions,
+  ColumnsOption,
+  SourceOptions,
+  SpatialDataType,
+  TableSourceOptions,
+  TilejsonResult,
+} from './types';
+
+export type VectorTableSourceOptions = SourceOptions &
+  TableSourceOptions &
+  FilterOptions &
+  ColumnsOption;
+type UrlParameters = {
+  columns?: string;
+  filters?: Record<string, unknown>;
+  spatialDataType: SpatialDataType;
+  spatialDataColumn?: string;
+  tileResolution?: string;
+  name: string;
+};
+
+export const vectorTableSource = async function (
+  options: VectorTableSourceOptions
+): Promise<TilejsonResult> {
+  const {
+    columns,
+    filters,
+    spatialDataColumn = 'geom',
+    tableName,
+    tileResolution = DEFAULT_TILE_RESOLUTION,
+  } = options;
+
+  const urlParameters: UrlParameters = {
+    name: tableName,
+    spatialDataColumn,
+    spatialDataType: 'geo',
+    tileResolution: tileResolution.toString(),
+  };
+
+  if (columns) {
+    urlParameters.columns = columns.join(',');
+  }
+  if (filters) {
+    urlParameters.filters = filters;
+  }
+  return baseSource<UrlParameters>(
+    'table',
+    options,
+    urlParameters
+  ) as Promise<TilejsonResult>;
+};

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

@@ -0,0 +1,26 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {baseSource} from './base-source';
+import type {
+  SourceOptions,
+  TilesetSourceOptions,
+  TilejsonResult,
+} from './types';
+
+export type VectorTilesetSourceOptions = SourceOptions & TilesetSourceOptions;
+type UrlParameters = {name: string};
+
+export const vectorTilesetSource = async function (
+  options: VectorTilesetSourceOptions
+): Promise<TilejsonResult> {
+  const {tableName} = options;
+  const urlParameters: UrlParameters = {name: tableName};
+
+  return baseSource<UrlParameters>(
+    'tileset',
+    options,
+    urlParameters
+  ) as Promise<TilejsonResult>;
+};

package/src/types-internal.ts

@@ -1,9 +1,62 @@
 /******************************************************************************
- * INTERNAL
+ * COMMON
  */
 
+import {Format} from './types';
+
 /** @internal */
 export type $TODO = any;
 
 /** @internal */
 export type $IntentionalAny = any;
+
+/******************************************************************************
+ * MAP INSTANTIATION
+ */
+
+/**
+ * @internalRemarks Source: @deck.gl/carto
+ * @internal
+ */
+export enum SchemaFieldType {
+  Number = 'number',
+  Bigint = 'bigint',
+  String = 'string',
+  Geometry = 'geometry',
+  Timestamp = 'timestamp',
+  Object = 'object',
+  Boolean = 'boolean',
+  Variant = 'variant',
+  Unknown = 'unknown',
+}
+
+/**
+ * @internalRemarks Source: @deck.gl/carto
+ * @internal
+ */
+export interface SchemaField {
+  name: string;
+  type: SchemaFieldType; // Field type in the CARTO stack, common for all providers
+}
+
+/**
+ * @internalRemarks Source: @deck.gl/carto
+ * @internal
+ */
+export interface MapInstantiation extends MapInstantiationFormats {
+  nrows: number;
+  size?: number;
+  schema: SchemaField[];
+}
+
+/**
+ * @internalRemarks Source: @deck.gl/carto
+ * @internal
+ */
+type MapInstantiationFormats = Record<
+  Format,
+  {
+    url: string[];
+    error?: any;
+  }
+>;

package/src/types.ts

@@ -1,6 +1,16 @@
 import type {FilterType} from './constants.js';
 import type {Polygon, MultiPolygon} from 'geojson';
 
+/******************************************************************************
+ * MAPS AND TILES
+ */
+
+/** @internalRemarks Source: @deck.gl/carto */
+export type Format = 'json' | 'geojson' | 'tilejson';
+
+/** @internalRemarks Source: @carto/constants, @deck.gl/carto */
+export type MapType = 'boundary' | 'query' | 'table' | 'tileset' | 'raster';
+
 /******************************************************************************
  * AGGREGATION
  */
@@ -26,6 +36,12 @@ export type AggregationType =
 /** @internalRemarks Source: @carto/react-api */
 export type SpatialFilter = Polygon | MultiPolygon;
 
+/** @internalRemarks Source: @deck.gl/carto */
+export interface Filters {
+  [column: string]: Filter;
+}
+
+// TODO: Would `{[FilterType.IN]?: number[] | string[]}` also be valid?
 /** @internalRemarks Source: @carto/react-api, @deck.gl/carto */
 export interface Filter {
   [FilterType.IN]?: {owner?: string; values: number[] | string[]};

package/src/utils.ts

@@ -90,3 +90,11 @@ export function isEmptyObject(object: object): boolean {
   }
   return true;
 }
+
+/** @internal */
+export const isObject: (x: unknown) => boolean = (x) =>
+  x !== null && typeof x === 'object';
+
+/** @internal */
+export const isPureObject: (x: any) => boolean = (x) =>
+  isObject(x) && x.constructor === {}.constructor;

package/src/widget-sources/index.ts

@@ -0,0 +1,5 @@
+export * from './widget-base-source.js';
+export * from './widget-query-source.js';
+export * from './widget-table-source.js';
+export * from './wrappers.js';
+export * from './types.js';