@carto/api-client 0.5.6-alpha.bundle.4 → 0.5.7-alpha-optional-spatial-filter.0

package/src/utils/CellSet.ts

@@ -0,0 +1,90 @@
+/** Flags 'empty' values in a Uint32Array index. */
+const EMPTY_U32 = 2 ** 32 - 1;
+
+/**
+ * Custom Set-like interface optimized for BigUint64 cell IDs. Unlike Set,
+ * limited in most JavaScript runtimes to ~16M entries, this implementation
+ * can support up to `n = 2^32 - 1` (4 billion) entries, with lookups in
+ * amortized O(1) time.
+ */
+export class CellSet {
+  /** List of cells stored by the set. Stored by reference, without copying. */
+  private cells: bigint[];
+
+  /** DataView representing a single cell ID. Pre-allocated to reduce memory during queries. */
+  private cellView = new DataView(new ArrayBuffer(8));
+
+  /** Hash table, mapping a hash index (computed) to an index in the 'cells' array. */
+  private hashTable: Uint32Array;
+
+  constructor(cells: bigint[]) {
+    this.cells = cells;
+
+    // Pre-allocate hash table for queries.
+    this.hashTable = new Uint32Array(hashBuckets(cells.length)).fill(EMPTY_U32);
+    for (let cellIndex = 0; cellIndex < cells.length; cellIndex++) {
+      this.hashTable[this.hashLookup(cells[cellIndex])] = cellIndex;
+    }
+  }
+
+  has(cell: bigint): boolean {
+    const hashIndex = this.hashLookup(cell);
+    return this.hashTable[hashIndex] !== EMPTY_U32;
+  }
+
+  private hashLookup(cell: bigint): number {
+    // Hash implementation operates on 32-bit chunks, so write the cell ID
+    // into a pre-allocated DataView for easier iteration.
+    this.cellView.setBigUint64(0, cell);
+    const hashval = hash(this.cellView);
+    const hashmod = this.hashTable.length - 1;
+    let bucket = hashval & hashmod;
+
+    // Find the first bucket in the hash table where either (a) no cell
+    // is yet stored, or (b) the stored cell and the query cell are equal.
+    for (let probe = 0; probe <= hashmod; probe++) {
+      const cellIndex = this.hashTable[bucket];
+
+      if (cellIndex === EMPTY_U32 || cell === this.cells[cellIndex]) {
+        return bucket;
+      }
+
+      bucket = (bucket + probe + 1) & hashmod; // Hash collision; quadratic probing.
+    }
+
+    throw new Error('Hash table full.'); // Unreachable.
+  }
+}
+
+/**
+ * MurmurHash2
+ *
+ * References:
+ * - https://github.com/mikolalysenko/murmurhash-js/blob/f19136e9f9c17f8cddc216ca3d44ec7c5c502f60/murmurhash2_gc.js#L14
+ * - https://github.com/zeux/meshoptimizer/blob/e47e1be6d3d9513153188216455bdbed40a206ef/src/indexgenerator.cpp#L12
+ */
+function hash(view: DataView, h = 0): number {
+  const m = 0x5bd1e995;
+  const r = 24;
+
+  for (let i = 0, il = view.byteLength / 4; i < il; i++) {
+    let k = view.getUint32(i * 4);
+
+    k = Math.imul(k, m) >>> 0;
+    k = (k ^ (k >> r)) >>> 0;
+    k = Math.imul(k, m) >>> 0;
+
+    h = Math.imul(h, m) >>> 0;
+    h = (h ^ k) >>> 0;
+  }
+
+  return h;
+}
+
+function hashBuckets(initialCount: number) {
+  let buckets = 1;
+  while (buckets < initialCount + initialCount / 4) {
+    buckets *= 2;
+  }
+  return buckets;
+}

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

@@ -21,7 +21,7 @@ import {assert, normalizeObjectKeys} from '../utils.js';
 import {DEFAULT_TILE_RESOLUTION} from '../constants-internal.js';
 import {WidgetSource, type WidgetSourceProps} from './widget-source.js';
 import type {Filters} from '../types.js';
-import {ApiVersion} from '../constants.js';
+import {AggregationTypes, ApiVersion} from '../constants.js';
 import {getApplicableFilters} from '../filters.js';
 
 export type WidgetRemoteSourceProps = WidgetSourceProps;
@@ -76,7 +76,7 @@ export abstract class WidgetRemoteSource<
     } = options;
     const {column, operation, operationColumn, operationExp} = params;
 
-    if (operation === 'custom') {
+    if (operation === AggregationTypes.Custom) {
       assert(operationExp, 'operationExp is required for custom operation');
     }
 
@@ -148,7 +148,7 @@ export abstract class WidgetRemoteSource<
 
     type FormulaModelResponse = {rows: {value: number}[]};
 
-    if (operation === 'custom') {
+    if (operation === AggregationTypes.Custom) {
       assert(operationExp, 'operationExp is required for custom operation');
     }
 
@@ -161,7 +161,7 @@ export abstract class WidgetRemoteSource<
       },
       params: {
         column: column ?? '*',
-        operation: operation ?? 'count',
+        operation: operation ?? AggregationTypes.Count,
         operationExp,
       },
       opts: {signal, headers: this.props.headers},
@@ -331,7 +331,7 @@ export abstract class WidgetRemoteSource<
       splitByCategoryValues,
     } = params;
 
-    if (operation === 'custom') {
+    if (operation === AggregationTypes.Custom) {
       assert(operationExp, 'operationExp is required for custom operation');
     }
 

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

@@ -39,6 +39,7 @@ import {WidgetSource} from './widget-source.js';
 import {booleanEqual} from '@turf/boolean-equal';
 import type {WidgetTilesetSourceProps} from './widget-tileset-source.js';
 import {getApplicableFilters} from '../filters.js';
+import {AggregationTypes} from '../constants.js';
 
 // TODO(cleanup): Parameter defaults in source functions and widget API calls are
 // currently duplicated and possibly inconsistent. Consider consolidating and
@@ -73,14 +74,13 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
     this._features.length = 0;
   }
 
-  protected _extractTileFeatures(spatialFilter: SpatialFilter) {
+  protected _extractTileFeatures(spatialFilter?: SpatialFilter) {
     // When spatial filter has not changed, don't redo extraction. If tiles or
     // tile extract options change, features will have been cleared already.
     const prevInputs = this._tileFeatureExtractPreviousInputs;
     if (
       this._features.length &&
-      prevInputs.spatialFilter &&
-      booleanEqual(prevInputs.spatialFilter, spatialFilter)
+      spatialFilterEquals(prevInputs.spatialFilter, spatialFilter)
     ) {
       return;
     }
@@ -120,7 +120,7 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
 
   async getFormula({
     column = '*',
-    operation = 'count',
+    operation = AggregationTypes.Count,
     joinOperation,
     filters,
     filterOwner,
@@ -132,16 +132,16 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
       filterOwner
     );
 
-    if (filteredFeatures.length === 0 && operation !== 'count') {
+    if (filteredFeatures.length === 0 && operation !== AggregationTypes.Count) {
       return {value: null};
     }
 
-    if (operation === 'custom') {
+    if (operation === AggregationTypes.Custom) {
       throw new Error('Custom aggregation not supported for tilesets');
     }
 
     // Column is required except when operation is 'count'.
-    if ((column && column !== '*') || operation !== 'count') {
+    if ((column && column !== '*') || operation !== AggregationTypes.Count) {
       assertColumn(this._features, column);
     }
 
@@ -152,7 +152,7 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
   }
 
   override async getHistogram({
-    operation = 'count',
+    operation = AggregationTypes.Count,
     ticks,
     column,
     joinOperation,
@@ -183,7 +183,7 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
 
   override async getCategories({
     column,
-    operation = 'count',
+    operation = AggregationTypes.Count,
     operationColumn,
     joinOperation,
     filters,
@@ -382,7 +382,6 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
     filters?: Record<string, Filter>,
     filterOwner?: string
   ): FeatureData[] {
-    assert(spatialFilter, 'spatialFilter required for tilesets');
     this._extractTileFeatures(spatialFilter);
     return applyFilters(
       this._features,
@@ -421,3 +420,9 @@ function normalizeColumns(columns: string | string[]): string[] {
       ? [columns]
       : [];
 }
+
+function spatialFilterEquals(a?: SpatialFilter, b?: SpatialFilter) {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  return booleanEqual(a, b);
+}