@carto/api-client 0.4.6 → 0.4.7-0

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

@@ -0,0 +1,311 @@
+import {
+  CategoryRequestOptions,
+  CategoryResponse,
+  FeaturesResponse,
+  FormulaRequestOptions,
+  FormulaResponse,
+  HistogramRequestOptions,
+  HistogramResponse,
+  RangeRequestOptions,
+  RangeResponse,
+  ScatterRequestOptions,
+  ScatterResponse,
+  TableRequestOptions,
+  TableResponse,
+  TimeSeriesRequestOptions,
+  TimeSeriesResponse,
+} from './types.js';
+import {SpatialFilter, Tile} from '../types.js';
+import {TileFeatureExtractOptions} from '../filters/index.js';
+import {FeatureCollection} from 'geojson';
+import {WidgetSource, WidgetSourceProps} from './widget-source.js';
+import {Method} from '../workers/constants.js';
+import {WorkerRequest, WorkerResponse} from '../workers/types.js';
+import {SpatialDataType, TilesetSourceOptions} from '../sources/types.js';
+import {TileFormat} from '../constants.js';
+import {WidgetTilesetSourceImpl} from './widget-tileset-source-impl.js';
+
+export type WidgetTilesetSourceProps = WidgetSourceProps &
+  Omit<TilesetSourceOptions, 'filters'> & {
+    tileFormat: TileFormat;
+    spatialDataType: SpatialDataType;
+  };
+
+export type WidgetTilesetSourceResult = {widgetSource: WidgetTilesetSource};
+
+/**
+ * Source for Widget API requests on a data source defined by a tileset.
+ *
+ * Generally not intended to be constructed directly. Instead, call
+ * {@link vectorTilesetSource}, {@link h3TilesetSource}, or {@link quadbinTilesetSource},
+ * which can be shared with map layers. Sources contain a `widgetSource`
+ * property, for use by widget implementations.
+ *
+ * Example:
+ *
+ * ```javascript
+ * import { vectorTilesetSource } from '@carto/api-client';
+ *
+ * const data = vectorTilesetSource({
+ *   accessToken: '••••',
+ *   connectionName: 'carto_dw',
+ *   tableName: 'carto-demo-data.demo_rasters.my_tileset_source'
+ * });
+ *
+ * const { widgetSource } = await data;
+ * ```
+ */
+export class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps> {
+  protected _localImpl: WidgetTilesetSourceImpl | null = null;
+
+  protected _workerImpl: Worker | null = null;
+  protected _workerEnabled: boolean;
+  protected _workerNextRequestId = 1;
+
+  constructor(props: WidgetTilesetSourceProps) {
+    super(props);
+
+    this._workerEnabled =
+      (props.widgetWorker ?? true) &&
+      TSUP_FORMAT !== 'cjs' &&
+      typeof Worker !== 'undefined';
+
+    if (!this._workerEnabled) {
+      this._localImpl = new WidgetTilesetSourceImpl(this.props);
+    }
+  }
+
+  destroy() {
+    this._localImpl?.destroy();
+    this._localImpl = null;
+
+    this._workerImpl?.terminate();
+    this._workerImpl = null;
+
+    super.destroy();
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // WEB WORKER MANAGEMENT
+
+  /**
+   * Returns an initialized Worker, to be reused for the lifecycle of this
+   * source instance.
+   */
+  protected _getWorker(): Worker {
+    if (this._workerImpl) {
+      return this._workerImpl;
+    }
+
+    this._workerImpl = new Worker(
+      new URL('@carto/api-client/worker', import.meta.url),
+      {
+        type: 'module',
+        name: 'cartowidgettileset',
+      }
+    );
+
+    this._workerImpl.postMessage({
+      method: Method.INIT,
+      params: [this.props],
+    } as WorkerRequest);
+
+    return this._workerImpl;
+  }
+
+  /** Executes a given method on the worker. */
+  protected _executeWorkerMethod<T>(
+    method: Method,
+    params: unknown[],
+    signal?: AbortSignal
+  ): Promise<T> {
+    if (!this._workerEnabled) {
+      // @ts-expect-error No type-checking dynamic method name.
+      return this._localImpl[method](...params);
+    }
+
+    const worker = this._getWorker();
+    const requestId = this._workerNextRequestId++;
+
+    // TODO: ViewState may contain non-serializable data, which we do not need.
+    // Remove this sanitization after sc-469614 is fixed.
+    const options = params[0] as any;
+    if (options?.spatialIndexReferenceViewState) {
+      const {zoom, latitude, longitude} =
+        options.spatialIndexReferenceViewState;
+      options.spatialIndexReferenceViewState = {zoom, latitude, longitude};
+    }
+
+    let resolve: ((value: T) => void) | null = null;
+    let reject: ((reason: any) => void) | null = null;
+
+    // If worker sends message to main process, check whether it's a response
+    // to this request, and whether the request can been aborted. Then resolve
+    // or reject the Promise.
+    function onMessage(e: MessageEvent) {
+      const response = e.data as WorkerResponse;
+      if (response.requestId !== requestId) return;
+
+      if (signal?.aborted) {
+        onAbort();
+      } else if (response.ok) {
+        resolve!(response.result as T);
+      } else {
+        reject!(new Error(response.error));
+      }
+    }
+
+    // If request is aborted by user, immediately reject the Promise.
+    function onAbort() {
+      // https://developer.mozilla.org/en-US/docs/Web/API/DOMException#aborterror
+      const abortError = new Error(signal!.reason);
+      abortError.name = 'AbortError';
+      reject!(abortError);
+    }
+
+    worker.addEventListener('message', onMessage);
+    signal?.addEventListener('abort', onAbort);
+
+    // Send the task to the worker, creating a Promise to resolve/reject later.
+    const promise = new Promise<T>((_resolve, _reject) => {
+      resolve = _resolve;
+      reject = _reject;
+
+      worker.postMessage({
+        requestId,
+        method,
+        params,
+      } as WorkerRequest);
+    });
+
+    // Whether the task completes, fails, or aborts: clean up afterward.
+    void promise.finally(() => {
+      worker.removeEventListener('message', onMessage);
+      signal?.removeEventListener('abort', onAbort);
+    });
+
+    return promise;
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // DATA LOADING
+
+  /**
+   * Loads features as a list of tiles (typically provided by deck.gl).
+   * After tiles are loaded, {@link extractTileFeatures} must be called
+   * before computing statistics on the tiles.
+   */
+  loadTiles(tiles: unknown[]) {
+    if (!this._workerEnabled) {
+      return this._localImpl!.loadTiles(tiles);
+    }
+
+    const worker = this._getWorker();
+
+    tiles = (tiles as Tile[]).map(({id, bbox, data}) => ({
+      id,
+      bbox,
+      data,
+    }));
+
+    worker.postMessage({
+      method: Method.LOAD_TILES,
+      params: [tiles],
+    } as WorkerRequest);
+  }
+
+  /** Configures options used to extract features from tiles. */
+  setTileFeatureExtractOptions(options: TileFeatureExtractOptions) {
+    if (!this._workerEnabled) {
+      return this._localImpl?.setTileFeatureExtractOptions(options);
+    }
+
+    const worker = this._getWorker();
+
+    worker.postMessage({
+      type: Method.SET_TILE_FEATURE_EXTRACT_OPTIONS,
+      params: [options],
+    });
+  }
+
+  /**
+   * Loads features as GeoJSON (used for testing).
+   * @experimental
+   * @internal Not for public use. Spatial filters in other method calls will be ignored.
+   */
+  loadGeoJSON({
+    geojson,
+    spatialFilter,
+  }: {
+    geojson: FeatureCollection;
+    spatialFilter: SpatialFilter;
+  }) {
+    if (!this._workerEnabled) {
+      return this._localImpl!.loadGeoJSON({geojson, spatialFilter});
+    }
+
+    const worker = this._getWorker();
+
+    worker.postMessage({
+      method: Method.LOAD_GEOJSON,
+      params: [{geojson, spatialFilter}],
+    } as WorkerRequest);
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // WIDGETS API
+
+  // eslint-disable-next-line @typescript-eslint/require-await
+  override async getFeatures(): Promise<FeaturesResponse> {
+    throw new Error('getFeatures not supported for tilesets');
+  }
+
+  async getFormula({
+    signal,
+    ...options
+  }: FormulaRequestOptions): Promise<FormulaResponse> {
+    return this._executeWorkerMethod(Method.GET_FORMULA, [options], signal);
+  }
+
+  override async getHistogram({
+    signal,
+    ...options
+  }: HistogramRequestOptions): Promise<HistogramResponse> {
+    return this._executeWorkerMethod(Method.GET_HISTOGRAM, [options], signal);
+  }
+
+  override async getCategories({
+    signal,
+    ...options
+  }: CategoryRequestOptions): Promise<CategoryResponse> {
+    return this._executeWorkerMethod(Method.GET_CATEGORIES, [options], signal);
+  }
+
+  override async getScatter({
+    signal,
+    ...options
+  }: ScatterRequestOptions): Promise<ScatterResponse> {
+    return this._executeWorkerMethod(Method.GET_SCATTER, [options], signal);
+  }
+
+  override async getTable({
+    signal,
+    ...options
+  }: TableRequestOptions): Promise<TableResponse> {
+    return this._executeWorkerMethod(Method.GET_TABLE, [options], signal);
+  }
+
+  override async getTimeSeries({
+    signal,
+    ...options
+  }: TimeSeriesRequestOptions): Promise<TimeSeriesResponse> {
+    return this._executeWorkerMethod(Method.GET_TIME_SERIES, [options], signal);
+  }
+
+  override async getRange({
+    signal,
+    ...options
+  }: RangeRequestOptions): Promise<RangeResponse> {
+    return this._executeWorkerMethod(Method.GET_RANGE, [options], signal);
+  }
+}

package/src/workers/constants.ts

@@ -0,0 +1,13 @@
+export enum Method {
+  INIT = 'init',
+  LOAD_TILES = 'loadTiles',
+  SET_TILE_FEATURE_EXTRACT_OPTIONS = 'setTileFeatureExtractOptions',
+  LOAD_GEOJSON = 'loadGeoJSON',
+  GET_FORMULA = 'getFormula',
+  GET_HISTOGRAM = 'getHistogram',
+  GET_CATEGORIES = 'getCategories',
+  GET_SCATTER = 'getScatter',
+  GET_TABLE = 'getTable',
+  GET_TIME_SERIES = 'getTimeSeries',
+  GET_RANGE = 'getRange',
+}

package/src/workers/types.ts

@@ -0,0 +1,19 @@
+import type {Method} from './constants.js';
+
+export type WorkerRequest = {
+  requestId?: number;
+  method: Method;
+  params: unknown[];
+};
+
+export type WorkerResponse =
+  | {
+      requestId: number;
+      ok: true;
+      result: unknown;
+    }
+  | {
+      requestId: number;
+      ok: false;
+      error: string;
+    };

package/src/workers/widget-tileset-worker.ts

@@ -0,0 +1,40 @@
+import {WidgetTilesetSourceImpl} from '../widget-sources/widget-tileset-source-impl.js';
+import {type WidgetTilesetSourceProps} from '../widget-sources/widget-tileset-source.js';
+import {Method} from './constants.js';
+import type {WorkerRequest, WorkerResponse} from './types.js';
+
+/*
+ * Web Worker, compiled as a separate `@carto/api-client/worker` entrypoint.
+ *
+ * Workers are scoped to the lifecycle of a single WidgetTilesetSource instance,
+ * representing and executing calculations on a single datasource.
+ */
+
+let source: WidgetTilesetSourceImpl;
+
+addEventListener('message', (e) => {
+  const {method, params, requestId} = e.data as WorkerRequest;
+
+  if (method === Method.INIT) {
+    source = new WidgetTilesetSourceImpl({
+      ...(params[0] as WidgetTilesetSourceProps),
+      widgetWorker: false,
+    });
+    return;
+  }
+
+  if (!source) {
+    const error = `Cannot execute "${method}" on uninitialized source.`;
+    postMessage({ok: false, error, requestId} as WorkerResponse);
+    return;
+  }
+
+  // @ts-expect-error No type-checking dynamic method name.
+  Promise.resolve(source[method](...params))
+    .then((result) => {
+      postMessage({ok: true, result, requestId} as WorkerResponse);
+    })
+    .catch((error) => {
+      postMessage({ok: false, error, requestId} as WorkerResponse);
+    });
+});

package/build/api/carto-api-error.d.ts

@@ -1,26 +0,0 @@
-import { MapType } from '../types';
-export type APIRequestType = 'Map data' | 'Map instantiation' | 'Public map' | 'Tile stats' | 'SQL' | 'Basemap style';
-export type APIErrorContext = {
-    requestType: APIRequestType;
-    mapId?: string;
-    connection?: string;
-    source?: string;
-    type?: MapType;
-};
-/**
- *
- * Custom error for reported errors in CARTO Maps API.
- * Provides useful debugging information in console and context for applications.
- *
- */
-export declare class CartoAPIError extends Error {
-    /** Source error from server */
-    error: Error;
-    /** Context (API call & parameters) in which error occured */
-    errorContext: APIErrorContext;
-    /** Response from server */
-    response?: Response;
-    /** JSON Response from server */
-    responseJson?: any;
-    constructor(error: Error, errorContext: APIErrorContext, response?: Response, responseJson?: any);
-}

package/build/api/endpoints.d.ts

@@ -1,24 +0,0 @@
-import { MapType } from '../types.js';
-export type V3Endpoint = 'maps' | 'stats' | 'sql';
-/** @internal Required by fetchMap(). */
-export declare function buildPublicMapUrl({ apiBaseUrl, cartoMapId, }: {
-    apiBaseUrl: string;
-    cartoMapId: string;
-}): string;
-/** @internal Required by fetchMap(). */
-export declare function buildStatsUrl({ attribute, apiBaseUrl, connectionName, source, type, }: {
-    attribute: string;
-    apiBaseUrl: string;
-    connectionName: string;
-    source: string;
-    type: MapType;
-}): string;
-export declare function buildSourceUrl({ apiBaseUrl, connectionName, endpoint, }: {
-    apiBaseUrl: string;
-    connectionName: string;
-    endpoint: MapType;
-}): string;
-export declare function buildQueryUrl({ apiBaseUrl, connectionName, }: {
-    apiBaseUrl: string;
-    connectionName: string;
-}): string;

package/build/api/index.d.ts

@@ -1,5 +0,0 @@
-export { CartoAPIError, APIErrorContext, APIRequestType, } from './carto-api-error.js';
-export { buildPublicMapUrl, buildStatsUrl } from './endpoints.js';
-export { query } from './query.js';
-export type { QueryOptions } from './query.js';
-export { requestWithParameters } from './request-with-parameters.js';

package/build/api/query.d.ts

@@ -1,3 +0,0 @@
-import type { SourceOptions, QuerySourceOptions, QueryResult } from '../sources/types';
-export type QueryOptions = SourceOptions & QuerySourceOptions;
-export declare const query: (options: QueryOptions) => Promise<QueryResult>;

package/build/api/request-with-parameters.d.ts

@@ -1,10 +0,0 @@
-import { APIErrorContext } from './carto-api-error';
-import { LocalCacheOptions } from '../sources/types';
-export declare function requestWithParameters<T = any>({ baseUrl, parameters, headers: customHeaders, errorContext, maxLengthURL, localCache, }: {
-    baseUrl: string;
-    parameters?: Record<string, unknown>;
-    headers?: Record<string, string>;
-    errorContext: APIErrorContext;
-    maxLengthURL?: number;
-    localCache?: LocalCacheOptions;
-}): Promise<T>;