@carto/api-client 0.4.0-alpha.5 → 0.4.0

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

@@ -1,3 +1,4 @@
+import { TileResolution } from '../sources/types';
 import { GroupDateType, SortColumnType, SortDirection, SpatialFilter } from '../types';
 /******************************************************************************
  * WIDGET API REQUESTS
@@ -14,6 +15,43 @@ export interface CategoryRequestOptions extends BaseRequestOptions {
     operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
     operationColumn?: string;
 }
+/**
+ * Options for {@link WidgetBaseSource#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 WidgetBaseSource#getFormula}. */
 export interface FormulaRequestOptions extends BaseRequestOptions {
     column: string;
@@ -61,6 +99,14 @@ export interface TimeSeriesRequestOptions extends BaseRequestOptions {
 /******************************************************************************
  * WIDGET API RESPONSES
  */
+/**
+ * Response from {@link WidgetBaseSource#getFeatures}.
+ * @experimental
+ * @internal
+ */
+export type FeaturesResponse = {
+    rows: Record<string, unknown>[];
+};
 /** Response from {@link WidgetBaseSource#getFormula}. */
 export type FormulaResponse = {
     value: number;

package/build/widget-sources/widget-base-source.d.ts

@@ -1,4 +1,4 @@
-import { CategoryRequestOptions, CategoryResponse, FormulaRequestOptions, FormulaResponse, HistogramRequestOptions, HistogramResponse, RangeRequestOptions, RangeResponse, ScatterRequestOptions, ScatterResponse, TableRequestOptions, TableResponse, TimeSeriesRequestOptions, TimeSeriesResponse } from './types.js';
+import { CategoryRequestOptions, CategoryResponse, FeaturesRequestOptions, FeaturesResponse, FormulaRequestOptions, FormulaResponse, HistogramRequestOptions, HistogramResponse, RangeRequestOptions, RangeResponse, ScatterRequestOptions, ScatterResponse, TableRequestOptions, TableResponse, TimeSeriesRequestOptions, TimeSeriesResponse } from './types.js';
 import { FilterLogicalOperator, Filter } from '../types.js';
 import { ModelSource } from '../models/model.js';
 import { SourceOptions } from '../sources/index.js';
@@ -35,6 +35,18 @@ export declare abstract class WidgetBaseSource<Props extends WidgetBaseSourcePro
      * charts including grouped bar charts, pie charts, and tree charts.
      */
     getCategories(options: CategoryRequestOptions): Promise<CategoryResponse>;
+    /****************************************************************************
+     * FEATURES
+     */
+    /**
+     * 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
+     */
+    getFeatures(options: FeaturesRequestOptions): Promise<FeaturesResponse>;
     /****************************************************************************
      * FORMULA
      */

package/package.json

@@ -4,7 +4,7 @@
   "repository": "github:CartoDB/carto-api-client",
   "author": "Don McCurdy <donmccurdy@carto.com>",
   "packageManager": "yarn@4.3.1",
-  "version": "0.4.0-alpha.5",
+  "version": "0.4.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -34,7 +34,7 @@
     "dev": "concurrently \"yarn build:watch\" \"vite --config examples/vite.config.ts --open\"",
     "test": "vitest run --typecheck",
     "test:watch": "vitest watch --typecheck",
-    "coverage": "vitest run --coverage",
+    "coverage": "vitest run --coverage.enabled --coverage.all false",
     "lint": "prettier \"**/*.{cjs,html,js,json,md,ts}\" --ignore-path ./.eslintignore --check",
     "format": "prettier \"**/*.{cjs,html,js,json,md,ts}\" --ignore-path ./.eslintignore --write",
     "clean": "rimraf build/*",
@@ -98,6 +98,5 @@
     "vite": "^5.2.10",
     "vitest": "1.6.0",
     "vue": "^3.4.27"
-  },
-  "stableVersion": "0.3.1"
+  }
 }

package/src/models/model.ts

@@ -16,6 +16,7 @@ const AVAILABLE_MODELS = [
   'category',
   'histogram',
   'formula',
+  'pick',
   'timeseries',
   'range',
   'scatterplot',
@@ -74,7 +75,13 @@ export function executeModel(props: {
 
   let url = `${apiBaseUrl}/v3/sql/${connectionName}/model/${model}`;
 
-  const {filters, filtersLogicalOperator = 'and', data} = source;
+  const {
+    data,
+    filters,
+    filtersLogicalOperator = 'and',
+    geoColumn = DEFAULT_GEO_COLUMN,
+  } = source;
+
   const queryParameters = source.queryParameters
     ? JSON.stringify(source.queryParameters)
     : '';
@@ -89,12 +96,14 @@ export function executeModel(props: {
     filtersLogicalOperator,
   };
 
+  // Picking Model API requires 'spatialDataColumn'.
+  if (model === 'pick') {
+    queryParams.spatialDataColumn = geoColumn;
+  }
+
   // API supports multiple filters, we apply it only to geoColumn
   const spatialFilters = source.spatialFilter
-    ? {
-        [source.geoColumn ? source.geoColumn : DEFAULT_GEO_COLUMN]:
-          source.spatialFilter,
-      }
+    ? {[geoColumn]: source.spatialFilter}
     : undefined;
 
   if (spatialFilters) {

package/src/widget-sources/types.ts

@@ -1,3 +1,4 @@
+import {TileResolution} from '../sources/types';
 import {
   GroupDateType,
   SortColumnType,
@@ -23,6 +24,49 @@ export interface CategoryRequestOptions extends BaseRequestOptions {
   operationColumn?: string;
 }
 
+/**
+ * Options for {@link WidgetBaseSource#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 WidgetBaseSource#getFormula}. */
 export interface FormulaRequestOptions extends BaseRequestOptions {
   column: string;
@@ -77,6 +121,13 @@ export interface TimeSeriesRequestOptions extends BaseRequestOptions {
  * WIDGET API RESPONSES
  */
 
+/**
+ * Response from {@link WidgetBaseSource#getFeatures}.
+ * @experimental
+ * @internal
+ */
+export type FeaturesResponse = {rows: Record<string, unknown>[]};
+
 /** Response from {@link WidgetBaseSource#getFormula}. */
 export type FormulaResponse = {value: number};
 

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

@@ -2,6 +2,8 @@ import {executeModel} from '../models/index.js';
 import {
   CategoryRequestOptions,
   CategoryResponse,
+  FeaturesRequestOptions,
+  FeaturesResponse,
   FormulaRequestOptions,
   FormulaResponse,
   HistogramRequestOptions,
@@ -21,7 +23,10 @@ import {getClient} from '../client.js';
 import {ModelSource} from '../models/model.js';
 import {SourceOptions} from '../sources/index.js';
 import {ApiVersion, DEFAULT_API_BASE_URL} from '../constants.js';
-import {DEFAULT_GEO_COLUMN} from '../constants-internal.js';
+import {
+  DEFAULT_GEO_COLUMN,
+  DEFAULT_TILE_RESOLUTION,
+} from '../constants-internal.js';
 
 export interface WidgetBaseSourceProps extends Omit<SourceOptions, 'filters'> {
   apiVersion?: ApiVersion;
@@ -105,6 +110,43 @@ export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
     }).then((res: CategoriesModelResponse) => normalizeObjectKeys(res.rows));
   }
 
+  /****************************************************************************
+   * FEATURES
+   */
+
+  /**
+   * 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
+   */
+  async getFeatures(
+    options: FeaturesRequestOptions
+  ): Promise<FeaturesResponse> {
+    const {filterOwner, spatialFilter, abortController, ...params} = options;
+    const {columns, dataType, featureIds, z, limit, tileResolution} = params;
+
+    type FeaturesModelResponse = {rows: Record<string, unknown>[]};
+
+    return executeModel({
+      model: 'pick',
+      source: {...this.getModelSource(filterOwner), spatialFilter},
+      params: {
+        columns,
+        dataType,
+        featureIds,
+        z,
+        limit: limit || 1000,
+        tileResolution: tileResolution || DEFAULT_TILE_RESOLUTION,
+      },
+      opts: {abortController},
+    }).then((res: FeaturesModelResponse) => ({
+      rows: normalizeObjectKeys(res.rows),
+    }));
+  }
+
   /****************************************************************************
    * FORMULA
    */