@carto/api-client 0.5.0-alpha.4 → 0.5.0-alpha.6

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

@@ -0,0 +1,268 @@
+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} from './widget-source.js';
+import {WidgetTilesetSourceProps} from './widget-tileset-source.js';
+import {Method} from '../workers/constants.js';
+import {WorkerRequest, WorkerResponse} from '../workers/types.js';
+
+/**
+ * Wrapper for {@link WidgetTilesetSource}, moving calculations to Web Workers.
+ * When supported, use of both classes is identical.
+ *
+ * To use this wrapper, the application and environment must support ESM Web
+ * Workers. For older build systems based on CommonJS, or in environments like
+ * Node.js, it may be necessary to use {@link WidgetTilesetSource} directly,
+ * and to (optionally) create workers manually in the application.
+ */
+export class WidgetTilesetWorkerSource extends WidgetSource<WidgetTilesetSourceProps> {
+  constructor(props: WidgetTilesetSourceProps) {
+    super(props);
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // WEB WORKER MANAGEMENT
+
+  protected _worker: Worker | null = null;
+  protected _workerNextRequestId = 1;
+
+  /**
+   * Returns an initialized Worker, to be reused for the lifecycle of this
+   * source instance.
+   */
+  _getWorker() {
+    if (this._worker) {
+      return this._worker;
+    }
+
+    this._worker = new Worker(
+      new URL('@carto/api-client/worker', import.meta.url),
+      {
+        type: 'module',
+        name: 'cartowidgettileset',
+      }
+    );
+
+    this._worker.postMessage({
+      method: Method.INIT,
+      params: [this.props],
+    } as WorkerRequest);
+
+    return this._worker;
+  }
+
+  /** Executes a given method on the worker. */
+  _executeWorkerMethod<T>(
+    method: Method,
+    params: unknown[],
+    signal?: AbortSignal
+  ): Promise<T> {
+    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) {
+        reject!(new Error(signal.reason));
+      } 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() {
+      reject!(new Error(signal!.reason));
+    }
+
+    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[]) {
+    tiles = (tiles as Tile[]).map(({id, bbox, data}) => ({
+      id,
+      bbox,
+      data,
+    }));
+
+    this._getWorker().postMessage({
+      method: Method.LOAD_TILES,
+      params: [tiles],
+    } as WorkerRequest);
+  }
+
+  /** Configures options used to extract features from tiles. */
+  setTileFeatureExtractOptions(options: TileFeatureExtractOptions) {
+    this._getWorker().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;
+  }) {
+    this._getWorker().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({
+    abortController,
+    ...options
+  }: FormulaRequestOptions): Promise<FormulaResponse> {
+    return this._executeWorkerMethod(
+      Method.GET_FORMULA,
+      [options],
+      abortController?.signal
+    );
+  }
+
+  override async getHistogram({
+    abortController,
+    ...options
+  }: HistogramRequestOptions): Promise<HistogramResponse> {
+    return this._executeWorkerMethod(
+      Method.GET_HISTOGRAM,
+      [options],
+      abortController?.signal
+    );
+  }
+
+  override async getCategories({
+    abortController,
+    ...options
+  }: CategoryRequestOptions): Promise<CategoryResponse> {
+    return this._executeWorkerMethod(
+      Method.GET_CATEGORIES,
+      [options],
+      abortController?.signal
+    );
+  }
+
+  override async getScatter({
+    abortController,
+    ...options
+  }: ScatterRequestOptions): Promise<ScatterResponse> {
+    return this._executeWorkerMethod(
+      Method.GET_SCATTER,
+      [options],
+      abortController?.signal
+    );
+  }
+
+  override async getTable({
+    abortController,
+    ...options
+  }: TableRequestOptions): Promise<TableResponse> {
+    return this._executeWorkerMethod(
+      Method.GET_TABLE,
+      [options],
+      abortController?.signal
+    );
+  }
+
+  override async getTimeSeries({
+    abortController,
+    ...options
+  }: TimeSeriesRequestOptions): Promise<TimeSeriesResponse> {
+    return this._executeWorkerMethod(
+      Method.GET_TIME_SERIES,
+      [options],
+      abortController?.signal
+    );
+  }
+
+  override async getRange({
+    abortController,
+    ...options
+  }: RangeRequestOptions): Promise<RangeResponse> {
+    return this._executeWorkerMethod(
+      Method.GET_RANGE,
+      [options],
+      abortController?.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/utils.ts

@@ -0,0 +1,33 @@
+let _isModuleWorkerSupported: boolean | null =
+  TSUP_FORMAT === 'cjs' ? false : null;
+
+/**
+ * Checks whether current environment supports ES Module Workers, by way of a
+ * two-part check:
+ * (1) If this is a CJS build, return false.
+ * (2) If this is an ESM build, return true if the runtime supports ESM Workers.
+ */
+export function isModuleWorkerSupported(): boolean {
+  if (_isModuleWorkerSupported !== null) {
+    return _isModuleWorkerSupported;
+  }
+
+  try {
+    // https://stackoverflow.com/a/62963963
+    new Worker('blob://', {
+      get type() {
+        _isModuleWorkerSupported = true;
+        return 'module' as const;
+      },
+    });
+  } catch {
+    // Do nothing. 'blob://' should always throw an error to prevent the
+    // browser from creating an (expensive) worker. We care whether the
+    // 'type' getter was called, not about the error.
+  } finally {
+    // If 'type' getter wasn't called, modules are unsupported.
+    _isModuleWorkerSupported ||= false;
+  }
+
+  return _isModuleWorkerSupported;
+}

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

@@ -0,0 +1,39 @@
+import {
+  WidgetTilesetSource,
+  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 WidgetTilesetWorkerSource
+ * instance, representing and executing calculations on a single datasource.
+ */
+
+let source: WidgetTilesetSource;
+
+addEventListener('message', (e) => {
+  const {method, params, requestId} = e.data as WorkerRequest;
+
+  if (method === Method.INIT) {
+    source = new WidgetTilesetSource(params[0] as WidgetTilesetSourceProps);
+    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.js';
-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.js';
-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.js';
-import { LocalCacheOptions } from '../sources/types.js';
-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>;