@carto/api-client 0.5.1-alpha.2 → 0.5.2-alpha.0

package/package.json

@@ -8,7 +8,7 @@
   "homepage": "https://github.com/CartoDB/carto-api-client#readme",
   "author": "Don McCurdy <donmccurdy@carto.com>",
   "packageManager": "yarn@4.3.1",
-  "version": "0.5.1-alpha.2",
+  "version": "0.5.2-alpha.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -39,7 +39,7 @@
   "scripts": {
     "build": "tsup",
     "build:watch": "tsup --watch",
-    "dev": "concurrently \"yarn build:watch\" \"vite --config examples/vite.config.ts --open\"",
+    "dev": "yarn build && concurrently --names tsup,vite \"yarn build:watch\" \"vite --config examples/vite.config.ts --open\"",
     "test": "vitest run --typecheck",
     "test:watch": "vitest watch --typecheck",
     "coverage": "vitest run --coverage.enabled --coverage.all false",
@@ -128,5 +128,5 @@
     "@carto/api-client": "portal:./",
     "rollup": "^4.20.0"
   },
-  "stableVersion": "0.5.0"
+  "stableVersion": "0.5.1"
 }

package/src/fetch-map/fetch-map.ts

@@ -1,5 +1,3 @@
-import {TilejsonResult} from '../sources/index.js';
-
 import {DEFAULT_API_BASE_URL} from '../constants.js';
 
 import {
@@ -119,11 +117,7 @@ async function fillInTileStats(
       const attribute = layer.visualChannels[channel]?.name;
       if (attribute) {
         const dataset = datasets.find((d) => d.id === layer.config.dataId);
-        if (
-          dataset &&
-          dataset.type !== 'tileset' &&
-          (dataset.data as TilejsonResult).tilestats
-        ) {
+        if (dataset && dataset.type !== 'tileset' && dataset.data.tilestats) {
           // Only fetch stats for QUERY & TABLE map types
           attributes.push({attribute, dataset});
         }

package/src/fetch-map/parse-map.ts

@@ -57,7 +57,7 @@ export function parseMap(json: any) {
   const {keplerMapConfig, datasets, token} = json;
   assert(keplerMapConfig.version === 'v1', 'Only support Kepler v1');
   const config = keplerMapConfig.config as KeplerMapConfig;
-  const {filters, mapState, mapStyle, popupSettings} = config;
+  const {filters, mapState, mapStyle, popupSettings, legendSettings} = config;
   const {layers, layerBlending, interactionConfig} = config.visState;
 
   return {
@@ -70,6 +70,7 @@ export function parseMap(json: any) {
     /** @deprecated Use `basemap`. */
     mapStyle,
     popupSettings,
+    legendSettings,
     token,
     layers: layers
       .reverse()

package/src/fetch-map/source.ts

@@ -201,11 +201,12 @@ function getDynamicTileResolution(
 }
 
 /**
+ * @internal
  * State of `aggregationResLevel` in the UI and backend config is based on an assumption of
  * 512x512px tiles. Because we may change tile resolution for performance goals, the
  * `aggregationResLevel` passed to the deck.gl layer must be scaled with tile resolution.
  */
-function scaleAggregationResLevel(
+export function scaleAggregationResLevel(
   aggregationResLevel: number,
   tileResolution: number
 ): number | undefined {
@@ -213,7 +214,12 @@ function scaleAggregationResLevel(
   return aggregationResLevel - Math.log2(0.5 / tileResolution);
 }
 
-function getColumnNameFromGeoColumn(geoColumn: string | null | undefined) {
+/**
+ * @internal
+ */
+export function getColumnNameFromGeoColumn(
+  geoColumn: string | null | undefined
+) {
   if (!geoColumn) {
     return geoColumn;
   }
@@ -221,7 +227,10 @@ function getColumnNameFromGeoColumn(geoColumn: string | null | undefined) {
   return parts.length === 1 ? parts[0] : parts.length === 2 ? parts[1] : null;
 }
 
-function getSpatialIndexFromGeoColumn(geoColumn: string) {
+/**
+ * @internal
+ */
+export function getSpatialIndexFromGeoColumn(geoColumn: string) {
   const spatialIndexToSearch = geoColumn.split(':')[0];
 
   for (const index of Object.values(SpatialIndex)) {

package/src/fetch-map/types.ts

@@ -1,6 +1,6 @@
 import {LayerType, SCALE_TYPE} from './layer-map.js';
 import {Format, MapType, ProviderType, QueryParameters} from '../types.js';
-import {TilejsonResult, GeojsonResult, JsonResult} from '../sources/types.js';
+import {TilejsonResult} from '../sources/types.js';
 
 export type VisualChannelField = {
   name: string;
@@ -117,6 +117,7 @@ export type KeplerMapConfig = {
     styleType: string;
     visibleLayerGroups: Record<string, boolean>;
   };
+  legendSettings?: any;
   popupSettings: any;
   visState: {
     layers: MapConfigLayer[];
@@ -208,7 +209,7 @@ export type Dataset = {
   cache?: number;
   connectionName: string;
   geoColumn: string;
-  data: TilejsonResult | GeojsonResult | JsonResult;
+  data: TilejsonResult;
   columns: string[];
   format: Format;
   aggregationExp: string;

package/src/filters.ts

@@ -2,6 +2,10 @@ import {FilterType} from './constants.js';
 import {Filter} from './types.js';
 import {isEmptyObject} from './utils.js';
 
+const FILTER_TYPES = new Set(Object.values(FilterType));
+const isFilterType = (type: string): type is FilterType =>
+  FILTER_TYPES.has(type as FilterType);
+
 type FilterTypeOptions<T extends FilterType> = {
   type: T;
   column: string;
@@ -53,7 +57,7 @@ export function removeFilter(
   }
 
   if (owner) {
-    for (const type of Object.values(FilterType)) {
+    for (const type of FILTER_TYPES) {
       if (owner === filter[type as FilterType]?.owner) {
         delete filter[type as FilterType];
       }
@@ -97,7 +101,7 @@ export function hasFilter(
     return true;
   }
 
-  for (const type of Object.values(FilterType)) {
+  for (const type of FILTER_TYPES) {
     if (owner === filter[type as FilterType]?.owner) {
       return true;
     }
@@ -127,3 +131,34 @@ export function getFilter<T extends FilterType>(
 
   return null;
 }
+
+/**
+ * Given all filters for a dataset, returns the subset of filters that are not
+ * attributable to the given owner. Typically used to allow filterable widgets
+ * to affect other widgets *without* filtering themselves.
+ *
+ * @privateRemarks Source: @carto/react-widgets
+ */
+export function getApplicableFilters(
+  owner?: string,
+  filters?: Record<string, Filter>
+): Record<string, Filter> {
+  if (!filters) return {};
+
+  const applicableFilters: Record<string, Filter> = {};
+
+  for (const column in filters) {
+    for (const type in filters[column]) {
+      if (!isFilterType(type)) continue;
+
+      const filter = filters[column][type];
+      const isApplicable = !owner || !filter?.owner || filter?.owner !== owner;
+      if (filter && isApplicable) {
+        applicableFilters[column] ||= {};
+        (applicableFilters[column][type] as typeof filter) = filter;
+      }
+    }
+  }
+
+  return applicableFilters;
+}

package/src/index.ts

@@ -26,3 +26,4 @@ export * from './filters/index.js';
 export * from './operations/index.js';
 export * from './utils/makeIntervalComplete.js';
 export * from './utils/transformToTileCoords.js';
+export * from './fetch-map/source.js';

package/src/sources/base-source.ts

@@ -7,8 +7,6 @@ import {DEFAULT_MAX_LENGTH_URL} from '../constants-internal.js';
 import {buildSourceUrl} from '../api/endpoints.js';
 import {requestWithParameters} from '../api/request-with-parameters.js';
 import type {
-  GeojsonResult,
-  JsonResult,
   SourceOptionalOptions,
   SourceRequiredOptions,
   TilejsonMapInstantiation,
@@ -20,7 +18,6 @@ import {getClient} from '../client.js';
 
 export const SOURCE_DEFAULTS: Omit<SourceOptionalOptions, 'clientId'> = {
   apiBaseUrl: DEFAULT_API_BASE_URL,
-  format: 'tilejson',
   headers: {},
   maxLengthURL: DEFAULT_MAX_LENGTH_URL,
 };
@@ -29,7 +26,7 @@ export async function baseSource<UrlParameters extends Record<string, unknown>>(
   endpoint: MapType,
   options: Partial<SourceOptionalOptions> & SourceRequiredOptions,
   urlParameters: UrlParameters
-): Promise<TilejsonResult | GeojsonResult | JsonResult> {
+): Promise<TilejsonResult> {
   const {accessToken, connectionName, cache, ...optionalOptions} = options;
   const mergedOptions = {
     ...SOURCE_DEFAULTS,
@@ -45,7 +42,7 @@ export async function baseSource<UrlParameters extends Record<string, unknown>>(
     }
   }
   const baseUrl = buildSourceUrl(mergedOptions);
-  const {clientId, maxLengthURL, format, localCache} = mergedOptions;
+  const {clientId, maxLengthURL, localCache} = mergedOptions;
   const headers = {
     Authorization: `Bearer ${options.accessToken}`,
     ...options.headers,
@@ -68,7 +65,7 @@ export async function baseSource<UrlParameters extends Record<string, unknown>>(
       localCache,
     });
 
-  const dataUrl = mapInstantiation[format].url[0];
+  const dataUrl = mapInstantiation.tilejson.url[0];
   if (cache) {
     cache.value = parseInt(
       new URL(dataUrl).searchParams.get('cache') || '',
@@ -77,22 +74,7 @@ export async function baseSource<UrlParameters extends Record<string, unknown>>(
   }
   errorContext.requestType = 'Map data';
 
-  if (format === 'tilejson') {
-    const json = await requestWithParameters<TilejsonResult>({
-      baseUrl: dataUrl,
-      parameters: {client: clientId},
-      headers,
-      errorContext,
-      maxLengthURL,
-      localCache,
-    });
-    if (accessToken) {
-      json.accessToken = accessToken;
-    }
-    return json;
-  }
-
-  return await requestWithParameters<GeojsonResult | JsonResult>({
+  const json = await requestWithParameters<TilejsonResult>({
     baseUrl: dataUrl,
     parameters: {client: clientId},
     headers,
@@ -100,4 +82,8 @@ export async function baseSource<UrlParameters extends Record<string, unknown>>(
     maxLengthURL,
     localCache,
   });
+  if (accessToken) {
+    json.accessToken = accessToken;
+  }
+  return json;
 }

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

@@ -48,9 +48,5 @@ export const boundaryQuerySource = async function (
     urlParameters.queryParameters = queryParameters;
   }
 
-  return baseSource<UrlParameters>(
-    'boundary',
-    options,
-    urlParameters
-  ) as Promise<BoundaryQuerySourceResponse>;
+  return baseSource<UrlParameters>('boundary', options, urlParameters);
 };

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

@@ -36,9 +36,5 @@ export const boundaryTableSource = async function (
     urlParameters.filters = filters;
   }
 
-  return baseSource<UrlParameters>(
-    'boundary',
-    options,
-    urlParameters
-  ) as Promise<BoundaryTableSourceResponse>;
+  return baseSource<UrlParameters>('boundary', options, urlParameters);
 };

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

@@ -67,7 +67,7 @@ export const h3QuerySource = async function (
 
   return baseSource<UrlParameters>('query', options, urlParameters).then(
     (result) => ({
-      ...(result as TilejsonResult),
+      ...result,
       widgetSource: new WidgetQuerySource({
         ...options,
         // NOTE: Parameters with default values above must be explicitly passed here.

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

@@ -62,7 +62,7 @@ export const h3TableSource = async function (
 
   return baseSource<UrlParameters>('table', options, urlParameters).then(
     (result) => ({
-      ...(result as TilejsonResult),
+      ...result,
       widgetSource: new WidgetTableSource({
         ...options,
         // NOTE: Parameters with default values above must be explicitly passed here.

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

@@ -28,10 +28,10 @@ export const h3TilesetSource = async function (
 
   return baseSource<UrlParameters>('tileset', options, urlParameters).then(
     (result) => ({
-      ...(result as TilejsonResult),
+      ...result,
       widgetSource: new WidgetTilesetSource({
         ...options,
-        tileFormat: getTileFormat(result as TilejsonResult),
+        tileFormat: getTileFormat(result),
         spatialDataColumn,
         spatialDataType: 'h3',
       }),

package/src/sources/index.ts

@@ -4,21 +4,29 @@
 
 export {SOURCE_DEFAULTS} from './base-source.js';
 export type {
-  GeojsonResult,
-  JsonResult,
+  SourceOptions,
+  SourceRequiredOptions,
+  SourceOptionalOptions,
+  TilejsonResult,
   QueryResult,
+  FilterOptions,
   QuerySourceOptions,
-  RasterBandColorinterp,
-  RasterMetadata,
-  RasterMetadataBand,
-  RasterMetadataBandStats,
-  SourceOptions,
-  SpatialFilterPolyfillMode,
   TableSourceOptions,
-  TilejsonResult,
-  TileResolution,
   TilesetSourceOptions,
+  ColumnsOption,
+  SpatialDataType,
+  SpatialFilterPolyfillMode,
+  TileResolution,
+  Tilejson,
+  Tilestats,
+  Layer,
+  Attribute,
   VectorLayer,
+  RasterMetadata,
+  RasterMetadataBand,
+  RasterMetadataBandStats,
+  RasterBandType,
+  RasterBandColorinterp,
 } from './types.js';
 
 export {boundaryQuerySource} from './boundary-query-source.js';

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

@@ -68,7 +68,7 @@ export const quadbinQuerySource = async function (
 
   return baseSource<UrlParameters>('query', options, urlParameters).then(
     (result) => ({
-      ...(result as TilejsonResult),
+      ...result,
       widgetSource: new WidgetQuerySource({
         ...options,
         // NOTE: Parameters with default values above must be explicitly passed here.

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

@@ -63,7 +63,7 @@ export const quadbinTableSource = async function (
 
   return baseSource<UrlParameters>('table', options, urlParameters).then(
     (result) => ({
-      ...(result as TilejsonResult),
+      ...result,
       widgetSource: new WidgetTableSource({
         ...options,
         // NOTE: Parameters with default values above must be explicitly passed here.

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

@@ -28,10 +28,10 @@ export const quadbinTilesetSource = async function (
 
   return baseSource<UrlParameters>('tileset', options, urlParameters).then(
     (result) => ({
-      ...(result as TilejsonResult),
+      ...result,
       widgetSource: new WidgetTilesetSource({
         ...options,
-        tileFormat: getTileFormat(result as TilejsonResult),
+        tileFormat: getTileFormat(result),
         spatialDataColumn,
         spatialDataType: 'quadbin',
       }),

package/src/sources/raster-source.ts

@@ -37,13 +37,13 @@ export const rasterSource = async function (
 
   return baseSource<UrlParameters>('raster', options, urlParameters).then(
     (result) => ({
-      ...(result as TilejsonResult),
+      ...result,
       widgetSource: new WidgetRasterSource({
         ...options,
-        tileFormat: getTileFormat(result as TilejsonResult),
+        tileFormat: getTileFormat(result),
         spatialDataColumn: 'quadbin',
         spatialDataType: 'quadbin',
-        rasterMetadata: (result as TilejsonResult).raster_metadata!,
+        rasterMetadata: result.raster_metadata!,
       }),
     })
   ) as Promise<RasterSourceResponse>;

package/src/sources/types.ts

@@ -2,9 +2,8 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {Feature} from 'geojson';
-import {Filters, Format, QueryParameters} from '../types.js';
-import {MapInstantiation} from '../types-internal.js';
+import {Filters, QueryParameters} from '../types.js';
+import {SchemaField} from '../types-internal.js';
 
 export type SourceRequiredOptions = {
   /** Carto platform access token. */
@@ -38,8 +37,6 @@ export type SourceOptionalOptions = {
   cache?: {value?: number};
 
   clientId: string;
-  /** @deprecated  use `query` instead **/
-  format: Format;
 
   /**
    * Maximum URL character length. Above this limit, requests use POST.
@@ -213,7 +210,10 @@ export type SpatialDataType = 'geo' | 'h3' | 'quadbin';
  * */
 export type SpatialFilterPolyfillMode = 'center' | 'intersects' | 'contains';
 
-export type TilejsonMapInstantiation = MapInstantiation & {
+export type TilejsonMapInstantiation = {
+  nrows: number;
+  size?: number;
+  schema: SchemaField[];
   tilejson: {url: string[]};
 };
 
@@ -415,8 +415,6 @@ export type RasterMetadata = {
 };
 
 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>[];

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

@@ -76,7 +76,7 @@ export const vectorQuerySource = async function (
 
   return baseSource<UrlParameters>('query', options, urlParameters).then(
     (result) => ({
-      ...(result as TilejsonResult),
+      ...result,
       widgetSource: new WidgetQuerySource({
         ...options,
         // NOTE: Parameters with default values above must be explicitly passed here.

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

@@ -71,7 +71,7 @@ export const vectorTableSource = async function (
 
   return baseSource<UrlParameters>('table', options, urlParameters).then(
     (result) => ({
-      ...(result as TilejsonResult),
+      ...result,
       widgetSource: new WidgetTableSource({
         ...options,
         // NOTE: Parameters with default values above must be explicitly passed here.

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

@@ -29,10 +29,10 @@ export const vectorTilesetSource = async function (
 
   return baseSource<UrlParameters>('tileset', options, urlParameters).then(
     (result) => ({
-      ...(result as TilejsonResult),
+      ...result,
       widgetSource: new WidgetTilesetSource({
         ...options,
-        tileFormat: getTileFormat(result as TilejsonResult),
+        tileFormat: getTileFormat(result),
         spatialDataColumn,
         spatialDataType: 'geo',
       }),

package/src/types-internal.ts

@@ -2,8 +2,6 @@
  * COMMON
  */
 
-import {Format} from './types.js';
-
 /** @internal */
 export type $TODO = any;
 
@@ -39,28 +37,6 @@ export interface SchemaField {
   type: SchemaFieldType; // Field type in the CARTO stack, common for all providers
 }
 
-/**
- * @privateRemarks Source: @deck.gl/carto
- * @internal
- */
-export interface MapInstantiation extends MapInstantiationFormats {
-  nrows: number;
-  size?: number;
-  schema: SchemaField[];
-}
-
-/**
- * @privateRemarks Source: @deck.gl/carto
- * @internal
- */
-type MapInstantiationFormats = Record<
-  Format,
-  {
-    url: string[];
-    error?: any;
-  }
->;
-
 /******************************************************************************
  * LOCAL CALCULATIONS
  */

package/src/utils.ts

@@ -1,38 +1,3 @@
-import {Filter} from './types.js';
-import {FilterType} from './constants.js';
-
-const FILTER_TYPES = new Set(Object.values(FilterType));
-const isFilterType = (type: string): type is FilterType =>
-  FILTER_TYPES.has(type as FilterType);
-
-/**
- * @privateRemarks Source: @carto/react-widgets
- * @internal
- */
-export function getApplicableFilters(
-  owner?: string,
-  filters?: Record<string, Filter>
-): Record<string, Filter> {
-  if (!filters) return {};
-
-  const applicableFilters: Record<string, Filter> = {};
-
-  for (const column in filters) {
-    for (const type in filters[column]) {
-      if (!isFilterType(type)) continue;
-
-      const filter = filters[column][type];
-      const isApplicable = !owner || !filter?.owner || filter?.owner !== owner;
-      if (filter && isApplicable) {
-        applicableFilters[column] ||= {};
-        (applicableFilters[column][type] as typeof filter) = filter;
-      }
-    }
-  }
-
-  return applicableFilters;
-}
-
 type Row<T> = Record<string, T> | Record<string, T>[] | T[] | T;
 
 /**

package/src/widget-sources/types.ts

@@ -117,9 +117,9 @@ export interface TableRequestOptions extends BaseRequestOptions {
   sortByColumnType?: SortColumnType;
   offset?: number;
   limit?: number;
-  /** Local only. */
+  /** @deprecated Supported for tilesets only. Prefer `filters` (for all sources) instead. */
   searchFilterColumn?: string;
-  /** Local only. */
+  /** @deprecated Supported for tilesets only. Prefer `filters` (for all sources) instead. */
   searchFilterText?: string;
 }
 

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

@@ -17,11 +17,12 @@ import {
   TimeSeriesRequestOptions,
   TimeSeriesResponse,
 } from './types.js';
-import {getApplicableFilters, normalizeObjectKeys} from '../utils.js';
+import {normalizeObjectKeys} from '../utils.js';
 import {DEFAULT_TILE_RESOLUTION} from '../constants-internal.js';
 import {WidgetSource, WidgetSourceProps} from './widget-source.js';
 import {Filters} from '../types.js';
 import {ApiVersion} from '../constants.js';
+import {getApplicableFilters} from '../filters.js';
 
 export type WidgetRemoteSourceProps = WidgetSourceProps;
 

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

@@ -16,12 +16,7 @@ import {
   TimeSeriesRequestOptions,
   TimeSeriesResponse,
 } from './types.js';
-import {
-  InvalidColumnError,
-  assert,
-  assignOptional,
-  getApplicableFilters,
-} from '../utils.js';
+import {InvalidColumnError, assert, assignOptional} from '../utils.js';
 import {Filter, SpatialFilter, Tile} from '../types.js';
 import {
   TileFeatureExtractOptions,
@@ -42,6 +37,7 @@ import {FeatureCollection} from 'geojson';
 import {WidgetSource} from './widget-source.js';
 import {booleanEqual} from '@turf/boolean-equal';
 import type {WidgetTilesetSourceProps} from './widget-tileset-source.js';
+import {getApplicableFilters} from '../filters.js';
 
 // TODO(cleanup): Parameter defaults in source functions and widget API calls are
 // currently duplicated and possibly inconsistent. Consider consolidating and
@@ -271,7 +267,11 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
     }
 
     // Search.
+    // TODO(v0.6): Remove "searchFilterText" and "searchFilterColumn".
     if (searchFilterColumn && searchFilterText) {
+      console.warn(
+        'WidgetTilesetSource: "searchFilterText" is deprecated, use "filters" and FilterType.STRING_SEARCH instead.'
+      );
       filteredFeatures = filteredFeatures.filter(
         (row) =>
           row[searchFilterColumn] &&