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

package/build/sources/types.d.ts

@@ -1,366 +0,0 @@
-import type { Feature } from 'geojson';
-import { Filters, Format, QueryParameters } from '../types';
-import { MapInstantiation } from '../types-internal';
-export type SourceRequiredOptions = {
-    /** Carto platform access token. */
-    accessToken: string;
-    /** Data warehouse connection name in Carto platform. */
-    connectionName: string;
-};
-export type SourceOptionalOptions = {
-    /**
-     * Base URL of the CARTO Maps API.
-     *
-     * Example for account located in EU-west region: `https://gcp-eu-west1.api.carto.com`
-     *
-     * @default https://gcp-us-east1.api.carto.com
-     */
-    apiBaseUrl: string;
-    /**
-     * Custom HTTP headers added to map instantiation and data requests.
-     */
-    headers: Record<string, string>;
-    /**
-     * Cache buster value returned by map instantiation.
-     *
-     * Carto source saves `cache` value of map instantiation response in `cache.value`, so it can be used to
-     * check if underlying map data has changed between distinct source requests.
-     */
-    cache?: {
-        value?: number;
-    };
-    clientId: string;
-    /** @deprecated  use `query` instead **/
-    format: Format;
-    /**
-     * Maximum URL character length. Above this limit, requests use POST.
-     * Used to avoid browser and CDN limits.
-     * @default {@link DEFAULT_MAX_LENGTH_URL}
-     */
-    maxLengthURL?: number;
-    /**
-     * The column name and the type of geospatial support.
-     *
-     * If not present, defaults to `'geom'` for generic queries, `'quadbin'` for Quadbin sources and `'h3'` for H3 sources.
-     */
-    spatialDataColumn?: string;
-    /**
-     * The type of geospatial support. Defaults to `'geo'`.
-     */
-    spatialDataType?: SpatialDataType;
-    /**
-     * Relative resolution of a tile. Higher values increase density and data size. At `tileResolution = 1`, tile geometry is
-     * quantized to a 1024x1024 grid. Increasing or decreasing the resolution will increase or decrease the dimensions of
-     * the quantization grid proportionately.
-     *
-     * Supported `tileResolution` values, with corresponding grid sizes:
-     *
-     * - 0.25: 256x256
-     * - 0.5: 512x512
-     * - 1: 1024x1024
-     * - 2: 2048x2048
-     * - 4: 4096x4096
-     */
-    tileResolution?: TileResolution;
-    /**
-     * By default, local in-memory caching is enabled.
-     */
-    localCache?: LocalCacheOptions;
-};
-export type LocalCacheOptions = {
-    /**
-     * Map that stores requests and their responses.
-     */
-    cache?: Map<string, Promise<unknown>>;
-    /**
-     * Cache control
-     *  * `no-cache`: If present, the source will always fetch from original source.
-     *  * `no-store`: If present, source will not store result in cache (for later reuse).
-     *
-     * See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#directives
-     */
-    cacheControl?: ('no-cache' | 'no-store')[];
-};
-export type SourceOptions = SourceRequiredOptions & Partial<SourceOptionalOptions>;
-export type AggregationOptions = {
-    /**
-     * Defines the aggregation expressions that will be calculated from the resulting columns on each grid cell.
-     *
-     * Example:
-     *
-     *     sum(pop) as total_population, avg(rev) as average_revenue
-     */
-    aggregationExp: string;
-    /**
-     * Defines the tile aggregation resolution.
-     *
-     * @default 6 for quadbin and 4 for h3 sources
-     */
-    aggregationResLevel?: number;
-    /**
-     * Original resolution of the spatial index data as stored in the DW
-     */
-    dataResolution?: number;
-};
-export type FilterOptions = {
-    /**
-     * Filters to apply to the data source on the server
-     */
-    filters?: Filters;
-};
-export type QuerySourceOptions = {
-    /** Full SQL query with query paremeter placeholders (if any). */
-    sqlQuery: string;
-    /**
-     * Values for named or positional paramteres in the query.
-     *
-     * The way query parameters are determined by data warehouse.
-     *
-     *  * BigQuery has named query parameters, specified with a dictionary, and referenced by key (`@key`)
-     *
-     *     ```
-     *     sqlQuery: "SELECT * FROM carto-demo-data.demo_tables.retail_stores WHERE storetype = ⁣@type AND revenue > ⁣@minRevenue"
-     *     queryParameters: { type: 'Supermarket', minRevenue: 1000000 }
-     *     ```
-     * * Snowflake supports positional parameters, in the form `:1`, `:2`, etc.
-     *
-     *     ```
-     *     sqlQuery: "SELECT * FROM demo_db.public.import_retail_stores WHERE storetype = :2 AND revenue > :1
-     *     queryParameters: [100000, "Supermarket"]
-     *     ```
-     * * Postgres and Redhisft supports positional parameters, but in the form `$1`, `$2`, etc.
-     *
-     *     ```
-     *     sqlQuery: "SELECT * FROM carto_demo_data.demo_tables.retail_stores WHERE storetype = $2 AND revenue > $1
-     *     queryParameters: [100000, "Supermarket"]
-     *     ```
-     */
-    queryParameters?: QueryParameters;
-    /**
-     * Comma-separated aggregation expressions. If assigned on a vector source, source is grouped by geometry and then aggregated.
-     *
-     * Example:
-     *
-     *     1 as value, avg(rev) as average_revenue
-     */
-    aggregationExp?: string;
-};
-export type TableSourceOptions = {
-    /**
-     * Fully qualified name of table.
-     */
-    tableName: string;
-    /**
-     * Comma-separated aggregation expressions. If assigned on a vector source, source is grouped by geometry and then aggregated.
-     *
-     * Example:
-     *
-     *     1 as value, avg(rev) as average_revenue
-     */
-    aggregationExp?: string;
-};
-export type TilesetSourceOptions = {
-    /**
-     * Fully qualified name of tileset.
-     */
-    tableName: string;
-};
-export type ColumnsOption = {
-    /**
-     * Columns to retrieve from the table.
-     *
-     * If not present, all columns are returned.
-     */
-    columns?: string[];
-};
-export type SpatialDataType = 'geo' | 'h3' | 'quadbin';
-/**
- * Strategy used for covering spatial filter geometry with spatial indexes.
- * See https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/quadbin#quadbin_polyfill_mode
- * or https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/h3#h3_polyfill_mode for more information.
- * @internalRemarks Source: cloud-native maps-api
- * */
-export type SpatialFilterPolyfillMode = 'center' | 'intersects' | 'contains';
-export type TilejsonMapInstantiation = MapInstantiation & {
-    tilejson: {
-        url: string[];
-    };
-};
-export type TileResolution = 0.25 | 0.5 | 1 | 2 | 4;
-export interface Tilejson {
-    tilejson: string;
-    name: string;
-    description: string;
-    version: string;
-    attribution: string;
-    scheme: string;
-    tiles: string[];
-    minzoom: number;
-    maxzoom: number;
-    bounds: [left: number, bottom: number, right: number, top: number];
-    center: [longitute: number, latitude: number, zoom: number];
-    vector_layers: VectorLayer[];
-    minresolution: number;
-    maxresolution: number;
-    properties_tiles: string[];
-    tilestats: Tilestats;
-    tileResolution?: TileResolution;
-    /**
-     * Resolution of data in spatial-index dataset (e.g. H3, Quadbin).
-     *
-     * @internal
-     */
-    dataresolution?: number;
-    /**
-     * Array of ratios of dropped features per zoom level.
-     *
-     * Example: `[0,0,0.5]` - means that 50% of features are dropped at zoom 2 and bigger.
-     *
-     * @internal
-     */
-    fraction_dropped_per_zoom?: number[];
-    /**
-     * Names of bands - rasters only.
-     *
-     * @internal
-     */
-    raster_bands?: string[];
-    /**
-     * Raster metadata - rasters only.
-     *
-     * @internal
-     */
-    raster_metadata?: RasterMetadata;
-}
-export interface Tilestats {
-    layerCount: number;
-    layers: Layer[];
-}
-export interface Layer {
-    layer: string;
-    count: number;
-    attributeCount: number;
-    attributes: Attribute[];
-}
-export interface Attribute {
-    attribute: string;
-    type: string;
-}
-export interface VectorLayer {
-    id: string;
-    minzoom: number;
-    maxzoom: number;
-    fields: Record<string, string>;
-    geometry_type?: string;
-}
-export type RasterMetadataBandStats = {
-    approximated_stats?: boolean;
-    min: number;
-    max: number;
-    mean: number;
-    stddev: number;
-    sum: number;
-    sum_squares: number;
-    count: number;
-    /**
-     * Quantiles by number of buckets.
-     *
-     * Example:
-     * ```ts
-     *   {
-     *     // for 3 buckets, first 1/3 of items lies in range [min, 20], second 1/3 is in [20, 40], and last 1/3 is in [40, max]
-     *     3: [20, 40],
-     *     4: [20, 30, 50], for 4 buckets ...
-     *   }
-     * ```
-     */
-    quantiles?: Record<number, number[]>;
-    /**
-     * Top values by number of values.
-     *
-     * Key of dictionary is value, value is count.
-     * Key order is random.
-     *
-     * Example:
-     * ```
-     *  {
-     *    3: 5, // means there are 5 pixels with value 3
-     *    11: 222,
-     *    12: 333, // means that 12 is most common value with count 333
-     *    ...      // (assuming 333 was largest value in dict)
-     *   }
-     * ```
-     */
-    top_values?: Record<number, number>;
-    /**
-     * Raster loader version.
-     */
-    version?: string;
-};
-export declare enum RasterBandColorinterp {
-    Gray = "gray",
-    Red = "red",
-    Green = "green",
-    Blue = "blue",
-    Alpha = "alpha",
-    Palette = "palette"
-}
-export type RasterMetadataBand = {
-    type: string;
-    name: string;
-    stats: RasterMetadataBandStats;
-    /**
-     * Known values:
-     *  * `palette`: use unique value and `colortable` ad default mapping
-     *  * `red`, `green`, `blue`: use the band as color channel
-     *  * `gray`: use the band as grayscale
-     */
-    colorinterp?: string | RasterBandColorinterp;
-    /**
-     * Default color mapping for unique values (or if coloprinterp is `palette`)
-     */
-    colortable?: Record<string, number[]>;
-    /**
-     * No value representation.
-     * Observed values:
-     *   * `'nan'` for `NaN`
-     *   * `number`: both as string as number, so parsing is needed
-     */
-    nodata: string | number;
-};
-export type RasterMetadata = {
-    block_resolution: number;
-    minresolution: number;
-    maxresolution: number;
-    nodata: number | string;
-    bands: RasterMetadataBand[];
-    bounds: [left: number, bottom: number, right: number, top: number];
-    center: [longitute: number, latitude: number, zoom: number];
-    width: number;
-    height: number;
-    block_width: number;
-    block_height: number;
-    num_blocks: number;
-    num_pixels: number;
-    pixel_resolution: number;
-};
-export type TilejsonResult = Tilejson & {
-    accessToken: string;
-};
-export type GeojsonResult = {
-    type: 'FeatureCollection';
-    features: Feature[];
-};
-export type JsonResult = any[];
-export type QueryResult = {
-    meta: {
-        cacheHit: boolean;
-        location: string;
-        totalBytesProcessed: string;
-    };
-    rows: Record<string, any>[];
-    schema: {
-        name: string;
-        type: string;
-    }[];
-};

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

@@ -1,5 +0,0 @@
-import { WidgetQuerySourceResult } from '../widget-sources/index.js';
-import type { FilterOptions, SourceOptions, QuerySourceOptions, TilejsonResult, ColumnsOption } from './types';
-export type VectorQuerySourceOptions = SourceOptions & QuerySourceOptions & FilterOptions & ColumnsOption;
-export type VectorQuerySourceResponse = TilejsonResult & WidgetQuerySourceResult;
-export declare const vectorQuerySource: (options: VectorQuerySourceOptions) => Promise<VectorQuerySourceResponse>;

package/build/sources/vector-table-source.d.ts

@@ -1,5 +0,0 @@
-import { WidgetTableSourceResult } from '../widget-sources/index.js';
-import type { FilterOptions, ColumnsOption, SourceOptions, TableSourceOptions, TilejsonResult } from './types';
-export type VectorTableSourceOptions = SourceOptions & TableSourceOptions & FilterOptions & ColumnsOption;
-export type VectorTableSourceResponse = TilejsonResult & WidgetTableSourceResult;
-export declare const vectorTableSource: (options: VectorTableSourceOptions) => Promise<VectorTableSourceResponse>;

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

@@ -1,5 +0,0 @@
-import { WidgetTilesetSourceResult } from '../widget-sources';
-import type { SourceOptions, TilesetSourceOptions, TilejsonResult } from './types';
-export type VectorTilesetSourceOptions = SourceOptions & TilesetSourceOptions;
-export type VectorTilesetSourceResponse = TilejsonResult & WidgetTilesetSourceResult;
-export declare const vectorTilesetSource: (options: VectorTilesetSourceOptions) => Promise<VectorTilesetSourceResponse>;

package/build/spatial-index.d.ts

@@ -1,8 +0,0 @@
-import type { ModelSource } from './models/model';
-import type { AggregationOptions } from './sources/types';
-import type { ViewState } from './widget-sources';
-export declare function getSpatialFiltersResolution(source: Partial<ModelSource & AggregationOptions>, viewState: ViewState): number | undefined;
-export declare function getHexagonResolution(viewport: {
-    zoom: number;
-    latitude: number;
-}, tileSize: number): number;

package/build/types-internal.d.ts

@@ -1,56 +0,0 @@
-/******************************************************************************
- * COMMON
- */
-import { Format } from './types';
-/** @internal */
-export type $TODO = any;
-/** @internal */
-export type $IntentionalAny = any;
-/******************************************************************************
- * MAP INSTANTIATION
- */
-/**
- * @internalRemarks Source: @deck.gl/carto
- * @internal
- */
-export declare enum SchemaFieldType {
-    Number = "number",
-    Bigint = "bigint",
-    String = "string",
-    Geometry = "geometry",
-    Timestamp = "timestamp",
-    Object = "object",
-    Boolean = "boolean",
-    Variant = "variant",
-    Unknown = "unknown"
-}
-/**
- * @internalRemarks Source: @deck.gl/carto
- * @internal
- */
-export interface SchemaField {
-    name: string;
-    type: SchemaFieldType;
-}
-/**
- * @internalRemarks Source: @deck.gl/carto
- * @internal
- */
-export interface MapInstantiation extends MapInstantiationFormats {
-    nrows: number;
-    size?: number;
-    schema: SchemaField[];
-}
-/**
- * @internalRemarks Source: @deck.gl/carto
- * @internal
- */
-type MapInstantiationFormats = Record<Format, {
-    url: string[];
-    error?: any;
-}>;
-/******************************************************************************
- * LOCAL CALCULATIONS
- */
-export type FeatureData = Record<string, unknown>;
-export {};

package/build/types.d.ts

@@ -1,140 +0,0 @@
-import type { FilterType } from './constants.js';
-import type { Polygon, MultiPolygon, Feature } from 'geojson';
-import type { BinaryFeature, BinaryFeatureCollection } from '@loaders.gl/schema';
-/******************************************************************************
- * MAPS AND TILES
- */
-/** @internalRemarks Source: @deck.gl/carto */
-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
- */
-/**
- * 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.
- */
-export type AggregationType = 'count' | 'avg' | 'min' | 'max' | 'sum' | 'custom';
-/******************************************************************************
- * FILTERS
- */
-/** @internalRemarks Source: @carto/react-api */
-export type SpatialFilter = Polygon | MultiPolygon;
-/** @internalRemarks Source: @deck.gl/carto */
-export interface Filters {
-    [column: string]: Filter;
-}
-/** @internalRemarks Source: @carto/react-api, @deck.gl/carto */
-export interface Filter {
-    [FilterType.IN]?: {
-        owner?: string;
-        values: number[] | string[];
-    };
-    /** [a, b] both are included. */
-    [FilterType.BETWEEN]?: {
-        owner?: string;
-        values: number[][];
-    };
-    /** [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[];
-        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
- */
-/**
- * Defines a step size increment for use with {@link TimeSeriesRequestOptions}.
- *
- * @internalRemarks Source: @carto/react-core
- */
-export type GroupDateType = 'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';
-/******************************************************************************
- * SORTING
- */
-export type SortDirection = 'asc' | 'desc';
-export type SortColumnType = 'number' | 'string' | 'date';
-/******************************************************************************
- * SQL QUERY PARAMETERS
- */
-/** @internalRemarks Source: @deck.gl/carto */
-export type QueryParameterValue = string | number | boolean | Array<QueryParameterValue> | object;
-/** @internalRemarks Source: @deck.gl/carto */
-export type NamedQueryParameter = Record<string, QueryParameterValue>;
-/** @internalRemarks Source: @deck.gl/carto */
-export type PositionalQueryParameter = QueryParameterValue[];
-/** @internalRemarks Source: @deck.gl/carto */
-export type QueryParameters = NamedQueryParameter | PositionalQueryParameter;

package/build/utils/dateUtils.d.ts

@@ -1,10 +0,0 @@
-/**
- * Returns midnight (local time) on the Monday preceeding a given date, in
- * milliseconds since the UNIX epoch.
- */
-export declare function getMonday(date: number | Date): number;
-/**
- * Returns midnight (UTC) on the Monday preceeding a given date, in
- * milliseconds since the UNIX epoch.
- */
-export declare function getUTCMonday(date: number | Date): number;

package/build/utils/getTileFormat.d.ts

@@ -1,3 +0,0 @@
-import { TileFormat } from '../constants.js';
-import { Tilejson } from '../sources/types.js';
-export declare function getTileFormat(tilejson: Tilejson): TileFormat;

package/build/utils/makeIntervalComplete.d.ts

@@ -1,2 +0,0 @@
-import { FilterInterval, FilterIntervalComplete } from '../types';
-export declare function makeIntervalComplete(intervals: FilterInterval[]): FilterIntervalComplete[];

package/build/utils/transformTileCoordsToWGS84.d.ts

@@ -1,8 +0,0 @@
-import { BBox, Geometry } from 'geojson';
-/**
- * Transform tile coords to WGS84 coordinates.
- *
- * @param geometry - any valid geojson geometry
- * @param bbox - geojson bbox
- */
-export declare function transformTileCoordsToWGS84<T extends Geometry>(geometry: T, bbox: BBox): T;

package/build/utils/transformToTileCoords.d.ts

@@ -1,9 +0,0 @@
-import { BBox, Geometry } from 'geojson';
-/**
- * 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 declare function transformToTileCoords<T extends Geometry>(geometry: T, bbox: BBox): T;

package/build/utils.d.ts

@@ -1,32 +0,0 @@
-import { Filter } from './types.js';
-/**
- * @privateRemarks Source: @carto/react-widgets
- * @internal
- */
-export declare function getApplicableFilters(owner?: string, filters?: Record<string, Filter>): Record<string, Filter>;
-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
- * @internal
- */
-export declare function normalizeObjectKeys<T, R extends Row<T>>(el: R): R;
-/** @internalRemarks Source: @carto/react-core */
-export declare function assert(condition: unknown, message: string): asserts condition;
-/**
- * @internalRemarks Source: @carto/react-core
- * @internal
- */
-export declare class InvalidColumnError extends Error {
-    protected static readonly NAME = "InvalidColumnError";
-    constructor(message: string);
-    static is(error: unknown): boolean;
-}
-export declare function isEmptyObject(object: object): boolean;
-/** @internal */
-export declare const isObject: (x: unknown) => boolean;
-/** @internal */
-export declare const isPureObject: (x: any) => boolean;
-export {};

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

@@ -1,5 +0,0 @@
-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';