@uwdata/mosaic-core 0.0.1 → 0.2.0

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/distinct.js

@@ -0,0 +1,14 @@
+export function distinct(a, b) {
+  return a === b ? false
+    : a instanceof Date && b instanceof Date ? +a !== +b
+    : Array.isArray(a) && Array.isArray(b) ? distinctArray(a, b)
+    : true;
+}
+
+export function distinctArray(a, b) {
+  if (a.length !== b.length) return true;
+  for (let i = 0; i < a.length; ++i) {
+    if (a[i] !== b[i]) return true;
+  }
+  return false;
+}

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;
+				}
+			}
+		}
+	};
+}

package/src/util/summarize.js

@@ -0,0 +1,23 @@
+import { Query, count, isNull, max, min } from '@uwdata/mosaic-sql';
+
+export const Count = 'count';
+export const Nulls = 'nulls';
+export const Max = 'max';
+export const Min = 'min';
+export const Distinct = 'distinct';
+
+export const Stats = { Count, Nulls, Max, Min, Distinct };
+
+export const statMap = {
+  [Count]: count,
+  [Distinct]: column => count(column).distinct(),
+  [Max]: max,
+  [Min]: min,
+  [Nulls]: column => count().where(isNull(column))
+};
+
+export function summarize({ table, column }, stats) {
+  return Query
+    .from(table)
+    .select(stats.map(s => [s, statMap[s](column)]));
+}

package/src/util/synchronizer.js

@@ -0,0 +1,47 @@
+/**
+ * Create a new synchronizer instance to aid synchronization
+ * of updates on multiple pending operations.
+ */
+export function synchronizer() {
+  const set = new Set;
+  let done;
+  let promise = new Promise(resolve => done = resolve);
+
+  return {
+    /**
+     * Mark an item as pending.
+     * @param {*} item An item to synchronize on.
+     */
+    pending(item) {
+      set.add(item);
+    },
+    /**
+     * Mark a pending item as ready, indicating it is
+     * ready for a synchronized update.
+     * @param {*} item An item to synchronize on.
+     * @returns {boolean} True if the synchronizer is ready to
+     *  resolve, false otherwise.
+     */
+    ready(item) {
+      set.delete(item);
+      return set.size === 0;
+    },
+    /**
+     * Resolve the current synchronization cycle, causing the synchronize
+     * promise to resolve and thereby trigger downstream updates.
+     */
+    resolve() {
+      promise = new Promise(resolve => {
+        done();
+        done = resolve;
+      });
+    },
+    /**
+     * The promise for the current synchronization cycle.
+     * @return {Promise} The synchronization promise.
+     */
+    get promise() {
+      return promise;
+    }
+  }
+}

package/src/util/throttle.js

@@ -1,11 +1,14 @@
-export function throttle(callback) {
+const NIL = {};
+
+export function throttle(callback, debounce = false) {
   let curr;
   let next;
+  let pending = NIL;
 
   function invoke(event) {
     curr = callback(event).then(() => {
       if (next) {
-        const value = next;
+        const { value } = next;
         next = null;
         invoke(value);
       } else {
@@ -15,8 +18,23 @@ export function throttle(callback) {
   }
 
   function enqueue(event) {
-    next = event;
+    next = { event };
+  }
+
+  function process(event) {
+    curr ? enqueue(event) : invoke(event);
+  }
+
+  function delay(event) {
+    if (pending !== event) {
+      requestAnimationFrame(() => {
+        const e = pending;
+        pending = NIL;
+        process(e);
+      });
+    }
+    pending = event;
   }
 
-  return event => curr ? enqueue(event) : invoke(event);
+  return debounce ? delay : process;
 }

package/src/util/void-logger.js

@@ -0,0 +1,9 @@
+export function voidLogger() {
+  return {
+    debug() {},
+    info() {},
+    log() {},
+    warn() {},
+    error() {}
+  };
+}

package/src/QueryCache.js

@@ -1,65 +0,0 @@
-export class QueryCache {
-  constructor({
-    max = 1000, // max entries
-    ttl = 3 * 60 * 60 * 1000 // time-to-live, default 3 hours
-  } = {}) {
-    this.max = max;
-    this.ttl = ttl;
-    this.clear();
-  }
-
-  clear() {
-    this.cache = new Map();
-  }
-
-  get(key) {
-    const entry = this.cache.get(key);
-    if (entry) {
-      entry.last = performance.now();
-      return entry.promise;
-    }
-  }
-
-  set(key, promise) {
-    const { cache, max } = this;
-    const now = performance.now();
-
-    const receive = promise.then(result => {
-      console.log(`Query: ${Math.round(performance.now() - now)}`);
-      return result;
-    });
-
-    cache.set(key, { last: now, promise });
-    if (cache.size > max) {
-      setTimeout(() => this.evict());
-    }
-
-    return receive;
-  }
-
-  evict() {
-    const expire = performance.now() - this.ttl;
-    let lruKey = null;
-    let lruLast = Infinity;
-
-    for (const [key, value] of this.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) {
-        this.cache.delete(key);
-      }
-    }
-
-    // remove lru entry
-    if (lruKey) {
-      this.cache.delete(lruKey);
-    }
-  }
-}

package/src/Signal.js

@@ -1,40 +0,0 @@
-export function isSignal(x) {
-  return x instanceof Signal;
-}
-
-export class Signal {
-  constructor(value) {
-    this._value = value;
-    this._listeners = new Map;
-  }
-
-  get value() {
-    return this._value;
-  }
-
-  update(value, { force } = {}) {
-    const changed = this._value !== value;
-    if (changed) this._value = value;
-    if (changed || force) this.emit('value', this.value);
-    return this;
-  }
-
-  addEventListener(type, callback) {
-    let list = this._listeners.get(type) || [];
-    if (list.indexOf(callback) < 0) {
-      list = list.concat(callback);
-    }
-    this._listeners.set(type, list);
-  }
-
-  removeEventListener(type, callback) {
-    const list = this._listeners.get(type);
-    if (list?.length) {
-      this._listeners.set(type, list.filter(x => x !== callback));
-    }
-  }
-
-  emit(type, event) {
-    this._listeners.get(type)?.forEach(l => l(event));
-  }
-}

package/src/util/skip-client.js

@@ -1,3 +0,0 @@
-export function skipClient(client, clause) {
-  return clause?.clients?.has(client);
-}

package/src/util/sql-from.js

@@ -1,22 +0,0 @@
-import { literalToSQL } from '@uwdata/mosaic-sql';
-
-export function sqlFrom(data, {
-  columns = Object.keys(data?.[0] || {})
-} = {}) {
-  let keys = [];
-  if (Array.isArray(columns)) {
-    keys = columns;
-    columns = keys.reduce((m, k) => (m[k] = k, m), {});
-  } else if (columns) {
-    keys = Object.keys(columns);
-  }
-  if (!keys.length) {
-    throw new Error('Can not create table from empty column set.');
-  }
-  const subq = [];
-  for (const datum of data) {
-    const sel = keys.map(k => `${literalToSQL(datum[k])} AS "${columns[k]}"`);
-    subq.push(`(SELECT ${sel.join(', ')})`);
-  }
-  return subq.join(' UNION ALL ');
-}