@uwdata/mosaic-core 0.9.0 → 0.11.0

package/src/util/index-columns.js

@@ -1,26 +1,32 @@
 import { Query, agg, sql } from '@uwdata/mosaic-sql';
 import { MosaicClient } from '../MosaicClient.js';
 
-export const NO_INDEX = { from: NaN };
-
 /**
  * Determine data cube index columns for a given Mosaic client.
  * @param {MosaicClient} client The Mosaic client.
  * @returns An object with necessary column data to generate data
- *  cube index columns, null if an invalid or unsupported expression
- *  is encountered, or NO_INDEX if the client is not indexable.
+ *  cube index columns, or null if the client is not indexable or
+ *  the client query contains an invalid or unsupported expression.
  */
 export function indexColumns(client) {
-  if (!client.filterIndexable) return NO_INDEX;
+  if (!client.filterIndexable) return null;
   const q = client.query();
-  const from = getBaseTable(q);
-  if (typeof from !== 'string' || !q.groupby) return NO_INDEX;
-  const g = new Set(q.groupby().map(c => c.column));
+  const from = getBase(q, q => q.from()?.[0].from.table);
+
+  // bail if no base table or the query is not analyzable
+  if (typeof from !== 'string' || !q.select) return null;
 
   const aggr = []; // list of output aggregate columns
   const dims = []; // list of grouping dimension columns
   const aux = {};  // auxiliary columns needed by aggregates
 
+  const avg = ref => {
+    const name = ref.column;
+    // @ts-ignore
+    const expr = getBase(q, q => q.select().find(c => c.as === name)?.expr);
+    return `(SELECT AVG(${expr ?? ref}) FROM "${from}")`;
+  };
+
   for (const entry of q.select()) {
     const { as, expr: { aggregate, args } } = entry;
     const op = aggregate?.toUpperCase?.();
@@ -47,32 +53,32 @@ export function indexColumns(client) {
       case 'VARIANCE':
       case 'VAR_SAMP':
         aux[as] = null;
-        aggr.push({ [as]: varianceExpr(aux, args[0], from) });
+        aggr.push({ [as]: varianceExpr(aux, args[0], avg) });
         break;
       case 'VAR_POP':
         aux[as] = null;
-        aggr.push({ [as]: varianceExpr(aux, args[0], from, false) });
+        aggr.push({ [as]: varianceExpr(aux, args[0], avg, false) });
         break;
       case 'STDDEV':
       case 'STDDEV_SAMP':
         aux[as] = null;
-        aggr.push({ [as]: agg`SQRT(${varianceExpr(aux, args[0], from)})` });
+        aggr.push({ [as]: agg`SQRT(${varianceExpr(aux, args[0], avg)})` });
         break;
       case 'STDDEV_POP':
         aux[as] = null;
-        aggr.push({ [as]: agg`SQRT(${varianceExpr(aux, args[0], from, false)})` });
+        aggr.push({ [as]: agg`SQRT(${varianceExpr(aux, args[0], avg, false)})` });
         break;
       case 'COVAR_SAMP':
         aux[as] = null;
-        aggr.push({ [as]: covarianceExpr(aux, args, from) });
+        aggr.push({ [as]: covarianceExpr(aux, args, avg) });
         break;
       case 'COVAR_POP':
         aux[as] = null;
-        aggr.push({ [as]: covarianceExpr(aux, args, from, false) });
+        aggr.push({ [as]: covarianceExpr(aux, args, avg, false) });
         break;
       case 'CORR':
         aux[as] = null;
-        aggr.push({ [as]: corrExpr(aux, args, from) });
+        aggr.push({ [as]: corrExpr(aux, args, avg) });
         break;
 
       // regression statistics
@@ -90,27 +96,27 @@ export function indexColumns(client) {
         break;
       case 'REGR_SYY':
         aux[as] = null;
-        aggr.push({ [as]: regrVarExpr(aux, 0, args, from) });
+        aggr.push({ [as]: regrVarExpr(aux, 0, args, avg) });
         break;
       case 'REGR_SXX':
         aux[as] = null;
-        aggr.push({ [as]: regrVarExpr(aux, 1, args, from) });
+        aggr.push({ [as]: regrVarExpr(aux, 1, args, avg) });
         break;
       case 'REGR_SXY':
         aux[as] = null;
-        aggr.push({ [as]: covarianceExpr(aux, args, from, null) });
+        aggr.push({ [as]: covarianceExpr(aux, args, avg, null) });
         break;
       case 'REGR_SLOPE':
         aux[as] = null;
-        aggr.push({ [as]: regrSlopeExpr(aux, args, from) });
+        aggr.push({ [as]: regrSlopeExpr(aux, args, avg) });
         break;
       case 'REGR_INTERCEPT':
         aux[as] = null;
-        aggr.push({ [as]: regrInterceptExpr(aux, args, from) });
+        aggr.push({ [as]: regrInterceptExpr(aux, args, avg) });
         break;
       case 'REGR_R2':
         aux[as] = null;
-        aggr.push({ [as]: agg`(${corrExpr(aux, args, from)}) ** 2` });
+        aggr.push({ [as]: agg`(${corrExpr(aux, args, avg)}) ** 2` });
         break;
 
       // aggregates that commute directly
@@ -127,11 +133,14 @@ export function indexColumns(client) {
 
       // otherwise, check if dimension
       default:
-        if (g.has(as)) dims.push(as);
+        if (!aggregate) dims.push(as);
         else return null; // unsupported aggregate
     }
   }
 
+  // bail if the query has no aggregates
+  if (!aggr.length) return null;
+
   return { from, dims, aggr, aux };
 }
 
@@ -161,29 +170,30 @@ function sanitize(col) {
 }
 
 /**
- * Identify a single base (source) table of a query.
+ * Identify a shared base (source) query and extract a value from it.
+ * This method is used to find a shared base table name or extract
+ * the original column name within a base table.
  * @param {Query} query The input query.
- * @returns {string | undefined | NaN} the base table name, or
+ * @param {(q: Query) => any} get A getter function to extract
+ *  a value from a base query.
+ * @returns {string | undefined | NaN} the base query value, or
  *  `undefined` if there is no source table, or `NaN` if the
  *  query operates over multiple source tables.
  */
-function getBaseTable(query) {
+function getBase(query, get) {
   const subq = query.subqueries;
 
   // select query
-  if (query.select) {
-    const from = query.from();
-    // @ts-ignore
-    if (!from.length) return undefined;
-    if (subq.length === 0) return from[0].from.table;
+  if (query.select && subq.length === 0) {
+    return get(query);
   }
 
   // handle set operations / subqueries
-  const base = getBaseTable(subq[0]);
+  const base = getBase(subq[0], get);
   for (let i = 1; i < subq.length; ++i) {
-    const from = getBaseTable(subq[i]);
-    if (from === undefined) continue;
-    if (from !== base) return NaN;
+    const value = getBase(subq[i], get);
+    if (value === undefined) continue;
+    if (value !== base) return NaN;
   }
   return base;
 }
@@ -222,17 +232,6 @@ function avgExpr(aux, as, arg) {
   return agg`(SUM("${as}" * ${n.name}) / ${n})`;
 }
 
-/**
- * Generate a scalar subquery for a global average.
- * This value can be used to mean-center data.
- * @param {*} x Souce data table column.
- * @param {string} from The source data table name.
- * @returns A scalar aggregate query
- */
-function avg(x, from) {
-  return sql`(SELECT AVG(${x}) FROM "${from}")`;
-}
-
 /**
  * Generate an expression for calculating argmax over data partitions.
  * As a side effect, this method adds a column to the input *aux* object
@@ -281,18 +280,18 @@ function argminExpr(aux, as, [, y]) {
  *  sufficient statistics) to include in the data cube aggregation.
  * @param {*} x The source data table column. This may be a string,
  *  column reference, SQL expression, or other string-coercible value.
- * @param {string} from The source data table name.
+ * @param {(field: any) => string} avg Global average query generator.
  * @param {boolean} [correction=true] A flag for whether a Bessel
  *  correction should be applied to compute the sample variance
  *  rather than the populatation variance.
  * @returns An aggregate expression for calculating variance over
  *  pre-aggregated data partitions.
  */
-function varianceExpr(aux, x, from, correction = true) {
+function varianceExpr(aux, x, avg, correction = true) {
   const n = countExpr(aux, x);
   const ssq = auxName('rssq', x); // residual sum of squares
   const sum = auxName('rsum', x); // residual sum
-  const delta = sql`${x} - ${avg(x, from)}`;
+  const delta = sql`${x} - ${avg(x)}`;
   aux[ssq] = agg`SUM((${delta}) ** 2)`;
   aux[sum] = agg`SUM(${delta})`;
   const adj = correction ? ` - 1` : ''; // Bessel correction
@@ -310,7 +309,7 @@ function varianceExpr(aux, x, from, correction = true) {
  *  sufficient statistics) to include in the data cube aggregation.
  * @param {any[]} args Source data table columns. The entries may be strings,
  *  column references, SQL expressions, or other string-coercible values.
- * @param {string} from The source data table name.
+ * @param {(field: any) => string} avg Global average query generator.
  * @param {boolean|null} [correction=true] A flag for whether a Bessel
  *  correction should be applied to compute the sample covariance rather
  *  than the populatation covariance. If null, an expression for the
@@ -318,11 +317,11 @@ function varianceExpr(aux, x, from, correction = true) {
  * @returns An aggregate expression for calculating covariance over
  *  pre-aggregated data partitions.
  */
-function covarianceExpr(aux, args, from, correction = true) {
+function covarianceExpr(aux, args, avg, correction = true) {
   const n = regrCountExpr(aux, args);
-  const sxy = regrSumXYExpr(aux, args, from);
-  const sx = regrSumExpr(aux, 1, args, from);
-  const sy = regrSumExpr(aux, 0, args, from);
+  const sxy = regrSumXYExpr(aux, args, avg);
+  const sx = regrSumExpr(aux, 1, args, avg);
+  const sy = regrSumExpr(aux, 0, args, avg);
   const adj = correction === null ? ''  // do not divide by count
     : correction ? ` / (${n} - 1)` // Bessel correction (sample)
     : ` / ${n}`;                   // no correction (population)
@@ -341,17 +340,17 @@ function covarianceExpr(aux, args, from, correction = true) {
  *  sufficient statistics) to include in the data cube aggregation.
  * @param {any[]} args Source data table columns. The entries may be strings,
  *  column references, SQL expressions, or other string-coercible values.
- * @param {string} from The source data table name.
+ * @param {(field: any) => string} avg Global average query generator.
  * @returns An aggregate expression for calculating correlation over
  *  pre-aggregated data partitions.
  */
-function corrExpr(aux, args, from) {
+function corrExpr(aux, args, avg) {
   const n = regrCountExpr(aux, args);
-  const sxy = regrSumXYExpr(aux, args, from);
-  const sxx = regrSumSqExpr(aux, 1, args, from);
-  const syy = regrSumSqExpr(aux, 0, args, from);
-  const sx = regrSumExpr(aux, 1, args, from);
-  const sy = regrSumExpr(aux, 0, args, from);
+  const sxy = regrSumXYExpr(aux, args, avg);
+  const sxx = regrSumSqExpr(aux, 1, args, avg);
+  const syy = regrSumSqExpr(aux, 0, args, avg);
+  const sx = regrSumExpr(aux, 1, args, avg);
+  const sy = regrSumExpr(aux, 0, args, avg);
   const vx = agg`(${sxx} - (${sx} ** 2) / ${n})`;
   const vy = agg`(${syy} - (${sy} ** 2) / ${n})`;
   return agg`(${sxy} - ${sx} * ${sy} / ${n}) / SQRT(${vx} * ${vy})`;
@@ -385,14 +384,14 @@ function regrCountExpr(aux, [y, x]) {
  * @param {number} i An index indicating which argument column to sum.
  * @param {any[]} args Source data table columns. The entries may be strings,
  *  column references, SQL expressions, or other string-coercible values.
- * @param {string} from The source data table name.
+ * @param {(field: any) => string} avg Global average query generator.
  * @returns An aggregate expression over pre-aggregated data partitions.
  */
-function regrSumExpr(aux, i, args, from) {
+function regrSumExpr(aux, i, args, avg) {
   const v = args[i];
   const o = args[1 - i];
   const sum = auxName('rs', v);
-  aux[sum] = agg`SUM(${v} - ${avg(v, from)}) FILTER (${o} IS NOT NULL)`;
+  aux[sum] = agg`SUM(${v} - ${avg(v)}) FILTER (${o} IS NOT NULL)`;
   return agg`SUM(${sum})`
 }
 
@@ -407,14 +406,14 @@ function regrSumExpr(aux, i, args, from) {
  * @param {number} i An index indicating which argument column to sum.
  * @param {any[]} args Source data table columns. The entries may be strings,
  *  column references, SQL expressions, or other string-coercible values.
- * @param {string} from The source data table name.
+ * @param {(field: any) => string} avg Global average query generator.
  * @returns An aggregate expression over pre-aggregated data partitions.
  */
-function regrSumSqExpr(aux, i, args, from) {
+function regrSumSqExpr(aux, i, args, avg) {
   const v = args[i];
   const u = args[1 - i];
   const ssq = auxName('rss', v);
-  aux[ssq] = agg`SUM((${v} - ${avg(v, from)}) ** 2) FILTER (${u} IS NOT NULL)`;
+  aux[ssq] = agg`SUM((${v} - ${avg(v)}) ** 2) FILTER (${u} IS NOT NULL)`;
   return agg`SUM(${ssq})`
 }
 
@@ -428,13 +427,13 @@ function regrSumSqExpr(aux, i, args, from) {
  *  sufficient statistics) to include in the data cube aggregation.
  * @param {any[]} args Source data table columns. The entries may be strings,
  *  column references, SQL expressions, or other string-coercible values.
- * @param {string} from The source data table name.
+ * @param {(field: any) => string} avg Global average query generator.
  * @returns An aggregate expression over pre-aggregated data partitions.
  */
-function regrSumXYExpr(aux, args, from) {
+function regrSumXYExpr(aux, args, avg) {
   const [y, x] = args;
   const sxy = auxName('sxy', y, x);
-  aux[sxy] = agg`SUM((${x} - ${avg(x, from)}) * (${y} - ${avg(y, from)}))`;
+  aux[sxy] = agg`SUM((${x} - ${avg(x)}) * (${y} - ${avg(y)}))`;
   return agg`SUM(${sxy})`;
 }
 
@@ -487,14 +486,14 @@ function regrAvgYExpr(aux, args) {
  * @param {number} i The index of the argument to compute the variance for.
  * @param {any[]} args Source data table columns. The entries may be strings,
  *  column references, SQL expressions, or other string-coercible values.
- * @param {string} from The source data table name.
+ * @param {(field: any) => string} avg Global average query generator.
  * @returns An aggregate expression for calculating variance over
  *  pre-aggregated data partitions.
  */
-function regrVarExpr(aux, i, args, from) {
+function regrVarExpr(aux, i, args, avg) {
   const n = regrCountExpr(aux, args);
-  const sum = regrSumExpr(aux, i, args, from);
-  const ssq = regrSumSqExpr(aux, i, args, from);
+  const sum = regrSumExpr(aux, i, args, avg);
+  const ssq = regrSumSqExpr(aux, i, args, avg);
   return agg`(${ssq} - (${sum} ** 2 / ${n}))`;
 }
 
@@ -507,13 +506,13 @@ function regrVarExpr(aux, i, args, from) {
  *  sufficient statistics) to include in the data cube aggregation.
  * @param {any[]} args Source data table columns. The entries may be strings,
  *  column references, SQL expressions, or other string-coercible values.
- * @param {string} from The source data table name.
+ * @param {(field: any) => string} avg Global average query generator.
  * @returns An aggregate expression for calculating regression slopes over
  *  pre-aggregated data partitions.
  */
-function regrSlopeExpr(aux, args, from) {
-  const cov = covarianceExpr(aux, args, from, null);
-  const varx = regrVarExpr(aux, 1, args, from);
+function regrSlopeExpr(aux, args, avg) {
+  const cov = covarianceExpr(aux, args, avg, null);
+  const varx = regrVarExpr(aux, 1, args, avg);
   return agg`(${cov}) / ${varx}`;
 }
 
@@ -526,13 +525,13 @@ function regrSlopeExpr(aux, args, from) {
  *  sufficient statistics) to include in the data cube aggregation.
  * @param {any[]} args Source data table columns. The entries may be strings,
  *  column references, SQL expressions, or other string-coercible values.
- * @param {string} from The source data table name.
+ * @param {(field: any) => string} avg Global average query generator.
  * @returns An aggregate expression for calculating regression intercepts over
  *  pre-aggregated data partitions.
  */
-function regrInterceptExpr(aux, args, from) {
+function regrInterceptExpr(aux, args, avg) {
   const ax = regrAvgXExpr(aux, args);
   const ay = regrAvgYExpr(aux, args);
-  const m = regrSlopeExpr(aux, args, from);
+  const m = regrSlopeExpr(aux, args, avg);
   return agg`${ay} - (${m}) * ${ax}`;
 }

package/src/util/is-arrow-table.js

@@ -0,0 +1,10 @@
+/**
+ * Test if a value is a Flechette Arrow table.
+ * We use a "duck typing" approach and check for a getChild function.
+ * @param {*} values The value to test
+ * @returns {values is import('@uwdata/flechette').Table}
+ *  true if the value duck types as Arrow data
+ */
+export function isArrowTable(values) {
+  return typeof values?.getChild === 'function';
+}

package/src/util/priority-queue.js

@@ -1,85 +1,84 @@
-/**
- * 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(
+export class PriorityQueue {
+  /**
+   * Create a new priority queue instance.
+   * @param {number} ranks An integer number of rank-order priority levels.
+   */
+  constructor(ranks) {
+    // one list for each integer priority level
+    this.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);
-		},
+  /**
+   * Indicate if the queue is empty.
+   * @returns {boolean} true if empty, false otherwise.
+   */
+  isEmpty() {
+    return this.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}`);
-			}
+  /**
+   * 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 = this.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);
-			}
-		},
+    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 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 this.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;
-				}
-			}
-		}
-	};
+  /**
+   * 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 this.queue) {
+      const { head } = list;
+      if (head !== null) {
+        list.head = head.next;
+        if (list.tail === head) {
+          list.tail = null;
+        }
+        return head.item;
+      }
+    }
+  }
 }

package/src/util/query-result.js

@@ -1,9 +1,42 @@
-export function queryResult() {
-  let resolve;
-  let reject;
-  const p = new Promise((r, e) => { resolve = r; reject = e; });
-  return Object.assign(p, {
-    fulfill: value => (resolve(value), p),
-    reject: err => (reject(err), p)
-  });
+/**
+ * A query result Promise that can allows external callers
+ * to resolve or reject the Promise.
+ */
+export class QueryResult extends Promise {
+  /**
+   * Create a new query result Promise.
+   */
+  constructor() {
+    let resolve;
+    let reject;
+    super((r, e) => {
+      resolve = r;
+      reject = e;
+    });
+    this._resolve = resolve;
+    this._reject = reject;
+  }
+
+  /**
+   * Resolve the result Promise with the provided value.
+   * @param {*} value The result value.
+   * @returns {this}
+   */
+  fulfill(value) {
+    this._resolve(value);
+    return this;
+  }
+
+  /**
+   * Rejects the result Promise with the provided error.
+   * @param {*} error The error value.
+   * @returns {this}
+   */
+  reject(error) {
+    this._reject(error);
+    return this;
+  }
 }
+
+// necessary to make Promise subclass act like a Promise
+QueryResult.prototype.constructor = Promise;

package/src/util/throttle.js

@@ -1,12 +1,22 @@
 const NIL = {};
 
+/**
+ * Throttle invocations of a callback function. The callback must return
+ * a Promise. Upon repeated invocation, the callback will not be invoked
+ * until a prior Promise resolves. If multiple invocations occurs while
+ * waiting, only the most recent invocation will be pending.
+ * @param {(event: *) => Promise} callback The callback function.
+ * @param {boolean} [debounce=true] Flag indicating if invocations
+ *  should also be debounced within the current animation frame.
+ * @returns A new function that throttles access to the callback.
+ */
 export function throttle(callback, debounce = false) {
   let curr;
   let next;
   let pending = NIL;
 
   function invoke(event) {
-    curr = callback(event).then(() => {
+    curr = callback(event).finally(() => {
       if (next) {
         const { value } = next;
         next = null;