@carto/api-client 0.4.6 → 0.4.7-alpha.0

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

@@ -2,8 +2,8 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {baseSource} from './base-source';
-import type {FilterOptions, SourceOptions, TilejsonResult} from './types';
+import {baseSource} from './base-source.js';
+import type {FilterOptions, SourceOptions, TilejsonResult} from './types.js';
 
 export type BoundaryTableSourceOptions = SourceOptions &
   FilterOptions & {

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

@@ -2,10 +2,12 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-/* eslint-disable camelcase */
-import {DEFAULT_AGGREGATION_RES_LEVEL_H3} from '../constants-internal';
-import {WidgetQuerySource, WidgetQuerySourceResult} from '../widget-sources';
-import {baseSource} from './base-source';
+import {DEFAULT_AGGREGATION_RES_LEVEL_H3} from '../constants-internal.js';
+import {
+  WidgetQuerySource,
+  WidgetQuerySourceResult,
+} from '../widget-sources/index.js';
+import {baseSource} from './base-source.js';
 import type {
   AggregationOptions,
   FilterOptions,
@@ -13,7 +15,7 @@ import type {
   SourceOptions,
   SpatialDataType,
   TilejsonResult,
-} from './types';
+} from './types.js';
 
 export type H3QuerySourceOptions = SourceOptions &
   QuerySourceOptions &

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

@@ -2,10 +2,12 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-/* eslint-disable camelcase */
-import {DEFAULT_AGGREGATION_RES_LEVEL_H3} from '../constants-internal';
-import {WidgetTableSource, WidgetTableSourceResult} from '../widget-sources';
-import {baseSource} from './base-source';
+import {DEFAULT_AGGREGATION_RES_LEVEL_H3} from '../constants-internal.js';
+import {
+  WidgetTableSource,
+  WidgetTableSourceResult,
+} from '../widget-sources/index.js';
+import {baseSource} from './base-source.js';
 import type {
   AggregationOptions,
   FilterOptions,
@@ -13,7 +15,7 @@ import type {
   SpatialDataType,
   TableSourceOptions,
   TilejsonResult,
-} from './types';
+} from './types.js';
 
 export type H3TableSourceOptions = SourceOptions &
   TableSourceOptions &

package/src/sources/h3-tileset-source.ts

@@ -2,12 +2,12 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {baseSource} from './base-source';
+import {baseSource} from './base-source.js';
 import type {
   SourceOptions,
   TilejsonResult,
   TilesetSourceOptions,
-} from './types';
+} from './types.js';
 
 export type H3TilesetSourceOptions = SourceOptions & TilesetSourceOptions;
 type UrlParameters = {name: string};

package/src/sources/index.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-export {SOURCE_DEFAULTS} from './base-source';
+export {SOURCE_DEFAULTS} from './base-source.js';
 export type {
   GeojsonResult,
   JsonResult,
@@ -19,73 +19,73 @@ export type {
   TileResolution,
   TilesetSourceOptions,
   VectorLayer,
-} from './types';
+} from './types.js';
 
-export {boundaryQuerySource} from './boundary-query-source';
+export {boundaryQuerySource} from './boundary-query-source.js';
 export type {
   BoundaryQuerySourceOptions,
   BoundaryQuerySourceResponse,
-} from './boundary-query-source';
+} from './boundary-query-source.js';
 
-export {boundaryTableSource} from './boundary-table-source';
+export {boundaryTableSource} from './boundary-table-source.js';
 export type {
   BoundaryTableSourceOptions,
   BoundaryTableSourceResponse,
-} from './boundary-table-source';
+} from './boundary-table-source.js';
 
-export {h3QuerySource} from './h3-query-source';
+export {h3QuerySource} from './h3-query-source.js';
 export type {
   H3QuerySourceOptions,
   H3QuerySourceResponse,
-} from './h3-query-source';
+} from './h3-query-source.js';
 
-export {h3TableSource} from './h3-table-source';
+export {h3TableSource} from './h3-table-source.js';
 export type {
   H3TableSourceOptions,
   H3TableSourceResponse,
-} from './h3-table-source';
+} from './h3-table-source.js';
 
-export {h3TilesetSource} from './h3-tileset-source';
+export {h3TilesetSource} from './h3-tileset-source.js';
 export type {
   H3TilesetSourceOptions,
   H3TilesetSourceResponse,
-} from './h3-tileset-source';
+} from './h3-tileset-source.js';
 
-export {rasterSource} from './raster-source';
-export type {RasterSourceOptions, RasterSourceResponse} from './raster-source';
+export {rasterSource} from './raster-source.js';
+export type {RasterSourceOptions} from './raster-source.js';
 
-export {quadbinQuerySource} from './quadbin-query-source';
+export {quadbinQuerySource} from './quadbin-query-source.js';
 export type {
   QuadbinQuerySourceOptions,
   QuadbinQuerySourceResponse,
-} from './quadbin-query-source';
+} from './quadbin-query-source.js';
 
-export {quadbinTableSource} from './quadbin-table-source';
+export {quadbinTableSource} from './quadbin-table-source.js';
 export type {
   QuadbinTableSourceOptions,
   QuadbinTableSourceResponse,
-} from './quadbin-table-source';
+} from './quadbin-table-source.js';
 
-export {quadbinTilesetSource} from './quadbin-tileset-source';
+export {quadbinTilesetSource} from './quadbin-tileset-source.js';
 export type {
   QuadbinTilesetSourceOptions,
   QuadbinTilesetSourceResponse,
-} from './quadbin-tileset-source';
+} from './quadbin-tileset-source.js';
 
-export {vectorQuerySource} from './vector-query-source';
+export {vectorQuerySource} from './vector-query-source.js';
 export type {
   VectorQuerySourceOptions,
   VectorQuerySourceResponse,
-} from './vector-query-source';
+} from './vector-query-source.js';
 
-export {vectorTableSource} from './vector-table-source';
+export {vectorTableSource} from './vector-table-source.js';
 export type {
   VectorTableSourceOptions,
   VectorTableSourceResponse,
-} from './vector-table-source';
+} from './vector-table-source.js';
 
-export {vectorTilesetSource} from './vector-tileset-source';
+export {vectorTilesetSource} from './vector-tileset-source.js';
 export type {
   VectorTilesetSourceOptions,
   VectorTilesetSourceResponse,
-} from './vector-tileset-source';
+} from './vector-tileset-source.js';

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

@@ -2,10 +2,12 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-/* eslint-disable camelcase */
-import {DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN} from '../constants-internal';
-import {WidgetQuerySource, WidgetQuerySourceResult} from '../widget-sources';
-import {baseSource} from './base-source';
+import {DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN} from '../constants-internal.js';
+import {
+  WidgetQuerySource,
+  WidgetQuerySourceResult,
+} from '../widget-sources/index.js';
+import {baseSource} from './base-source.js';
 import type {
   AggregationOptions,
   FilterOptions,
@@ -13,7 +15,7 @@ import type {
   SourceOptions,
   SpatialDataType,
   TilejsonResult,
-} from './types';
+} from './types.js';
 
 export type QuadbinQuerySourceOptions = SourceOptions &
   QuerySourceOptions &

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

@@ -2,10 +2,12 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-/* eslint-disable camelcase */
-import {DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN} from '../constants-internal';
-import {WidgetTableSource, WidgetTableSourceResult} from '../widget-sources';
-import {baseSource} from './base-source';
+import {DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN} from '../constants-internal.js';
+import {
+  WidgetTableSource,
+  WidgetTableSourceResult,
+} from '../widget-sources/index.js';
+import {baseSource} from './base-source.js';
 import type {
   AggregationOptions,
   FilterOptions,
@@ -13,7 +15,7 @@ import type {
   SpatialDataType,
   TableSourceOptions,
   TilejsonResult,
-} from './types';
+} from './types.js';
 
 export type QuadbinTableSourceOptions = SourceOptions &
   TableSourceOptions &

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

@@ -2,12 +2,12 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {baseSource} from './base-source';
+import {baseSource} from './base-source.js';
 import type {
   SourceOptions,
   TilejsonResult,
   TilesetSourceOptions,
-} from './types';
+} from './types.js';
 
 export type QuadbinTilesetSourceOptions = SourceOptions & TilesetSourceOptions;
 type UrlParameters = {name: string};

package/src/sources/raster-source.ts

@@ -2,13 +2,13 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {baseSource} from './base-source';
+import {baseSource} from './base-source.js';
 import type {
   FilterOptions,
   SourceOptions,
   TilejsonResult,
   TilesetSourceOptions,
-} from './types';
+} from './types.js';
 
 export type RasterSourceOptions = SourceOptions &
   TilesetSourceOptions &
@@ -28,6 +28,7 @@ export const rasterSource = async function (
   if (filters) {
     urlParameters.filters = filters;
   }
+
   return baseSource<UrlParameters>(
     'raster',
     options,

package/src/sources/types.ts

@@ -3,8 +3,8 @@
 // Copyright (c) vis.gl contributors
 
 import type {Feature} from 'geojson';
-import {Filters, Format, QueryParameters} from '../types';
-import {MapInstantiation} from '../types-internal';
+import {Filters, Format, QueryParameters} from '../types.js';
+import {MapInstantiation} from '../types-internal.js';
 
 export type SourceRequiredOptions = {
   /** Carto platform access token. */
@@ -208,7 +208,7 @@ export type SpatialDataType = 'geo' | 'h3' | 'quadbin';
  * Strategy used for covering spatial filter geometry with spatial indexes.
  * See https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/quadbin#quadbin_polyfill_mode
  * or https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/h3#h3_polyfill_mode for more information.
- * @internalRemarks Source: cloud-native maps-api
+ * @privateRemarks Source: cloud-native maps-api
  * */
 export type SpatialFilterPolyfillMode = 'center' | 'intersects' | 'contains';
 

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

@@ -2,13 +2,15 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-/* eslint-disable camelcase */
-import {DEFAULT_TILE_RESOLUTION} from '../constants-internal.js';
+import {
+  DEFAULT_GEO_COLUMN,
+  DEFAULT_TILE_RESOLUTION,
+} from '../constants-internal.js';
 import {
   WidgetQuerySource,
   WidgetQuerySourceResult,
 } from '../widget-sources/index.js';
-import {baseSource} from './base-source';
+import {baseSource} from './base-source.js';
 import type {
   FilterOptions,
   SourceOptions,
@@ -16,7 +18,7 @@ import type {
   SpatialDataType,
   TilejsonResult,
   ColumnsOption,
-} from './types';
+} from './types.js';
 
 export type VectorQuerySourceOptions = SourceOptions &
   QuerySourceOptions &
@@ -43,7 +45,7 @@ export const vectorQuerySource = async function (
   const {
     columns,
     filters,
-    spatialDataColumn = 'geom',
+    spatialDataColumn = DEFAULT_GEO_COLUMN,
     sqlQuery,
     tileResolution = DEFAULT_TILE_RESOLUTION,
     queryParameters,

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

@@ -2,13 +2,15 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-/* eslint-disable camelcase */
-import {DEFAULT_TILE_RESOLUTION} from '../constants-internal.js';
+import {
+  DEFAULT_GEO_COLUMN,
+  DEFAULT_TILE_RESOLUTION,
+} from '../constants-internal.js';
 import {
   WidgetTableSource,
   WidgetTableSourceResult,
 } from '../widget-sources/index.js';
-import {baseSource} from './base-source';
+import {baseSource} from './base-source.js';
 import type {
   FilterOptions,
   ColumnsOption,
@@ -16,7 +18,7 @@ import type {
   SpatialDataType,
   TableSourceOptions,
   TilejsonResult,
-} from './types';
+} from './types.js';
 
 export type VectorTableSourceOptions = SourceOptions &
   TableSourceOptions &
@@ -42,7 +44,7 @@ export const vectorTableSource = async function (
   const {
     columns,
     filters,
-    spatialDataColumn = 'geom',
+    spatialDataColumn = DEFAULT_GEO_COLUMN,
     tableName,
     tileResolution = DEFAULT_TILE_RESOLUTION,
     aggregationExp,

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

@@ -2,12 +2,12 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {baseSource} from './base-source';
+import {baseSource} from './base-source.js';
 import type {
   SourceOptions,
   TilesetSourceOptions,
   TilejsonResult,
-} from './types';
+} from './types.js';
 
 export type VectorTilesetSourceOptions = SourceOptions & TilesetSourceOptions;
 type UrlParameters = {name: string};

package/src/spatial-index.ts

@@ -1,11 +1,10 @@
 import {
   DEFAULT_AGGREGATION_RES_LEVEL_H3,
   DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN,
-} from './constants-internal';
-import type {ModelSource} from './models/model';
-import type {AggregationOptions} from './sources/types';
-import {assert} from './utils';
-import type {ViewState} from './widget-sources';
+} from './constants-internal.js';
+import type {ModelSource} from './models/model.js';
+import type {AggregationOptions} from './sources/types.js';
+import type {ViewState} from './widget-sources/index.js';
 
 const DEFAULT_TILE_SIZE = 512;
 const QUADBIN_ZOOM_MAX_OFFSET = 4;

package/src/types-internal.ts

@@ -2,7 +2,7 @@
  * COMMON
  */
 
-import {Format} from './types';
+import {Format} from './types.js';
 
 /** @internal */
 export type $TODO = any;
@@ -15,7 +15,7 @@ export type $IntentionalAny = any;
  */
 
 /**
- * @internalRemarks Source: @deck.gl/carto
+ * @privateRemarks Source: @deck.gl/carto
  * @internal
  */
 export enum SchemaFieldType {
@@ -31,7 +31,7 @@ export enum SchemaFieldType {
 }
 
 /**
- * @internalRemarks Source: @deck.gl/carto
+ * @privateRemarks Source: @deck.gl/carto
  * @internal
  */
 export interface SchemaField {
@@ -40,7 +40,7 @@ export interface SchemaField {
 }
 
 /**
- * @internalRemarks Source: @deck.gl/carto
+ * @privateRemarks Source: @deck.gl/carto
  * @internal
  */
 export interface MapInstantiation extends MapInstantiationFormats {
@@ -50,7 +50,7 @@ export interface MapInstantiation extends MapInstantiationFormats {
 }
 
 /**
- * @internalRemarks Source: @deck.gl/carto
+ * @privateRemarks Source: @deck.gl/carto
  * @internal
  */
 type MapInstantiationFormats = Record<
@@ -60,3 +60,9 @@ type MapInstantiationFormats = Record<
     error?: any;
   }
 >;
+
+/******************************************************************************
+ * LOCAL CALCULATIONS
+ */
+
+export type FeatureData = Record<string, unknown>;

package/src/types.ts

@@ -1,16 +1,54 @@
 import type {FilterType} from './constants.js';
-import type {Polygon, MultiPolygon} from 'geojson';
+import type {Polygon, MultiPolygon, Feature} from 'geojson';
+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';
 
+/**
+ * Alias for GeoJSON 'BBox' type, semantically representing a viewport.
+ * Order of values is "west", "south", "east", "north".
+ */
+export type Viewport = [number, number, number, number];
+
+/**
+ * Subset of deck.gl's Tile2DHeader type, containing only the properties
+ * 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.
+ * @privateRemarks Source: @deck.gl/geo-layers
+ */
+export type Tile = {
+  index: {x: number; y: number; z: number};
+  id: string;
+  content: unknown;
+  zoom: number;
+  bbox: {west: number; east: number; north: number; south: number};
+  isVisible: boolean;
+  data?: BinaryFeatureCollection;
+};
+
+/** Subset of deck.gl's Tile2DHeader type, for spatial indexes. */
+export type SpatialIndexTile = Tile & {
+  data?: (Feature & {id: bigint})[];
+};
+
+/** @privateRemarks Source: @deck.gl/carto */
+export type Raster = {
+  blockSize: number;
+  cells: {
+    numericProps: BinaryFeature['numericProps'];
+    properties: BinaryFeature['properties'];
+  };
+};
+
 /******************************************************************************
  * AGGREGATION
  */
@@ -18,8 +56,8 @@ export type MapType = 'boundary' | 'query' | 'table' | 'tileset' | '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'
@@ -33,15 +71,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. */
@@ -49,12 +87,32 @@ export interface Filter {
   /** [a, b) a is included, b is not. */
   [FilterType.CLOSED_OPEN]?: {owner?: string; values: number[][]};
   [FilterType.TIME]?: {owner?: string; values: number[][]};
-  [FilterType.STRING_SEARCH]?: {owner?: string; values: string[]};
+  [FilterType.STRING_SEARCH]?: {
+    owner?: string;
+    values: string[];
+    params?: StringSearchOptions;
+  };
 }
 
-/** @internalRemarks Source: @carto/react-core */
+/** @privateRemarks Source: @carto/react-core */
 export type FilterLogicalOperator = 'and' | 'or';
 
+/**
+ * Type for minimum or maximum value of an interval. Values 'null' and
+ * 'undefined' are intentionally allowed, and represent an unbounded value.
+ */
+export type FilterIntervalExtremum = number | null | undefined;
+export type FilterInterval = [FilterIntervalExtremum, FilterIntervalExtremum];
+export type FilterIntervalComplete = [number, number];
+
+export type StringSearchOptions = {
+  useRegExp?: boolean;
+  mustStart?: boolean;
+  mustEnd?: boolean;
+  caseSensitive?: boolean;
+  keepSpecialCharacters?: boolean;
+};
+
 /******************************************************************************
  * GROUPING
  */
@@ -62,7 +120,7 @@ export type FilterLogicalOperator = 'and' | 'or';
 /**
  * Defines a step size increment for use with {@link TimeSeriesRequestOptions}.
  *
- * @internalRemarks Source: @carto/react-core
+ * @privateRemarks Source: @carto/react-core
  */
 export type GroupDateType =
   | 'year'
@@ -84,7 +142,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
@@ -92,11 +150,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/dateUtils.ts

@@ -0,0 +1,28 @@
+/**
+ * Returns midnight (local time) on the Monday preceeding a given date, in
+ * milliseconds since the UNIX epoch.
+ */
+export function getMonday(date: number | Date): number {
+  const dateCp = new Date(date);
+  const day = dateCp.getDay();
+  const diff = dateCp.getDate() - day + (day ? 1 : -6); // adjust when day is sunday
+  dateCp.setDate(diff);
+  dateCp.setHours(0, 0, 0, 0);
+  return dateCp.getTime();
+}
+
+/**
+ * Returns midnight (UTC) on the Monday preceeding a given date, in
+ * milliseconds since the UNIX epoch.
+ */
+export function getUTCMonday(date: number | Date): number {
+  const dateCp = new Date(date);
+  const day = dateCp.getUTCDay();
+  const diff = dateCp.getUTCDate() - day + (day ? 1 : -6); // adjust when day is sunday
+  dateCp.setUTCDate(diff);
+  return Date.UTC(
+    dateCp.getUTCFullYear(),
+    dateCp.getUTCMonth(),
+    dateCp.getUTCDate()
+  );
+}

package/src/utils/getTileFormat.ts

@@ -0,0 +1,9 @@
+import {TileFormat} from '../constants.js';
+import {Tilejson} from '../sources/types.js';
+
+export function getTileFormat(tilejson: Tilejson): TileFormat {
+  const tileParams = new URL(tilejson.tiles[0]).searchParams;
+  return tileParams.get('formatTiles') === 'mvt'
+    ? TileFormat.MVT
+    : TileFormat.BINARY;
+}