@carto/api-client 0.5.1-alpha.1 → 0.5.1

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.1",
+  "version": "0.5.1",
   "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",
@@ -127,6 +127,5 @@
   "resolutions": {
     "@carto/api-client": "portal:./",
     "rollup": "^4.20.0"
-  },
-  "stableVersion": "0.5.0"
+  }
 }

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/tileFeatures.ts

@@ -23,6 +23,8 @@ export type TileFeatures = {
 /** @privateRemarks Source: @carto/react-core */
 export type TileFeatureExtractOptions = {
   storeGeometry?: boolean;
+  spatialDataType?: SpatialDataType;
+  spatialDataColumn?: string;
   uniqueIdProperty?: string;
 };
 

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

@@ -100,3 +100,30 @@ export const isObject: (x: unknown) => boolean = (x) =>
 /** @internal */
 export const isPureObject: (x: any) => boolean = (x) =>
   isObject(x) && x.constructor === {}.constructor;
+
+/**
+ * Merges one or more source objects into a target object. Unlike `Object.assign`, does not
+ * assign properties with undefined values. Null values will overwrite existing properties.
+ */
+export function assignOptional<T extends object, U, V>(
+  target: T,
+  source1: U,
+  source2: V
+): T & U & V;
+export function assignOptional<T extends object, U>(
+  target: T,
+  source: U
+): T & U;
+export function assignOptional<T extends object, U>(
+  target: T,
+  ...sources: any[]
+): any {
+  for (const source of sources) {
+    for (const key in source) {
+      if (source[key] !== undefined) {
+        (target as Record<string, unknown>)[key] = source[key];
+      }
+    }
+  }
+  return target as T & U;
+}

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-tileset-source-impl.ts

@@ -16,7 +16,12 @@ import {
   TimeSeriesRequestOptions,
   TimeSeriesResponse,
 } from './types.js';
-import {InvalidColumnError, assert, getApplicableFilters} from '../utils.js';
+import {
+  InvalidColumnError,
+  assert,
+  assignOptional,
+  getApplicableFilters,
+} from '../utils.js';
 import {Filter, SpatialFilter, Tile} from '../types.js';
 import {
   TileFeatureExtractOptions,
@@ -84,8 +89,7 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
     }
 
     this._features = tileFeatures({
-      ...this.props,
-      ...this._tileFeatureExtractOptions,
+      ...assignOptional({}, this.props, this._tileFeatureExtractOptions),
       tiles: this._tiles,
       spatialFilter,
     });
@@ -267,7 +271,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] &&