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

package/src/utils/transformToTileCoords.ts

@@ -0,0 +1,85 @@
+import {lngLatToWorld} from '@math.gl/web-mercator';
+import {BBox, GeoJsonGeometryTypes, Geometry, Position} from 'geojson';
+
+type TransformFn = (coordinates: any[], bbox: Position[]) => any[];
+
+const TRANSFORM_FN: Record<
+  Exclude<GeoJsonGeometryTypes, 'GeometryCollection'>,
+  TransformFn
+> = {
+  Point: transformPoint,
+  MultiPoint: transformMultiPoint,
+  LineString: transformLineString,
+  MultiLineString: transformMultiLineString,
+  Polygon: transformPolygon,
+  MultiPolygon: transformMultiPolygon,
+};
+
+/**
+ * Transform WGS84 coordinates to tile coords.
+ * It's the inverse of deck.gl coordinate-transform (https://github.com/visgl/deck.gl/blob/master/modules/geo-layers/src/mvt-layer/coordinate-transform.js)
+ *
+ * @param geometry - any valid geojson geometry
+ * @param bbox - geojson bbox
+ */
+export function transformToTileCoords<T extends Geometry>(
+  geometry: T,
+  bbox: BBox
+): T {
+  const [west, south, east, north] = bbox;
+  const nw = projectFlat([west, north]);
+  const se = projectFlat([east, south]);
+  const projectedBbox = [nw, se];
+
+  if (geometry.type === 'GeometryCollection') {
+    throw new Error('Unsupported geometry type GeometryCollection');
+  }
+
+  const transformFn = TRANSFORM_FN[geometry.type];
+  const coordinates = transformFn(geometry.coordinates, projectedBbox);
+  return {...geometry, coordinates};
+}
+
+function transformPoint([pointX, pointY]: Position, [nw, se]: Position[]) {
+  const x = inverseLerp(nw[0], se[0], pointX);
+  const y = inverseLerp(nw[1], se[1], pointY);
+
+  return [x, y];
+}
+
+function getPoints(geometry: Position[], bbox: Position[]) {
+  return geometry.map((g) => transformPoint(projectFlat(g), bbox));
+}
+
+function transformMultiPoint(multiPoint: Position[], bbox: Position[]) {
+  return getPoints(multiPoint, bbox);
+}
+
+function transformLineString(line: Position[], bbox: Position[]) {
+  return getPoints(line, bbox);
+}
+
+function transformMultiLineString(
+  multiLineString: Position[][],
+  bbox: Position[]
+) {
+  return multiLineString.map((lineString) =>
+    transformLineString(lineString, bbox)
+  );
+}
+
+function transformPolygon(polygon: Position[][], bbox: Position[]) {
+  return polygon.map((polygonRing) => getPoints(polygonRing, bbox));
+}
+
+function transformMultiPolygon(multiPolygon: Position[][][], bbox: Position[]) {
+  return multiPolygon.map((polygon) => transformPolygon(polygon, bbox));
+}
+
+function projectFlat(xyz: Position): Position {
+  return lngLatToWorld(xyz);
+}
+
+function inverseLerp(a: number, b: number, x: number): number {
+  return (x - a) / (b - a);
+}

package/src/utils.ts

@@ -49,15 +49,18 @@ export function normalizeObjectKeys<T, R extends Row<T>>(el: R): R {
     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;
+  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) {
+export function assert(condition: unknown, message: string): asserts condition {
   if (!condition) {
     throw new Error(message);
   }

package/src/widget-sources/index.ts

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

package/src/widget-sources/types.ts

@@ -1,31 +1,43 @@
-import {TileResolution} from '../sources/types';
+import {SpatialFilterPolyfillMode, TileResolution} from '../sources/types';
 import {
   GroupDateType,
   SortColumnType,
   SortDirection,
   SpatialFilter,
 } from '../types';
+import type {WidgetRemoteSource} from './widget-remote-source';
 
 /******************************************************************************
  * WIDGET API REQUESTS
  */
 
-/** Common options for {@link WidgetBaseSource} requests. */
+export interface ViewState {
+  zoom: number;
+  latitude: number;
+  longitude: number;
+}
+
+/** Common options for {@link WidgetRemoteSource} requests. */
 interface BaseRequestOptions {
   spatialFilter?: SpatialFilter;
+  spatialFiltersMode?: SpatialFilterPolyfillMode;
+  /** Required for table- and query-based spatial index sources (H3, Quadbin). */
+  spatialIndexReferenceViewState?: ViewState;
   abortController?: AbortController;
   filterOwner?: string;
 }
 
-/** Options for {@link WidgetBaseSource#getCategories}. */
+/** Options for {@link WidgetRemoteSource#getCategories}. */
 export interface CategoryRequestOptions extends BaseRequestOptions {
   column: string;
   operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
   operationColumn?: string;
+  /** Local only. */
+  joinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
 }
 
 /**
- * Options for {@link WidgetBaseSource#getFeatures}.
+ * Options for {@link WidgetRemoteSource#getFeatures}.
  * @experimental
  * @internal
  */
@@ -67,26 +79,29 @@ export interface FeaturesRequestOptions extends BaseRequestOptions {
   tileResolution?: TileResolution;
 }
 
-/** Options for {@link WidgetBaseSource#getFormula}. */
+/** Options for {@link WidgetRemoteSource#getFormula}. */
 export interface FormulaRequestOptions extends BaseRequestOptions {
   column: string;
-  operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
+  operation?: 'count' | 'avg' | 'min' | 'max' | 'sum' | 'custom';
   operationExp?: string;
+  joinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
 }
 
-/** Options for {@link WidgetBaseSource#getHistogram}. */
+/** Options for {@link WidgetRemoteSource#getHistogram}. */
 export interface HistogramRequestOptions extends BaseRequestOptions {
   column: string;
   ticks: number[];
   operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
+  /** Local only. */
+  joinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
 }
 
-/** Options for {@link WidgetBaseSource#getRange}. */
+/** Options for {@link WidgetRemoteSource#getRange}. */
 export interface RangeRequestOptions extends BaseRequestOptions {
   column: string;
 }
 
-/** Options for {@link WidgetBaseSource#getScatter}. */
+/** Options for {@link WidgetRemoteSource#getScatter}. */
 export interface ScatterRequestOptions extends BaseRequestOptions {
   xAxisColumn: string;
   xAxisJoinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
@@ -94,7 +109,7 @@ export interface ScatterRequestOptions extends BaseRequestOptions {
   yAxisJoinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
 }
 
-/** Options for {@link WidgetBaseSource#getTable}. */
+/** Options for {@link WidgetRemoteSource#getTable}. */
 export interface TableRequestOptions extends BaseRequestOptions {
   columns: string[];
   sortBy?: string;
@@ -102,12 +117,16 @@ export interface TableRequestOptions extends BaseRequestOptions {
   sortByColumnType?: SortColumnType;
   offset?: number;
   limit?: number;
+  /** Local only. */
+  searchFilterColumn?: string;
+  /** Local only. */
+  searchFilterText?: string;
 }
 
-/** Options for {@link WidgetBaseSource#getTimeSeries}. */
+/** Options for {@link WidgetRemoteSource#getTimeSeries}. */
 export interface TimeSeriesRequestOptions extends BaseRequestOptions {
   column: string;
-  stepSize?: GroupDateType;
+  stepSize: GroupDateType;
   stepMultiplier?: number;
   operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
   operationColumn?: string;
@@ -122,35 +141,35 @@ export interface TimeSeriesRequestOptions extends BaseRequestOptions {
  */
 
 /**
- * Response from {@link WidgetBaseSource#getFeatures}.
+ * Response from {@link WidgetRemoteSource#getFeatures}.
  * @experimental
  * @internal
  */
 export type FeaturesResponse = {rows: Record<string, unknown>[]};
 
-/** Response from {@link WidgetBaseSource#getFormula}. */
-export type FormulaResponse = {value: number};
+/** Response from {@link WidgetRemoteSource#getFormula}. */
+export type FormulaResponse = {value: number | null};
 
-/** Response from {@link WidgetBaseSource#getCategories}. */
+/** Response from {@link WidgetRemoteSource#getCategories}. */
 export type CategoryResponse = {name: string; value: number}[];
 
-/** Response from {@link WidgetBaseSource#getRange}. */
-export type RangeResponse = {min: number; max: number};
+/** Response from {@link WidgetRemoteSource#getRange}. */
+export type RangeResponse = {min: number; max: number} | null;
 
-/** Response from {@link WidgetBaseSource#getTable}. */
+/** Response from {@link WidgetRemoteSource#getTable}. */
 export type TableResponse = {
   totalCount: number;
   rows: Record<string, number | string>[];
 };
 
-/** Response from {@link WidgetBaseSource#getScatter}. */
+/** Response from {@link WidgetRemoteSource#getScatter}. */
 export type ScatterResponse = [number, number][];
 
-/** Response from {@link WidgetBaseSource#getTimeSeries}. */
+/** Response from {@link WidgetRemoteSource#getTimeSeries}. */
 export type TimeSeriesResponse = {
   rows: {name: string; value: number}[];
-  categories: string[];
+  categories?: string[];
 };
 
-/** Response from {@link WidgetBaseSource#getHistogram}. */
+/** Response from {@link WidgetRemoteSource#getHistogram}. */
 export type HistogramResponse = number[];

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

@@ -3,7 +3,10 @@ import {
   QuadbinQuerySourceOptions,
   VectorQuerySourceOptions,
 } from '../sources/index.js';
-import {WidgetBaseSource, WidgetBaseSourceProps} from './widget-base-source.js';
+import {
+  WidgetRemoteSource,
+  WidgetRemoteSourceProps,
+} from './widget-remote-source.js';
 import {ModelSource} from '../models/model.js';
 
 type LayerQuerySourceOptions =
@@ -35,8 +38,8 @@ export type WidgetQuerySourceResult = {widgetSource: WidgetQuerySource};
  * const { widgetSource } = await data;
  * ```
  */
-export class WidgetQuerySource extends WidgetBaseSource<
-  LayerQuerySourceOptions & WidgetBaseSourceProps
+export class WidgetQuerySource extends WidgetRemoteSource<
+  LayerQuerySourceOptions & WidgetRemoteSourceProps
 > {
   protected override getModelSource(owner: string): ModelSource {
     return {