@carto/api-client 0.4.6 → 0.4.7-alpha.0

package/src/utils/makeIntervalComplete.ts

@@ -0,0 +1,17 @@
+import {FilterInterval, FilterIntervalComplete} from '../types.js';
+
+export function makeIntervalComplete(
+  intervals: FilterInterval[]
+): FilterIntervalComplete[] {
+  return intervals.map((val) => {
+    if (val[0] === undefined || val[0] === null) {
+      return [Number.MIN_SAFE_INTEGER, val[1]];
+    }
+
+    if (val[1] === undefined || val[1] === null) {
+      return [val[0], Number.MAX_SAFE_INTEGER];
+    }
+
+    return val;
+  }) as FilterIntervalComplete[];
+}

package/src/utils/transformTileCoordsToWGS84.ts

@@ -0,0 +1,77 @@
+import {lerp} from '@math.gl/core';
+import {lngLatToWorld, worldToLngLat} 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 tile coords to WGS84 coordinates.
+ *
+ * @param geometry - any valid geojson geometry
+ * @param bbox - geojson bbox
+ */
+export function transformTileCoordsToWGS84<T extends Geometry>(
+  geometry: T,
+  bbox: BBox
+): T {
+  const [west, south, east, north] = bbox;
+  const nw = lngLatToWorld([west, north]);
+  const se = lngLatToWorld([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 = lerp(nw[0], se[0], pointX);
+  const y = lerp(nw[1], se[1], pointY);
+
+  return worldToLngLat([x, y]);
+}
+
+function getPoints(geometry: Position[], bbox: Position[]) {
+  return geometry.map((g) => transformPoint(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));
+}

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

@@ -39,7 +39,7 @@ type Row<T> = Record<string, T> | Record<string, T>[] | T[] | T;
  * Due to each data warehouse having its own behavior with columns,
  * we need to normalize them and transform every key to lowercase.
  *
- * @internalRemarks Source: @carto/react-widgets
+ * @privateRemarks Source: @carto/react-widgets
  * @internal
  */
 export function normalizeObjectKeys<T, R extends Row<T>>(el: R): R {
@@ -59,7 +59,7 @@ export function normalizeObjectKeys<T, R extends Row<T>>(el: R): R {
   ) as R;
 }
 
-/** @internalRemarks Source: @carto/react-core */
+/** @privateRemarks Source: @carto/react-core */
 export function assert(condition: unknown, message: string): asserts condition {
   if (!condition) {
     throw new Error(message);
@@ -67,7 +67,7 @@ export function assert(condition: unknown, message: string): asserts condition {
 }
 
 /**
- * @internalRemarks Source: @carto/react-core
+ * @privateRemarks Source: @carto/react-core
  * @internal
  */
 export class InvalidColumnError extends Error {

package/src/widget-sources/index.ts

@@ -1,4 +1,6 @@
-export * from './widget-base-source.js';
+export * from './widget-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,10 +1,11 @@
-import {SpatialFilterPolyfillMode, TileResolution} from '../sources/types';
+import {SpatialFilterPolyfillMode, TileResolution} from '../sources/types.js';
 import {
+  Filters,
   GroupDateType,
   SortColumnType,
   SortDirection,
   SpatialFilter,
-} from '../types';
+} from '../types.js';
 
 /******************************************************************************
  * WIDGET API REQUESTS
@@ -16,25 +17,31 @@ export interface ViewState {
   longitude: number;
 }
 
-/** Common options for {@link WidgetBaseSource} requests. */
+/** Common options for {@link WidgetRemoteSource} requests. */
 interface BaseRequestOptions {
+  /** @deprecated */
+  abortController?: AbortController;
+  signal?: AbortSignal;
   spatialFilter?: SpatialFilter;
   spatialFiltersMode?: SpatialFilterPolyfillMode;
   /** Required for table- and query-based spatial index sources (H3, Quadbin). */
   spatialIndexReferenceViewState?: ViewState;
-  abortController?: AbortController;
+  /** Overrides source filters, if any. */
+  filters?: Filters;
   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
  */
@@ -76,26 +83,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';
@@ -103,7 +113,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;
@@ -111,12 +121,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;
@@ -131,35 +145,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,8 +3,12 @@ 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';
+import {Filters} from '../types.js';
 
 type LayerQuerySourceOptions =
   | Omit<VectorQuerySourceOptions, 'filters'>
@@ -35,12 +39,15 @@ 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 {
+  protected override getModelSource(
+    filters: Filters | undefined,
+    filterOwner?: string
+  ): ModelSource {
     return {
-      ...super._getModelSource(owner),
+      ...super._getModelSource(filters, filterOwner),
       type: 'query',
       data: this.props.sqlQuery,
       queryParameters: this.props.queryParameters,