@uwdata/mosaic-core 0.8.0 → 0.10.0

package/src/QueryManager.js

@@ -1,52 +1,55 @@
 import { consolidator } from './QueryConsolidator.js';
 import { lruCache, voidCache } from './util/cache.js';
 import { priorityQueue } from './util/priority-queue.js';
-import { queryResult } from './util/query-result.js';
+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,87 @@ 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 = new 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);
+    if (set.size) {
+      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

@@ -22,10 +22,13 @@ export class Selection extends Param {
    * @param {boolean} [options.cross=false] Boolean flag indicating
    *  cross-filtered resolution. If true, selection clauses will not
    *  be applied to the clients they are associated with.
+   * @param {boolean} [options.empty=false] Boolean flag indicating if a lack
+   *  of clauses should correspond to an empty selection with no records. This
+   *  setting determines the default selection state.
    * @returns {Selection} The new Selection instance.
    */
-  static intersect({ cross = false } = {}) {
-    return new Selection(new SelectionResolver({ cross }));
+  static intersect({ cross = false, empty = false } = {}) {
+    return new Selection(new SelectionResolver({ cross, empty }));
   }
 
   /**
@@ -35,10 +38,13 @@ export class Selection extends Param {
    * @param {boolean} [options.cross=false] Boolean flag indicating
    *  cross-filtered resolution. If true, selection clauses will not
    *  be applied to the clients they are associated with.
+   * @param {boolean} [options.empty=false] Boolean flag indicating if a lack
+   *  of clauses should correspond to an empty selection with no records. This
+   *  setting determines the default selection state.
    * @returns {Selection} The new Selection instance.
    */
-  static union({ cross = false } = {}) {
-    return new Selection(new SelectionResolver({ cross, union: true }));
+  static union({ cross = false, empty = false } = {}) {
+    return new Selection(new SelectionResolver({ cross, empty, union: true }));
   }
 
   /**
@@ -48,19 +54,26 @@ export class Selection extends Param {
    * @param {boolean} [options.cross=false] Boolean flag indicating
    *  cross-filtered resolution. If true, selection clauses will not
    *  be applied to the clients they are associated with.
+   * @param {boolean} [options.empty=false] Boolean flag indicating if a lack
+   *  of clauses should correspond to an empty selection with no records. This
+   *  setting determines the default selection state.
    * @returns {Selection} The new Selection instance.
    */
-  static single({ cross = false } = {}) {
-    return new Selection(new SelectionResolver({ cross, single: true }));
+  static single({ cross = false, empty = false } = {}) {
+    return new Selection(new SelectionResolver({ cross, empty, single: true }));
   }
 
   /**
    * Create a new Selection instance with a
    * cross-filtered intersect resolution strategy.
+   * @param {object} [options] The selection options.
+   * @param {boolean} [options.empty=false] Boolean flag indicating if a lack
+   *  of clauses should correspond to an empty selection with no records. This
+   *  setting determines the default selection state.
    * @returns {Selection} The new Selection instance.
    */
-  static crossfilter() {
-    return new Selection(new SelectionResolver({ cross: true }));
+  static crossfilter({ empty = false } = {}) {
+    return new Selection(new SelectionResolver({ cross: true, empty }));
   }
 
   /**
@@ -98,19 +111,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 +132,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;
   }
 
   /**
@@ -217,11 +245,15 @@ export class SelectionResolver {
    *  If false, an intersection strategy is used.
    * @param {boolean} [options.cross=false] Boolean flag to indicate cross-filtering.
    * @param {boolean} [options.single=false] Boolean flag to indicate single clauses only.
+   * @param {boolean} [options.empty=false] Boolean flag indicating if a lack
+   *  of clauses should correspond to an empty selection with no records. This
+   *  setting determines the default selection state.
    */
-  constructor({ union, cross, single } = {}) {
+  constructor({ union, cross, single, empty } = {}) {
     this.union = !!union;
     this.cross = !!cross;
     this.single = !!single;
+    this.empty = !!empty;
   }
 
   /**
@@ -259,7 +291,11 @@ export class SelectionResolver {
    *  based on the current state of this selection.
    */
   predicate(clauseList, active, client) {
-    const { union } = this;
+    const { empty, union } = this;
+
+    if (empty && !clauseList.length) {
+      return ['FALSE'];
+    }
 
     // do nothing if cross-filtering and client is currently active
     if (this.skip(client, active)) return undefined;

package/src/SelectionClause.js

@@ -0,0 +1,161 @@
+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 clausePoint(field, value, {
+  source,
+  clients = source ? new Set([source]) : 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 clausePoints(fields, value, {
+  source,
+  clients = source ? new Set([source]) : 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 clauseInterval(field, value, {
+  source,
+  clients = source ? new Set([source]) : undefined,
+  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 && [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 clauseIntervals(fields, value, {
+  source,
+  clients = source ? new Set([source]) : undefined,
+  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 clauseMatch(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

@@ -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

@@ -8,12 +8,22 @@ export { restConnector } from './connectors/rest.js';
 export { socketConnector } from './connectors/socket.js';
 export { wasmConnector } from './connectors/wasm.js';
 
+export {
+  clauseInterval,
+  clauseIntervals,
+  clausePoint,
+  clausePoints,
+  clauseMatch
+} from './SelectionClause.js';
+
 export {
   isArrowTable,
   convertArrowArrayType,
   convertArrowValue,
   convertArrowColumn
 } from './util/convert-arrow.js'
+
 export { distinct } from './util/distinct.js';
 export { synchronizer } from './util/synchronizer.js';
 export { throttle } from './util/throttle.js';
+export { toDataColumns } from './util/to-data-columns.js'

package/src/util/AsyncDispatch.js

@@ -1,8 +1,7 @@
 /**
- * Event dispatcher supporting asynchronous updates.
- * If an event handler callback returns a Promise, this dispatcher will
- * wait for all such Promises to settle before dispatching future events
- * of the same type.
+ * Event dispatcher supporting asynchronous updates. If an event handler
+ * callback returns a Promise, the dispatcher waits for all such Promises
+ * to settle before dispatching future events of the same type.
  */
 export class AsyncDispatch {
 
@@ -63,7 +62,7 @@ export class AsyncDispatch {
    * queue of unemitted event values prior to enqueueing a new value.
    * This default implementation simply returns null, indicating that
    * any other unemitted event values should be dropped (that is, all
-   * queued events are filtered)
+   * 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
@@ -83,6 +82,17 @@ export class AsyncDispatch {
     entry?.queue.clear();
   }
 
+  /**
+   * Returns a promise that resolves when any pending updates complete for
+   * the event of the given type currently being processed. The Promise will
+   * resolve immediately if the queue for the given event type is empty.
+   * @param {string} type The event type to wait for.
+   * @returns {Promise} A pending event promise.
+   */
+  async pending(type) {
+    await this._callbacks.get(type)?.pending;
+  }
+
   /**
    * Emit an event value to listeners for the given event type.
    * If a previous emit has not yet resolved, the event value