@carto/api-client 0.4.0-alpha.0 → 0.4.0-alpha.3

package/src/sources/index.ts

@@ -3,7 +3,12 @@
 // Copyright (c) vis.gl contributors
 
 export {SOURCE_DEFAULTS} from './base-source';
-export type {TilejsonResult, GeojsonResult, JsonResult} from './types';
+export type {
+  TilejsonResult,
+  GeojsonResult,
+  JsonResult,
+  QueryResult,
+} from './types';
 
 export {boundaryQuerySource} from './boundary-query-source';
 export type {BoundaryQuerySourceOptions} from './boundary-query-source';

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

@@ -3,7 +3,8 @@
 // Copyright (c) vis.gl contributors
 
 /* eslint-disable camelcase */
-import {DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN} from '../constants';
+import {DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN} from '../constants-internal';
+import {WidgetQuerySource, WidgetQuerySourceResult} from '../widget-sources';
 import {baseSource} from './base-source';
 import type {
   AggregationOptions,
@@ -31,7 +32,7 @@ type UrlParameters = {
 
 export const quadbinQuerySource = async function (
   options: QuadbinQuerySourceOptions
-): Promise<TilejsonResult> {
+): Promise<TilejsonResult & WidgetQuerySourceResult> {
   const {
     aggregationExp,
     aggregationResLevel = DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN,
@@ -56,9 +57,10 @@ export const quadbinQuerySource = async function (
   if (filters) {
     urlParameters.filters = filters;
   }
-  return baseSource<UrlParameters>(
-    'query',
-    options,
-    urlParameters
-  ) as Promise<TilejsonResult>;
+  return baseSource<UrlParameters>('query', options, urlParameters).then(
+    (result) => ({
+      ...(result as TilejsonResult),
+      widgetSource: new WidgetQuerySource(options),
+    })
+  );
 };

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

@@ -3,7 +3,8 @@
 // Copyright (c) vis.gl contributors
 
 /* eslint-disable camelcase */
-import {DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN} from '../constants';
+import {DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN} from '../constants-internal';
+import {WidgetTableSource, WidgetTableSourceResult} from '../widget-sources';
 import {baseSource} from './base-source';
 import type {
   AggregationOptions,
@@ -30,7 +31,7 @@ type UrlParameters = {
 
 export const quadbinTableSource = async function (
   options: QuadbinTableSourceOptions
-): Promise<TilejsonResult> {
+): Promise<TilejsonResult & WidgetTableSourceResult> {
   const {
     aggregationExp,
     aggregationResLevel = DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN,
@@ -52,9 +53,10 @@ export const quadbinTableSource = async function (
   if (filters) {
     urlParameters.filters = filters;
   }
-  return baseSource<UrlParameters>(
-    'table',
-    options,
-    urlParameters
-  ) as Promise<TilejsonResult>;
+  return baseSource<UrlParameters>('table', options, urlParameters).then(
+    (result) => ({
+      ...(result as TilejsonResult),
+      widgetSource: new WidgetTableSource(options),
+    })
+  );
 };

package/src/sources/types.ts

@@ -3,12 +3,8 @@
 // Copyright (c) vis.gl contributors
 
 import type {Feature} from 'geojson';
-import type {
-  Filters,
-  Format,
-  MapInstantiation,
-  QueryParameters,
-} from '../api/types';
+import {Filters, Format, QueryParameters} from '../types';
+import {MapInstantiation} from '../types-internal';
 
 export type SourceRequiredOptions = {
   /** Carto platform access token. */

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

@@ -3,7 +3,11 @@
 // Copyright (c) vis.gl contributors
 
 /* eslint-disable camelcase */
-import {DEFAULT_TILE_RESOLUTION} from '../constants';
+import {DEFAULT_TILE_RESOLUTION} from '../constants.js';
+import {
+  WidgetQuerySource,
+  WidgetQuerySourceResult,
+} from '../widget-sources/index.js';
 import {baseSource} from './base-source';
 import type {
   FilterOptions,
@@ -31,7 +35,7 @@ type UrlParameters = {
 
 export const vectorQuerySource = async function (
   options: VectorQuerySourceOptions
-): Promise<TilejsonResult> {
+): Promise<TilejsonResult & WidgetQuerySourceResult> {
   const {
     columns,
     filters,
@@ -57,9 +61,10 @@ export const vectorQuerySource = async function (
   if (queryParameters) {
     urlParameters.queryParameters = queryParameters;
   }
-  return baseSource<UrlParameters>(
-    'query',
-    options,
-    urlParameters
-  ) as Promise<TilejsonResult>;
+  return baseSource<UrlParameters>('query', options, urlParameters).then(
+    (result) => ({
+      ...(result as TilejsonResult),
+      widgetSource: new WidgetQuerySource(options),
+    })
+  );
 };

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

@@ -3,7 +3,11 @@
 // Copyright (c) vis.gl contributors
 
 /* eslint-disable camelcase */
-import {DEFAULT_TILE_RESOLUTION} from '../constants';
+import {DEFAULT_TILE_RESOLUTION} from '../constants.js';
+import {
+  WidgetTableSource,
+  WidgetTableSourceResult,
+} from '../widget-sources/index.js';
 import {baseSource} from './base-source';
 import type {
   FilterOptions,
@@ -29,7 +33,7 @@ type UrlParameters = {
 
 export const vectorTableSource = async function (
   options: VectorTableSourceOptions
-): Promise<TilejsonResult> {
+): Promise<TilejsonResult & WidgetTableSourceResult> {
   const {
     columns,
     filters,
@@ -51,9 +55,10 @@ export const vectorTableSource = async function (
   if (filters) {
     urlParameters.filters = filters;
   }
-  return baseSource<UrlParameters>(
-    'table',
-    options,
-    urlParameters
-  ) as Promise<TilejsonResult>;
+  return baseSource<UrlParameters>('table', options, urlParameters).then(
+    (result) => ({
+      ...(result as TilejsonResult),
+      widgetSource: new WidgetTableSource(options),
+    })
+  );
 };

package/src/types-internal.ts

@@ -1,9 +1,62 @@
 /******************************************************************************
- * INTERNAL
+ * COMMON
  */
 
+import {Format} from './types';
+
 /** @internal */
 export type $TODO = any;
 
 /** @internal */
 export type $IntentionalAny = any;
+
+/******************************************************************************
+ * MAP INSTANTIATION
+ */
+
+/**
+ * @internalRemarks Source: @deck.gl/carto
+ * @internal
+ */
+export enum SchemaFieldType {
+  Number = 'number',
+  Bigint = 'bigint',
+  String = 'string',
+  Geometry = 'geometry',
+  Timestamp = 'timestamp',
+  Object = 'object',
+  Boolean = 'boolean',
+  Variant = 'variant',
+  Unknown = 'unknown',
+}
+
+/**
+ * @internalRemarks Source: @deck.gl/carto
+ * @internal
+ */
+export interface SchemaField {
+  name: string;
+  type: SchemaFieldType; // Field type in the CARTO stack, common for all providers
+}
+
+/**
+ * @internalRemarks Source: @deck.gl/carto
+ * @internal
+ */
+export interface MapInstantiation extends MapInstantiationFormats {
+  nrows: number;
+  size?: number;
+  schema: SchemaField[];
+}
+
+/**
+ * @internalRemarks Source: @deck.gl/carto
+ * @internal
+ */
+type MapInstantiationFormats = Record<
+  Format,
+  {
+    url: string[];
+    error?: any;
+  }
+>;

package/src/types.ts

@@ -1,6 +1,16 @@
 import type {FilterType} from './constants.js';
 import type {Polygon, MultiPolygon} from 'geojson';
 
+/******************************************************************************
+ * MAPS AND TILES
+ */
+
+/** @internalRemarks Source: @deck.gl/carto */
+export type Format = 'json' | 'geojson' | 'tilejson';
+
+/** @internalRemarks Source: @carto/constants, @deck.gl/carto */
+export type MapType = 'boundary' | 'query' | 'table' | 'tileset' | 'raster';
+
 /******************************************************************************
  * AGGREGATION
  */
@@ -26,6 +36,12 @@ export type AggregationType =
 /** @internalRemarks Source: @carto/react-api */
 export type SpatialFilter = Polygon | MultiPolygon;
 
+/** @internalRemarks Source: @deck.gl/carto */
+export interface Filters {
+  [column: string]: Filter;
+}
+
+// TODO: Would `{[FilterType.IN]?: number[] | string[]}` also be valid?
 /** @internalRemarks Source: @carto/react-api, @deck.gl/carto */
 export interface Filter {
   [FilterType.IN]?: {owner?: string; values: number[] | string[]};

package/src/widget-sources/index.ts

@@ -1,5 +1,4 @@
 export * from './widget-base-source.js';
 export * from './widget-query-source.js';
 export * from './widget-table-source.js';
-export * from './wrappers.js';
 export * from './types.js';

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

@@ -17,14 +17,14 @@ import {
 } from './types.js';
 import {FilterLogicalOperator, Filter} from '../types.js';
 import {getApplicableFilters, normalizeObjectKeys} from '../utils.js';
-import {
-  DEFAULT_API_BASE_URL,
-  DEFAULT_GEO_COLUMN,
-  ApiVersion,
-} from '../constants-internal.js';
 import {getClient} from '../client.js';
 import {ModelSource} from '../models/model.js';
 import {SourceOptions} from '../sources/index.js';
+import {
+  ApiVersion,
+  DEFAULT_API_BASE_URL,
+  DEFAULT_GEO_COLUMN,
+} from '../constants.js';
 
 export interface WidgetBaseSourceProps extends Omit<SourceOptions, 'filters'> {
   apiVersion?: ApiVersion;

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

@@ -3,7 +3,6 @@ import {
   QuadbinQuerySourceOptions,
   VectorQuerySourceOptions,
 } from '../sources/index.js';
-import {MapType} from '../constants-internal.js';
 import {WidgetBaseSource, WidgetBaseSourceProps} from './widget-base-source.js';
 import {ModelSource} from '../models/model.js';
 
@@ -12,6 +11,8 @@ type LayerQuerySourceOptions =
   | Omit<H3QuerySourceOptions, 'filters'>
   | Omit<QuadbinQuerySourceOptions, 'filters'>;
 
+export type WidgetQuerySourceResult = {widgetSource: WidgetQuerySource};
+
 /**
  * Source for Widget API requests on a data source defined by a SQL query.
  *
@@ -40,7 +41,7 @@ export class WidgetQuerySource extends WidgetBaseSource<
   protected override getModelSource(owner: string): ModelSource {
     return {
       ...super._getModelSource(owner),
-      type: MapType.QUERY,
+      type: 'query',
       data: this.props.sqlQuery,
       queryParameters: this.props.queryParameters,
     };

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

@@ -4,7 +4,6 @@ import {
   VectorTableSourceOptions,
 } from '../sources/index.js';
 import {WidgetBaseSource, WidgetBaseSourceProps} from './widget-base-source.js';
-import {MapType} from '../constants-internal.js';
 import {ModelSource} from '../models/model.js';
 
 type LayerTableSourceOptions =
@@ -12,6 +11,8 @@ type LayerTableSourceOptions =
   | Omit<H3TableSourceOptions, 'filters'>
   | Omit<QuadbinTableSourceOptions, 'filters'>;
 
+export type WidgetTableSourceResult = {widgetSource: WidgetTableSource};
+
 /**
  * Source for Widget API requests on a data source defined as a table.
  *
@@ -40,7 +41,7 @@ export class WidgetTableSource extends WidgetBaseSource<
   protected override getModelSource(owner: string): ModelSource {
     return {
       ...super._getModelSource(owner),
-      type: MapType.TABLE,
+      type: 'table',
       data: this.props.tableName,
     };
   }

package/build/api/types.d.ts

@@ -1,227 +0,0 @@
-export type Format = 'json' | 'geojson' | 'tilejson';
-export type MapType = 'boundary' | 'query' | 'table' | 'tileset' | 'raster';
-export type RequestType = 'Map data' | 'Map instantiation' | 'Public map' | 'Tile stats' | 'SQL' | 'Basemap style';
-export type ScaleType = 'linear' | 'ordinal' | 'log' | 'point' | 'quantile' | 'quantize' | 'sqrt' | 'custom' | 'identity';
-export type APIErrorContext = {
-    requestType: RequestType;
-    mapId?: string;
-    connection?: string;
-    source?: string;
-    type?: MapType;
-};
-export declare enum SchemaFieldType {
-    Number = "number",
-    Bigint = "bigint",
-    String = "string",
-    Geometry = "geometry",
-    Timestamp = "timestamp",
-    Object = "object",
-    Boolean = "boolean",
-    Variant = "variant",
-    Unknown = "unknown"
-}
-export interface SchemaField {
-    name: string;
-    type: SchemaFieldType;
-}
-export interface MapInstantiation extends MapInstantiationFormats {
-    nrows: number;
-    size?: number;
-    schema: SchemaField[];
-}
-type MapInstantiationFormats = Record<Format, {
-    url: string[];
-    error?: any;
-}>;
-export type QueryParameterValue = string | number | boolean | Array<QueryParameterValue> | object;
-export type NamedQueryParameter = Record<string, QueryParameterValue>;
-export type PositionalQueryParameter = QueryParameterValue[];
-export type QueryParameters = NamedQueryParameter | PositionalQueryParameter;
-export type VisualChannelField = {
-    name: string;
-    type: string;
-    colorColumn?: string;
-};
-export interface Filters {
-    [column: string]: Filter;
-}
-interface Filter {
-    [FilterTypes.In]?: number[];
-    [FilterTypes.Between]?: number[][];
-    [FilterTypes.ClosedOpen]?: number[][];
-    [FilterTypes.Time]?: number[][];
-    [FilterTypes.StringSearch]?: string[];
-}
-export declare enum FilterTypes {
-    In = "in",
-    Between = "between",// [a, b] both are included
-    ClosedOpen = "closed_open",// [a, b) a is included, b is not
-    Time = "time",
-    StringSearch = "stringSearch"
-}
-export type VisualChannels = {
-    colorField?: VisualChannelField;
-    colorScale?: ScaleType;
-    customMarkersField?: VisualChannelField;
-    customMarkersScale?: ScaleType;
-    radiusField?: VisualChannelField;
-    radiusScale?: ScaleType;
-    rotationScale?: ScaleType;
-    rotationField?: VisualChannelField;
-    sizeField?: VisualChannelField;
-    sizeScale?: ScaleType;
-    strokeColorField?: VisualChannelField;
-    strokeColorScale?: ScaleType;
-    heightField?: VisualChannelField;
-    heightScale?: ScaleType;
-    weightField?: VisualChannelField;
-};
-export type ColorRange = {
-    category: string;
-    colors: string[];
-    colorMap: string[][] | undefined;
-    name: string;
-    type: string;
-};
-export type CustomMarkersRange = {
-    markerMap: {
-        value: string;
-        markerUrl?: string;
-    }[];
-    othersMarker?: string;
-};
-export type VisConfig = {
-    filled?: boolean;
-    opacity?: number;
-    enable3d?: boolean;
-    colorAggregation?: any;
-    colorRange: ColorRange;
-    customMarkers?: boolean;
-    customMarkersRange?: CustomMarkersRange | null;
-    customMarkersUrl?: string | null;
-    radius: number;
-    radiusRange?: number[];
-    sizeAggregation?: any;
-    sizeRange?: any;
-    strokeColorAggregation?: any;
-    strokeOpacity?: number;
-    strokeColorRange?: ColorRange;
-    heightRange?: any;
-    heightAggregation?: any;
-    weightAggregation?: any;
-};
-export type TextLabel = {
-    field: VisualChannelField | null | undefined;
-    alignment?: 'center' | 'bottom' | 'top';
-    anchor?: 'middle' | 'start' | 'end';
-    size: number;
-    color?: number[];
-    offset?: [number, number];
-    outlineColor?: number[];
-};
-export type MapLayerConfig = {
-    columns?: Record<string, any>;
-    color?: number[];
-    label?: string;
-    dataId: string;
-    textLabel: TextLabel[];
-    visConfig: VisConfig;
-};
-export type MapTextSubLayerConfig = Omit<MapLayerConfig, 'textLabel'> & {
-    textLabel?: TextLabel;
-};
-export type MapConfigLayer = {
-    type: string;
-    id: string;
-    config: MapLayerConfig;
-    visualChannels: VisualChannels;
-};
-export type MapDataset = {
-    id: string;
-    data: any;
-    aggregationExp: string | null;
-    aggregationResLevel: number | null;
-    geoColumn: string;
-};
-export interface CustomStyle {
-    url?: string;
-    style?: any;
-    customAttribution?: string;
-}
-export type KeplerMapConfig = {
-    mapState: any;
-    mapStyle: {
-        styleType: string;
-        visibleLayerGroups: Record<string, boolean>;
-    };
-    visState: {
-        layers: MapConfigLayer[];
-    };
-    layerBlending: any;
-    interactionConfig: any;
-    customBaseMaps?: {
-        customStyle?: CustomStyle;
-    };
-};
-export type BasemapType = 'maplibre' | 'google-maps';
-export type Basemap = MapLibreBasemap | GoogleBasemap;
-export type BasemapCommon = {
-    /**
-     * Type of basemap.
-     */
-    type: BasemapType;
-    /**
-     * Custom attribution for style data if not provided by style definition.
-     */
-    attribution?: string;
-    /**
-     * Properties of the basemap. These properties are specific to the basemap type.
-     */
-    props: Record<string, any>;
-};
-export type MapLibreBasemap = BasemapCommon & {
-    type: 'maplibre';
-    /**
-     * MapLibre map properties.
-     *
-     * Meant to be passed to directly to `maplibregl.Map` object.
-     */
-    props: MapLibreBasemapProps;
-    /**
-     * Layer groups to be displayed in the basemap.
-     */
-    visibleLayerGroups?: Record<string, boolean>;
-    /**
-     * If `style` has been filtered by `visibleLayerGroups` then this property contains original style object, so user
-     * can use `applyLayerGroupFilters` again with new settings.
-     */
-    rawStyle?: string | Record<string, any>;
-};
-export type MapLibreBasemapProps = {
-    style: string | Record<string, any>;
-    center: [number, number];
-    zoom: number;
-    pitch?: number;
-    bearing?: number;
-};
-export type GoogleBasemap = BasemapCommon & {
-    type: 'google-maps';
-    /**
-     * Google map properties.
-     *
-     * Meant to be passed to directly to `google.maps.Map` object.
-     */
-    props: GoogleBasemapProps;
-};
-export type GoogleBasemapProps = {
-    mapTypeId: string;
-    mapId?: string;
-    center?: {
-        lat: number;
-        lng: number;
-    };
-    zoom?: number;
-    tilt?: number;
-    heading?: number;
-};
-export {};

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

@@ -1,48 +0,0 @@
-import { h3TableSource as _h3TableSource, h3QuerySource as _h3QuerySource, vectorTableSource as _vectorTableSource, vectorQuerySource as _vectorQuerySource, quadbinTableSource as _quadbinTableSource, quadbinQuerySource as _quadbinQuerySource, VectorTableSourceOptions as _VectorTableSourceOptions, VectorQuerySourceOptions as _VectorQuerySourceOptions, H3TableSourceOptions as _H3TableSourceOptions, H3QuerySourceOptions as _H3QuerySourceOptions, QuadbinTableSourceOptions as _QuadbinTableSourceOptions, QuadbinQuerySourceOptions as _QuadbinQuerySourceOptions } from '../sources/index.js';
-import { WidgetBaseSourceProps } from './widget-base-source.js';
-import { WidgetQuerySource } from './widget-query-source.js';
-import { WidgetTableSource } from './widget-table-source.js';
-type WrappedSourceOptions<T> = Omit<T, 'filters'> & WidgetBaseSourceProps;
-/******************************************************************************
- * RESPONSE OBJECTS
- */
-type WidgetTableSourceResponse = {
-    widgetSource: WidgetTableSource;
-};
-type WidgetQuerySourceResponse = {
-    widgetSource: WidgetQuerySource;
-};
-export type VectorTableSourceResponse = WidgetTableSourceResponse & Awaited<ReturnType<typeof _vectorTableSource>>;
-export type VectorQuerySourceResponse = WidgetQuerySourceResponse & Awaited<ReturnType<typeof _vectorQuerySource>>;
-export type H3TableSourceResponse = WidgetTableSourceResponse & Awaited<ReturnType<typeof _h3TableSource>>;
-export type H3QuerySourceResponse = WidgetQuerySourceResponse & Awaited<ReturnType<typeof _h3QuerySource>>;
-export type QuadbinTableSourceResponse = WidgetTableSourceResponse & Awaited<ReturnType<typeof _quadbinTableSource>>;
-export type QuadbinQuerySourceResponse = WidgetQuerySourceResponse & Awaited<ReturnType<typeof _quadbinQuerySource>>;
-/******************************************************************************
- * VECTOR SOURCES
- */
-export type VectorTableSourceOptions = WrappedSourceOptions<_VectorTableSourceOptions>;
-export type VectorQuerySourceOptions = WrappedSourceOptions<_VectorQuerySourceOptions>;
-/** Wrapper adding Widget API support to [vectorTableSource](https://deck.gl/docs/api-reference/carto/data-sources). */
-export declare function vectorTableSource(props: VectorTableSourceOptions): Promise<VectorTableSourceResponse>;
-/** Wrapper adding Widget API support to [vectorQuerySource](https://deck.gl/docs/api-reference/carto/data-sources). */
-export declare function vectorQuerySource(props: VectorQuerySourceOptions): Promise<VectorQuerySourceResponse>;
-/******************************************************************************
- * H3 SOURCES
- */
-export type H3TableSourceOptions = WrappedSourceOptions<_H3TableSourceOptions>;
-export type H3QuerySourceOptions = WrappedSourceOptions<_H3QuerySourceOptions>;
-/** Wrapper adding Widget API support to [h3TableSource](https://deck.gl/docs/api-reference/carto/data-sources). */
-export declare function h3TableSource(props: H3TableSourceOptions): Promise<H3TableSourceResponse>;
-/** Wrapper adding Widget API support to [h3QuerySource](https://deck.gl/docs/api-reference/carto/data-sources). */
-export declare function h3QuerySource(props: H3QuerySourceOptions): Promise<H3QuerySourceResponse>;
-/******************************************************************************
- * QUADBIN SOURCES
- */
-export type QuadbinTableSourceOptions = WrappedSourceOptions<_QuadbinTableSourceOptions>;
-export type QuadbinQuerySourceOptions = WrappedSourceOptions<_QuadbinQuerySourceOptions>;
-/** Wrapper adding Widget API support to [quadbinTableSource](https://deck.gl/docs/api-reference/carto/data-sources). */
-export declare function quadbinTableSource(props: QuadbinTableSourceOptions & WidgetBaseSourceProps): Promise<QuadbinTableSourceResponse>;
-/** Wrapper adding Widget API support to [quadbinQuerySource](https://deck.gl/docs/api-reference/carto/data-sources). */
-export declare function quadbinQuerySource(props: QuadbinQuerySourceOptions & WidgetBaseSourceProps): Promise<QuadbinQuerySourceResponse>;
-export {};