@carto/api-client 0.5.0-alpha.2 → 0.5.0-alpha.4

package/src/types.ts

@@ -6,10 +6,10 @@ import type {BinaryFeature, BinaryFeatureCollection} from '@loaders.gl/schema';
  * MAPS AND TILES
  */
 
-/** @internalRemarks Source: @deck.gl/carto */
+/** @privateRemarks Source: @deck.gl/carto */
 export type Format = 'json' | 'geojson' | 'tilejson';
 
-/** @internalRemarks Source: @carto/constants, @deck.gl/carto */
+/** @privateRemarks Source: @carto/constants, @deck.gl/carto */
 export type MapType = 'boundary' | 'query' | 'table' | 'tileset' | 'raster';
 
 /**
@@ -23,7 +23,7 @@ export type Viewport = [number, number, number, number];
  * 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
+ * @privateRemarks Source: @deck.gl/geo-layers
  */
 export type Tile = {
   index: {x: number; y: number; z: number};
@@ -40,7 +40,13 @@ export type SpatialIndexTile = Tile & {
   data?: (Feature & {id: bigint})[];
 };
 
-/** @internalRemarks Source: @deck.gl/carto */
+export type RasterTile = Tile & {
+  id: string;
+  index: {q: bigint; i: string};
+  data?: Raster;
+};
+
+/** @privateRemarks Source: @deck.gl/carto */
 export type Raster = {
   blockSize: number;
   cells: {
@@ -56,8 +62,8 @@ export type Raster = {
 /**
  * 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.
+ * @privateRemarks Source: @carto/constants
+ * @privateRemarks Converted from enum to type union, for improved declarative API.
  */
 export type AggregationType =
   | 'count'
@@ -71,15 +77,15 @@ export type AggregationType =
  * FILTERS
  */
 
-/** @internalRemarks Source: @carto/react-api */
+/** @privateRemarks Source: @carto/react-api */
 export type SpatialFilter = Polygon | MultiPolygon;
 
-/** @internalRemarks Source: @deck.gl/carto */
+/** @privateRemarks Source: @deck.gl/carto */
 export interface Filters {
   [column: string]: Filter;
 }
 
-/** @internalRemarks Source: @carto/react-api, @deck.gl/carto */
+/** @privateRemarks Source: @carto/react-api, @deck.gl/carto */
 export interface Filter {
   [FilterType.IN]?: {owner?: string; values: number[] | string[]};
   /** [a, b] both are included. */
@@ -94,7 +100,7 @@ export interface Filter {
   };
 }
 
-/** @internalRemarks Source: @carto/react-core */
+/** @privateRemarks Source: @carto/react-core */
 export type FilterLogicalOperator = 'and' | 'or';
 
 /**
@@ -120,7 +126,7 @@ export type StringSearchOptions = {
 /**
  * Defines a step size increment for use with {@link TimeSeriesRequestOptions}.
  *
- * @internalRemarks Source: @carto/react-core
+ * @privateRemarks Source: @carto/react-core
  */
 export type GroupDateType =
   | 'year'
@@ -142,7 +148,7 @@ export type SortColumnType = 'number' | 'string' | 'date';
  * SQL QUERY PARAMETERS
  */
 
-/** @internalRemarks Source: @deck.gl/carto */
+/** @privateRemarks Source: @deck.gl/carto */
 export type QueryParameterValue =
   | string
   | number
@@ -150,11 +156,11 @@ export type QueryParameterValue =
   | Array<QueryParameterValue>
   | object;
 
-/** @internalRemarks Source: @deck.gl/carto */
+/** @privateRemarks Source: @deck.gl/carto */
 export type NamedQueryParameter = Record<string, QueryParameterValue>;
 
-/** @internalRemarks Source: @deck.gl/carto */
+/** @privateRemarks Source: @deck.gl/carto */
 export type PositionalQueryParameter = QueryParameterValue[];
 
-/** @internalRemarks Source: @deck.gl/carto */
+/** @privateRemarks Source: @deck.gl/carto */
 export type QueryParameters = NamedQueryParameter | PositionalQueryParameter;

package/src/utils/makeIntervalComplete.ts

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

package/src/utils.ts

@@ -39,7 +39,7 @@ 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
+ * @privateRemarks Source: @carto/react-widgets
  * @internal
  */
 export function normalizeObjectKeys<T, R extends Row<T>>(el: R): R {
@@ -59,7 +59,7 @@ export function normalizeObjectKeys<T, R extends Row<T>>(el: R): R {
   ) as R;
 }
 
-/** @internalRemarks Source: @carto/react-core */
+/** @privateRemarks Source: @carto/react-core */
 export function assert(condition: unknown, message: string): asserts condition {
   if (!condition) {
     throw new Error(message);
@@ -67,7 +67,7 @@ export function assert(condition: unknown, message: string): asserts condition {
 }
 
 /**
- * @internalRemarks Source: @carto/react-core
+ * @privateRemarks Source: @carto/react-core
  * @internal
  */
 export class InvalidColumnError extends Error {

package/src/widget-sources/index.ts

@@ -1,5 +1,6 @@
 export * from './widget-source.js';
 export * from './widget-query-source.js';
+export * from './widget-raster-source.js';
 export * from './widget-remote-source.js';
 export * from './widget-table-source.js';
 export * from './widget-tileset-source.js';

package/src/widget-sources/types.ts

@@ -1,11 +1,11 @@
-import {SpatialFilterPolyfillMode, TileResolution} from '../sources/types';
+import {SpatialFilterPolyfillMode, TileResolution} from '../sources/types.js';
 import {
+  Filters,
   GroupDateType,
   SortColumnType,
   SortDirection,
   SpatialFilter,
-} from '../types';
-import type {WidgetRemoteSource} from './widget-remote-source';
+} from '../types.js';
 
 /******************************************************************************
  * WIDGET API REQUESTS
@@ -24,6 +24,8 @@ interface BaseRequestOptions {
   /** Required for table- and query-based spatial index sources (H3, Quadbin). */
   spatialIndexReferenceViewState?: ViewState;
   abortController?: AbortController;
+  /** Overrides source filters, if any. */
+  filters?: Filters;
   filterOwner?: string;
 }
 

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

@@ -8,6 +8,7 @@ import {
   WidgetRemoteSourceProps,
 } from './widget-remote-source.js';
 import {ModelSource} from '../models/model.js';
+import {Filters} from '../types.js';
 
 type LayerQuerySourceOptions =
   | Omit<VectorQuerySourceOptions, 'filters'>
@@ -41,9 +42,12 @@ export type WidgetQuerySourceResult = {widgetSource: WidgetQuerySource};
 export class WidgetQuerySource extends WidgetRemoteSource<
   LayerQuerySourceOptions & WidgetRemoteSourceProps
 > {
-  protected override getModelSource(owner: string): ModelSource {
+  protected override getModelSource(
+    filters: Filters | undefined,
+    filterOwner?: string
+  ): ModelSource {
     return {
-      ...super._getModelSource(owner),
+      ...super._getModelSource(filters, filterOwner),
       type: 'query',
       data: this.props.sqlQuery,
       queryParameters: this.props.queryParameters,

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

@@ -0,0 +1,14 @@
+import {RasterMetadata} from '../sources/index.js';
+import {
+  WidgetTilesetSource,
+  WidgetTilesetSourceProps,
+} from './widget-tileset-source.js';
+
+export type WidgetRasterSourceProps = WidgetTilesetSourceProps & {
+  rasterMetadata: RasterMetadata;
+  spatialDataType: 'quadbin';
+};
+
+export type WidgetRasterSourceResult = {widgetSource: WidgetRasterSource};
+
+export class WidgetRasterSource extends WidgetTilesetSource<WidgetRasterSourceProps> {}

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

@@ -31,10 +31,18 @@ export type WidgetRemoteSourceProps = WidgetSourceProps;
 export abstract class WidgetRemoteSource<
   Props extends WidgetRemoteSourceProps,
 > extends WidgetSource<Props> {
+  protected _headers: Record<string, string> = {};
+
+  /** Assigns HTTP headers to be included on API requests from this source. */
+  setRequestHeaders(headers: Record<string, string>): void {
+    this._headers = headers;
+  }
+
   async getCategories(
     options: CategoryRequestOptions
   ): Promise<CategoryResponse> {
     const {
+      filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
@@ -43,7 +51,7 @@ export abstract class WidgetRemoteSource<
       ...params
     } = options;
     const {column, operation, operationColumn} = params;
-    const source = this.getModelSource(filterOwner);
+    const source = this.getModelSource(filters, filterOwner);
     const spatialFiltersResolution = this._getSpatialFiltersResolution(
       source,
       spatialFilter,
@@ -65,7 +73,7 @@ export abstract class WidgetRemoteSource<
         operation,
         operationColumn: operationColumn || column,
       },
-      opts: {abortController},
+      opts: {abortController, headers: this._headers},
     }).then((res: CategoriesModelResponse) => normalizeObjectKeys(res.rows));
   }
 
@@ -73,6 +81,7 @@ export abstract class WidgetRemoteSource<
     options: FeaturesRequestOptions
   ): Promise<FeaturesResponse> {
     const {
+      filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
@@ -81,7 +90,7 @@ export abstract class WidgetRemoteSource<
       ...params
     } = options;
     const {columns, dataType, featureIds, z, limit, tileResolution} = params;
-    const source = this.getModelSource(filterOwner);
+    const source = this.getModelSource(filters, filterOwner);
     const spatialFiltersResolution = this._getSpatialFiltersResolution(
       source,
       spatialFilter,
@@ -106,13 +115,14 @@ export abstract class WidgetRemoteSource<
         limit: limit || 1000,
         tileResolution: tileResolution || DEFAULT_TILE_RESOLUTION,
       },
-      opts: {abortController},
+      opts: {abortController, headers: this._headers},
       // Avoid `normalizeObjectKeys()`, which changes column names.
     }).then(({rows}: FeaturesModelResponse) => ({rows}));
   }
 
   async getFormula(options: FormulaRequestOptions): Promise<FormulaResponse> {
     const {
+      filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
@@ -122,7 +132,7 @@ export abstract class WidgetRemoteSource<
       ...params
     } = options;
     const {column, operation} = params;
-    const source = this.getModelSource(filterOwner);
+    const source = this.getModelSource(filters, filterOwner);
     const spatialFiltersResolution = this._getSpatialFiltersResolution(
       source,
       spatialFilter,
@@ -144,7 +154,7 @@ export abstract class WidgetRemoteSource<
         operation: operation ?? 'count',
         operationExp,
       },
-      opts: {abortController},
+      opts: {abortController, headers: this._headers},
     }).then((res: FormulaModelResponse) => normalizeObjectKeys(res.rows[0]));
   }
 
@@ -152,6 +162,7 @@ export abstract class WidgetRemoteSource<
     options: HistogramRequestOptions
   ): Promise<HistogramResponse> {
     const {
+      filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
@@ -160,7 +171,7 @@ export abstract class WidgetRemoteSource<
       ...params
     } = options;
     const {column, operation, ticks} = params;
-    const source = this.getModelSource(filterOwner);
+    const source = this.getModelSource(filters, filterOwner);
     const spatialFiltersResolution = this._getSpatialFiltersResolution(
       source,
       spatialFilter,
@@ -178,7 +189,7 @@ export abstract class WidgetRemoteSource<
         spatialFilter,
       },
       params: {column, operation, ticks},
-      opts: {abortController},
+      opts: {abortController, headers: this._headers},
     }).then((res: HistogramModelResponse) => normalizeObjectKeys(res.rows));
 
     if (data.length) {
@@ -196,6 +207,7 @@ export abstract class WidgetRemoteSource<
 
   async getRange(options: RangeRequestOptions): Promise<RangeResponse> {
     const {
+      filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
@@ -204,7 +216,7 @@ export abstract class WidgetRemoteSource<
       ...params
     } = options;
     const {column} = params;
-    const source = this.getModelSource(filterOwner);
+    const source = this.getModelSource(filters, filterOwner);
     const spatialFiltersResolution = this._getSpatialFiltersResolution(
       source,
       spatialFilter,
@@ -222,12 +234,13 @@ export abstract class WidgetRemoteSource<
         spatialFilter,
       },
       params: {column},
-      opts: {abortController},
+      opts: {abortController, headers: this._headers},
     }).then((res: RangeModelResponse) => normalizeObjectKeys(res.rows[0]));
   }
 
   async getScatter(options: ScatterRequestOptions): Promise<ScatterResponse> {
     const {
+      filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
@@ -238,7 +251,7 @@ export abstract class WidgetRemoteSource<
     const {xAxisColumn, xAxisJoinOperation, yAxisColumn, yAxisJoinOperation} =
       params;
 
-    const source = this.getModelSource(filterOwner);
+    const source = this.getModelSource(filters, filterOwner);
     const spatialFiltersResolution = this._getSpatialFiltersResolution(
       source,
       spatialFilter,
@@ -265,7 +278,7 @@ export abstract class WidgetRemoteSource<
         yAxisJoinOperation,
         limit: HARD_LIMIT,
       },
-      opts: {abortController},
+      opts: {abortController, headers: this._headers},
     })
       .then((res: ScatterModelResponse) => normalizeObjectKeys(res.rows))
       .then((res) => res.map(({x, y}: {x: number; y: number}) => [x, y]));
@@ -273,6 +286,7 @@ export abstract class WidgetRemoteSource<
 
   async getTable(options: TableRequestOptions): Promise<TableResponse> {
     const {
+      filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
@@ -281,7 +295,7 @@ export abstract class WidgetRemoteSource<
       ...params
     } = options;
     const {columns, sortBy, sortDirection, offset = 0, limit = 10} = params;
-    const source = this.getModelSource(filterOwner);
+    const source = this.getModelSource(filters, filterOwner);
     const spatialFiltersResolution = this._getSpatialFiltersResolution(
       source,
       spatialFilter,
@@ -308,7 +322,7 @@ export abstract class WidgetRemoteSource<
         limit,
         offset,
       },
-      opts: {abortController},
+      opts: {abortController, headers: this._headers},
     }).then((res: TableModelResponse) => ({
       // Avoid `normalizeObjectKeys()`, which changes column names.
       rows: res.rows ?? (res as any).ROWS,
@@ -320,6 +334,7 @@ export abstract class WidgetRemoteSource<
     options: TimeSeriesRequestOptions
   ): Promise<TimeSeriesResponse> {
     const {
+      filters = this.props.filters,
       filterOwner,
       abortController,
       spatialFilter,
@@ -339,7 +354,7 @@ export abstract class WidgetRemoteSource<
       splitByCategoryValues,
     } = params;
 
-    const source = this.getModelSource(filterOwner);
+    const source = this.getModelSource(filters, filterOwner);
     const spatialFiltersResolution = this._getSpatialFiltersResolution(
       source,
       spatialFilter,
@@ -370,7 +385,7 @@ export abstract class WidgetRemoteSource<
         splitByCategoryLimit,
         splitByCategoryValues,
       },
-      opts: {abortController},
+      opts: {abortController, headers: this._headers},
     }).then((res: TimeSeriesModelResponse) => ({
       rows: normalizeObjectKeys(res.rows),
       categories: res.metadata?.categories,

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

@@ -17,7 +17,12 @@ import {
   TimeSeriesResponse,
   ViewState,
 } from './types.js';
-import {FilterLogicalOperator, Filter, SpatialFilter} from '../types.js';
+import {
+  FilterLogicalOperator,
+  Filter,
+  SpatialFilter,
+  Filters,
+} from '../types.js';
 import {getApplicableFilters} from '../utils.js';
 import {getClient} from '../client.js';
 import {ModelSource} from '../models/model.js';
@@ -58,10 +63,14 @@ export abstract class WidgetSource<Props extends WidgetSourceProps> {
    * properties, and adding additional required properties including 'type' and
    * 'data'.
    */
-  protected abstract getModelSource(owner: string | undefined): ModelSource;
+  protected abstract getModelSource(
+    filters: Filters | undefined,
+    filterOwner?: string
+  ): ModelSource;
 
   protected _getModelSource(
-    owner?: string
+    filters: Filters | undefined,
+    filterOwner?: string
   ): Omit<ModelSource, 'type' | 'data'> {
     const props = this.props;
     return {
@@ -70,7 +79,7 @@ export abstract class WidgetSource<Props extends WidgetSourceProps> {
       clientId: props.clientId as string,
       accessToken: props.accessToken,
       connectionName: props.connectionName,
-      filters: getApplicableFilters(owner, props.filters),
+      filters: getApplicableFilters(filterOwner, filters || props.filters),
       filtersLogicalOperator: props.filtersLogicalOperator,
       spatialDataType: props.spatialDataType,
       spatialDataColumn: props.spatialDataColumn,

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

@@ -8,6 +8,7 @@ import {
   WidgetRemoteSourceProps,
 } from './widget-remote-source.js';
 import {ModelSource} from '../models/model.js';
+import {Filters} from '../types.js';
 
 type LayerTableSourceOptions =
   | Omit<VectorTableSourceOptions, 'filters'>
@@ -41,9 +42,12 @@ export type WidgetTableSourceResult = {widgetSource: WidgetTableSource};
 export class WidgetTableSource extends WidgetRemoteSource<
   LayerTableSourceOptions & WidgetRemoteSourceProps
 > {
-  protected override getModelSource(owner: string): ModelSource {
+  protected override getModelSource(
+    filters: Filters | undefined,
+    filterOwner?: string
+  ): ModelSource {
     return {
-      ...super._getModelSource(owner),
+      ...super._getModelSource(filters, filterOwner),
       type: 'table',
       data: this.props.tableName,
     };