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

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-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,76 +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 } from '../types.js';
-import { TileFeatureExtractOptions } from '../filters/index.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 extends WidgetSource<WidgetTilesetSourceProps> {
-    private _tiles;
-    private _features;
-    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;
-}