@carto/api-client 0.5.15-alpha.raster-5 → 0.5.15

package/src/index.ts

@@ -2,13 +2,7 @@ export * from './client.js';
 export * from './constants.js';
 export * from './deck/index.js';
 export * from './fetch-map/index.js';
-export {
-  createVecExprEvaluator as _createVecExprEvaluator,
-  evaluateVecExpr as _evaluateVecExpr,
-  validateVecExprSyntax as _validateVecExprSyntax,
-  type VecExprResult as _VecExprResult,
-  ErrorCode as _ErrorCode,
-} from './fetch-map/vec-expr-evaluator.js';
+export type {LayerDescriptor, LayerType} from './fetch-map/index.js';
 export * from './filters.js';
 export * from './geo.js';
 export * from './sources/index.js';

package/src/sources/index.ts

@@ -97,3 +97,15 @@ export type {
   VectorTilesetSourceOptions,
   VectorTilesetSourceResponse,
 } from './vector-tileset-source.js';
+
+export {trajectoryQuerySource} from './trajectory-query-source.js';
+export type {
+  TrajectoryQuerySourceOptions,
+  TrajectoryQuerySourceResponse,
+} from './trajectory-query-source.js';
+
+export {trajectoryTableSource} from './trajectory-table-source.js';
+export type {
+  TrajectoryTableSourceOptions,
+  TrajectoryTableSourceResponse,
+} from './trajectory-table-source.js';

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

@@ -0,0 +1,101 @@
+import {
+  DEFAULT_GEO_COLUMN,
+  DEFAULT_TILE_RESOLUTION,
+} from '../constants-internal.js';
+import {
+  WidgetQuerySource,
+  type RangeResponse,
+  type WidgetQuerySourceResult,
+} from '../widget-sources/index.js';
+import {baseSource} from './base-source.js';
+import type {
+  SourceOptions,
+  QuerySourceOptions,
+  SpatialDataType,
+  TilejsonResult,
+  ColumnsOption,
+} from './types.js';
+
+export type TrajectoryQuerySourceOptions = SourceOptions &
+  QuerySourceOptions &
+  ColumnsOption & {
+    /** Column name containing the trajectory identifier */
+    trajectoryIdColumn: string;
+    /** Column name containing the timestamp */
+    timestampColumn: string;
+  };
+
+type UrlParameters = {
+  columns?: string;
+  spatialDataType: SpatialDataType;
+  spatialDataColumn?: string;
+  tileResolution?: string;
+  q: string;
+  queryParameters?: Record<string, unknown> | unknown[];
+  aggregationExp?: string;
+  trajectoryIdColumn: string;
+  timestampColumn: string;
+};
+
+export type TrajectoryQuerySourceResponse = TilejsonResult &
+  WidgetQuerySourceResult & {
+    timestampRange: RangeResponse;
+  };
+
+export const trajectoryQuerySource = async function (
+  options: TrajectoryQuerySourceOptions
+): Promise<TrajectoryQuerySourceResponse> {
+  const {
+    columns,
+    spatialDataColumn = DEFAULT_GEO_COLUMN,
+    sqlQuery,
+    tileResolution = DEFAULT_TILE_RESOLUTION,
+    queryParameters,
+    aggregationExp,
+    trajectoryIdColumn,
+    timestampColumn,
+  } = options;
+
+  const spatialDataType = 'trajectory';
+
+  const urlParameters: UrlParameters = {
+    spatialDataColumn,
+    spatialDataType,
+    tileResolution: tileResolution.toString(),
+    q: sqlQuery,
+    trajectoryIdColumn,
+    timestampColumn,
+  };
+
+  if (columns) {
+    urlParameters.columns = columns.join(',');
+  }
+  if (queryParameters) {
+    urlParameters.queryParameters = queryParameters;
+  }
+  if (aggregationExp) {
+    urlParameters.aggregationExp = aggregationExp;
+  }
+
+  const result = await baseSource<UrlParameters>(
+    'query',
+    options,
+    urlParameters
+  );
+
+  const widgetSource = new WidgetQuerySource({
+    ...options,
+    // NOTE: Parameters with default values above must be explicitly passed here.
+    spatialDataColumn,
+    spatialDataType,
+    tileResolution,
+  });
+
+  const timestampRange = await widgetSource.getRange({column: timestampColumn});
+
+  return {
+    ...result,
+    widgetSource,
+    timestampRange,
+  };
+};

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

@@ -0,0 +1,96 @@
+import {
+  DEFAULT_GEO_COLUMN,
+  DEFAULT_TILE_RESOLUTION,
+} from '../constants-internal.js';
+import {
+  WidgetTableSource,
+  type RangeResponse,
+  type WidgetTableSourceResult,
+} from '../widget-sources/index.js';
+import {baseSource} from './base-source.js';
+import type {
+  ColumnsOption,
+  SourceOptions,
+  SpatialDataType,
+  TableSourceOptions,
+  TilejsonResult,
+} from './types.js';
+
+export type TrajectoryTableSourceOptions = SourceOptions &
+  TableSourceOptions &
+  ColumnsOption & {
+    /** Column name containing the trajectory identifier */
+    trajectoryIdColumn: string;
+    /** Column name containing the timestamp */
+    timestampColumn: string;
+  };
+
+type UrlParameters = {
+  columns?: string;
+  spatialDataType: SpatialDataType;
+  spatialDataColumn?: string;
+  tileResolution?: string;
+  name: string;
+  aggregationExp?: string;
+  trajectoryIdColumn: string;
+  timestampColumn: string;
+};
+
+export type TrajectoryTableSourceResponse = TilejsonResult &
+  WidgetTableSourceResult & {
+    timestampRange: RangeResponse;
+  };
+
+export const trajectoryTableSource = async function (
+  options: TrajectoryTableSourceOptions
+): Promise<TrajectoryTableSourceResponse> {
+  const {
+    columns,
+    spatialDataColumn = DEFAULT_GEO_COLUMN,
+    tableName,
+    tileResolution = DEFAULT_TILE_RESOLUTION,
+    aggregationExp,
+    trajectoryIdColumn,
+    timestampColumn,
+  } = options;
+
+  const spatialDataType = 'trajectory';
+
+  const urlParameters: UrlParameters = {
+    name: tableName,
+    spatialDataColumn,
+    spatialDataType,
+    tileResolution: tileResolution.toString(),
+    trajectoryIdColumn,
+    timestampColumn,
+  };
+
+  if (columns) {
+    urlParameters.columns = columns.join(',');
+  }
+  if (aggregationExp) {
+    urlParameters.aggregationExp = aggregationExp;
+  }
+
+  const result = await baseSource<UrlParameters>(
+    'table',
+    options,
+    urlParameters
+  );
+
+  const widgetSource = new WidgetTableSource({
+    ...options,
+    // NOTE: Parameters with default values above must be explicitly passed here.
+    spatialDataColumn,
+    spatialDataType,
+    tileResolution,
+  });
+
+  const timestampRange = await widgetSource.getRange({column: timestampColumn});
+
+  return {
+    ...result,
+    widgetSource,
+    timestampRange,
+  };
+};

package/src/sources/types.ts

@@ -211,7 +211,7 @@ export type ColumnsOption = {
   columns?: string[];
 };
 
-export type SpatialDataType = 'geo' | 'h3' | 'quadbin';
+export type SpatialDataType = 'geo' | 'h3' | 'quadbin' | 'trajectory';
 
 /**
  * Strategy used for covering spatial filter geometry with spatial indexes.
@@ -292,64 +292,14 @@ export interface Tilestats {
 
 export interface Layer {
   layer: string;
-  /** Number of features in the layer. */
   count: number;
-
-  /** Number of attributes in the layer. */
   attributeCount: number;
   attributes: Attribute[];
-
-  /** Type of geometry as in geojson geometry type (Point, LineString, Polygon, etc.) */
-  geometry?: string;
-}
-
-export interface AttributeCategoryItem {
-  category: string;
-  frequency: number;
-}
-
-/**
- * Quantiles by number of buckets.
- *
- * Example:
- * ```ts
- *   {
- *     // for 3 buckets, first 1/3 of items lies in range [min, 20], second 1/3 is in [20, 40], and last 1/3 is in [40, max]
- *     3: [20, 40],
- *     4: [20, 30, 50], for 4 buckets ...
- *   }
- * ```
- */
-export interface QuantileStats {
-  [bucketCount: number]: number[];
 }
 
 export interface Attribute {
-  /**
-   * String, Number, Timestamp, Boolean
-   */
-  type: string;
-
-  /**
-   * Attribute name.
-   */
   attribute: string;
-
-  // Stats for numeric attributes
-  min?: number;
-  max?: number;
-  sum?: number;
-
-  /** Quantiles by number of buckets */
-  quantiles?:
-    | {
-        // Quantile stats for numeric attributes in static spatial index tilesets are enclosed in extra global object
-        global: QuantileStats;
-      }
-    | QuantileStats;
-
-  // Stats for string/boolean attributes
-  categories?: AttributeCategoryItem[];
+  type: string;
 }
 
 export interface VectorLayer {
@@ -375,8 +325,17 @@ export type RasterMetadataBandStats = {
 
   /**
    * Quantiles by number of buckets.
+   *
+   * Example:
+   * ```ts
+   *   {
+   *     // for 3 buckets, first 1/3 of items lies in range [min, 20], second 1/3 is in [20, 40], and last 1/3 is in [40, max]
+   *     3: [20, 40],
+   *     4: [20, 30, 50], for 4 buckets ...
+   *   }
+   * ```
    */
-  quantiles?: QuantileStats;
+  quantiles?: Record<number, number[]>;
 
   /**
    * Top values by number of values.

package/src/widget-sources/types.ts

@@ -241,7 +241,10 @@ export type CategoryResponseRaw = {
 };
 
 /** Response from {@link WidgetRemoteSource#getRange}. */
-export type RangeResponse = {min: number; max: number} | null;
+export type RangeResponse =
+  | {min: number; max: number}
+  | {min: string; max: string}
+  | null;
 
 /** Response from {@link WidgetRemoteSource#getTable}. */
 export type TableResponse = {