@carto/api-client 0.4.1-alpha.0 → 0.4.1

package/src/sources/quadbin-table-source.ts

@@ -56,12 +56,7 @@ export const quadbinTableSource = async function (
   return baseSource<UrlParameters>('table', options, urlParameters).then(
     (result) => ({
       ...(result as TilejsonResult),
-      widgetSource: new WidgetTableSource({
-        ...options,
-        // NOTE: passing redundant spatialDataColumn here to apply the default value 'quadbin'
-        spatialDataColumn,
-        spatialDataType: 'quadbin',
-      }),
+      widgetSource: new WidgetTableSource(options),
     })
   );
 };

package/src/sources/types.ts

@@ -49,31 +49,25 @@ export type SourceOptionalOptions = {
   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.
+   * By default, local in-memory caching is enabled.
    */
-  spatialDataColumn?: string;
+  localCache?: LocalCacheOptions;
+};
 
+export type LocalCacheOptions = {
   /**
-   * The type of geospatial support. Defaults to `'geo'`.
+   * Map that stores requests and their responses.
    */
-  spatialDataType?: SpatialDataType;
+  cache?: Map<string, Promise<unknown>>;
 
   /**
-   * 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.
+   * 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).
    *
-   * Supported `tileResolution` values, with corresponding grid sizes:
-   *
-   * - 0.25: 256x256
-   * - 0.5: 512x512
-   * - 1: 1024x1024
-   * - 2: 2048x2048
-   * - 4: 4096x4096
+   * See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#directives
    */
-  tileResolution?: TileResolution;
+  cacheControl?: ('no-cache' | 'no-store')[];
 };
 
 export type SourceOptions = SourceRequiredOptions &
@@ -95,11 +89,6 @@ export type AggregationOptions = {
    * @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 = {
@@ -110,9 +99,31 @@ export type FilterOptions = {
 };
 
 export type QuerySourceOptions = {
-  /** Full SQL query with query paremeter placeholders (if any). */
+  /**
+   * 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;
+
+  /** SQL query. */
   sqlQuery: string;
 
+  /**
+   * 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;
+
   /**
    * Values for named or positional paramteres in the query.
    *
@@ -145,6 +156,28 @@ export type TableSourceOptions = {
    * Fully qualified name of table.
    */
   tableName: string;
+
+  /**
+   * The column name and the type of geospatial support.
+   *
+   * If not present, defaults to `'geom'` for generic tables, `'quadbin'` for Quadbin sources and `'h3'` for H3 sources.
+   */
+  spatialDataColumn?: string;
+
+  /**
+   * 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;
 };
 
 export type TilesetSourceOptions = {
@@ -165,14 +198,6 @@ export type ColumnsOption = {
 
 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[]};
 };
@@ -187,16 +212,51 @@ export interface Tilejson {
   attribution: string;
   scheme: string;
   tiles: string[];
-  properties_tiles: string[];
-  minresolution: number;
-  maxresolution: number;
   minzoom: number;
   maxzoom: number;
-  bounds: [number, number, number, number];
-  center: [number, number, number];
+  bounds: [left: number, bottom: number, right: number, top: number];
+  center: [longitute: number, latitude: number, zoom: number];
   vector_layers: VectorLayer[];
+
+  //
+  // Carto additions over standard Tilejson properties
+  //
+
+  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 {
@@ -217,12 +277,116 @@ export interface Attribute {
 }
 
 export interface VectorLayer {
+  // tilejson standard
   id: string;
   minzoom: number;
   maxzoom: number;
   fields: Record<string, string>;
+
+  // Carto additions over standard Tilejson properties
+  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 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; // use RasterBandColorinterp, but it's external value, so let's use string
+
+  /**
+   * 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; // 255, '0', 'nan'
+};
+
+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[];

package/src/sources/vector-query-source.ts

@@ -64,10 +64,7 @@ export const vectorQuerySource = async function (
   return baseSource<UrlParameters>('query', options, urlParameters).then(
     (result) => ({
       ...(result as TilejsonResult),
-      widgetSource: new WidgetQuerySource({
-        ...options,
-        spatialDataType: 'geo',
-      }),
+      widgetSource: new WidgetQuerySource(options),
     })
   );
 };

package/src/sources/vector-table-source.ts

@@ -22,7 +22,6 @@ export type VectorTableSourceOptions = SourceOptions &
   TableSourceOptions &
   FilterOptions &
   ColumnsOption;
-
 type UrlParameters = {
   columns?: string;
   filters?: Record<string, unknown>;
@@ -59,10 +58,7 @@ export const vectorTableSource = async function (
   return baseSource<UrlParameters>('table', options, urlParameters).then(
     (result) => ({
       ...(result as TilejsonResult),
-      widgetSource: new WidgetTableSource({
-        ...options,
-        spatialDataType: 'geo',
-      }),
+      widgetSource: new WidgetTableSource(options),
     })
   );
 };

package/src/utils.ts

@@ -57,7 +57,7 @@ export function normalizeObjectKeys<T, R extends Row<T>>(el: R): R {
 }
 
 /** @internalRemarks Source: @carto/react-core */
-export function assert(condition: unknown, message: string): asserts condition {
+export function assert(condition: unknown, message: string) {
   if (!condition) {
     throw new Error(message);
   }

package/src/widget-sources/types.ts

@@ -1,4 +1,4 @@
-import {SpatialFilterPolyfillMode, TileResolution} from '../sources/types';
+import {TileResolution} from '../sources/types';
 import {
   GroupDateType,
   SortColumnType,
@@ -10,19 +10,11 @@ import {
  * WIDGET API REQUESTS
  */
 
-export interface ViewState {
-  zoom: number;
-  latitude: number;
-  longitude: number;
-}
-
 /** Common options for {@link WidgetBaseSource} requests. */
 interface BaseRequestOptions {
   spatialFilter?: SpatialFilter;
-  spatialFiltersMode?: SpatialFilterPolyfillMode;
   abortController?: AbortController;
   filterOwner?: string;
-  viewState?: ViewState;
 }
 
 /** Options for {@link WidgetBaseSource#getCategories}. */