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

package/build/api-client.cjs

@@ -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,12 +3381,13 @@ 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");
@@ -3335,7 +3397,6 @@ var _WidgetTilesetWorkerSource = class _WidgetTilesetWorkerSource extends Widget
     ...options
   }) {
     return this._executeWorkerMethod(
-      this.props.tableName,
       "getFormula" /* GET_FORMULA */,
       [options],
       abortController?.signal
@@ -3346,7 +3407,6 @@ var _WidgetTilesetWorkerSource = class _WidgetTilesetWorkerSource extends Widget
     ...options
   }) {
     return this._executeWorkerMethod(
-      this.props.tableName,
       "getHistogram" /* GET_HISTOGRAM */,
       [options],
       abortController?.signal
@@ -3357,7 +3417,6 @@ var _WidgetTilesetWorkerSource = class _WidgetTilesetWorkerSource extends Widget
     ...options
   }) {
     return this._executeWorkerMethod(
-      this.props.tableName,
       "getCategories" /* GET_CATEGORIES */,
       [options],
       abortController?.signal
@@ -3368,7 +3427,6 @@ var _WidgetTilesetWorkerSource = class _WidgetTilesetWorkerSource extends Widget
     ...options
   }) {
     return this._executeWorkerMethod(
-      this.props.tableName,
       "getScatter" /* GET_SCATTER */,
       [options],
       abortController?.signal
@@ -3379,7 +3437,6 @@ var _WidgetTilesetWorkerSource = class _WidgetTilesetWorkerSource extends Widget
     ...options
   }) {
     return this._executeWorkerMethod(
-      this.props.tableName,
       "getTable" /* GET_TABLE */,
       [options],
       abortController?.signal
@@ -3390,7 +3447,6 @@ var _WidgetTilesetWorkerSource = class _WidgetTilesetWorkerSource extends Widget
     ...options
   }) {
     return this._executeWorkerMethod(
-      this.props.tableName,
       "getTimeSeries" /* GET_TIME_SERIES */,
       [options],
       abortController?.signal
@@ -3401,58 +3457,12 @@ var _WidgetTilesetWorkerSource = class _WidgetTilesetWorkerSource extends Widget
     ...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);
-    });
-  }
 };
-/////////////////////////////////////////////////////////////////////////////
-// 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

@@ -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
@@ -1176,10 +1191,6 @@ declare class WidgetTilesetWorkerSource extends WidgetSource<WidgetTilesetSource
     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>;
 }
 
 type H3QuerySourceOptions = SourceOptions & QuerySourceOptions & AggregationOptions & FilterOptions;

package/build/api-client.d.ts

@@ -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
@@ -1176,10 +1191,6 @@ declare class WidgetTilesetWorkerSource extends WidgetSource<WidgetTilesetSource
     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>;
 }
 
 type H3QuerySourceOptions = SourceOptions & QuerySourceOptions & AggregationOptions & FilterOptions;

package/build/api-client.js

@@ -41,7 +41,7 @@ import {
   tileFeaturesGeometries,
   tileFeaturesSpatialIndex,
   transformToTileCoords
-} from "./chunk-V3E7BKVR.js";
+} from "./chunk-LEI5PI5X.js";
 
 // src/deck/get-data-filter-extension-props.ts
 function getDataFilterExtensionProps(filters, filtersLogicalOperator, filterSize) {
@@ -1109,16 +1109,79 @@ var WidgetTableSource = class extends WidgetRemoteSource {
 };
 
 // src/widget-sources/widget-tileset-worker-source.ts
-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", import.meta.url),
+      {
+        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
@@ -1130,16 +1193,14 @@ var _WidgetTilesetWorkerSource = class _WidgetTilesetWorkerSource extends Widget
       bbox,
       data
     }));
-    _WidgetTilesetWorkerSource.WORKER.postMessage({
-      tableName: this.props.tableName,
+    this._getWorker().postMessage({
       method: "loadTiles" /* LOAD_TILES */,
       params: [tiles]
     });
   }
   /** 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]
     });
@@ -1153,12 +1214,13 @@ 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");
@@ -1168,7 +1230,6 @@ var _WidgetTilesetWorkerSource = class _WidgetTilesetWorkerSource extends Widget
     ...options
   }) {
     return this._executeWorkerMethod(
-      this.props.tableName,
       "getFormula" /* GET_FORMULA */,
       [options],
       abortController?.signal
@@ -1179,7 +1240,6 @@ var _WidgetTilesetWorkerSource = class _WidgetTilesetWorkerSource extends Widget
     ...options
   }) {
     return this._executeWorkerMethod(
-      this.props.tableName,
       "getHistogram" /* GET_HISTOGRAM */,
       [options],
       abortController?.signal
@@ -1190,7 +1250,6 @@ var _WidgetTilesetWorkerSource = class _WidgetTilesetWorkerSource extends Widget
     ...options
   }) {
     return this._executeWorkerMethod(
-      this.props.tableName,
       "getCategories" /* GET_CATEGORIES */,
       [options],
       abortController?.signal
@@ -1201,7 +1260,6 @@ var _WidgetTilesetWorkerSource = class _WidgetTilesetWorkerSource extends Widget
     ...options
   }) {
     return this._executeWorkerMethod(
-      this.props.tableName,
       "getScatter" /* GET_SCATTER */,
       [options],
       abortController?.signal
@@ -1212,7 +1270,6 @@ var _WidgetTilesetWorkerSource = class _WidgetTilesetWorkerSource extends Widget
     ...options
   }) {
     return this._executeWorkerMethod(
-      this.props.tableName,
       "getTable" /* GET_TABLE */,
       [options],
       abortController?.signal
@@ -1223,7 +1280,6 @@ var _WidgetTilesetWorkerSource = class _WidgetTilesetWorkerSource extends Widget
     ...options
   }) {
     return this._executeWorkerMethod(
-      this.props.tableName,
       "getTimeSeries" /* GET_TIME_SERIES */,
       [options],
       abortController?.signal
@@ -1234,58 +1290,12 @@ var _WidgetTilesetWorkerSource = class _WidgetTilesetWorkerSource extends Widget
     ...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", import.meta.url),
-      {
-        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);
-    });
-  }
 };
-/////////////////////////////////////////////////////////////////////////////
-// 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/worker.js

@@ -1,19 +1,17 @@
 import {
   WidgetTilesetSource
-} from "./chunk-V3E7BKVR.js";
+} from "./chunk-LEI5PI5X.js";
 
 // src/workers/widget-tileset-worker.ts
-var SOURCES_BY_NAME = /* @__PURE__ */ new Map();
+var source;
 addEventListener("message", (e) => {
-  const { tableName, method, params, requestId } = e.data;
+  const { method, params, requestId } = e.data;
   if (method === "init" /* INIT */) {
-    const props = params[0];
-    SOURCES_BY_NAME.set(tableName, new WidgetTilesetSource(props));
+    source = new WidgetTilesetSource(params[0]);
     return;
   }
-  const source = SOURCES_BY_NAME.get(tableName);
   if (!source) {
-    const error = `Unknown dataset: ${tableName}`;
+    const error = `Cannot execute "${method}" on uninitialized source.`;
     postMessage({ ok: false, error, requestId });
     return;
   }

package/package.json

@@ -8,7 +8,7 @@
   "homepage": "https://github.com/CartoDB/carto-api-client#readme",
   "author": "Don McCurdy <donmccurdy@carto.com>",
   "packageManager": "yarn@4.3.1",
-  "version": "0.5.0-alpha.5",
+  "version": "0.5.0-alpha.6",
   "license": "MIT",
   "publishConfig": {
     "access": "public",

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

@@ -195,12 +195,12 @@ export class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps>
       filterOwner
     );
 
-    assertColumn(this._features, column);
-
     if (!this._features.length) {
       return [];
     }
 
+    assertColumn(this._features, column);
+
     return histogram({
       data: filteredFeatures,
       valuesColumns: normalizeColumns(column),

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

@@ -24,20 +24,119 @@ import {Method} from '../workers/constants.js';
 import {WorkerRequest, WorkerResponse} from '../workers/types.js';
 
 /**
- * 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.
  */
 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',
+      }
+    );
 
-    WidgetTilesetWorkerSource.init();
-    WidgetTilesetWorkerSource.WORKER.postMessage({
-      tableName: this.props.tableName,
+    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
@@ -50,8 +149,7 @@ export class WidgetTilesetWorkerSource extends WidgetSource<WidgetTilesetSourceP
       data,
     }));
 
-    WidgetTilesetWorkerSource.WORKER.postMessage({
-      tableName: this.props.tableName,
+    this._getWorker().postMessage({
       method: Method.LOAD_TILES,
       params: [tiles],
     } as WorkerRequest);
@@ -59,8 +157,7 @@ export class WidgetTilesetWorkerSource extends WidgetSource<WidgetTilesetSourceP
 
   /** Configures options used to extract features from tiles. */
   setTileFeatureExtractOptions(options: TileFeatureExtractOptions) {
-    WidgetTilesetWorkerSource.WORKER.postMessage({
-      tableName: this.props.tableName,
+    this._getWorker().postMessage({
       type: Method.SET_TILE_FEATURE_EXTRACT_OPTIONS,
       params: [options],
     });
@@ -78,13 +175,15 @@ export class WidgetTilesetWorkerSource extends WidgetSource<WidgetTilesetSourceP
     geojson: FeatureCollection;
     spatialFilter: SpatialFilter;
   }) {
-    WidgetTilesetWorkerSource.WORKER.postMessage({
-      tableName: this.props.tableName,
+    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');
@@ -95,7 +194,6 @@ export class WidgetTilesetWorkerSource extends WidgetSource<WidgetTilesetSourceP
     ...options
   }: FormulaRequestOptions): Promise<FormulaResponse> {
     return this._executeWorkerMethod(
-      this.props.tableName,
       Method.GET_FORMULA,
       [options],
       abortController?.signal
@@ -107,7 +205,6 @@ export class WidgetTilesetWorkerSource extends WidgetSource<WidgetTilesetSourceP
     ...options
   }: HistogramRequestOptions): Promise<HistogramResponse> {
     return this._executeWorkerMethod(
-      this.props.tableName,
       Method.GET_HISTOGRAM,
       [options],
       abortController?.signal
@@ -119,7 +216,6 @@ export class WidgetTilesetWorkerSource extends WidgetSource<WidgetTilesetSourceP
     ...options
   }: CategoryRequestOptions): Promise<CategoryResponse> {
     return this._executeWorkerMethod(
-      this.props.tableName,
       Method.GET_CATEGORIES,
       [options],
       abortController?.signal
@@ -131,7 +227,6 @@ export class WidgetTilesetWorkerSource extends WidgetSource<WidgetTilesetSourceP
     ...options
   }: ScatterRequestOptions): Promise<ScatterResponse> {
     return this._executeWorkerMethod(
-      this.props.tableName,
       Method.GET_SCATTER,
       [options],
       abortController?.signal
@@ -143,7 +238,6 @@ export class WidgetTilesetWorkerSource extends WidgetSource<WidgetTilesetSourceP
     ...options
   }: TableRequestOptions): Promise<TableResponse> {
     return this._executeWorkerMethod(
-      this.props.tableName,
       Method.GET_TABLE,
       [options],
       abortController?.signal
@@ -155,7 +249,6 @@ export class WidgetTilesetWorkerSource extends WidgetSource<WidgetTilesetSourceP
     ...options
   }: TimeSeriesRequestOptions): Promise<TimeSeriesResponse> {
     return this._executeWorkerMethod(
-      this.props.tableName,
       Method.GET_TIME_SERIES,
       [options],
       abortController?.signal
@@ -167,72 +260,9 @@ export class WidgetTilesetWorkerSource extends WidgetSource<WidgetTilesetSourceP
     ...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/types.ts

@@ -2,7 +2,6 @@ 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[];
 };

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

@@ -5,22 +5,25 @@ import {
 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>();
+/*
+ * 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 {tableName, method, params, requestId} = e.data as WorkerRequest;
+  const {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));
+    source = new WidgetTilesetSource(params[0] as WidgetTilesetSourceProps);
     return;
   }
 
-  const source = SOURCES_BY_NAME.get(tableName);
-
   if (!source) {
-    const error = `Unknown dataset: ${tableName}`;
+    const error = `Cannot execute "${method}" on uninitialized source.`;
     postMessage({ok: false, error, requestId} as WorkerResponse);
     return;
   }

package/build/{chunk-V3E7BKVR.js → chunk-LEI5PI5X.js}

@@ -1829,10 +1829,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),