@uwdata/mosaic-core 0.7.1 → 0.9.0

package/src/QueryManager.js

@@ -5,48 +5,51 @@ import { queryResult } from './util/query-result.js';
 
 export const Priority = { High: 0, Normal: 1, Low: 2 };
 
-export function QueryManager() {
-  const queue = priorityQueue(3);
-  let db;
-  let clientCache;
-  let logger;
-  let recorders = [];
-  let pending = null;
-  let consolidate;
-
-  function next() {
-    if (pending || queue.isEmpty()) return;
-    const { request, result } = queue.next();
-    pending = submit(request, result);
-    pending.finally(() => { pending = null; next(); });
+export class QueryManager {
+  constructor() {
+    this.queue = priorityQueue(3);
+    this.db = null;
+    this.clientCache = null;
+    this._logger = null;
+    this._logQueries = false;
+    this.recorders = [];
+    this.pending = null;
+    this._consolidate = null;
   }
 
-  function enqueue(entry, priority = Priority.Normal) {
-    queue.insert(entry, priority);
-    next();
+  next() {
+    if (this.pending || this.queue.isEmpty()) return;
+    const { request, result } = this.queue.next();
+    this.pending = this.submit(request, result);
+    this.pending.finally(() => { this.pending = null; this.next(); });
   }
 
-  function recordQuery(sql) {
-    if (recorders.length && sql) {
-      recorders.forEach(rec => rec.add(sql));
+  enqueue(entry, priority = Priority.Normal) {
+    this.queue.insert(entry, priority);
+    this.next();
+  }
+
+  recordQuery(sql) {
+    if (this.recorders.length && sql) {
+      this.recorders.forEach(rec => rec.add(sql));
     }
   }
 
-  async function submit(request, result) {
+  async submit(request, result) {
     try {
       const { query, type, cache = false, record = true, options } = request;
       const sql = query ? `${query}` : null;
 
       // update recorders
       if (record) {
-        recordQuery(sql);
+        this.recordQuery(sql);
       }
 
       // check query cache
       if (cache) {
-        const cached = clientCache.get(sql);
+        const cached = this.clientCache.get(sql);
         if (cached) {
-          logger.debug('Cache');
+          this._logger.debug('Cache');
           result.fulfill(cached);
           return;
         }
@@ -54,80 +57,85 @@ export function QueryManager() {
 
       // issue query, potentially cache result
       const t0 = performance.now();
-      const data = await db.query({ type, sql, ...options });
-      if (cache) clientCache.set(sql, data);
-      logger.debug(`Request: ${(performance.now() - t0).toFixed(1)}`);
+      if (this._logQueries) {
+        this._logger.debug('Query', { type, sql, ...options });
+      }
+      const data = await this.db.query({ type, sql, ...options });
+      if (cache) this.clientCache.set(sql, data);
+      this._logger.debug(`Request: ${(performance.now() - t0).toFixed(1)}`);
       result.fulfill(data);
     } catch (err) {
       result.reject(err);
     }
   }
 
-  return {
-    cache(value) {
-      return value !== undefined
-        ? (clientCache = value === true ? lruCache() : (value || voidCache()))
-        : clientCache;
-    },
-
-    logger(value) {
-      return value ? (logger = value) : logger;
-    },
-
-    connector(connector) {
-      return connector ? (db = connector) : db;
-    },
-
-    consolidate(flag) {
-      if (flag && !consolidate) {
-        consolidate = consolidator(enqueue, clientCache, recordQuery);
-      } else if (!flag && consolidate) {
-        consolidate = null;
-      }
-    },
-
-    request(request, priority = Priority.Normal) {
-      const result = queryResult();
-      const entry = { request, result };
-      if (consolidate) {
-        consolidate.add(entry, priority);
-      } else {
-        enqueue(entry, priority);
-      }
-      return result;
-    },
-
-    cancel(requests) {
-      const set = new Set(requests);
-      queue.remove(({ result }) => set.has(result));
-    },
-
-    clear() {
-      queue.remove(({ result }) => {
-        result.reject('Cleared');
-        return true;
-      });
-    },
-
-    record() {
-      let state = [];
-      const recorder = {
-        add(query) {
-          state.push(query);
-        },
-        reset() {
-          state = [];
-        },
-        snapshot() {
-          return state.slice();
-        },
-        stop() {
-          recorders = recorders.filter(x => x !== recorder);
-          return state;
-        }
-      };
-      recorders.push(recorder);
-      return recorder;
+  cache(value) {
+    return value !== undefined
+      ? (this.clientCache = value === true ? lruCache() : (value || voidCache()))
+      : this.clientCache;
+  }
+
+  logger(value) {
+    return value ? (this._logger = value) : this._logger;
+  }
+
+  logQueries(value) {
+    return value !== undefined ? this._logQueries = !!value : this._logQueries;
+  }
+
+  connector(connector) {
+    return connector ? (this.db = connector) : this.db;
+  }
+
+  consolidate(flag) {
+    if (flag && !this._consolidate) {
+      this._consolidate = consolidator(this.enqueue.bind(this), this.clientCache, this.recordQuery.bind(this));
+    } else if (!flag && this._consolidate) {
+      this._consolidate = null;
+    }
+  }
+
+  request(request, priority = Priority.Normal) {
+    const result = queryResult();
+    const entry = { request, result };
+    if (this._consolidate) {
+      this._consolidate.add(entry, priority);
+    } else {
+      this.enqueue(entry, priority);
     }
-  };
+    return result;
+  }
+
+  cancel(requests) {
+    const set = new Set(requests);
+    this.queue.remove(({ result }) => set.has(result));
+  }
+
+  clear() {
+    this.queue.remove(({ result }) => {
+      result.reject('Cleared');
+      return true;
+    });
+  }
+
+  record() {
+    let state = [];
+    const recorder = {
+      add(query) {
+        state.push(query);
+      },
+      reset() {
+        state = [];
+      },
+      snapshot() {
+        return state.slice();
+      },
+      stop() {
+        this.recorders = this.recorders.filter(x => x !== recorder);
+        return state;
+      }
+    };
+    this.recorders.push(recorder);
+    return recorder;
+  }
 }

package/src/Selection.js

@@ -4,7 +4,7 @@ import { Param } from './Param.js';
 /**
  * Test if a value is a Selection instance.
  * @param {*} x The value to test.
- * @returns {boolean} True if the input is a Selection, false otherwise.
+ * @returns {x is Selection} True if the input is a Selection, false otherwise.
  */
 export function isSelection(x) {
   return x instanceof Selection;
@@ -76,7 +76,7 @@ export class Selection extends Param {
 
   /**
    * Create a cloned copy of this Selection instance.
-   * @returns {this} A clone of this selection.
+   * @returns {Selection} A clone of this selection.
    */
   clone() {
     const s = new Selection(this._resolver);
@@ -88,7 +88,7 @@ export class Selection extends Param {
    * Create a clone of this Selection with clauses corresponding
    * to the provided source removed.
    * @param {*} source The clause source to remove.
-   * @returns {this} A cloned and updated Selection.
+   * @returns {Selection} A cloned and updated Selection.
    */
   remove(source) {
     const s = this.clone();
@@ -98,19 +98,17 @@ export class Selection extends Param {
   }
 
   /**
-   * The current active (most recently updated) selection clause.
+   * The selection clause resolver.
    */
-  get active() {
-    return this.clauses.active;
+  get resolver() {
+    return this._resolver;
   }
 
   /**
-   * The value corresponding to the current active selection clause.
-   * This method ensures compatibility where a normal Param is expected.
+   * Indicate if this selection has a single resolution strategy.
    */
-  get value() {
-    // return value of the active clause
-    return this.active?.value;
+  get single() {
+    return this._resolver.single;
   }
 
   /**
@@ -121,10 +119,27 @@ export class Selection extends Param {
   }
 
   /**
-   * Indicate if this selection has a single resolution strategy.
+   * The current active (most recently updated) selection clause.
    */
-  get single() {
-    return this._resolver.single;
+  get active() {
+    return this.clauses.active;
+  }
+
+  /**
+   * The value corresponding to the current active selection clause.
+   * This method ensures compatibility where a normal Param is expected.
+   */
+  get value() {
+    return this.active?.value;
+  }
+
+  /**
+   * The value corresponding to a given source. Returns undefined if
+   * this selection does not include a clause from this source.
+   * @param {*} source The clause source to look up the value for.
+   */
+  valueFor(source) {
+    return this.clauses.find(c => c.source === source)?.value;
   }
 
   /**
@@ -168,9 +183,9 @@ export class Selection extends Param {
    * Upon value-typed updates, returns a dispatch queue filter function.
    * The return value depends on the selection resolution strategy.
    * @param {string} type The event type.
-   * @param {*} value The input event value.
-   * @returns {*} For value-typed events, returns a dispatch queue filter
-   *  function. Otherwise returns null.
+   * @param {*} value The new event value that will be enqueued.
+   * @returns {(value: *) => boolean|null} For value-typed events,
+   *  returns a dispatch queue filter function. Otherwise returns null.
    */
   emitQueueFilter(type, value) {
     return type === 'value'
@@ -285,5 +300,6 @@ export class SelectionResolver {
       const source = value.active?.source;
       return clauses => clauses.active?.source !== source;
     }
+    return null;
   }
 }

package/src/SelectionClause.js

@@ -0,0 +1,147 @@
+import {
+  SQLExpression, and, contains, isBetween, isNotDistinct, literal,
+  or, prefix, regexp_matches, suffix
+} from '@uwdata/mosaic-sql';
+import { MosaicClient } from './MosaicClient.js';
+
+/**
+ * @typedef {import('./util/selection-types.js').SelectionClause} SelectionClause
+ * @typedef {import('./util/selection-types.js').Scale} Scale
+ * @typedef {import('./util/selection-types.js').Extent} Extent
+ * @typedef {import('./util/selection-types.js').MatchMethod} MatchMethod
+ * @typedef {import('./util/selection-types.js').BinMethod} BinMethod
+ * @typedef {SQLExpression | string} Field
+ */
+
+/**
+ * Generate a selection clause for a single selected point value.
+ * @param {Field} field The table column or expression to select.
+ * @param {*} value The selected value.
+ * @param {object} options Additional clause properties.
+ * @param {*} options.source The source component generating this clause.
+ * @param {Set<MosaicClient>} [options.clients] The Mosaic clients associated
+ *  with this clause. These clients are not filtered by this clause in
+ *  cross-filtering contexts.
+ * @returns {SelectionClause} The generated selection clause.
+ */
+export function point(field, value, { source, clients = undefined }) {
+  /** @type {SQLExpression | null} */
+  const predicate = value !== undefined
+    ? isNotDistinct(field, literal(value))
+    : null;
+  return {
+    meta: { type: 'point' },
+    source,
+    clients,
+    value,
+    predicate
+  };
+}
+
+/**
+ * Generate a selection clause for multiple selected point values.
+ * @param {Field[]} fields The table columns or expressions to select.
+ * @param {any[][]} value The selected values, as an array of arrays where
+ *  each subarray contains values corresponding to each *fields* entry.
+ * @param {object} options Additional clause properties.
+ * @param {*} options.source The source component generating this clause.
+ * @param {Set<MosaicClient>} [options.clients] The Mosaic clients associated
+ *  with this clause. These clients are not filtered by this clause in
+ *  cross-filtering contexts.
+ * @returns {SelectionClause} The generated selection clause.
+ */
+export function points(fields, value, { source, clients = undefined }) {
+  /** @type {SQLExpression | null} */
+  let predicate = null;
+  if (value) {
+    const clauses = value.map(vals => {
+      const list = vals.map((v, i) => isNotDistinct(fields[i], literal(v)));
+      return list.length > 1 ? and(list) : list[0];
+    });
+    predicate = clauses.length > 1 ? or(clauses) : clauses[0];
+  }
+  return {
+    meta: { type: 'point' },
+    source,
+    clients,
+    value,
+    predicate
+  };
+}
+
+/**
+ * Generate a selection clause for a selected 1D interval.
+ * @param {Field} field The table column or expression to select.
+ * @param {Extent} value The selected interval as a [lo, hi] array.
+ * @param {object} options Additional clause properties.
+ * @param {*} options.source The source component generating this clause.
+ * @param {Set<MosaicClient>} [options.clients] The Mosaic clients associated
+ *  with this clause. These clients are not filtered by this clause in
+ *  cross-filtering contexts.
+ * @param {Scale} [options.scale] The scale mapping descriptor.
+ * @param {BinMethod} [options.bin] A binning method hint.
+ * @param {number} [options.pixelSize=1] The interactive pixel size.
+ * @returns {SelectionClause} The generated selection clause.
+ */
+export function interval(field, value, {
+  source, clients, bin, scale, pixelSize = 1
+}) {
+  /** @type {SQLExpression | null} */
+  const predicate = value != null ? isBetween(field, value) : null;
+  /** @type {import('./util/selection-types.js').IntervalMetadata} */
+  const meta = { type: 'interval', scales: [scale], bin, pixelSize };
+  return { meta, source, clients, value, predicate };
+}
+
+/**
+ * Generate a selection clause for multiple selected intervals.
+ * @param {Field[]} fields The table columns or expressions to select.
+ * @param {Extent[]} value The selected intervals, as an array of extents.
+ * @param {object} options Additional clause properties.
+ * @param {*} options.source The source component generating this clause.
+ * @param {Set<MosaicClient>} [options.clients] The Mosaic clients associated
+ *  with this clause. These clients are not filtered by this clause in
+ *  cross-filtering contexts.
+ * @param {Scale[]} [options.scales] The scale mapping descriptors,
+ *  in an order matching the given *fields* and *value* extents.
+ * @param {BinMethod} [options.bin] A binning method hint.
+ * @param {number} [options.pixelSize=1] The interactive pixel size.
+ * @returns {SelectionClause} The generated selection clause.
+ */
+export function intervals(fields, value, {
+  source, clients, bin, scales = [], pixelSize = 1
+}) {
+  /** @type {SQLExpression | null} */
+  const predicate = value != null
+    ? and(fields.map((f, i) => isBetween(f, value[i])))
+    : null;
+  /** @type {import('./util/selection-types.js').IntervalMetadata} */
+  const meta = { type: 'interval', scales, bin, pixelSize };
+  return { meta, source, clients, value, predicate };
+}
+
+const MATCH_METHODS = { contains, prefix, suffix, regexp: regexp_matches };
+
+/**
+ * Generate a selection clause for text search matching.
+ * @param {Field} field The table column or expression to select.
+ * @param {string} value The selected text search query string.
+ * @param {object} options Additional clause properties.
+ * @param {*} options.source The source component generating this clause.
+ * @param {Set<MosaicClient>} [options.clients] The Mosaic clients associated
+ *  with this clause. These clients are not filtered by this clause in
+ *  cross-filtering contexts.
+ * @param {MatchMethod} [options.method] The
+ *  text matching method to use. Defaults to `'contains'`.
+ * @returns {SelectionClause} The generated selection clause.
+ */
+export function match(field, value, {
+  source, clients = undefined, method = 'contains'
+}) {
+  let fn = MATCH_METHODS[method];
+  /** @type {SQLExpression | null} */
+  const predicate = value ? fn(field, literal(value)) : null;
+  /** @type {import('./util/selection-types.js').MatchMetadata} */
+  const meta = { type: 'match', method };
+  return { meta, source, clients, value, predicate };
+}

package/src/connectors/rest.js

@@ -2,6 +2,13 @@ import { tableFromIPC } from 'apache-arrow';
 
 export function restConnector(uri = 'http://localhost:3000/') {
   return {
+    /**
+     * Query the DuckDB server.
+     * @param {object} query
+     * @param {'exec' | 'arrow' | 'json'} [query.type] The query type: 'exec', 'arrow', or 'json'.
+     * @param {string} query.sql A SQL query string.
+     * @returns the query result
+     */
     async query(query) {
       const req = fetch(uri, {
         method: 'POST',

package/src/connectors/socket.js

@@ -81,6 +81,13 @@ export function socketConnector(uri = 'ws://localhost:3000/') {
     get connected() {
       return connected;
     },
+    /**
+     * Query the DuckDB server.
+     * @param {object} query
+     * @param {'exec' | 'arrow' | 'json'} [query.type] The query type: 'exec', 'arrow', or 'json'.
+     * @param {string} query.sql A SQL query string.
+     * @returns the query result
+     */
     query(query) {
       return new Promise(
         (resolve, reject) => enqueue(query, resolve, reject)

package/src/connectors/wasm.js

@@ -22,7 +22,7 @@ export function wasmConnector(options = {}) {
   /**
    * Get the backing DuckDB-WASM instance.
    * Will lazily initialize DuckDB-WASM if not already loaded.
-   * @returns {duckdb.AsyncDuckDB} The DuckDB-WASM instance.
+   * @returns {Promise<duckdb.AsyncDuckDB>} The DuckDB-WASM instance.
    */
   async function getDuckDB() {
     if (!db) await load();
@@ -32,7 +32,7 @@ export function wasmConnector(options = {}) {
   /**
    * Get the backing DuckDB-WASM connection.
    * Will lazily initialize DuckDB-WASM if not already loaded.
-   * @returns {duckdb.AsyncDuckDBConnection} The DuckDB-WASM connection.
+   * @returns {Promise<duckdb.AsyncDuckDBConnection>} The DuckDB-WASM connection.
    */
   async function getConnection() {
     if (!con) await load();
@@ -45,7 +45,7 @@ export function wasmConnector(options = {}) {
     /**
      * Query the DuckDB-WASM instance.
      * @param {object} query
-     * @param {string} [query.type] The query type: 'exec', 'arrow', or 'json'.
+     * @param {'exec' | 'arrow' | 'json'} [query.type] The query type: 'exec', 'arrow', or 'json'.
      * @param {string} query.sql A SQL query string.
      * @returns the query result
      */
@@ -55,7 +55,7 @@ export function wasmConnector(options = {}) {
       const result = await con.query(sql);
       return type === 'exec' ? undefined
         : type === 'arrow' ? result
-        : Array.from(result);
+        : result.toArray();
     }
   };
 }

package/src/index.js

@@ -3,6 +3,7 @@ export { Coordinator, coordinator } from './Coordinator.js';
 export { Selection, isSelection } from './Selection.js';
 export { Param, isParam } from './Param.js';
 export { Priority } from './QueryManager.js';
+export { point, points, interval, intervals, match } from './SelectionClause.js';
 
 export { restConnector } from './connectors/rest.js';
 export { socketConnector } from './connectors/socket.js';

package/src/util/AsyncDispatch.js

@@ -16,7 +16,7 @@ export class AsyncDispatch {
   /**
    * Add an event listener callback for the provided event type.
    * @param {string} type The event type.
-   * @param {(value: *) => Promise?} callback The event handler
+   * @param {(value: *) => void | Promise} callback The event handler
    *  callback function to add. If the callback has already been
    *  added for the event type, this method has no effect.
    */
@@ -35,7 +35,7 @@ export class AsyncDispatch {
   /**
    * Remove an event listener callback for the provided event type.
    * @param {string} type The event type.
-   * @param {(value: *) => Promise?} callback The event handler
+   * @param {(value: *) => void | Promise} callback The event handler
    *  callback function to remove.
    */
   removeEventListener(type, callback) {
@@ -64,11 +64,12 @@ export class AsyncDispatch {
    * This default implementation simply returns null, indicating that
    * any other unemitted event values should be dropped (that is, all
    * queued events are filtered)
+   * @param {string} type The event type.
    * @param {*} value The new event value that will be enqueued.
    * @returns {(value: *) => boolean|null} A dispatch queue filter
    *  function, or null if all unemitted event values should be filtered.
    */
-  emitQueueFilter() {
+  emitQueueFilter(type, value) { // eslint-disable-line no-unused-vars
     // removes all pending items
     return null;
   }
@@ -94,20 +95,22 @@ export class AsyncDispatch {
   emit(type, value) {
     const entry = this._callbacks.get(type) || {};
     if (entry.pending) {
+      // an earlier emit is still processing
+      // enqueue the current update, possibly filtering other pending updates
       entry.queue.enqueue(value, this.emitQueueFilter(type, value));
     } else {
       const event = this.willEmit(type, value);
       const { callbacks, queue } = entry;
       if (callbacks?.size) {
-        const promise = Promise
-          .allSettled(Array.from(callbacks, callback => callback(event)))
-          .then(() => {
-            entry.pending = null;
-            if (!queue.isEmpty()) {
-              this.emit(type, queue.dequeue());
-            }
-          });
-        entry.pending = promise;
+        // broadcast update to callbacks, which may return promises
+        // wait until promises resolve, then process pending updates
+        const callbackValues = Array.from(callbacks, cb => cb(event));
+        entry.pending = Promise.allSettled(callbackValues).then(() => {
+          entry.pending = null;
+          if (!queue.isEmpty()) {
+            this.emit(type, queue.dequeue());
+          }
+        });
       }
     }
   }