@carto/api-client 0.4.2-alpha.0 → 0.4.3

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

@@ -12,9 +12,11 @@ import type {
 export type H3TilesetSourceOptions = SourceOptions & TilesetSourceOptions;
 type UrlParameters = {name: string};
 
+export type H3TilesetSourceResponse = TilejsonResult;
+
 export const h3TilesetSource = async function (
   options: H3TilesetSourceOptions
-): Promise<TilejsonResult> {
+): Promise<H3TilesetSourceResponse> {
   const {tableName} = options;
   const urlParameters: UrlParameters = {name: tableName};
 
@@ -22,5 +24,5 @@ export const h3TilesetSource = async function (
     'tileset',
     options,
     urlParameters
-  ) as Promise<TilejsonResult>;
+  ) as Promise<H3TilesetSourceResponse>;
 };

package/src/sources/index.ts

@@ -4,56 +4,86 @@
 
 export {SOURCE_DEFAULTS} from './base-source';
 export type {
-  VectorLayer,
-  RasterMetadataBandStats,
-  RasterBandColorinterp,
-  RasterMetadataBand,
-  RasterMetadata,
-  TilejsonResult,
   GeojsonResult,
   JsonResult,
   QueryResult,
+  QuerySourceOptions,
+  RasterBandColorinterp,
+  RasterMetadata,
+  RasterMetadataBand,
+  RasterMetadataBandStats,
+  SourceOptions,
+  TableSourceOptions,
+  TilejsonResult,
+  TilesetSourceOptions,
+  VectorLayer,
 } from './types';
 
 export {boundaryQuerySource} from './boundary-query-source';
-export type {BoundaryQuerySourceOptions} from './boundary-query-source';
+export type {
+  BoundaryQuerySourceOptions,
+  BoundaryQuerySourceResponse,
+} from './boundary-query-source';
 
 export {boundaryTableSource} from './boundary-table-source';
-export type {BoundaryTableSourceOptions} from './boundary-table-source';
+export type {
+  BoundaryTableSourceOptions,
+  BoundaryTableSourceResponse,
+} from './boundary-table-source';
 
 export {h3QuerySource} from './h3-query-source';
-export type {H3QuerySourceOptions} from './h3-query-source';
+export type {
+  H3QuerySourceOptions,
+  H3QuerySourceResponse,
+} from './h3-query-source';
 
 export {h3TableSource} from './h3-table-source';
-export type {H3TableSourceOptions} from './h3-table-source';
+export type {
+  H3TableSourceOptions,
+  H3TableSourceResponse,
+} from './h3-table-source';
 
 export {h3TilesetSource} from './h3-tileset-source';
-export type {H3TilesetSourceOptions} from './h3-tileset-source';
+export type {
+  H3TilesetSourceOptions,
+  H3TilesetSourceResponse,
+} from './h3-tileset-source';
 
 export {rasterSource} from './raster-source';
-export type {RasterSourceOptions} from './raster-source';
+export type {RasterSourceOptions, RasterSourceResponse} from './raster-source';
 
 export {quadbinQuerySource} from './quadbin-query-source';
-export type {QuadbinQuerySourceOptions} from './quadbin-query-source';
+export type {
+  QuadbinQuerySourceOptions,
+  QuadbinQuerySourceResponse,
+} from './quadbin-query-source';
 
 export {quadbinTableSource} from './quadbin-table-source';
-export type {QuadbinTableSourceOptions} from './quadbin-table-source';
+export type {
+  QuadbinTableSourceOptions,
+  QuadbinTableSourceResponse,
+} from './quadbin-table-source';
 
 export {quadbinTilesetSource} from './quadbin-tileset-source';
-export type {QuadbinTilesetSourceOptions} from './quadbin-tileset-source';
+export type {
+  QuadbinTilesetSourceOptions,
+  QuadbinTilesetSourceResponse,
+} from './quadbin-tileset-source';
 
 export {vectorQuerySource} from './vector-query-source';
-export type {VectorQuerySourceOptions} from './vector-query-source';
+export type {
+  VectorQuerySourceOptions,
+  VectorQuerySourceResponse,
+} from './vector-query-source';
 
 export {vectorTableSource} from './vector-table-source';
-export type {VectorTableSourceOptions} from './vector-table-source';
+export type {
+  VectorTableSourceOptions,
+  VectorTableSourceResponse,
+} from './vector-table-source';
 
 export {vectorTilesetSource} from './vector-tileset-source';
-export type {VectorTilesetSourceOptions} from './vector-tileset-source';
-
 export type {
-  SourceOptions,
-  QuerySourceOptions,
-  TableSourceOptions,
-  TilesetSourceOptions,
-} from './types';
+  VectorTilesetSourceOptions,
+  VectorTilesetSourceResponse,
+} from './vector-tileset-source';

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

@@ -30,9 +30,12 @@ type UrlParameters = {
   filters?: Record<string, unknown>;
 };
 
+export type QuadbinQuerySourceResponse = TilejsonResult &
+  WidgetQuerySourceResult;
+
 export const quadbinQuerySource = async function (
   options: QuadbinQuerySourceOptions
-): Promise<TilejsonResult & WidgetQuerySourceResult> {
+): Promise<QuadbinQuerySourceResponse> {
   const {
     aggregationExp,
     aggregationResLevel = DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN,
@@ -60,12 +63,7 @@ export const quadbinQuerySource = async function (
   return baseSource<UrlParameters>('query', options, urlParameters).then(
     (result) => ({
       ...(result as TilejsonResult),
-      widgetSource: new WidgetQuerySource({
-        ...options,
-        // NOTE: passing redundant spatialDataColumn here to apply the default value 'quadbin'
-        spatialDataColumn,
-        spatialDataType: 'quadbin',
-      }),
+      widgetSource: new WidgetQuerySource(options),
     })
   );
 };

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

@@ -29,9 +29,12 @@ type UrlParameters = {
   filters?: Record<string, unknown>;
 };
 
+export type QuadbinTableSourceResponse = TilejsonResult &
+  WidgetTableSourceResult;
+
 export const quadbinTableSource = async function (
   options: QuadbinTableSourceOptions
-): Promise<TilejsonResult & WidgetTableSourceResult> {
+): Promise<QuadbinTableSourceResponse> {
   const {
     aggregationExp,
     aggregationResLevel = DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN,
@@ -56,12 +59,7 @@ export const quadbinTableSource = async function (
   return baseSource<UrlParameters>('table', options, urlParameters).then(
     (result) => ({
       ...(result as TilejsonResult),
-      widgetSource: new WidgetTableSource({
-        ...options,
-        // NOTE: passing redundant spatialDataColumn here to apply the default value 'quadbin'
-        spatialDataColumn,
-        spatialDataType: 'quadbin',
-      }),
+      widgetSource: new WidgetTableSource(options),
     })
   );
 };

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

@@ -12,9 +12,11 @@ import type {
 export type QuadbinTilesetSourceOptions = SourceOptions & TilesetSourceOptions;
 type UrlParameters = {name: string};
 
+export type QuadbinTilesetSourceResponse = TilejsonResult;
+
 export const quadbinTilesetSource = async function (
   options: QuadbinTilesetSourceOptions
-): Promise<TilejsonResult> {
+): Promise<QuadbinTilesetSourceResponse> {
   const {tableName} = options;
   const urlParameters: UrlParameters = {name: tableName};
 
@@ -22,5 +24,5 @@ export const quadbinTilesetSource = async function (
     'tileset',
     options,
     urlParameters
-  ) as Promise<TilejsonResult>;
+  ) as Promise<QuadbinTilesetSourceResponse>;
 };

package/src/sources/raster-source.ts

@@ -18,9 +18,11 @@ type UrlParameters = {
   filters?: Record<string, unknown>;
 };
 
+export type RasterSourceResponse = TilejsonResult;
+
 export const rasterSource = async function (
   options: RasterSourceOptions
-): Promise<TilejsonResult> {
+): Promise<RasterSourceResponse> {
   const {tableName, filters} = options;
   const urlParameters: UrlParameters = {name: tableName};
   if (filters) {
@@ -30,5 +32,5 @@ export const rasterSource = async function (
     'raster',
     options,
     urlParameters
-  ) as Promise<TilejsonResult>;
+  ) as Promise<RasterSourceResponse>;
 };

package/src/sources/types.ts

@@ -48,33 +48,6 @@ export type SourceOptionalOptions = {
    */
   maxLengthURL?: number;
 
-  /**
-   * 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;
-
-  /**
-   * The type of geospatial support. Defaults to `'geo'`.
-   */
-  spatialDataType?: SpatialDataType;
-
-  /**
-   * 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;
-
   /**
    * By default, local in-memory caching is enabled.
    */
@@ -116,11 +89,6 @@ export type AggregationOptions = {
    * @default 6 for quadbin and 4 for h3 sources
    */
   aggregationResLevel?: number;
-
-  /**
-   * Original resolution of the spatial index data as stored in the DW
-   */
-  dataResolution?: number;
 };
 
 export type FilterOptions = {
@@ -131,9 +99,31 @@ export type FilterOptions = {
 };
 
 export type QuerySourceOptions = {
-  /** Full SQL query with query paremeter placeholders (if any). */
+  /**
+   * 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.
    *
@@ -159,6 +149,15 @@ export type QuerySourceOptions = {
    *     ```
    */
   queryParameters?: QueryParameters;
+
+  /**
+   * Comma-separated aggregation expressions. If assigned on a vector source, source is grouped by geometry and then aggregated.
+   *
+   * Example:
+   *
+   *     1 as value, avg(rev) as average_revenue
+   */
+  aggregationExp?: string;
 };
 
 export type TableSourceOptions = {
@@ -166,6 +165,37 @@ 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;
+
+  /**
+   * Comma-separated aggregation expressions. If assigned on a vector source, source is grouped by geometry and then aggregated.
+   *
+   * Example:
+   *
+   *     1 as value, avg(rev) as average_revenue
+   */
+  aggregationExp?: string;
 };
 
 export type TilesetSourceOptions = {
@@ -186,14 +216,6 @@ export type ColumnsOption = {
 
 export type SpatialDataType = 'geo' | 'h3' | 'quadbin';
 
-/**
- * Strategy used for covering spatial filter geometry with spatial indexes.
- * See https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/quadbin#quadbin_polyfill_mode
- * or https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/h3#h3_polyfill_mode for more information.
- * @internalRemarks Source: cloud-native maps-api
- * */
-export type SpatialFilterPolyfillMode = 'center' | 'intersects' | 'contains';
-
 export type TilejsonMapInstantiation = MapInstantiation & {
   tilejson: {url: string[]};
 };

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

@@ -31,11 +31,15 @@ type UrlParameters = {
   tileResolution?: string;
   q: string;
   queryParameters?: Record<string, unknown> | unknown[];
+  aggregationExp?: string;
 };
 
+export type VectorQuerySourceResponse = TilejsonResult &
+  WidgetQuerySourceResult;
+
 export const vectorQuerySource = async function (
   options: VectorQuerySourceOptions
-): Promise<TilejsonResult & WidgetQuerySourceResult> {
+): Promise<VectorQuerySourceResponse> {
   const {
     columns,
     filters,
@@ -43,6 +47,7 @@ export const vectorQuerySource = async function (
     sqlQuery,
     tileResolution = DEFAULT_TILE_RESOLUTION,
     queryParameters,
+    aggregationExp,
   } = options;
 
   const urlParameters: UrlParameters = {
@@ -61,13 +66,13 @@ export const vectorQuerySource = async function (
   if (queryParameters) {
     urlParameters.queryParameters = queryParameters;
   }
+  if (aggregationExp) {
+    urlParameters.aggregationExp = aggregationExp;
+  }
   return baseSource<UrlParameters>('query', options, urlParameters).then(
     (result) => ({
       ...(result as TilejsonResult),
-      widgetSource: new WidgetQuerySource({
-        ...options,
-        spatialDataType: 'geo',
-      }),
+      widgetSource: new WidgetQuerySource(options),
     })
   );
 };

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

@@ -30,17 +30,22 @@ type UrlParameters = {
   spatialDataColumn?: string;
   tileResolution?: string;
   name: string;
+  aggregationExp?: string;
 };
 
+export type VectorTableSourceResponse = TilejsonResult &
+  WidgetTableSourceResult;
+
 export const vectorTableSource = async function (
   options: VectorTableSourceOptions
-): Promise<TilejsonResult & WidgetTableSourceResult> {
+): Promise<VectorTableSourceResponse> {
   const {
     columns,
     filters,
     spatialDataColumn = 'geom',
     tableName,
     tileResolution = DEFAULT_TILE_RESOLUTION,
+    aggregationExp,
   } = options;
 
   const urlParameters: UrlParameters = {
@@ -56,13 +61,13 @@ export const vectorTableSource = async function (
   if (filters) {
     urlParameters.filters = filters;
   }
+  if (aggregationExp) {
+    urlParameters.aggregationExp = aggregationExp;
+  }
   return baseSource<UrlParameters>('table', options, urlParameters).then(
     (result) => ({
       ...(result as TilejsonResult),
-      widgetSource: new WidgetTableSource({
-        ...options,
-        spatialDataType: 'geo',
-      }),
+      widgetSource: new WidgetTableSource(options),
     })
   );
 };

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

@@ -12,9 +12,11 @@ import type {
 export type VectorTilesetSourceOptions = SourceOptions & TilesetSourceOptions;
 type UrlParameters = {name: string};
 
+export type VectorTilesetSourceResponse = TilejsonResult;
+
 export const vectorTilesetSource = async function (
   options: VectorTilesetSourceOptions
-): Promise<TilejsonResult> {
+): Promise<VectorTilesetSourceResponse> {
   const {tableName} = options;
   const urlParameters: UrlParameters = {name: tableName};
 
@@ -22,5 +24,5 @@ export const vectorTilesetSource = async function (
     'tileset',
     options,
     urlParameters
-  ) as Promise<TilejsonResult>;
+  ) as Promise<VectorTilesetSourceResponse>;
 };

package/src/utils.ts

@@ -57,7 +57,7 @@ export function normalizeObjectKeys<T, R extends Row<T>>(el: R): R {
 }
 
 /** @internalRemarks Source: @carto/react-core */
-export function assert(condition: unknown, message: string): asserts condition {
+export function assert(condition: unknown, message: string) {
   if (!condition) {
     throw new Error(message);
   }

package/src/widget-sources/types.ts

@@ -1,4 +1,4 @@
-import {SpatialFilterPolyfillMode, TileResolution} from '../sources/types';
+import {TileResolution} from '../sources/types';
 import {
   GroupDateType,
   SortColumnType,
@@ -10,19 +10,11 @@ import {
  * WIDGET API REQUESTS
  */
 
-export interface ViewState {
-  zoom: number;
-  latitude: number;
-  longitude: number;
-}
-
 /** Common options for {@link WidgetBaseSource} requests. */
 interface BaseRequestOptions {
   spatialFilter?: SpatialFilter;
-  spatialFiltersMode?: SpatialFilterPolyfillMode;
   abortController?: AbortController;
   filterOwner?: string;
-  viewState?: ViewState;
 }
 
 /** Options for {@link WidgetBaseSource#getCategories}. */