@carto/api-client 0.4.6 → 0.4.7-0

package/src/types.ts

@@ -1,16 +1,54 @@
 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
  */
 
-/** @internalRemarks Source: @deck.gl/carto */
+/** @privateRemarks Source: @deck.gl/carto */
 export type Format = 'json' | 'geojson' | 'tilejson';
 
-/** @internalRemarks Source: @carto/constants, @deck.gl/carto */
+/** @privateRemarks 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.
+ * @privateRemarks 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})[];
+};
+
+/** @privateRemarks Source: @deck.gl/carto */
+export type Raster = {
+  blockSize: number;
+  cells: {
+    numericProps: BinaryFeature['numericProps'];
+    properties: BinaryFeature['properties'];
+  };
+};
+
 /******************************************************************************
  * AGGREGATION
  */
@@ -18,8 +56,8 @@ export type MapType = 'boundary' | 'query' | 'table' | 'tileset' | 'raster';
 /**
  * Enum for the different types of aggregations available for widgets.
  *
- * @internalRemarks Source: @carto/constants
- * @internalRemarks Converted from enum to type union, for improved declarative API.
+ * @privateRemarks Source: @carto/constants
+ * @privateRemarks Converted from enum to type union, for improved declarative API.
  */
 export type AggregationType =
   | 'count'
@@ -33,15 +71,15 @@ export type AggregationType =
  * FILTERS
  */
 
-/** @internalRemarks Source: @carto/react-api */
+/** @privateRemarks Source: @carto/react-api */
 export type SpatialFilter = Polygon | MultiPolygon;
 
-/** @internalRemarks Source: @deck.gl/carto */
+/** @privateRemarks Source: @deck.gl/carto */
 export interface Filters {
   [column: string]: Filter;
 }
 
-/** @internalRemarks Source: @carto/react-api, @deck.gl/carto */
+/** @privateRemarks Source: @carto/react-api, @deck.gl/carto */
 export interface Filter {
   [FilterType.IN]?: {owner?: string; values: number[] | string[]};
   /** [a, b] both are included. */
@@ -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 */
+/** @privateRemarks 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
  */
@@ -62,7 +120,7 @@ export type FilterLogicalOperator = 'and' | 'or';
 /**
  * Defines a step size increment for use with {@link TimeSeriesRequestOptions}.
  *
- * @internalRemarks Source: @carto/react-core
+ * @privateRemarks Source: @carto/react-core
  */
 export type GroupDateType =
   | 'year'
@@ -84,7 +142,7 @@ export type SortColumnType = 'number' | 'string' | 'date';
  * SQL QUERY PARAMETERS
  */
 
-/** @internalRemarks Source: @deck.gl/carto */
+/** @privateRemarks Source: @deck.gl/carto */
 export type QueryParameterValue =
   | string
   | number
@@ -92,11 +150,11 @@ export type QueryParameterValue =
   | Array<QueryParameterValue>
   | object;
 
-/** @internalRemarks Source: @deck.gl/carto */
+/** @privateRemarks Source: @deck.gl/carto */
 export type NamedQueryParameter = Record<string, QueryParameterValue>;
 
-/** @internalRemarks Source: @deck.gl/carto */
+/** @privateRemarks Source: @deck.gl/carto */
 export type PositionalQueryParameter = QueryParameterValue[];
 
-/** @internalRemarks Source: @deck.gl/carto */
+/** @privateRemarks Source: @deck.gl/carto */
 export type QueryParameters = NamedQueryParameter | PositionalQueryParameter;

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.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,29 @@ export interface ViewState {
   longitude: number;
 }
 
-/** Common options for {@link WidgetBaseSource} requests. */
+/** Common options for {@link WidgetRemoteSource} requests. */
 interface BaseRequestOptions {
+  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 +81,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 +111,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 +119,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 +143,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,