@carto/api-client 0.3.0 → 0.4.0-alpha.0

package/src/sources/types.ts

@@ -1,105 +1,241 @@
-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
+
+import type {Feature} from 'geojson';
+import type {
+  Filters,
+  Format,
+  MapInstantiation,
+  QueryParameters,
+} from '../api/types';
+
+export type SourceRequiredOptions = {
+  /** Carto platform access token. */
+  accessToken: string;
+
+  /** Data warehouse connection name in Carto platform. */
+  connectionName: string;
+};
 
-/** Options for {@link WidgetBaseSource#getCategories}. */
-export interface CategoryRequestOptions extends BaseRequestOptions {
-  column: string;
-  operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
-  operationColumn?: 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#getFormula}. */
-export interface FormulaRequestOptions extends BaseRequestOptions {
-  column: string;
-  operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
-  operationExp?: string;
-}
+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#getHistogram}. */
-export interface HistogramRequestOptions extends BaseRequestOptions {
-  column: string;
-  ticks: number[];
-  operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
-}
+export type FilterOptions = {
+  /**
+   * Filters to apply to the data source on the server
+   */
+  filters?: Filters;
+};
 
-/** Options for {@link WidgetBaseSource#getRange}. */
-export interface RangeRequestOptions extends BaseRequestOptions {
-  column: 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;
+};
 
-/** 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 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;
+};
 
-/** Options for {@link WidgetBaseSource#getTable}. */
-export interface TableRequestOptions extends BaseRequestOptions {
-  columns: string[];
-  sortBy?: string;
-  sortDirection?: SortDirection;
-  sortByColumnType?: SortColumnType;
-  offset?: number;
-  limit?: number;
-}
+export type TilesetSourceOptions = {
+  /**
+   * Fully qualified name of tileset.
+   */
+  tableName: string;
+};
 
-/** 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 ColumnsOption = {
+  /**
+   * Columns to retrieve from the table.
+   *
+   * If not present, all columns are returned.
+   */
+  columns?: string[];
+};
 
-/******************************************************************************
- * WIDGET API RESPONSES
- */
+export type SpatialDataType = 'geo' | 'h3' | 'quadbin';
 
-/** Response from {@link WidgetBaseSource#getFormula}. */
-export type FormulaResponse = {value: number};
+export type TilejsonMapInstantiation = MapInstantiation & {
+  tilejson: {url: string[]};
+};
+
+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#getCategories}. */
-export type CategoryResponse = {name: string; value: number}[];
+export interface Tilestats {
+  layerCount: number;
+  layers: Layer[];
+}
 
-/** Response from {@link WidgetBaseSource#getRange}. */
-export type RangeResponse = {min: number; max: number};
+export interface Layer {
+  layer: string;
+  count: number;
+  attributeCount: number;
+  attributes: Attribute[];
+}
 
-/** Response from {@link WidgetBaseSource#getTable}. */
-export type TableResponse = {
-  totalCount: number;
-  rows: Record<string, number | string>[];
-};
+export interface Attribute {
+  attribute: string;
+  type: string;
+}
 
-/** Response from {@link WidgetBaseSource#getScatter}. */
-export type ScatterResponse = [number, number][];
+export interface VectorLayer {
+  id: string;
+  minzoom: number;
+  maxzoom: number;
+  fields: Record<string, string>;
+}
 
-/** Response from {@link WidgetBaseSource#getTimeSeries}. */
-export type TimeSeriesResponse = {
-  rows: {name: string; value: number}[];
-  categories: 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}[];
 };
-
-/** Response from {@link WidgetBaseSource#getHistogram}. */
-export type HistogramResponse = number[];

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';
+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';
+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/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';

package/src/widget-sources/types.ts

@@ -0,0 +1,105 @@
+import {
+  GroupDateType,
+  SortColumnType,
+  SortDirection,
+  SpatialFilter,
+} from '../types';
+
+/******************************************************************************
+ * WIDGET API REQUESTS
+ */
+
+/** Common options for {@link WidgetBaseSource} requests. */
+interface BaseRequestOptions {
+  spatialFilter?: SpatialFilter;
+  abortController?: AbortController;
+  filterOwner?: string;
+}
+
+/** Options for {@link WidgetBaseSource#getCategories}. */
+export interface CategoryRequestOptions extends BaseRequestOptions {
+  column: string;
+  operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
+  operationColumn?: string;
+}
+
+/** Options for {@link WidgetBaseSource#getFormula}. */
+export interface FormulaRequestOptions extends BaseRequestOptions {
+  column: string;
+  operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
+  operationExp?: string;
+}
+
+/** Options for {@link WidgetBaseSource#getHistogram}. */
+export interface HistogramRequestOptions extends BaseRequestOptions {
+  column: string;
+  ticks: number[];
+  operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
+}
+
+/** Options for {@link WidgetBaseSource#getRange}. */
+export interface RangeRequestOptions extends BaseRequestOptions {
+  column: string;
+}
+
+/** 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';
+}
+
+/** Options for {@link WidgetBaseSource#getTable}. */
+export interface TableRequestOptions extends BaseRequestOptions {
+  columns: string[];
+  sortBy?: string;
+  sortDirection?: SortDirection;
+  sortByColumnType?: SortColumnType;
+  offset?: number;
+  limit?: number;
+}
+
+/** 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[];
+}
+
+/******************************************************************************
+ * WIDGET API RESPONSES
+ */
+
+/** Response from {@link WidgetBaseSource#getFormula}. */
+export type FormulaResponse = {value: number};
+
+/** Response from {@link WidgetBaseSource#getCategories}. */
+export type CategoryResponse = {name: string; value: number}[];
+
+/** Response from {@link WidgetBaseSource#getRange}. */
+export type RangeResponse = {min: number; max: number};
+
+/** Response from {@link WidgetBaseSource#getTable}. */
+export type TableResponse = {
+  totalCount: number;
+  rows: Record<string, number | string>[];
+};
+
+/** Response from {@link WidgetBaseSource#getScatter}. */
+export type ScatterResponse = [number, number][];
+
+/** Response from {@link WidgetBaseSource#getTimeSeries}. */
+export type TimeSeriesResponse = {
+  rows: {name: string; value: number}[];
+  categories: string[];
+};
+
+/** Response from {@link WidgetBaseSource#getHistogram}. */
+export type HistogramResponse = number[];

package/src/{sources → widget-sources}/widget-base-source.ts

@@ -16,7 +16,6 @@ import {
   TimeSeriesResponse,
 } from './types.js';
 import {FilterLogicalOperator, Filter} from '../types.js';
-import {SourceOptions} from '@deck.gl/carto';
 import {getApplicableFilters, normalizeObjectKeys} from '../utils.js';
 import {
   DEFAULT_API_BASE_URL,
@@ -25,6 +24,7 @@ import {
 } from '../constants-internal.js';
 import {getClient} from '../client.js';
 import {ModelSource} from '../models/model.js';
+import {SourceOptions} from '../sources/index.js';
 
 export interface WidgetBaseSourceProps extends Omit<SourceOptions, 'filters'> {
   apiVersion?: ApiVersion;
@@ -258,8 +258,9 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
       },
       opts: {abortController},
     }).then((res: TableModelResponse) => ({
-      rows: normalizeObjectKeys(res.rows),
-      totalCount: res.metadata.total,
+      // Avoid `normalizeObjectKeys()`, which changes column names.
+      rows: res.rows ?? (res as any).ROWS,
+      totalCount: res.metadata?.total ?? (res as any).METADATA?.TOTAL,
     }));
   }
 

package/src/{sources → widget-sources}/widget-query-source.ts

@@ -2,7 +2,7 @@ import {
   H3QuerySourceOptions,
   QuadbinQuerySourceOptions,
   VectorQuerySourceOptions,
-} from '@deck.gl/carto';
+} from '../sources/index.js';
 import {MapType} from '../constants-internal.js';
 import {WidgetBaseSource, WidgetBaseSourceProps} from './widget-base-source.js';
 import {ModelSource} from '../models/model.js';

package/src/{sources → widget-sources}/widget-table-source.ts

@@ -2,7 +2,7 @@ import {
   H3TableSourceOptions,
   QuadbinTableSourceOptions,
   VectorTableSourceOptions,
-} from '@deck.gl/carto';
+} from '../sources/index.js';
 import {WidgetBaseSource, WidgetBaseSourceProps} from './widget-base-source.js';
 import {MapType} from '../constants-internal.js';
 import {ModelSource} from '../models/model.js';