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

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

@@ -0,0 +1,238 @@
+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';
+
+/**
+ * TODO
+ */
+export class WidgetTilesetWorkerSource extends WidgetSource<WidgetTilesetSourceProps> {
+  constructor(props: WidgetTilesetSourceProps) {
+    super(props);
+
+    WidgetTilesetWorkerSource.init();
+    WidgetTilesetWorkerSource.WORKER.postMessage({
+      tableName: this.props.tableName,
+      method: Method.INIT,
+      params: [this.props],
+    } as WorkerRequest);
+  }
+
+  /**
+   * 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,
+    }));
+
+    WidgetTilesetWorkerSource.WORKER.postMessage({
+      tableName: this.props.tableName,
+      method: Method.LOAD_TILES,
+      params: [tiles],
+    } as WorkerRequest);
+  }
+
+  /** Configures options used to extract features from tiles. */
+  setTileFeatureExtractOptions(options: TileFeatureExtractOptions) {
+    WidgetTilesetWorkerSource.WORKER.postMessage({
+      tableName: this.props.tableName,
+      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;
+  }) {
+    WidgetTilesetWorkerSource.WORKER.postMessage({
+      tableName: this.props.tableName,
+      method: Method.LOAD_GEOJSON,
+      params: [{geojson, spatialFilter}],
+    } as WorkerRequest);
+  }
+
+  // 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(
+      this.props.tableName,
+      Method.GET_FORMULA,
+      [options],
+      abortController?.signal
+    );
+  }
+
+  override async getHistogram({
+    abortController,
+    ...options
+  }: HistogramRequestOptions): Promise<HistogramResponse> {
+    return this._executeWorkerMethod(
+      this.props.tableName,
+      Method.GET_HISTOGRAM,
+      [options],
+      abortController?.signal
+    );
+  }
+
+  override async getCategories({
+    abortController,
+    ...options
+  }: CategoryRequestOptions): Promise<CategoryResponse> {
+    return this._executeWorkerMethod(
+      this.props.tableName,
+      Method.GET_CATEGORIES,
+      [options],
+      abortController?.signal
+    );
+  }
+
+  override async getScatter({
+    abortController,
+    ...options
+  }: ScatterRequestOptions): Promise<ScatterResponse> {
+    return this._executeWorkerMethod(
+      this.props.tableName,
+      Method.GET_SCATTER,
+      [options],
+      abortController?.signal
+    );
+  }
+
+  override async getTable({
+    abortController,
+    ...options
+  }: TableRequestOptions): Promise<TableResponse> {
+    return this._executeWorkerMethod(
+      this.props.tableName,
+      Method.GET_TABLE,
+      [options],
+      abortController?.signal
+    );
+  }
+
+  override async getTimeSeries({
+    abortController,
+    ...options
+  }: TimeSeriesRequestOptions): Promise<TimeSeriesResponse> {
+    return this._executeWorkerMethod(
+      this.props.tableName,
+      Method.GET_TIME_SERIES,
+      [options],
+      abortController?.signal
+    );
+  }
+
+  override async getRange({
+    abortController,
+    ...options
+  }: RangeRequestOptions): Promise<RangeResponse> {
+    return this._executeWorkerMethod(
+      this.props.tableName,
+      Method.GET_RANGE,
+      [options],
+      abortController?.signal
+    );
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // WEB WORKER MANAGEMENT
+
+  // TODO: Singleton? Pool shared among datasets? One per dataset?
+  protected static WORKER: Worker;
+  protected static _nextRequestID = 1;
+
+  static init() {
+    WidgetTilesetWorkerSource.WORKER = new Worker(
+      new URL('@carto/api-client/worker', import.meta.url),
+      {
+        type: 'module',
+        name: 'cartowidgettileset',
+      }
+    );
+  }
+
+  _executeWorkerMethod<T>(
+    tableName: string,
+    method: Method,
+    params: unknown[],
+    signal?: AbortSignal
+  ): Promise<T> {
+    const worker = WidgetTilesetWorkerSource.WORKER;
+    const requestId = WidgetTilesetWorkerSource._nextRequestID++;
+
+    // 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};
+    }
+
+    worker.postMessage({
+      requestId,
+      tableName,
+      method,
+      params,
+    } as WorkerRequest);
+
+    return new Promise((resolve, reject) => {
+      function listener(e: MessageEvent) {
+        const response = e.data as WorkerResponse;
+        if (response.requestId !== requestId) return;
+
+        worker.removeEventListener('message', listener);
+
+        if (signal?.aborted) {
+          reject(new Error(signal.reason));
+        } else if (response.ok) {
+          resolve(response.result as T);
+        } else {
+          reject(new Error(response.error));
+        }
+      }
+
+      worker.addEventListener('message', listener);
+    });
+  }
+}

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,20 @@
+import type {Method} from './constants.js';
+
+export type WorkerRequest = {
+  requestId?: number;
+  tableName: string; // TODO: Table name is not a unique identifier.
+  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,36 @@
+import {
+  WidgetTilesetSource,
+  type WidgetTilesetSourceProps,
+} from '../widget-sources/widget-tileset-source.js';
+import {Method} from './constants.js';
+import type {WorkerRequest, WorkerResponse} from './types.js';
+
+// TODO: Cannot rely on tableName as unique ID.
+const SOURCES_BY_NAME = new Map<string, WidgetTilesetSource>();
+
+addEventListener('message', (e) => {
+  const {tableName, method, params, requestId} = e.data as WorkerRequest;
+
+  if (method === Method.INIT) {
+    const props = params[0] as WidgetTilesetSourceProps;
+    SOURCES_BY_NAME.set(tableName, new WidgetTilesetSource(props));
+    return;
+  }
+
+  const source = SOURCES_BY_NAME.get(tableName);
+
+  if (!source) {
+    const error = `Unknown dataset: ${tableName}`;
+    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>;