Spatial index widgets second proposal (#35)

src/api/query.ts

@@ -12,8 +12,7 @@ import {buildQueryUrl} from './endpoints';
 import {requestWithParameters} from './request-with-parameters';
 import {APIErrorContext} from './carto-api-error';
 
-export type QueryOptions = SourceOptions &
-  Omit<QuerySourceOptions, 'spatialDataColumn'>;
+export type QueryOptions = SourceOptions & QuerySourceOptions;
 type UrlParameters = {q: string; queryParameters?: string};
 
 export const query = async function (

src/sources/h3-query-source.ts

@@ -18,9 +18,7 @@ import type {
 export type H3QuerySourceOptions = SourceOptions &
   QuerySourceOptions &
   AggregationOptions &
-  FilterOptions & {
-    spatialDataType: 'h3';
-  };
+  FilterOptions;
 
 type UrlParameters = {
   aggregationExp: string;
@@ -33,7 +31,7 @@ type UrlParameters = {
 };
 
 export const h3QuerySource = async function (
-  options: Omit<H3QuerySourceOptions, 'spatialDataType'>
+  options: H3QuerySourceOptions
 ): Promise<TilejsonResult & WidgetQuerySourceResult> {
   const {
     aggregationExp,

src/sources/h3-table-source.ts

@@ -18,9 +18,7 @@ import type {
 export type H3TableSourceOptions = SourceOptions &
   TableSourceOptions &
   AggregationOptions &
-  FilterOptions & {
-    spatialDataType: 'h3';
-  };
+  FilterOptions;
 
 type UrlParameters = {
   aggregationExp: string;
@@ -32,7 +30,7 @@ type UrlParameters = {
 };
 
 export const h3TableSource = async function (
-  options: Omit<H3TableSourceOptions, 'spatialDataType'>
+  options: H3TableSourceOptions
 ): Promise<TilejsonResult & WidgetTableSourceResult> {
   const {
     aggregationExp,

src/sources/quadbin-query-source.ts

@@ -18,9 +18,7 @@ import type {
 export type QuadbinQuerySourceOptions = SourceOptions &
   QuerySourceOptions &
   AggregationOptions &
-  FilterOptions & {
-    spatialDataType: 'quadbin';
-  };
+  FilterOptions;
 
 type UrlParameters = {
   aggregationExp: string;
@@ -33,7 +31,7 @@ type UrlParameters = {
 };
 
 export const quadbinQuerySource = async function (
-  options: Omit<QuadbinQuerySourceOptions, 'spatialDataType'>
+  options: QuadbinQuerySourceOptions
 ): Promise<TilejsonResult & WidgetQuerySourceResult> {
   const {
     aggregationExp,

src/sources/quadbin-table-source.ts

@@ -18,9 +18,7 @@ import type {
 export type QuadbinTableSourceOptions = SourceOptions &
   TableSourceOptions &
   AggregationOptions &
-  FilterOptions & {
-    spatialDataType: 'quadbin';
-  };
+  FilterOptions;
 
 type UrlParameters = {
   aggregationExp: string;
@@ -32,7 +30,7 @@ type UrlParameters = {
 };
 
 export const quadbinTableSource = async function (
-  options: Omit<QuadbinTableSourceOptions, 'spatialDataType'>
+  options: QuadbinTableSourceOptions
 ): Promise<TilejsonResult & WidgetTableSourceResult> {
   const {
     aggregationExp,

src/sources/types.ts

@@ -47,6 +47,33 @@ export type SourceOptionalOptions = {
    * @default {@link DEFAULT_MAX_LENGTH_URL}
    */
   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;
 };
 
 export type SourceOptions = SourceRequiredOptions &
@@ -68,6 +95,11 @@ 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 = {
@@ -78,31 +110,10 @@ export type FilterOptions = {
 };
 
 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. */
+  /** Full SQL query with query paremeter placeholders (if any). */
   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.
    *
@@ -135,28 +146,6 @@ 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;
 };
 
 export type TilesetSourceOptions = {

src/sources/vector-query-source.ts

@@ -21,9 +21,7 @@ import type {
 export type VectorQuerySourceOptions = SourceOptions &
   QuerySourceOptions &
   FilterOptions &
-  ColumnsOption & {
-    spatialDataType: 'geo';
-  };
+  ColumnsOption;
 
 type UrlParameters = {
   columns?: string;
@@ -36,7 +34,7 @@ type UrlParameters = {
 };
 
 export const vectorQuerySource = async function (
-  options: Omit<VectorQuerySourceOptions, 'spatialDataType'>
+  options: VectorQuerySourceOptions
 ): Promise<TilejsonResult & WidgetQuerySourceResult> {
   const {
     columns,

src/sources/vector-table-source.ts

@@ -21,9 +21,7 @@ import type {
 export type VectorTableSourceOptions = SourceOptions &
   TableSourceOptions &
   FilterOptions &
-  ColumnsOption & {
-    spatialDataType: 'geo';
-  };
+  ColumnsOption;
 
 type UrlParameters = {
   columns?: string;
@@ -35,7 +33,7 @@ type UrlParameters = {
 };
 
 export const vectorTableSource = async function (
-  options: Omit<VectorTableSourceOptions, 'spatialDataType'>
+  options: VectorTableSourceOptions
 ): Promise<TilejsonResult & WidgetTableSourceResult> {
   const {
     columns,

src/spatial-index.ts

@@ -4,6 +4,7 @@ import {
 } from './constants-internal';
 import {ModelSource} from './models/model';
 import {AggregationOptions} from './sources/types';
+import { assert } from './utils';
 
 const DEFAULT_TILE_SIZE = 512;
 const QUADBIN_ZOOM_MAX_OFFSET = 4;
@@ -12,8 +13,12 @@ export function getSpatialFiltersResolution({
   source,
   viewState,
 }: {
-  source: ModelSource & AggregationOptions;
-  viewState: {
+  source: {
+    spatialDataType?: ModelSource['spatialDataType'];
+    dataResolution?: ModelSource['dataResolution'];
+    aggregationResLevel?: AggregationOptions['aggregationResLevel']
+  };
+  viewState?: {
     zoom: number;
     latitude: number;
     longitude: number;
@@ -23,7 +28,7 @@ export function getSpatialFiltersResolution({
     return undefined;
   }
 
-  const currentZoom = viewState.zoom ?? 1;
+  assert(viewState, "viewState prop is required to compute automatic spatialFiltersResolution when using spatialFilter with spatial indexes. Either pass a `spatialFiltersResolution` prop or a `viewState` prop to avoid this error")
 
   const dataResolution = source.dataResolution ?? Number.MAX_VALUE;
 
@@ -38,7 +43,7 @@ export function getSpatialFiltersResolution({
     Math.floor(aggregationResLevel)
   );
 
-  const currentZoomInt = Math.ceil(currentZoom);
+  const currentZoomInt = Math.ceil(viewState.zoom);
   if (source.spatialDataType === 'h3') {
     const tileSize = DEFAULT_TILE_SIZE;
     const maxResolutionForZoom =
@@ -50,11 +55,7 @@ export function getSpatialFiltersResolution({
       ? Math.min(dataResolution, maxResolutionForZoom)
       : dataResolution;
 
-    const hexagonResolution =
-      getHexagonResolution(
-        {zoom: currentZoom, latitude: viewState.latitude},
-        tileSize
-      ) + aggregationResLevelOffset;
+    const hexagonResolution = getHexagonResolution(viewState, tileSize) + aggregationResLevelOffset;
 
     return Math.min(hexagonResolution, maxSpatialFiltersResolution);
   }

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) {
+export function assert(condition: unknown, message: string): asserts condition {
   if (!condition) {
     throw new Error(message);
   }

src/widget-sources/types.ts

@@ -10,13 +10,20 @@ import {
  * WIDGET API REQUESTS
  */
 
+export interface ViewState {
+  zoom: number;
+  latitude: number;
+  longitude: number;
+};
+
 /** Common options for {@link WidgetBaseSource} requests. */
 interface BaseRequestOptions {
   spatialFilter?: SpatialFilter;
   spatialFiltersResolution?: number;
   spatialFiltersMode?: SpatialFilterPolyfillMode;
   abortController?: AbortController;
   filterOwner?: string;
+  viewState?: ViewState;
 }
 
 /** Options for {@link WidgetBaseSource#getCategories}. */