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

package/build/api-client.cjs

@@ -2180,7 +2180,7 @@ async function makeCall({
         method: opts?.method,
         body: opts?.body
       },
-      signal: opts?.abortController?.signal,
+      signal: opts?.signal,
       ...opts?.otherOptions
     });
     data = await response.json();
@@ -2315,12 +2315,12 @@ var WidgetRemoteSource = class extends WidgetSource {
   }
   async getCategories(options) {
     const {
+      signal,
       filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
       spatialIndexReferenceViewState,
-      abortController,
       ...params
     } = options;
     const { column, operation, operationColumn } = params;
@@ -2343,17 +2343,17 @@ var WidgetRemoteSource = class extends WidgetSource {
         operation,
         operationColumn: operationColumn || column
       },
-      opts: { abortController, headers: this._headers }
+      opts: { signal, headers: this._headers }
     }).then((res) => normalizeObjectKeys(res.rows));
   }
   async getFeatures(options) {
     const {
+      signal,
       filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
       spatialIndexReferenceViewState,
-      abortController,
       ...params
     } = options;
     const { columns, dataType, featureIds, z, limit, tileResolution } = params;
@@ -2379,18 +2379,18 @@ var WidgetRemoteSource = class extends WidgetSource {
         limit: limit || 1e3,
         tileResolution: tileResolution || DEFAULT_TILE_RESOLUTION
       },
-      opts: { abortController, headers: this._headers }
+      opts: { signal, headers: this._headers }
       // Avoid `normalizeObjectKeys()`, which changes column names.
     }).then(({ rows }) => ({ rows }));
   }
   async getFormula(options) {
     const {
+      signal,
       filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
       spatialIndexReferenceViewState,
-      abortController,
       operationExp,
       ...params
     } = options;
@@ -2414,17 +2414,17 @@ var WidgetRemoteSource = class extends WidgetSource {
         operation: operation ?? "count",
         operationExp
       },
-      opts: { abortController, headers: this._headers }
+      opts: { signal, headers: this._headers }
     }).then((res) => normalizeObjectKeys(res.rows[0]));
   }
   async getHistogram(options) {
     const {
+      signal,
       filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
       spatialIndexReferenceViewState,
-      abortController,
       ...params
     } = options;
     const { column, operation, ticks } = params;
@@ -2443,7 +2443,7 @@ var WidgetRemoteSource = class extends WidgetSource {
         spatialFilter
       },
       params: { column, operation, ticks },
-      opts: { abortController, headers: this._headers }
+      opts: { signal, headers: this._headers }
     }).then((res) => normalizeObjectKeys(res.rows));
     if (data.length) {
       const result = Array(ticks.length + 1).fill(0);
@@ -2456,12 +2456,12 @@ var WidgetRemoteSource = class extends WidgetSource {
   }
   async getRange(options) {
     const {
+      signal,
       filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
       spatialIndexReferenceViewState,
-      abortController,
       ...params
     } = options;
     const { column } = params;
@@ -2480,17 +2480,17 @@ var WidgetRemoteSource = class extends WidgetSource {
         spatialFilter
       },
       params: { column },
-      opts: { abortController, headers: this._headers }
+      opts: { signal, headers: this._headers }
     }).then((res) => normalizeObjectKeys(res.rows[0]));
   }
   async getScatter(options) {
     const {
+      signal,
       filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
       spatialIndexReferenceViewState,
-      abortController,
       ...params
     } = options;
     const { xAxisColumn, xAxisJoinOperation, yAxisColumn, yAxisJoinOperation } = params;
@@ -2516,17 +2516,17 @@ var WidgetRemoteSource = class extends WidgetSource {
         yAxisJoinOperation,
         limit: HARD_LIMIT
       },
-      opts: { abortController, headers: this._headers }
+      opts: { signal, headers: this._headers }
     }).then((res) => normalizeObjectKeys(res.rows)).then((res) => res.map(({ x, y }) => [x, y]));
   }
   async getTable(options) {
     const {
+      signal,
       filters = this.props.filters,
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
       spatialIndexReferenceViewState,
-      abortController,
       ...params
     } = options;
     const { columns, sortBy, sortDirection, offset = 0, limit = 10 } = params;
@@ -2551,7 +2551,7 @@ var WidgetRemoteSource = class extends WidgetSource {
         limit,
         offset
       },
-      opts: { abortController, headers: this._headers }
+      opts: { signal, headers: this._headers }
     }).then((res) => ({
       // Avoid `normalizeObjectKeys()`, which changes column names.
       rows: res.rows ?? res.ROWS,
@@ -2560,9 +2560,9 @@ var WidgetRemoteSource = class extends WidgetSource {
   }
   async getTimeSeries(options) {
     const {
+      signal,
       filters = this.props.filters,
       filterOwner,
-      abortController,
       spatialFilter,
       spatialFiltersMode,
       spatialIndexReferenceViewState,
@@ -2604,7 +2604,7 @@ var WidgetRemoteSource = class extends WidgetSource {
         splitByCategoryLimit,
         splitByCategoryValues
       },
-      opts: { abortController, headers: this._headers }
+      opts: { signal, headers: this._headers }
     }).then((res) => ({
       rows: normalizeObjectKeys(res.rows),
       categories: res.metadata?.categories
@@ -3086,10 +3086,10 @@ var WidgetTilesetSource = class extends WidgetSource {
       filters,
       filterOwner
     );
-    assertColumn(this._features, column);
     if (!this._features.length) {
       return [];
     }
+    assertColumn(this._features, column);
     return histogram({
       data: filteredFeatures,
       valuesColumns: normalizeColumns(column),
@@ -3276,16 +3276,79 @@ function normalizeColumns(columns) {
 
 // src/widget-sources/widget-tileset-worker-source.ts
 init_cjs_shims();
-var _WidgetTilesetWorkerSource = class _WidgetTilesetWorkerSource extends WidgetSource {
+var WidgetTilesetWorkerSource = class extends WidgetSource {
   constructor(props) {
     super(props);
-    _WidgetTilesetWorkerSource.init();
-    _WidgetTilesetWorkerSource.WORKER.postMessage({
-      tableName: this.props.tableName,
+    /////////////////////////////////////////////////////////////////////////////
+    // WEB WORKER MANAGEMENT
+    __publicField(this, "_worker", null);
+    __publicField(this, "_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", importMetaUrl),
+      {
+        type: "module",
+        name: "cartowidgettileset"
+      }
+    );
+    this._worker.postMessage({
       method: "init" /* INIT */,
       params: [this.props]
     });
+    return this._worker;
+  }
+  /** Executes a given method on the worker. */
+  _executeWorkerMethod(method, params, signal) {
+    const worker = this._getWorker();
+    const requestId = this._workerNextRequestId++;
+    const options = params[0];
+    if (options?.spatialIndexReferenceViewState) {
+      const { zoom, latitude, longitude } = options.spatialIndexReferenceViewState;
+      options.spatialIndexReferenceViewState = { zoom, latitude, longitude };
+    }
+    let resolve = null;
+    let reject = null;
+    function onMessage(e) {
+      const response = e.data;
+      if (response.requestId !== requestId) return;
+      if (signal?.aborted) {
+        reject(new Error(signal.reason));
+      } else if (response.ok) {
+        resolve(response.result);
+      } else {
+        reject(new Error(response.error));
+      }
+    }
+    function onAbort() {
+      reject(new Error(signal.reason));
+    }
+    worker.addEventListener("message", onMessage);
+    signal?.addEventListener("abort", onAbort);
+    const promise = new Promise((_resolve, _reject) => {
+      resolve = _resolve;
+      reject = _reject;
+      worker.postMessage({
+        requestId,
+        method,
+        params
+      });
+    });
+    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
@@ -3297,16 +3360,14 @@ var _WidgetTilesetWorkerSource = class _WidgetTilesetWorkerSource extends Widget
       bbox,
       data
     }));
-    _WidgetTilesetWorkerSource.WORKER.postMessage({
-      tableName: this.props.tableName,
+    this._getWorker().postMessage({
       method: "loadTiles" /* LOAD_TILES */,
       params: [tiles2]
     });
   }
   /** Configures options used to extract features from tiles. */
   setTileFeatureExtractOptions(options) {
-    _WidgetTilesetWorkerSource.WORKER.postMessage({
-      tableName: this.props.tableName,
+    this._getWorker().postMessage({
       type: "setTileFeatureExtractOptions" /* SET_TILE_FEATURE_EXTRACT_OPTIONS */,
       params: [options]
     });
@@ -3320,139 +3381,60 @@ var _WidgetTilesetWorkerSource = class _WidgetTilesetWorkerSource extends Widget
     geojson,
     spatialFilter
   }) {
-    _WidgetTilesetWorkerSource.WORKER.postMessage({
-      tableName: this.props.tableName,
+    this._getWorker().postMessage({
       method: "loadGeoJSON" /* LOAD_GEOJSON */,
       params: [{ geojson, spatialFilter }]
     });
   }
+  /////////////////////////////////////////////////////////////////////////////
+  // WIDGETS API
   // eslint-disable-next-line @typescript-eslint/require-await
   async getFeatures() {
     throw new Error("getFeatures not supported for tilesets");
   }
   async getFormula({
-    abortController,
+    signal,
     ...options
   }) {
-    return this._executeWorkerMethod(
-      this.props.tableName,
-      "getFormula" /* GET_FORMULA */,
-      [options],
-      abortController?.signal
-    );
+    return this._executeWorkerMethod("getFormula" /* GET_FORMULA */, [options], signal);
   }
   async getHistogram({
-    abortController,
+    signal,
     ...options
   }) {
-    return this._executeWorkerMethod(
-      this.props.tableName,
-      "getHistogram" /* GET_HISTOGRAM */,
-      [options],
-      abortController?.signal
-    );
+    return this._executeWorkerMethod("getHistogram" /* GET_HISTOGRAM */, [options], signal);
   }
   async getCategories({
-    abortController,
+    signal,
     ...options
   }) {
-    return this._executeWorkerMethod(
-      this.props.tableName,
-      "getCategories" /* GET_CATEGORIES */,
-      [options],
-      abortController?.signal
-    );
+    return this._executeWorkerMethod("getCategories" /* GET_CATEGORIES */, [options], signal);
   }
   async getScatter({
-    abortController,
+    signal,
     ...options
   }) {
-    return this._executeWorkerMethod(
-      this.props.tableName,
-      "getScatter" /* GET_SCATTER */,
-      [options],
-      abortController?.signal
-    );
+    return this._executeWorkerMethod("getScatter" /* GET_SCATTER */, [options], signal);
   }
   async getTable({
-    abortController,
+    signal,
     ...options
   }) {
-    return this._executeWorkerMethod(
-      this.props.tableName,
-      "getTable" /* GET_TABLE */,
-      [options],
-      abortController?.signal
-    );
+    return this._executeWorkerMethod("getTable" /* GET_TABLE */, [options], signal);
   }
   async getTimeSeries({
-    abortController,
+    signal,
     ...options
   }) {
-    return this._executeWorkerMethod(
-      this.props.tableName,
-      "getTimeSeries" /* GET_TIME_SERIES */,
-      [options],
-      abortController?.signal
-    );
+    return this._executeWorkerMethod("getTimeSeries" /* GET_TIME_SERIES */, [options], signal);
   }
   async getRange({
-    abortController,
+    signal,
     ...options
   }) {
-    return this._executeWorkerMethod(
-      this.props.tableName,
-      "getRange" /* GET_RANGE */,
-      [options],
-      abortController?.signal
-    );
-  }
-  static init() {
-    _WidgetTilesetWorkerSource.WORKER = new Worker(
-      new URL("@carto/api-client/worker", importMetaUrl),
-      {
-        type: "module",
-        name: "cartowidgettileset"
-      }
-    );
-  }
-  _executeWorkerMethod(tableName, method, params, signal) {
-    const worker = _WidgetTilesetWorkerSource.WORKER;
-    const requestId = _WidgetTilesetWorkerSource._nextRequestID++;
-    const options = params[0];
-    if (options?.spatialIndexReferenceViewState) {
-      const { zoom, latitude, longitude } = options.spatialIndexReferenceViewState;
-      options.spatialIndexReferenceViewState = { zoom, latitude, longitude };
-    }
-    worker.postMessage({
-      requestId,
-      tableName,
-      method,
-      params
-    });
-    return new Promise((resolve, reject) => {
-      function listener(e) {
-        const response = e.data;
-        if (response.requestId !== requestId) return;
-        worker.removeEventListener("message", listener);
-        if (signal?.aborted) {
-          reject(new Error(signal.reason));
-        } else if (response.ok) {
-          resolve(response.result);
-        } else {
-          reject(new Error(response.error));
-        }
-      }
-      worker.addEventListener("message", listener);
-    });
+    return this._executeWorkerMethod("getRange" /* GET_RANGE */, [options], signal);
   }
 };
-/////////////////////////////////////////////////////////////////////////////
-// WEB WORKER MANAGEMENT
-// TODO: Singleton? Pool shared among datasets? One per dataset?
-__publicField(_WidgetTilesetWorkerSource, "WORKER");
-__publicField(_WidgetTilesetWorkerSource, "_nextRequestID", 1);
-var WidgetTilesetWorkerSource = _WidgetTilesetWorkerSource;
 
 // src/sources/h3-query-source.ts
 var h3QuerySource = async function(options) {

package/build/api-client.d.cts

@@ -681,11 +681,11 @@ interface ViewState {
 }
 /** Common options for {@link WidgetRemoteSource} requests. */
 interface BaseRequestOptions {
+    signal?: AbortSignal;
     spatialFilter?: SpatialFilter;
     spatialFiltersMode?: SpatialFilterPolyfillMode;
     /** Required for table- and query-based spatial index sources (H3, Quadbin). */
     spatialIndexReferenceViewState?: ViewState;
-    abortController?: AbortController;
     /** Overrides source filters, if any. */
     filters?: Filters;
     filterOwner?: string;
@@ -1147,10 +1147,25 @@ declare enum Method {
 }
 
 /**
- * TODO
+ * 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.
  */
 declare class WidgetTilesetWorkerSource extends WidgetSource<WidgetTilesetSourceProps> {
     constructor(props: WidgetTilesetSourceProps);
+    protected _worker: Worker | null;
+    protected _workerNextRequestId: number;
+    /**
+     * Returns an initialized Worker, to be reused for the lifecycle of this
+     * source instance.
+     */
+    _getWorker(): Worker;
+    /** Executes a given method on the worker. */
+    _executeWorkerMethod<T>(method: Method, params: unknown[], signal?: AbortSignal): Promise<T>;
     /**
      * Loads features as a list of tiles (typically provided by deck.gl).
      * After tiles are loaded, {@link extractTileFeatures} must be called
@@ -1169,17 +1184,13 @@ declare class WidgetTilesetWorkerSource extends WidgetSource<WidgetTilesetSource
         spatialFilter: SpatialFilter;
     }): void;
     getFeatures(): Promise<FeaturesResponse>;
-    getFormula({ abortController, ...options }: FormulaRequestOptions): Promise<FormulaResponse>;
-    getHistogram({ abortController, ...options }: HistogramRequestOptions): Promise<HistogramResponse>;
-    getCategories({ abortController, ...options }: CategoryRequestOptions): Promise<CategoryResponse>;
-    getScatter({ abortController, ...options }: ScatterRequestOptions): Promise<ScatterResponse>;
-    getTable({ abortController, ...options }: TableRequestOptions): Promise<TableResponse>;
-    getTimeSeries({ abortController, ...options }: TimeSeriesRequestOptions): Promise<TimeSeriesResponse>;
-    getRange({ abortController, ...options }: RangeRequestOptions): Promise<RangeResponse>;
-    protected static WORKER: Worker;
-    protected static _nextRequestID: number;
-    static init(): void;
-    _executeWorkerMethod<T>(tableName: string, method: Method, params: unknown[], signal?: AbortSignal): Promise<T>;
+    getFormula({ signal, ...options }: FormulaRequestOptions): Promise<FormulaResponse>;
+    getHistogram({ signal, ...options }: HistogramRequestOptions): Promise<HistogramResponse>;
+    getCategories({ signal, ...options }: CategoryRequestOptions): Promise<CategoryResponse>;
+    getScatter({ signal, ...options }: ScatterRequestOptions): Promise<ScatterResponse>;
+    getTable({ signal, ...options }: TableRequestOptions): Promise<TableResponse>;
+    getTimeSeries({ signal, ...options }: TimeSeriesRequestOptions): Promise<TimeSeriesResponse>;
+    getRange({ signal, ...options }: RangeRequestOptions): Promise<RangeResponse>;
 }
 
 type H3QuerySourceOptions = SourceOptions & QuerySourceOptions & AggregationOptions & FilterOptions;

package/build/api-client.d.ts

@@ -681,11 +681,11 @@ interface ViewState {
 }
 /** Common options for {@link WidgetRemoteSource} requests. */
 interface BaseRequestOptions {
+    signal?: AbortSignal;
     spatialFilter?: SpatialFilter;
     spatialFiltersMode?: SpatialFilterPolyfillMode;
     /** Required for table- and query-based spatial index sources (H3, Quadbin). */
     spatialIndexReferenceViewState?: ViewState;
-    abortController?: AbortController;
     /** Overrides source filters, if any. */
     filters?: Filters;
     filterOwner?: string;
@@ -1147,10 +1147,25 @@ declare enum Method {
 }
 
 /**
- * TODO
+ * 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.
  */
 declare class WidgetTilesetWorkerSource extends WidgetSource<WidgetTilesetSourceProps> {
     constructor(props: WidgetTilesetSourceProps);
+    protected _worker: Worker | null;
+    protected _workerNextRequestId: number;
+    /**
+     * Returns an initialized Worker, to be reused for the lifecycle of this
+     * source instance.
+     */
+    _getWorker(): Worker;
+    /** Executes a given method on the worker. */
+    _executeWorkerMethod<T>(method: Method, params: unknown[], signal?: AbortSignal): Promise<T>;
     /**
      * Loads features as a list of tiles (typically provided by deck.gl).
      * After tiles are loaded, {@link extractTileFeatures} must be called
@@ -1169,17 +1184,13 @@ declare class WidgetTilesetWorkerSource extends WidgetSource<WidgetTilesetSource
         spatialFilter: SpatialFilter;
     }): void;
     getFeatures(): Promise<FeaturesResponse>;
-    getFormula({ abortController, ...options }: FormulaRequestOptions): Promise<FormulaResponse>;
-    getHistogram({ abortController, ...options }: HistogramRequestOptions): Promise<HistogramResponse>;
-    getCategories({ abortController, ...options }: CategoryRequestOptions): Promise<CategoryResponse>;
-    getScatter({ abortController, ...options }: ScatterRequestOptions): Promise<ScatterResponse>;
-    getTable({ abortController, ...options }: TableRequestOptions): Promise<TableResponse>;
-    getTimeSeries({ abortController, ...options }: TimeSeriesRequestOptions): Promise<TimeSeriesResponse>;
-    getRange({ abortController, ...options }: RangeRequestOptions): Promise<RangeResponse>;
-    protected static WORKER: Worker;
-    protected static _nextRequestID: number;
-    static init(): void;
-    _executeWorkerMethod<T>(tableName: string, method: Method, params: unknown[], signal?: AbortSignal): Promise<T>;
+    getFormula({ signal, ...options }: FormulaRequestOptions): Promise<FormulaResponse>;
+    getHistogram({ signal, ...options }: HistogramRequestOptions): Promise<HistogramResponse>;
+    getCategories({ signal, ...options }: CategoryRequestOptions): Promise<CategoryResponse>;
+    getScatter({ signal, ...options }: ScatterRequestOptions): Promise<ScatterResponse>;
+    getTable({ signal, ...options }: TableRequestOptions): Promise<TableResponse>;
+    getTimeSeries({ signal, ...options }: TimeSeriesRequestOptions): Promise<TimeSeriesResponse>;
+    getRange({ signal, ...options }: RangeRequestOptions): Promise<RangeResponse>;
 }
 
 type H3QuerySourceOptions = SourceOptions & QuerySourceOptions & AggregationOptions & FilterOptions;