carto: add typedocs to source types

Author: zbigg

modules/carto/src/sources/base-source.ts

@@ -8,7 +8,6 @@ import type {
   JsonResult,
   SourceOptionalOptions,
   SourceRequiredOptions,
-  Tilejson,
   TilejsonMapInstantiation,
   TilejsonResult
 } from './types';

modules/carto/src/sources/types.ts

@@ -2,39 +2,127 @@ import type {Feature} from 'geojson';
 import type {Format, MapInstantiation, QueryParameters} from '../api/types';
 
 export type SourceRequiredOptions = {
+  /** Carto platform access token. */
   accessToken: string;
+
+  /** Data warehouse connection name in Carto platform. */
   connectionName: string;
 };
 
 export type SourceOptionalOptions = {
+  /**
+   * Base URL of the CARTO Maps API.
+   *
+   * Example for account located in EU-west region: `https://gcp-eu-west1.api.carto.com`
+   *
+   * @default https://gcp-us-east1.api.carto.com
+   */
   apiBaseUrl: string;
+
+  /**
+   * Custom HTTP headers added to map instantiation and data requests.
+   */
+  headers: Record<string, string>;
+
+  /**
+   * Cache buster value returned by map instantiation.
+   *
+   * Carto source saves `cache` value of map instantiation response in `cache.value`, so it can be used to
+   * check if underlying map data has changed between distinct source requests.
+   */
   cache?: {value?: number};
+
   clientId: string;
   /** @deprecated  use `query` instead **/
   format: Format;
-  headers: Record<string, string>;
 };
 
 export type SourceOptions = SourceRequiredOptions & Partial<SourceOptionalOptions>;
 
 export type AggregationOptions = {
+  /**
+   * Defines the aggregation expressions that will be calculated from the resulting columns on each grid cell.
+   *
+   * Example:
+   *
+   *     sum(pop) as total_population, avg(rev) as average_revenue
+   */
   aggregationExp: string;
+
+  /**
+   * Defines the tile aggregation resolution.
+   *
+   * If not present,
+   *
+   * @default 6 for quadbin and 4 for h3 sources
+   */
   aggregationResLevel?: number;
 };
 
 export type QuerySourceOptions = {
+  /**
+   * The column name and the type of geospatial support.
+   *
+   * If not present, defaults to `'geom'` for generic queries, `'quadbin'` for Quadbin sources and `'h3'` for H3 sources.
+   */
   spatialDataColumn?: string;
+
+  /** SQL query. */
   sqlQuery: string;
+
+  /**
+   * Values for named or positional paramteres in the query.
+   *
+   *
+   * The way query parameters are determined by data ware house.
+   *
+   *  * BigQuery has named query parameters as `⁣⁣@name` and they can be specified as dictionary
+   *
+   *     ```
+   *     sqlQuery: "SELECT * FROM carto-demo-data.demo_tables.retail_stores WHERE storetype = ⁣@type AND revenue > ⁣@minRevenue"
+   *     queryParameters: { type: 'Supermarket', minRevenue: 1000000 }
+   *     ```
+   * * Snowflake supports positional parametes, in form `:1`, `:2`, etc.
+   *
+   *     ```
+   *     sqlQuery: "SELECT * FROM demo_db.public.import_retail_stores WHERE storetype = :2 AND revenue > :1
+   *     queryParameters: [100000, "Supermarket"]
+   *     ```
+   * * Postgres and Redhisft supports positional parametes, but in form `$1`, `$2`, etc.
+   *
+   *     ```
+   *     sqlQuery: "SELECT * FROM carto_demo_data.demo_tables.retail_stores WHERE storetype = $2 AND revenue > $1
+   *     queryParameters: [100000, "Supermarket"]
+   *     ```
+   */
   queryParameters?: QueryParameters;
 };
 
 export type TableSourceOptions = {
+  /**
+   * Fully qualified name of table.
+   */
+  tableName: string;
+
+  /**
+   * Columns to retrieve from the table.
+   *
+   * If not specidfied, default all columns are returned.
+   */
   columns?: string[];
+
+  /**
+   * The column name and the type of geospatial support.
+   *
+   * If not present, defaults to `'geom'` for generic tables, `'quadbin'` for Quadbin sources and `'h3'` for H3 sources.
+   */
   spatialDataColumn?: string;
-  tableName: string;
 };
 
 export type TilesetSourceOptions = {
+  /**
+   * Fully qualified name of tileset.
+   */
   tableName: string;
 };