@carto/api-client 0.4.5 → 0.5.0-alpha.1

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

@@ -2,6 +2,12 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+import {DEFAULT_GEO_COLUMN} from '../constants-internal';
+import {getTileFormat} from '../utils/getTileFormat';
+import {
+  WidgetTilesetSource,
+  WidgetTilesetSourceResult,
+} from '../widget-sources';
 import {baseSource} from './base-source';
 import type {
   SourceOptions,
@@ -12,17 +18,24 @@ import type {
 export type VectorTilesetSourceOptions = SourceOptions & TilesetSourceOptions;
 type UrlParameters = {name: string};
 
-export type VectorTilesetSourceResponse = TilejsonResult;
+export type VectorTilesetSourceResponse = TilejsonResult &
+  WidgetTilesetSourceResult;
 
 export const vectorTilesetSource = async function (
   options: VectorTilesetSourceOptions
 ): Promise<VectorTilesetSourceResponse> {
-  const {tableName} = options;
+  const {tableName, spatialDataColumn = DEFAULT_GEO_COLUMN} = options;
   const urlParameters: UrlParameters = {name: tableName};
 
-  return baseSource<UrlParameters>(
-    'tileset',
-    options,
-    urlParameters
+  return baseSource<UrlParameters>('tileset', options, urlParameters).then(
+    (result) => ({
+      ...(result as TilejsonResult),
+      widgetSource: new WidgetTilesetSource({
+        ...options,
+        tileFormat: getTileFormat(result as TilejsonResult),
+        spatialDataColumn,
+        spatialDataType: 'geo',
+      }),
+    })
   ) as Promise<VectorTilesetSourceResponse>;
 };

package/src/types-internal.ts

@@ -60,3 +60,9 @@ type MapInstantiationFormats = Record<
     error?: any;
   }
 >;
+
+/******************************************************************************
+ * LOCAL CALCULATIONS
+ */
+
+export type FeatureData = Record<string, unknown>;

package/src/types.ts

@@ -1,5 +1,6 @@
 import type {FilterType} from './constants.js';
-import type {Polygon, MultiPolygon} from 'geojson';
+import type {Polygon, MultiPolygon, Feature} from 'geojson';
+import type {BinaryFeature, BinaryFeatureCollection} from '@loaders.gl/schema';
 
 /******************************************************************************
  * MAPS AND TILES
@@ -11,6 +12,43 @@ export type Format = 'json' | 'geojson' | 'tilejson';
 /** @internalRemarks Source: @carto/constants, @deck.gl/carto */
 export type MapType = 'boundary' | 'query' | 'table' | 'tileset' | 'raster';
 
+/**
+ * Alias for GeoJSON 'BBox' type, semantically representing a viewport.
+ * Order of values is "west", "south", "east", "north".
+ */
+export type Viewport = [number, number, number, number];
+
+/**
+ * Subset of deck.gl's Tile2DHeader type, containing only the properties
+ * required for local widget calculations. Deeper dependencies on deck.gl
+ * APIs should be minimized within this library: @deck.gl/carto depends
+ * on the API client, not the other way around.
+ * @internalRemarks Source: @deck.gl/geo-layers
+ */
+export type Tile = {
+  index: {x: number; y: number; z: number};
+  id: string;
+  content: unknown;
+  zoom: number;
+  bbox: {west: number; east: number; north: number; south: number};
+  isVisible: boolean;
+  data?: BinaryFeatureCollection;
+};
+
+/** Subset of deck.gl's Tile2DHeader type, for spatial indexes. */
+export type SpatialIndexTile = Tile & {
+  data?: (Feature & {id: bigint})[];
+};
+
+/** @internalRemarks Source: @deck.gl/carto */
+export type Raster = {
+  blockSize: number;
+  cells: {
+    numericProps: BinaryFeature['numericProps'];
+    properties: BinaryFeature['properties'];
+  };
+};
+
 /******************************************************************************
  * AGGREGATION
  */
@@ -49,12 +87,32 @@ export interface Filter {
   /** [a, b) a is included, b is not. */
   [FilterType.CLOSED_OPEN]?: {owner?: string; values: number[][]};
   [FilterType.TIME]?: {owner?: string; values: number[][]};
-  [FilterType.STRING_SEARCH]?: {owner?: string; values: string[]};
+  [FilterType.STRING_SEARCH]?: {
+    owner?: string;
+    values: string[];
+    params?: StringSearchOptions;
+  };
 }
 
 /** @internalRemarks Source: @carto/react-core */
 export type FilterLogicalOperator = 'and' | 'or';
 
+/**
+ * Type for minimum or maximum value of an interval. Values 'null' and
+ * 'undefined' are intentionally allowed, and represent an unbounded value.
+ */
+export type FilterIntervalExtremum = number | null | undefined;
+export type FilterInterval = [FilterIntervalExtremum, FilterIntervalExtremum];
+export type FilterIntervalComplete = [number, number];
+
+export type StringSearchOptions = {
+  useRegExp?: boolean;
+  mustStart?: boolean;
+  mustEnd?: boolean;
+  caseSensitive?: boolean;
+  keepSpecialCharacters?: boolean;
+};
+
 /******************************************************************************
  * GROUPING
  */

package/src/utils/dateUtils.ts

@@ -0,0 +1,28 @@
+/**
+ * Returns midnight (local time) on the Monday preceeding a given date, in
+ * milliseconds since the UNIX epoch.
+ */
+export function getMonday(date: number | Date): number {
+  const dateCp = new Date(date);
+  const day = dateCp.getDay();
+  const diff = dateCp.getDate() - day + (day ? 1 : -6); // adjust when day is sunday
+  dateCp.setDate(diff);
+  dateCp.setHours(0, 0, 0, 0);
+  return dateCp.getTime();
+}
+
+/**
+ * Returns midnight (UTC) on the Monday preceeding a given date, in
+ * milliseconds since the UNIX epoch.
+ */
+export function getUTCMonday(date: number | Date): number {
+  const dateCp = new Date(date);
+  const day = dateCp.getUTCDay();
+  const diff = dateCp.getUTCDate() - day + (day ? 1 : -6); // adjust when day is sunday
+  dateCp.setUTCDate(diff);
+  return Date.UTC(
+    dateCp.getUTCFullYear(),
+    dateCp.getUTCMonth(),
+    dateCp.getUTCDate()
+  );
+}

package/src/utils/getTileFormat.ts

@@ -0,0 +1,9 @@
+import {TileFormat} from '../constants.js';
+import {Tilejson} from '../sources/types.js';
+
+export function getTileFormat(tilejson: Tilejson): TileFormat {
+  const tileParams = new URL(tilejson.tiles[0]).searchParams;
+  return tileParams.get('formatTiles') === 'mvt'
+    ? TileFormat.MVT
+    : TileFormat.BINARY;
+}

package/src/utils/makeIntervalComplete.ts

@@ -0,0 +1,17 @@
+import {FilterInterval, FilterIntervalComplete} from '../types';
+
+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/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

@@ -5,6 +5,7 @@ import {
   SortDirection,
   SpatialFilter,
 } from '../types';
+import type {WidgetRemoteSource} from './widget-remote-source';
 
 /******************************************************************************
  * WIDGET API REQUESTS
@@ -16,7 +17,7 @@ export interface ViewState {
   longitude: number;
 }
 
-/** Common options for {@link WidgetBaseSource} requests. */
+/** Common options for {@link WidgetRemoteSource} requests. */
 interface BaseRequestOptions {
   spatialFilter?: SpatialFilter;
   spatialFiltersMode?: SpatialFilterPolyfillMode;
@@ -26,15 +27,17 @@ interface BaseRequestOptions {
   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 +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';
@@ -103,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;
@@ -111,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;
@@ -131,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 {