@uwdata/mosaic-core 0.1.0 → 0.2.0

package/src/Selection.js

@@ -1,82 +1,278 @@
 import { or } from '@uwdata/mosaic-sql';
 import { Param } from './Param.js';
-import { skipClient } from './util/skip-client.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.
+ */
 export function isSelection(x) {
   return x instanceof Selection;
 }
 
+/**
+ * Represents a dynamic set of query filter predicates.
+ */
 export class Selection extends Param {
 
-  static intersect() {
-    return new Selection();
+  /**
+   * Create a new Selection instance with an
+   * intersect (conjunction) resolution strategy.
+   * @param {object} [options] The selection options.
+   * @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.
+   * @returns {Selection} The new Selection instance.
+   */
+  static intersect({ cross = false } = {}) {
+    return new Selection(new SelectionResolver({ cross }));
   }
 
-  static crossfilter() {
-    return new Selection({ cross: true });
+  /**
+   * Create a new Selection instance with a
+   * union (disjunction) resolution strategy.
+   * @param {object} [options] The selection options.
+   * @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.
+   * @returns {Selection} The new Selection instance.
+   */
+  static union({ cross = false } = {}) {
+    return new Selection(new SelectionResolver({ cross, union: true }));
   }
 
-  static union() {
-    return new Selection({ union: true });
+  /**
+   * Create a new Selection instance with a singular resolution strategy
+   * that keeps only the most recent selection clause.
+   * @param {object} [options] The selection options.
+   * @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.
+   * @returns {Selection} The new Selection instance.
+   */
+  static single({ cross = false } = {}) {
+    return new Selection(new SelectionResolver({ cross, single: true }));
   }
 
-  static single() {
-    return new Selection({ single: true });
+  /**
+   * Create a new Selection instance with a
+   * cross-filtered intersect resolution strategy.
+   * @returns {Selection} The new Selection instance.
+   */
+  static crossfilter() {
+    return new Selection(new SelectionResolver({ cross: true }));
   }
 
-  constructor({ union, cross, single } = {}) {
+  /**
+   * Create a new Selection instance.
+   * @param {SelectionResolver} resolver The selection resolution
+   *  strategy to apply.
+   */
+  constructor(resolver = new SelectionResolver()) {
     super([]);
-    this.active = null;
-    this.union = !!union;
-    this.cross = !!cross;
-    this.single = !!single;
+    this._resolved = this._value;
+    this._resolver = resolver;
   }
 
+  /**
+   * Create a cloned copy of this Selection instance.
+   * @returns {this} A clone of this selection.
+   */
   clone() {
-    const s = new Selection();
-    s.active = this.active;
-    s.union = this.union;
-    s.cross = this.cross;
-    s._value = this._value;
+    const s = new Selection(this._resolver);
+    s._value = s._resolved = this._value;
     return s;
   }
 
+  /**
+   * Create a clone of this Selection with clauses corresponding
+   * to provided source removed.
+   * @param {*} source The clause source to remove.
+   * @returns {this} A cloned and updated Selection.
+   */
+  remove(source) {
+    const s = this.clone();
+    s._value = s._resolved = s._resolver.resolve(this._resolved, { source });
+    s._value.active = { source };
+    return s;
+  }
+
+  /**
+   * The current active (most recently updated) selection clause.
+   */
+  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 value of most recently added clause
-    const { clauses } = this;
-    return clauses[clauses.length - 1]?.value;
+    // return value of the active clause
+    return this.active?.value;
   }
 
+  /**
+   * The current array of selection clauses.
+   */
   get clauses() {
     return super.value;
   }
 
+  /**
+   * Emit an activate event with the given selection clause.
+   * @param {*} clause The clause repesenting the potential activation.
+   */
   activate(clause) {
     this.emit('activate', clause);
   }
 
+  /**
+   * Update the selection with a new selection clause.
+   * @param {*} clause The selection clause to add.
+   * @returns {this} This Selection instance.
+   */
   update(clause) {
+    // we maintain an up-to-date list of all resolved clauses
+    // this ensures consistent clause state across unemitted event values
+    this._resolved = this._resolver.resolve(this._resolved, clause, true);
+    this._resolved.active = clause;
+    return super.update(this._resolved);
+  }
+
+  /**
+   * Upon value-typed updates, sets the current clause list to the
+   * input value and returns the active clause value.
+   * @param {string} type The event type.
+   * @param {*} value The input event value.
+   * @returns {*} For value-typed events, returns the active clause
+   *  values. Otherwise returns the input event value as-is.
+   */
+  willEmit(type, value) {
+    if (type === 'value') {
+      this._value = value;
+      return this.value;
+    }
+    return value;
+  }
+
+  /**
+   * 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.
+   */
+  emitQueueFilter(type, value) {
+    return type === 'value'
+      ? this._resolver.queueFilter(value)
+      : null;
+  }
+
+  /**
+   * Indicates if a selection clause should not be applied to a given client.
+   * The return value depends on the selection resolution strategy.
+   * @param {*} client The selection clause.
+   * @param {*} clause The client to test.
+   * @returns True if the client should be skipped, false otherwise.
+   */
+  skip(client, clause) {
+    return this._resolver.skip(client, clause);
+  }
+
+  /**
+   * Return a selection query predicate for the given client.
+   * @param {*} client The client whose data may be filtered.
+   * @returns {*} The query predicate for filtering client data,
+   *  based on the current state of this selection.
+   */
+  predicate(client) {
+    const { clauses } = this;
+    return this._resolver.predicate(clauses, clauses.active, client);
+  }
+}
+
+/**
+ * Implements selection clause resolution strategies.
+ */
+export class SelectionResolver {
+
+  /**
+   * Create a new selection resolved instance.
+   * @param {object} [options] The resolution strategy options.
+   * @param {boolean} [options.union=false] Boolean flag to indicate a union strategy.
+   *  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.
+   */
+  constructor({ union, cross, single } = {}) {
+    this.union = !!union;
+    this.cross = !!cross;
+    this.single = !!single;
+  }
+
+  /**
+   * Resolve a list of selection clauses according to the resolution strategy.
+   * @param {*[]} clauseList An array of selection clauses.
+   * @param {*} clause A new selection clause to add.
+   * @returns {*[]} An updated array of selection clauses.
+   */
+  resolve(clauseList, clause, reset = false) {
     const { source, predicate } = clause;
-    this.active = clause;
-    const clauses = this.single ? [] : this.clauses.filter(c => source !== c.source);
+    const filtered = clauseList.filter(c => source !== c.source);
+    const clauses = this.single ? [] : filtered;
+    if (this.single && reset) filtered.forEach(c => c.source?.reset?.());
     if (predicate) clauses.push(clause);
-    return super.update(clauses);
+    return clauses;
   }
 
-  predicate(client) {
-    const { active, clauses, cross, union } = this;
+  /**
+   * Indicates if a selection clause should not be applied to a given client.
+   * The return value depends on the resolution strategy.
+   * @param {*} client The selection clause.
+   * @param {*} clause The client to test.
+   * @returns True if the client should be skipped, false otherwise.
+   */
+  skip(client, clause) {
+    return this.cross && clause?.clients?.has(client);
+  }
+
+  /**
+   * Return a selection query predicate for the given client.
+   * @param {*[]} clauseList An array of selection clauses.
+   * @param {*} active The current active selection clause.
+   * @param {*} client The client whose data may be filtered.
+   * @returns {*} The query predicate for filtering client data,
+   *  based on the current state of this selection.
+   */
+  predicate(clauseList, active, client) {
+    const { union } = this;
 
     // do nothing if cross-filtering and client is currently active
-    if (cross && skipClient(client, active)) return undefined;
+    if (this.skip(client, active)) return undefined;
 
     // remove client-specific predicates if cross-filtering
-    const list = (cross
-      ? clauses.filter(clause => !skipClient(client, clause))
-      : clauses
-    ).map(s => s.predicate);
+    const predicates = clauseList
+      .filter(clause => !this.skip(client, clause))
+      .map(clause => clause.predicate);
 
     // return appropriate conjunction or disjunction
     // an array of predicates is implicitly conjunctive
-    return union && list.length > 1 ? or(list) : list;
+    return union && predicates.length > 1 ? or(predicates) : predicates;
+  }
+
+  /**
+   * Returns a filter function for queued selection updates.
+   * @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.
+   */
+  queueFilter(value) {
+    if (this.cross) {
+      const source = value.active?.source;
+      return clauses => clauses.active?.source !== source;
+    }
   }
 }

package/src/{clients → connectors}/rest.js

@@ -1,6 +1,6 @@
 import { tableFromIPC } from 'apache-arrow';
 
-export function restClient(uri = 'http://localhost:3000/') {
+export function restConnector(uri = 'http://localhost:3000/') {
   return {
     async query(query) {
       const req = fetch(uri, {

package/src/{clients → connectors}/socket.js

@@ -1,6 +1,6 @@
 import { tableFromIPC } from 'apache-arrow';
 
-export function socketClient(uri = 'ws://localhost:3000/') {
+export function socketConnector(uri = 'ws://localhost:3000/') {
   const queue = [];
   let connected = false;
   let request = null;

package/src/{clients → connectors}/wasm.js

@@ -1,6 +1,6 @@
 import * as duckdb from '@duckdb/duckdb-wasm';
 
-export async function wasmClient(options) {
+export async function wasmConnector(options) {
   const db = await initDatabase(options);
   const con = await db.connect();
 

package/src/index.js

@@ -2,9 +2,12 @@ export { MosaicClient } from './MosaicClient.js';
 export { Coordinator, coordinator } from './Coordinator.js';
 export { Selection, isSelection } from './Selection.js';
 export { Param, isParam } from './Param.js';
+export { Priority } from './QueryManager.js';
+
+export { restConnector } from './connectors/rest.js';
+export { socketConnector } from './connectors/socket.js';
+export { wasmConnector } from './connectors/wasm.js';
+
 export { distinct } from './util/distinct.js';
-export { sqlFrom } from './util/sql-from.js';
+export { synchronizer } from './util/synchronizer.js';
 export { throttle } from './util/throttle.js';
-export { restClient } from './clients/rest.js';
-export { socketClient } from './clients/socket.js';
-export { wasmClient } from './clients/wasm.js';

package/src/util/AsyncDispatch.js

@@ -0,0 +1,180 @@
+/**
+ * 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.
+ */
+export class AsyncDispatch {
+
+  /**
+   * Create a new asynchronous dispatcher instance.
+   */
+  constructor() {
+    this._callbacks = new Map;
+  }
+
+  /**
+   * Add an event listener callback for the provided event type.
+   * @param {string} type The event type.
+   * @param {(value: *) => 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.
+   */
+  addEventListener(type, callback) {
+    if (!this._callbacks.has(type)) {
+      this._callbacks.set(type, {
+        callbacks: new Set,
+        pending: null,
+        queue: new DispatchQueue()
+      });
+    }
+    const entry = this._callbacks.get(type);
+    entry.callbacks.add(callback);
+  }
+
+  /**
+   * Remove an event listener callback for the provided event type.
+   * @param {string} type The event type.
+   * @param {(value: *) => Promise?} callback The event handler
+   *  callback function to remove.
+   */
+  removeEventListener(type, callback) {
+    const entry = this._callbacks.get(type);
+    if (entry) {
+      entry.callbacks.delete(callback);
+    }
+  }
+
+  /**
+   * Lifecycle method that returns the event value to emit.
+   * This default implementation simply returns the input value as-is.
+   * Subclasses may override this method to implement custom transformations
+   * prior to emitting an event value to all listeners.
+   * @param {string} type The event type.
+   * @param {*} value The event value.
+   * @returns The (possibly transformed) event value to emit.
+   */
+  willEmit(type, value) {
+    return value;
+  }
+
+  /**
+   * Lifecycle method that returns a filter function for updating the
+   * 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)
+   * @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() {
+    // removes all pending items
+    return null;
+  }
+
+  /**
+   * Cancel all unemitted event values for the given event type.
+   * @param {string} type The event type.
+   */
+  cancel(type) {
+    const entry = this._callbacks.get(type);
+    entry?.queue.clear();
+  }
+
+  /**
+   * Emit an event value to listeners for the given event type.
+   * If a previous emit has not yet resolved, the event value
+   * will be queued to be emitted later.
+   * The actual event value given to listeners will be the result
+   * of passing the input value through the emitValue() method.
+   * @param {string} type The event type.
+   * @param {*} value The event value.
+   */
+  emit(type, value) {
+    const entry = this._callbacks.get(type) || {};
+    if (entry.pending) {
+      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;
+      }
+    }
+  }
+}
+
+/**
+ * Queue for managing unemitted event values.
+ */
+export class DispatchQueue {
+
+  /**
+   * Create a new dispatch queue instance.
+   */
+  constructor() {
+    this.clear();
+  }
+
+  /**
+   * Clear the queue state of all event values.
+   */
+  clear() {
+    this.next = null;
+  }
+
+  /**
+   * Indicate if the queue is empty.
+   * @returns {boolean} True if queue is empty, false otherwise.
+   */
+  isEmpty() {
+    return !this.next;
+  }
+
+  /**
+   * Add a new value to the queue, and optionally filter the
+   * current queue content in response.
+   * @param {*} value The value to add.
+   * @param {(value: *) => boolean} [filter] An optional filter
+   *  function to apply to existing queue content. If unspecified
+   *  or falsy, all previously queued values are removed. Otherwise,
+   *  the provided function is applied to all queue entries. The
+   *  entry is retained if the filter function returns a truthy value,
+   *  otherwise the entry is removed.
+   */
+  enqueue(value, filter) {
+    const tail = { value };
+    if (filter && this.next) {
+      let curr = this;
+      while (curr.next) {
+        if (filter(curr.next.value)) {
+          curr = curr.next;
+        } else {
+          curr.next = curr.next.next;
+        }
+      }
+      curr.next = tail;
+    } else {
+      this.next = tail;
+    }
+  }
+
+  /**
+   * Remove and return the next queued event value.
+   * @returns {*} The next event value in the queue.
+   */
+  dequeue() {
+    const { next } = this;
+    this.next = next?.next;
+    return next?.value;
+  }
+}

package/src/util/cache.js

@@ -0,0 +1,58 @@
+const requestIdle = typeof requestIdleCallback !== 'undefined'
+  ? requestIdleCallback
+  : setTimeout;
+
+export const voidCache = () => ({
+  get: () => undefined,
+  set: (key, value) => value,
+  clear: () => {}
+});
+
+export function lruCache({
+  max = 1000, // max entries
+  ttl = 3 * 60 * 60 * 1000 // time-to-live, default 3 hours
+} = {}) {
+  let cache = new Map;
+
+  function evict() {
+    const expire = performance.now() - ttl;
+    let lruKey = null;
+    let lruLast = Infinity;
+
+    for (const [key, value] of cache) {
+      const { last } = value;
+
+      // least recently used entry seen so far
+      if (last < lruLast) {
+        lruKey = key;
+        lruLast = last;
+      }
+
+      // remove if time since last access exceeds ttl
+      if (expire > last) {
+        cache.delete(key);
+      }
+    }
+
+    // remove lru entry
+    if (lruKey) {
+      cache.delete(lruKey);
+    }
+  }
+
+  return {
+    get(key) {
+      const entry = cache.get(key);
+      if (entry) {
+        entry.last = performance.now();
+        return entry.value;
+      }
+    },
+    set(key, value) {
+      cache.set(key, { last: performance.now(), value });
+      if (cache.size > max) requestIdle(evict);
+      return value;
+    },
+    clear() { cache = new Map; }
+  };
+}

package/src/util/priority-queue.js

@@ -0,0 +1,85 @@
+/**
+ * Create a new priority queue instance.
+ * @param {number} ranks An integer number of rank-order priority levels.
+ * @returns A priority queue instance.
+ */
+export function priorityQueue(ranks) {
+	// one list for each integer priority level
+	const queue = Array.from(
+		{ length: ranks },
+		() => ({ head: null, tail: null })
+	);
+
+	return {
+		/**
+		 * Indicate if the queue is empty.
+		 * @returns [boolean] true if empty, false otherwise.
+		 */
+		isEmpty() {
+			return queue.every(list => !list.head);
+		},
+
+		/**
+		 * Insert an item into the queue with a given priority rank.
+		 * @param {*} item The item to add.
+		 * @param {number} rank The integer priority rank.
+		 *  Priority ranks are integers starting at zero.
+		 *  Lower ranks indicate higher priority.
+		 */
+		insert(item, rank) {
+			const list = queue[rank];
+			if (!list) {
+				throw new Error(`Invalid queue priority rank: ${rank}`);
+			}
+
+			const node = { item, next: null };
+			if (list.head === null) {
+				list.head = list.tail = node;
+			} else {
+				list.tail = (list.tail.next = node);
+			}
+		},
+
+		/**
+		 * Remove a set of items from the queue, regardless of priority rank.
+		 * If a provided item is not in the queue it will be ignored.
+		 * @param {(item: *) => boolean} test A predicate function to test
+		 * 	if an item should be removed (true to drop, false to keep).
+		 */
+		remove(test) {
+			for (const list of queue) {
+				let { head, tail } = list;
+				for (let prev = null, curr = head; curr; prev = curr, curr = curr.next) {
+					if (test(curr.item)) {
+						if (curr === head) {
+							head = curr.next;
+						} else {
+							prev.next = curr.next;
+						}
+						if (curr === tail) tail = prev || head;
+					}
+				}
+				list.head = head;
+				list.tail = tail;
+			}
+		},
+
+		/**
+		 * Remove and return the next highest priority item.
+		 * @returns {*} The next item in the queue,
+		 *  or undefined if this queue is empty.
+		 */
+		next() {
+			for (const list of queue) {
+				const { head } = list;
+				if (head !== null) {
+					list.head = head.next;
+					if (list.tail === head) {
+						list.tail = null;
+					}
+					return head.item;
+				}
+			}
+		}
+	};
+}