@carto/api-client 0.5.0-alpha.3 → 0.5.0-alpha.5

package/build/widget-sources/types.d.ts

@@ -1,158 +0,0 @@
-import { SpatialFilterPolyfillMode, TileResolution } from '../sources/types';
-import { GroupDateType, SortColumnType, SortDirection, SpatialFilter } from '../types';
-/******************************************************************************
- * WIDGET API 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 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 WidgetRemoteSource#getFeatures}.
- * @experimental
- * @internal
- */
-export interface FeaturesRequestOptions extends BaseRequestOptions {
-    /**
-     * Feature IDs, as found in `_carto_feature_id`. Feature IDs are a hash
-     * of geometry, and features with identical geometry will have the same
-     * feature ID. Order is important; features in the result set will be
-     * sorted according to the order of IDs in the request.
-     */
-    featureIds: string[];
-    /**
-     * Columns to be returned for each picked object. Note that for datasets
-     * containing features with identical geometry, more than one result per
-     * requested feature ID may be returned. To match results back to the
-     * requested feature ID, include `_carto_feature_id` in the columns list.
-     */
-    columns: string[];
-    /** Topology of objects to be picked. */
-    dataType: 'points' | 'lines' | 'polygons';
-    /** Zoom level, required if using 'points' data type. */
-    z?: number;
-    /**
-     * Maximum number of objects to return in the result set. For datasets
-     * containing features with identical geometry, those features will have
-     * the same feature IDs, and so more results may be returned than feature IDs
-     * given in the request.
-     */
-    limit?: number;
-    /**
-     * Must match `tileResolution` used when obtaining the `_carto_feature_id`
-     * column, typically in a layer's tile requests.
-     */
-    tileResolution?: TileResolution;
-}
-/** Options for {@link WidgetRemoteSource#getFormula}. */
-export interface FormulaRequestOptions extends BaseRequestOptions {
-    column: string;
-    operation?: 'count' | 'avg' | 'min' | 'max' | 'sum' | 'custom';
-    operationExp?: string;
-    joinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
-}
-/** 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 WidgetRemoteSource#getRange}. */
-export interface RangeRequestOptions extends BaseRequestOptions {
-    column: string;
-}
-/** Options for {@link WidgetRemoteSource#getScatter}. */
-export interface ScatterRequestOptions extends BaseRequestOptions {
-    xAxisColumn: string;
-    xAxisJoinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
-    yAxisColumn: string;
-    yAxisJoinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
-}
-/** Options for {@link WidgetRemoteSource#getTable}. */
-export interface TableRequestOptions extends BaseRequestOptions {
-    columns: string[];
-    sortBy?: string;
-    sortDirection?: SortDirection;
-    sortByColumnType?: SortColumnType;
-    offset?: number;
-    limit?: number;
-    /** Local only. */
-    searchFilterColumn?: string;
-    /** Local only. */
-    searchFilterText?: string;
-}
-/** Options for {@link WidgetRemoteSource#getTimeSeries}. */
-export interface TimeSeriesRequestOptions extends BaseRequestOptions {
-    column: string;
-    stepSize: GroupDateType;
-    stepMultiplier?: number;
-    operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
-    operationColumn?: string;
-    joinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
-    splitByCategory?: string;
-    splitByCategoryLimit?: number;
-    splitByCategoryValues?: string[];
-}
-/******************************************************************************
- * WIDGET API RESPONSES
- */
-/**
- * Response from {@link WidgetRemoteSource#getFeatures}.
- * @experimental
- * @internal
- */
-export type FeaturesResponse = {
-    rows: Record<string, unknown>[];
-};
-/** Response from {@link WidgetRemoteSource#getFormula}. */
-export type FormulaResponse = {
-    value: number | null;
-};
-/** Response from {@link WidgetRemoteSource#getCategories}. */
-export type CategoryResponse = {
-    name: string;
-    value: number;
-}[];
-/** Response from {@link WidgetRemoteSource#getRange}. */
-export type RangeResponse = {
-    min: number;
-    max: number;
-} | null;
-/** Response from {@link WidgetRemoteSource#getTable}. */
-export type TableResponse = {
-    totalCount: number;
-    rows: Record<string, number | string>[];
-};
-/** Response from {@link WidgetRemoteSource#getScatter}. */
-export type ScatterResponse = [number, number][];
-/** Response from {@link WidgetRemoteSource#getTimeSeries}. */
-export type TimeSeriesResponse = {
-    rows: {
-        name: string;
-        value: number;
-    }[];
-    categories?: string[];
-};
-/** Response from {@link WidgetRemoteSource#getHistogram}. */
-export type HistogramResponse = number[];
-export {};

package/build/widget-sources/widget-query-source.d.ts

@@ -1,33 +0,0 @@
-import { H3QuerySourceOptions, QuadbinQuerySourceOptions, VectorQuerySourceOptions } from '../sources/index.js';
-import { WidgetRemoteSource, WidgetRemoteSourceProps } from './widget-remote-source.js';
-import { ModelSource } from '../models/model.js';
-type LayerQuerySourceOptions = Omit<VectorQuerySourceOptions, 'filters'> | Omit<H3QuerySourceOptions, 'filters'> | Omit<QuadbinQuerySourceOptions, 'filters'>;
-export type WidgetQuerySourceResult = {
-    widgetSource: WidgetQuerySource;
-};
-/**
- * Source for Widget API requests on a data source defined by a SQL query.
- *
- * Generally not intended to be constructed directly. Instead, call
- * {@link vectorQuerySource}, {@link h3QuerySource}, or {@link quadbinQuerySource},
- * which can be shared with map layers. Sources contain a `widgetSource` property,
- * for use by widget implementations.
- *
- * Example:
- *
- * ```javascript
- * import { vectorQuerySource } from '@carto/api-client';
- *
- * const data = vectorQuerySource({
- *   accessToken: '••••',
- *   connectionName: 'carto_dw',
- *   sqlQuery: 'SELECT * FROM carto-demo-data.demo_tables.retail_stores'
- * });
- *
- * const { widgetSource } = await data;
- * ```
- */
-export declare class WidgetQuerySource extends WidgetRemoteSource<LayerQuerySourceOptions & WidgetRemoteSourceProps> {
-    protected getModelSource(owner: string): ModelSource;
-}
-export {};

package/build/widget-sources/widget-raster-source.d.ts

@@ -1,11 +0,0 @@
-import { RasterMetadata } from '../sources/index.js';
-import { WidgetTilesetSource, WidgetTilesetSourceProps } from './widget-tileset-source.js';
-export type WidgetRasterSourceProps = WidgetTilesetSourceProps & {
-    rasterMetadata: RasterMetadata;
-    spatialDataType: 'quadbin';
-};
-export type WidgetRasterSourceResult = {
-    widgetSource: WidgetRasterSource;
-};
-export declare class WidgetRasterSource extends WidgetTilesetSource<WidgetRasterSourceProps> {
-}

package/build/widget-sources/widget-remote-source.d.ts

@@ -1,18 +0,0 @@
-import { CategoryRequestOptions, CategoryResponse, FeaturesRequestOptions, FeaturesResponse, FormulaRequestOptions, FormulaResponse, HistogramRequestOptions, HistogramResponse, RangeRequestOptions, RangeResponse, ScatterRequestOptions, ScatterResponse, TableRequestOptions, TableResponse, TimeSeriesRequestOptions, TimeSeriesResponse } from './types.js';
-import { WidgetSource, WidgetSourceProps } from './widget-source.js';
-export type WidgetRemoteSourceProps = WidgetSourceProps;
-/**
- * Source for Widget API requests.
- *
- * Abstract class. Use {@link WidgetQuerySource} or {@link WidgetTableSource}.
- */
-export declare abstract class WidgetRemoteSource<Props extends WidgetRemoteSourceProps> extends WidgetSource<Props> {
-    getCategories(options: CategoryRequestOptions): Promise<CategoryResponse>;
-    getFeatures(options: FeaturesRequestOptions): Promise<FeaturesResponse>;
-    getFormula(options: FormulaRequestOptions): Promise<FormulaResponse>;
-    getHistogram(options: HistogramRequestOptions): Promise<HistogramResponse>;
-    getRange(options: RangeRequestOptions): Promise<RangeResponse>;
-    getScatter(options: ScatterRequestOptions): Promise<ScatterResponse>;
-    getTable(options: TableRequestOptions): Promise<TableResponse>;
-    getTimeSeries(options: TimeSeriesRequestOptions): Promise<TimeSeriesResponse>;
-}

package/build/widget-sources/widget-source.d.ts

@@ -1,74 +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 { ModelSource } from '../models/model.js';
-import { SourceOptions } from '../sources/index.js';
-import { ApiVersion } from '../constants.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 declare abstract class WidgetSource<Props extends WidgetSourceProps> {
-    readonly props: Props;
-    static defaultProps: Partial<WidgetSourceProps>;
-    constructor(props: 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'>;
-    protected _getSpatialFiltersResolution(source: Omit<ModelSource, 'type' | 'data'>, spatialFilter?: SpatialFilter, referenceViewState?: ViewState): number | undefined;
-    /**
-     * 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/build/widget-sources/widget-table-source.d.ts

@@ -1,33 +0,0 @@
-import { H3TableSourceOptions, QuadbinTableSourceOptions, VectorTableSourceOptions } from '../sources/index.js';
-import { WidgetRemoteSource, WidgetRemoteSourceProps } from './widget-remote-source.js';
-import { ModelSource } from '../models/model.js';
-type LayerTableSourceOptions = Omit<VectorTableSourceOptions, 'filters'> | Omit<H3TableSourceOptions, 'filters'> | Omit<QuadbinTableSourceOptions, 'filters'>;
-export type WidgetTableSourceResult = {
-    widgetSource: WidgetTableSource;
-};
-/**
- * Source for Widget API requests on a data source defined as a table.
- *
- * Generally not intended to be constructed directly. Instead, call
- * {@link vectorTableSource}, {@link h3TableSource}, or {@link quadbinTableSource},
- * which can be shared with map layers. Sources contain a `widgetSource` property,
- * for use by widget implementations.
- *
- * Example:
- *
- * ```javascript
- * import { vectorTableSource } from '@carto/api-client';
- *
- * const data = vectorTableSource({
- *   accessToken: '••••',
- *   connectionName: 'carto_dw',
- *   tableName: 'carto-demo-data.demo_tables.retail_stores'
- * });
- *
- * const { widgetSource } = await data;
- * ```
- */
-export declare class WidgetTableSource extends WidgetRemoteSource<LayerTableSourceOptions & WidgetRemoteSourceProps> {
-    protected getModelSource(owner: string): ModelSource;
-}
-export {};

package/build/widget-sources/widget-tileset-source.d.ts

@@ -1,77 +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 { TileFormat } from '../constants.js';
-import { SpatialFilter, Tile } from '../types.js';
-import { TileFeatureExtractOptions } from '../filters/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';
-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 declare class WidgetTilesetSource<Props extends WidgetTilesetSourceProps = WidgetTilesetSourceProps> extends WidgetSource<Props> {
-    protected _tiles: Tile[];
-    protected _features: FeatureData[];
-    protected getModelSource(owner: string): ModelSource;
-    /**
-     * 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[]): void;
-    /**
-     * Extracts feature data from tiles previously loaded with {@link loadTiles}.
-     * Must be called before computing statistics on tiles.
-     */
-    extractTileFeatures({ spatialFilter, uniqueIdProperty, options, }: {
-        spatialFilter: SpatialFilter;
-        uniqueIdProperty?: string;
-        options?: TileFeatureExtractOptions;
-    }): void;
-    /** Loads features as GeoJSON (used for testing). */
-    loadGeoJSON({ geojson, spatialFilter, uniqueIdProperty, }: {
-        geojson: FeatureCollection;
-        spatialFilter: SpatialFilter;
-        uniqueIdProperty?: string;
-    }): void;
-    getFeatures(options: FeaturesRequestOptions): Promise<FeaturesResponse>;
-    getFormula({ column, operation, joinOperation, filterOwner, }: FormulaRequestOptions): Promise<FormulaResponse>;
-    getHistogram({ operation, ticks, column, joinOperation, filterOwner, }: HistogramRequestOptions): Promise<HistogramResponse>;
-    getCategories({ column, operation, operationColumn, joinOperation, filterOwner, }: CategoryRequestOptions): Promise<CategoryResponse>;
-    getScatter({ xAxisColumn, yAxisColumn, xAxisJoinOperation, yAxisJoinOperation, filterOwner, }: ScatterRequestOptions): Promise<ScatterResponse>;
-    getTable(options: TableRequestOptions): Promise<TableResponse>;
-    getTimeSeries({ column, stepSize, operation, operationColumn, joinOperation, filterOwner, }: TimeSeriesRequestOptions): Promise<TimeSeriesResponse>;
-    getRange({ column, filterOwner, }: RangeRequestOptions): Promise<RangeResponse>;
-    /****************************************************************************
-     * INTERNAL
-     */
-    private _getFilteredFeatures;
-}

package/src/filters/tileFeaturesRaster.ts

@@ -1,111 +0,0 @@
-import {
-  cellToChildren as _cellToChildren,
-  cellToTile,
-  geometryToCells,
-  getResolution,
-} from 'quadbin';
-import {RasterTile, SpatialFilter, Tile} from '../types';
-import {FeatureData} from '../types-internal';
-import {
-  RasterMetadata,
-  RasterMetadataBand,
-  SpatialDataType,
-} from '../sources/types';
-
-export type TileFeaturesRasterOptions = {
-  tiles: RasterTile[];
-  spatialFilter: SpatialFilter;
-  spatialDataColumn: string;
-  spatialDataType: SpatialDataType;
-  rasterMetadata: RasterMetadata;
-};
-
-export function tileFeaturesRaster({
-  tiles,
-  ...options
-}: TileFeaturesRasterOptions): FeatureData[] {
-  // Cache band metadata for faster lookup while iterating over pixels.
-  const bandMetadataByName: Record<string, RasterMetadataBand> = {};
-  for (const band of options.rasterMetadata.bands) {
-    bandMetadataByName[band.name] = band;
-  }
-
-  // Omit empty and invisible tiles for simpler processing and types.
-  tiles = tiles.filter(isRasterTileVisible);
-  if (tiles.length === 0) return [];
-
-  // Raster tiles, and all pixels, are quadbin cells. Resolution of a pixel is
-  // the resolution of the tile, plus the number of subdivisions. Block size
-  // must be square, N x N, where N is a power of two.
-  const tileResolution = getResolution(tiles[0].index.q as bigint);
-  const tileBlockSize = tiles[0].data!.blockSize;
-  const cellResolution = tileResolution + BigInt(Math.log2(tileBlockSize));
-
-  // Compute covering cells for the spatial filter, at same resolution as the
-  // raster pixels, to be used as a mask.
-  const spatialFilterCells = new Set(
-    geometryToCells(options.spatialFilter, cellResolution)
-  );
-
-  const data = new Map<bigint, FeatureData>();
-
-  for (const tile of tiles as Required<RasterTile>[]) {
-    const parent = tile.index.q as bigint;
-
-    const children = cellToChildrenSorted(parent, cellResolution);
-
-    // For each pixel/cell within the spatial filter, create a FeatureData.
-    // Order is row-major, starting from NW and ending at SE.
-    for (let i = 0; i < children.length; i++) {
-      if (!spatialFilterCells.has(children[i])) continue;
-
-      const cellData: FeatureData = {};
-      let cellDataExists = false;
-
-      for (const band in tile.data.cells.numericProps) {
-        const value = tile.data.cells.numericProps[band].value[i];
-        // TODO(cleanup): nodata should be a number, not a string.
-        if (Number(bandMetadataByName[band].nodata) !== value) {
-          cellData[band] = tile.data!.cells.numericProps[band].value[i];
-          cellDataExists = true;
-        }
-      }
-
-      if (cellDataExists) {
-        data.set(children[i], cellData);
-      }
-    }
-  }
-
-  return Array.from(data.values());
-}
-
-/**
- * Detects whether a given {@link Tile} is a {@link RasterTile}.
- * @privateRemarks Method of detection is arbitrary, and may be changed.
- */
-export function isRasterTile(tile: Tile): tile is RasterTile {
-  return tile.data ? tile.data.hasOwnProperty('cells') : false;
-}
-
-function isRasterTileVisible(tile: RasterTile): tile is Required<RasterTile> {
-  return !!(tile.isVisible && tile.data?.cells?.numericProps);
-}
-
-/**
- * For the raster format, children are sorted in row-major order, starting from
- * NW and ending at SE. Order returned by quadbin's cellToChildren() is not
- * defined (and not related to the raster format), so sort explicitly here.
- */
-function cellToChildrenSorted(parent: bigint, resolution: bigint): bigint[] {
-  return _cellToChildren(parent, resolution).sort(
-    (cellA: bigint, cellB: bigint) => {
-      const tileA = cellToTile(cellA);
-      const tileB = cellToTile(cellB);
-      if (tileA.y !== tileB.y) {
-        return tileA.y > tileB.y ? 1 : -1;
-      }
-      return tileA.x > tileB.x ? 1 : -1;
-    }
-  );
-}

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

@@ -1,14 +0,0 @@
-import {RasterMetadata} from '../sources/index.js';
-import {
-  WidgetTilesetSource,
-  WidgetTilesetSourceProps,
-} from './widget-tileset-source.js';
-
-export type WidgetRasterSourceProps = WidgetTilesetSourceProps & {
-  rasterMetadata: RasterMetadata;
-  spatialDataType: 'quadbin';
-};
-
-export type WidgetRasterSourceResult = {widgetSource: WidgetRasterSource};
-
-export class WidgetRasterSource extends WidgetTilesetSource<WidgetRasterSourceProps> {}