@carto/api-client 0.4.6-0 → 0.4.6

package/src/utils/transformToTileCoords.ts

@@ -1,85 +0,0 @@
-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/widget-source.ts

@@ -1,160 +0,0 @@
-import {
-  CategoryRequestOptions,
-  CategoryResponse,
-  FeaturesRequestOptions,
-  FeaturesResponse,
-  FormulaRequestOptions,
-  FormulaResponse,
-  HistogramRequestOptions,
-  HistogramResponse,
-  RangeRequestOptions,
-  RangeResponse,
-  ScatterRequestOptions,
-  ScatterResponse,
-  TableRequestOptions,
-  TableResponse,
-  TimeSeriesRequestOptions,
-  TimeSeriesResponse,
-  ViewState,
-} from './types.js';
-import {FilterLogicalOperator, Filter, SpatialFilter} from '../types.js';
-import {getApplicableFilters} from '../utils.js';
-import {getClient} from '../client.js';
-import {ModelSource} from '../models/model.js';
-import {SourceOptions} from '../sources/index.js';
-import {ApiVersion, DEFAULT_API_BASE_URL} from '../constants.js';
-import {getSpatialFiltersResolution} from '../spatial-index.js';
-import {AggregationOptions} from '../sources/types.js';
-
-export interface WidgetSourceProps extends Omit<SourceOptions, 'filters'> {
-  apiVersion?: ApiVersion;
-  filters?: Record<string, Filter>;
-  filtersLogicalOperator?: FilterLogicalOperator;
-}
-
-/**
- * Source for Widget API requests on a data source defined by a SQL query.
- *
- * Abstract class. Use {@link WidgetQuerySource} or {@link WidgetTableSource}.
- */
-export abstract class WidgetSource<Props extends WidgetSourceProps> {
-  readonly props: Props;
-
-  static defaultProps: Partial<WidgetSourceProps> = {
-    apiVersion: ApiVersion.V3,
-    apiBaseUrl: DEFAULT_API_BASE_URL,
-    clientId: getClient(),
-    filters: {},
-    filtersLogicalOperator: 'and',
-  };
-
-  constructor(props: Props) {
-    this.props = {...WidgetSource.defaultProps, ...props};
-  }
-
-  /**
-   * Subclasses of {@link WidgetRemoteSource} must implement this method, calling
-   * {@link WidgetRemoteSource.prototype._getModelSource} for common source
-   * properties, and adding additional required properties including 'type' and
-   * 'data'.
-   */
-  protected abstract getModelSource(owner: string | undefined): ModelSource;
-
-  protected _getModelSource(
-    owner?: string
-  ): Omit<ModelSource, 'type' | 'data'> {
-    const props = this.props;
-    return {
-      apiVersion: props.apiVersion as ApiVersion,
-      apiBaseUrl: props.apiBaseUrl as string,
-      clientId: props.clientId as string,
-      accessToken: props.accessToken,
-      connectionName: props.connectionName,
-      filters: getApplicableFilters(owner, props.filters),
-      filtersLogicalOperator: props.filtersLogicalOperator,
-      spatialDataType: props.spatialDataType,
-      spatialDataColumn: props.spatialDataColumn,
-      dataResolution: (props as Partial<AggregationOptions>).dataResolution,
-    };
-  }
-
-  protected _getSpatialFiltersResolution(
-    source: Omit<ModelSource, 'type' | 'data'>,
-    spatialFilter?: SpatialFilter,
-    referenceViewState?: ViewState
-  ): number | undefined {
-    // spatialFiltersResolution applies only to spatial index sources.
-    if (!spatialFilter || source.spatialDataType === 'geo') {
-      return;
-    }
-
-    if (!referenceViewState) {
-      throw new Error(
-        'Missing required option, "spatialIndexReferenceViewState".'
-      );
-    }
-
-    return getSpatialFiltersResolution(source, referenceViewState);
-  }
-
-  /**
-   * Returns a list of labeled datapoints for categorical data. Suitable for
-   * charts including grouped bar charts, pie charts, and tree charts.
-   */
-  abstract getCategories(
-    options: CategoryRequestOptions
-  ): Promise<CategoryResponse>;
-
-  /**
-   * Given a list of feature IDs (as found in `_carto_feature_id`) returns all
-   * matching features. In datasets containing features with duplicate geometries,
-   * feature IDs may be duplicated (IDs are a hash of geometry) and so more
-   * results may be returned than IDs in the request.
-   * @internal
-   * @experimental
-   */
-  abstract getFeatures(
-    options: FeaturesRequestOptions
-  ): Promise<FeaturesResponse>;
-
-  /**
-   * Returns a scalar numerical statistic over all matching data. Suitable
-   * for 'headline' or 'scorecard' figures such as counts and sums.
-   */
-  abstract getFormula(options: FormulaRequestOptions): Promise<FormulaResponse>;
-
-  /**
-   * Returns a list of labeled datapoints for 'bins' of data defined as ticks
-   * over a numerical range. Suitable for histogram charts.
-   */
-  abstract getHistogram(
-    options: HistogramRequestOptions
-  ): Promise<HistogramResponse>;
-
-  /**
-   * Returns a range (min and max) for a numerical column of matching rows.
-   * Suitable for displaying certain 'headline' or 'scorecard' statistics,
-   * or rendering a range slider UI for filtering.
-   */
-  abstract getRange(options: RangeRequestOptions): Promise<RangeResponse>;
-
-  /**
-   * Returns a list of bivariate datapoints defined as numerical 'x' and 'y'
-   * values. Suitable for rendering scatter plots.
-   */
-  abstract getScatter(options: ScatterRequestOptions): Promise<ScatterResponse>;
-
-  /**
-   * Returns a list of arbitrary data rows, with support for pagination and
-   * sorting. Suitable for displaying tables and lists.
-   */
-  abstract getTable(options: TableRequestOptions): Promise<TableResponse>;
-
-  /**
-   * Returns a series of labeled numerical values, grouped into equally-sized
-   * time intervals. Suitable for rendering time series charts.
-   */
-  abstract getTimeSeries(
-    options: TimeSeriesRequestOptions
-  ): Promise<TimeSeriesResponse>;
-}

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

@@ -1,407 +0,0 @@
-import {TilesetSourceOptions} from '../sources/index.js';
-import type {ModelSource} from '../models/index.js';
-import {
-  CategoryRequestOptions,
-  CategoryResponse,
-  FeaturesRequestOptions,
-  FeaturesResponse,
-  FormulaRequestOptions,
-  FormulaResponse,
-  HistogramRequestOptions,
-  HistogramResponse,
-  RangeRequestOptions,
-  RangeResponse,
-  ScatterRequestOptions,
-  ScatterResponse,
-  TableRequestOptions,
-  TableResponse,
-  TimeSeriesRequestOptions,
-  TimeSeriesResponse,
-} from './types.js';
-import {InvalidColumnError, getApplicableFilters} from '../utils.js';
-import {TileFormat} from '../constants.js';
-import {SpatialFilter, Tile} from '../types.js';
-import {
-  TileFeatureExtractOptions,
-  applyFilters,
-  geojsonFeatures,
-  tileFeatures,
-} from '../filters/index.js';
-import {
-  aggregationFunctions,
-  applySorting,
-  groupValuesByColumn,
-  groupValuesByDateColumn,
-  histogram,
-  scatterPlot,
-} from '../operations/index.js';
-import {FeatureData} from '../types-internal.js';
-import {FeatureCollection} from 'geojson';
-import {SpatialDataType} from '../sources/types.js';
-import {WidgetSource, WidgetSourceProps} from './widget-source.js';
-
-// TODO(cleanup): Parameter defaults in source functions and widget API calls are
-// currently duplicated and possibly inconsistent. Consider consolidating and
-// operating on Required<T> objects. See:
-// https://github.com/CartoDB/carto-api-client/issues/39
-
-export type WidgetTilesetSourceProps = WidgetSourceProps &
-  Omit<TilesetSourceOptions, 'filters'> & {
-    tileFormat: TileFormat;
-    spatialDataType: SpatialDataType;
-  };
-
-export type WidgetTilesetSourceResult = {widgetSource: WidgetTilesetSource};
-
-/**
- * Source for Widget API requests on a data source defined by a tileset.
- *
- * Generally not intended to be constructed directly. Instead, call
- * {@link vectorTilesetSource}, {@link h3TilesetSource}, or {@link quadbinTilesetSource},
- * which can be shared with map layers. Sources contain a `widgetSource`
- * property, for use by widget implementations.
- *
- * Example:
- *
- * ```javascript
- * import { vectorTilesetSource } from '@carto/api-client';
- *
- * const data = vectorTilesetSource({
- *   accessToken: '••••',
- *   connectionName: 'carto_dw',
- *   tableName: 'carto-demo-data.demo_rasters.my_tileset_source'
- * });
- *
- * const { widgetSource } = await data;
- * ```
- */
-export class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps> {
-  private _tiles: Tile[] = [];
-  private _features: FeatureData[] = [];
-
-  protected override getModelSource(owner: string): ModelSource {
-    return {
-      ...super._getModelSource(owner),
-      type: 'tileset',
-      data: this.props.tableName,
-    };
-  }
-
-  /**
-   * Loads features as a list of tiles (typically provided by deck.gl).
-   * After tiles are loaded, {@link extractTileFeatures} must be called
-   * before computing statistics on the tiles.
-   */
-  loadTiles(tiles: unknown[]) {
-    this._tiles = tiles as Tile[];
-  }
-
-  /**
-   * Extracts feature data from tiles previously loaded with {@link loadTiles}.
-   * Must be called before computing statistics on tiles.
-   */
-  extractTileFeatures({
-    spatialFilter,
-    uniqueIdProperty,
-    options,
-  }: {
-    spatialFilter: SpatialFilter;
-    // TODO(cleanup): As an optional property, 'uniqueIdProperty' will be easy to forget.
-    // Would it be better to configure it on the source function, rather than separately
-    // on the layer and in 'loadTiles()'?
-    uniqueIdProperty?: string;
-    options?: TileFeatureExtractOptions;
-  }) {
-    this._features = tileFeatures({
-      tiles: this._tiles,
-      options,
-      spatialFilter,
-      uniqueIdProperty,
-      tileFormat: this.props.tileFormat,
-      spatialDataColumn: this.props.spatialDataColumn,
-      spatialDataType: this.props.spatialDataType,
-    });
-  }
-
-  /** Loads features as GeoJSON (used for testing). */
-  loadGeoJSON({
-    geojson,
-    spatialFilter,
-    uniqueIdProperty,
-  }: {
-    geojson: FeatureCollection;
-    spatialFilter: SpatialFilter;
-    uniqueIdProperty?: string;
-  }) {
-    this._features = geojsonFeatures({
-      geojson,
-      spatialFilter,
-      uniqueIdProperty,
-    });
-  }
-
-  override async getFeatures(
-    options: FeaturesRequestOptions
-  ): Promise<FeaturesResponse> {
-    throw new Error('getFeatures not supported for tilesets');
-  }
-
-  async getFormula({
-    column = '*',
-    operation = 'count',
-    joinOperation,
-    filterOwner,
-  }: FormulaRequestOptions): Promise<FormulaResponse> {
-    if (operation === 'custom') {
-      throw new Error('Custom aggregation not supported for tilesets');
-    }
-
-    if (!this._features.length) {
-      return {value: null};
-    }
-
-    // Column is required except when operation is 'count'.
-    if ((column && column !== '*') || operation !== 'count') {
-      assertColumn(this._features, column);
-    }
-
-    const filteredFeatures = this._getFilteredFeatures(filterOwner);
-
-    if (filteredFeatures.length === 0 && operation !== 'count') {
-      return {value: null};
-    }
-
-    const targetOperation = aggregationFunctions[operation];
-    return {
-      value: targetOperation(
-        filteredFeatures as FeatureData[],
-        column,
-        joinOperation
-      ),
-    };
-  }
-
-  override async getHistogram({
-    operation = 'count',
-    ticks,
-    column,
-    joinOperation,
-    filterOwner,
-  }: HistogramRequestOptions): Promise<HistogramResponse> {
-    if (!this._features.length) {
-      return [];
-    }
-
-    const filteredFeatures = this._getFilteredFeatures(filterOwner);
-
-    assertColumn(this._features, column);
-
-    return histogram({
-      data: filteredFeatures,
-      valuesColumns: normalizeColumns(column),
-      joinOperation,
-      ticks,
-      operation,
-    });
-  }
-
-  override async getCategories({
-    column,
-    operation = 'count',
-    operationColumn,
-    joinOperation,
-    filterOwner,
-  }: CategoryRequestOptions): Promise<CategoryResponse> {
-    if (!this._features.length) {
-      return [];
-    }
-
-    const filteredFeatures = this._getFilteredFeatures(filterOwner);
-
-    assertColumn(this._features, column as string, operationColumn as string);
-
-    const groups = groupValuesByColumn({
-      data: filteredFeatures,
-      valuesColumns: normalizeColumns(operationColumn || column),
-      joinOperation,
-      keysColumn: column,
-      operation,
-    });
-
-    return groups || [];
-  }
-
-  override async getScatter({
-    xAxisColumn,
-    yAxisColumn,
-    xAxisJoinOperation,
-    yAxisJoinOperation,
-    filterOwner,
-  }: ScatterRequestOptions): Promise<ScatterResponse> {
-    if (!this._features.length) {
-      return [];
-    }
-
-    const filteredFeatures = this._getFilteredFeatures(filterOwner);
-
-    assertColumn(this._features, xAxisColumn, yAxisColumn);
-
-    return scatterPlot({
-      data: filteredFeatures,
-      xAxisColumns: normalizeColumns(xAxisColumn),
-      xAxisJoinOperation,
-      yAxisColumns: normalizeColumns(yAxisColumn),
-      yAxisJoinOperation,
-    });
-  }
-
-  override async getTable(
-    options: TableRequestOptions
-  ): Promise<TableResponse> {
-    const {filterOwner, spatialFilter, abortController, ...params} = options;
-    const {
-      columns,
-      searchFilterColumn,
-      searchFilterText,
-      sortBy,
-      sortDirection,
-      sortByColumnType,
-      offset = 0,
-      limit = 10,
-    } = params;
-
-    if (!this._features.length) {
-      return {rows: [], totalCount: 0};
-    }
-
-    // Filter.
-    let filteredFeatures = this._getFilteredFeatures(filterOwner);
-
-    // Search.
-    // TODO: Could we get the same behavior by applying filters in loadTiles()?
-    if (searchFilterColumn && searchFilterText) {
-      filteredFeatures = filteredFeatures.filter(
-        (row) =>
-          row[searchFilterColumn] &&
-          String(row[searchFilterColumn])
-            .toLowerCase()
-            .includes(String(searchFilterText).toLowerCase())
-      );
-    }
-
-    // Sort.
-    let rows = applySorting(filteredFeatures, {
-      sortBy,
-      sortByDirection: sortDirection,
-      sortByColumnType,
-    });
-    const totalCount = rows.length;
-
-    // Offset and limit.
-    rows = rows.slice(
-      Math.min(offset, totalCount),
-      Math.min(offset + limit, totalCount)
-    );
-
-    // Select columns.
-    rows = rows.map((srcRow: FeatureData) => {
-      const dstRow: FeatureData = {};
-      for (const column of columns) {
-        dstRow[column] = srcRow[column];
-      }
-      return dstRow;
-    });
-
-    return {rows, totalCount} as TableResponse;
-  }
-
-  override async getTimeSeries({
-    column,
-    stepSize,
-    operation,
-    operationColumn,
-    joinOperation,
-    filterOwner,
-  }: TimeSeriesRequestOptions): Promise<TimeSeriesResponse> {
-    if (!this._features.length) {
-      return {rows: []};
-    }
-
-    const filteredFeatures = this._getFilteredFeatures(filterOwner);
-
-    assertColumn(this._features, column as string, operationColumn as string);
-
-    const rows =
-      groupValuesByDateColumn({
-        data: filteredFeatures,
-        valuesColumns: normalizeColumns(operationColumn || column),
-        keysColumn: column,
-        groupType: stepSize,
-        operation,
-        joinOperation,
-      }) || [];
-
-    return {rows};
-  }
-
-  override async getRange({
-    column,
-    filterOwner,
-  }: RangeRequestOptions): Promise<RangeResponse> {
-    if (!this._features.length) {
-      // TODO: Is this the only nullable response in the Widgets API? If so,
-      // can we do something more consistent?
-      return null;
-    }
-
-    assertColumn(this._features, column);
-
-    const filteredFeatures = this._getFilteredFeatures(filterOwner);
-    return {
-      min: aggregationFunctions.min(filteredFeatures, column),
-      max: aggregationFunctions.max(filteredFeatures, column),
-    };
-  }
-
-  /****************************************************************************
-   * INTERNAL
-   */
-
-  private _getFilteredFeatures(filterOwner: string | undefined): FeatureData[] {
-    return applyFilters(
-      this._features,
-      getApplicableFilters(filterOwner, this.props.filters),
-      this.props.filtersLogicalOperator || 'and'
-    );
-  }
-}
-
-function assertColumn(
-  features: FeatureData[],
-  ...columnArgs: string[] | string[][]
-) {
-  // TODO(cleanup): Can drop support for multiple column shapes here?
-
-  // Due to the multiple column shape, we normalise it as an array with normalizeColumns
-  const columns = Array.from(new Set(columnArgs.map(normalizeColumns).flat()));
-
-  const featureKeys = Object.keys(features[0]);
-
-  const invalidColumns = columns.filter(
-    (column) => !featureKeys.includes(column)
-  );
-
-  if (invalidColumns.length) {
-    throw new InvalidColumnError(
-      `Missing column(s): ${invalidColumns.join(', ')}`
-    );
-  }
-}
-
-function normalizeColumns(columns: string | string[]): string[] {
-  return Array.isArray(columns)
-    ? columns
-    : typeof columns === 'string'
-      ? [columns]
-      : [];
-}